feat: typed raw request methods

Get, Post, Put, Patch and Delete on the client take an API path and
reuse the configured auth, refresh, retries, client tag and error
mapping. They exist for endpoints without a typed method yet, so a
coverage gap never forces a fork or a second HTTP client.

Author: Zingzy

raw.go

@@ -0,0 +1,58 @@
+package spoo
+
+import (
+	"context"
+	"net/http"
+	"net/url"
+)
+
+// The raw request methods below are the supported pressure valve for
+// API endpoints the SDK has no typed method for yet. They speak
+// through the configured client, so auth, token refresh, retries,
+// timeout, the attribution tag and *Error mapping all apply; only the
+// request and response types are the caller's. path is relative to the
+// client's base URL and must start with "/", e.g. "/api/v1/urls".
+// Needing one of these means the SDK surface has a gap worth an issue
+// at https://github.com/spoo-me/spoo-go/issues.
+
+// Get performs a raw GET request against an API path and decodes the
+// JSON response into out (skipped when out is nil). It is the
+// supported pressure valve for endpoints the SDK does not cover yet;
+// needing it is worth an issue.
+func (c *Client) Get(ctx context.Context, path string, query url.Values, out any) error {
+	return c.do(ctx, http.MethodGet, path, query, nil, out)
+}
+
+// Post performs a raw POST request against an API path, marshaling
+// body to JSON (no body when nil) and decoding the JSON response into
+// out (skipped when out is nil). It is the supported pressure valve
+// for endpoints the SDK does not cover yet; needing it is worth an
+// issue.
+func (c *Client) Post(ctx context.Context, path string, body, out any) error {
+	return c.do(ctx, http.MethodPost, path, nil, body, out)
+}
+
+// Put performs a raw PUT request against an API path, marshaling body
+// to JSON (no body when nil) and decoding the JSON response into out
+// (skipped when out is nil). It is the supported pressure valve for
+// endpoints the SDK does not cover yet; needing it is worth an issue.
+func (c *Client) Put(ctx context.Context, path string, body, out any) error {
+	return c.do(ctx, http.MethodPut, path, nil, body, out)
+}
+
+// Patch performs a raw PATCH request against an API path, marshaling
+// body to JSON (no body when nil) and decoding the JSON response into
+// out (skipped when out is nil). It is the supported pressure valve
+// for endpoints the SDK does not cover yet; needing it is worth an
+// issue.
+func (c *Client) Patch(ctx context.Context, path string, body, out any) error {
+	return c.do(ctx, http.MethodPatch, path, nil, body, out)
+}
+
+// Delete performs a raw DELETE request against an API path and decodes
+// the JSON response into out (skipped when out is nil). It is the
+// supported pressure valve for endpoints the SDK does not cover yet;
+// needing it is worth an issue.
+func (c *Client) Delete(ctx context.Context, path string, out any) error {
+	return c.do(ctx, http.MethodDelete, path, nil, nil, out)
+}

raw_test.go

@@ -0,0 +1,91 @@
+package spoo
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"testing"
+
+	"github.com/spoo-me/spoo-go/option"
+)
+
+// The raw methods must ride the same machinery as every typed call:
+// auth header, client tag, query encoding, body marshaling, decoding.
+func TestRawMethodsReuseClientMachinery(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("Authorization") != "Bearer spoo_key123" {
+			t.Errorf("Authorization = %q", r.Header.Get("Authorization"))
+		}
+		if r.Header.Get("X-Spoo-Client") != "raw-test/1.0" {
+			t.Errorf("X-Spoo-Client = %q", r.Header.Get("X-Spoo-Client"))
+		}
+		switch r.Method {
+		case http.MethodGet:
+			if r.URL.Path != "/api/v1/future" || r.URL.Query().Get("page") != "2" {
+				t.Errorf("unexpected GET: %s %v", r.URL.Path, r.URL.Query())
+			}
+		case http.MethodPost, http.MethodPut, http.MethodPatch:
+			var body map[string]any
+			json.NewDecoder(r.Body).Decode(&body)
+			if body["name"] != "x" {
+				t.Errorf("%s body = %v", r.Method, body)
+			}
+		case http.MethodDelete:
+			if r.URL.Path != "/api/v1/future/abc" {
+				t.Errorf("unexpected DELETE path: %s", r.URL.Path)
+			}
+		}
+		w.Write([]byte(`{"ok":true}`))
+	}))
+	defer srv.Close()
+
+	c := NewClient(
+		option.WithBaseURL(srv.URL),
+		option.WithAPIKey("spoo_key123"),
+		option.WithClientTag("raw-test/1.0"),
+	)
+	ctx := context.Background()
+	body := map[string]string{"name": "x"}
+
+	var out struct {
+		OK bool `json:"ok"`
+	}
+	if err := c.Get(ctx, "/api/v1/future", url.Values{"page": {"2"}}, &out); err != nil || !out.OK {
+		t.Fatalf("Get: err=%v out=%+v", err, out)
+	}
+	if err := c.Post(ctx, "/api/v1/future", body, nil); err != nil {
+		t.Fatalf("Post: %v", err)
+	}
+	if err := c.Put(ctx, "/api/v1/future", body, nil); err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+	if err := c.Patch(ctx, "/api/v1/future", body, nil); err != nil {
+		t.Fatalf("Patch: %v", err)
+	}
+	if err := c.Delete(ctx, "/api/v1/future/abc", nil); err != nil {
+		t.Fatalf("Delete: %v", err)
+	}
+}
+
+// Raw calls surface API failures as the same *Error every typed
+// method returns.
+func TestRawMethodsMapErrors(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusNotFound)
+		w.Write([]byte(`{"error":"no such thing","code":"not_found"}`))
+	}))
+	defer srv.Close()
+
+	c := NewClient(option.WithBaseURL(srv.URL))
+	err := c.Get(context.Background(), "/api/v1/future", nil, nil)
+	var apiErr *Error
+	if !errors.As(err, &apiErr) || apiErr.Code != "not_found" {
+		t.Fatalf("err = %v, want *Error with code not_found", err)
+	}
+	if !IsNotFound(err) {
+		t.Fatalf("IsNotFound(%v) = false", err)
+	}
+}