feat: link tags

Tags went live on the API in spoo v2.4.0 and this SDK had no way to
reach them. Adds the tag endpoints, tag_ids on shorten and update, tags
on every link response, the tagIds/tagNames/tagsMatch list filters, the
tag and tag_id stats and export filters, and BulkUpdateTags next to the
other bulk methods. Refreshes openapi.json so spec drift stays green.

Author: Zingzy

README.md

@@ -115,7 +115,56 @@ for _, row := range res.Results {
 }
 ```
 
-`BulkDelete`, `BulkUpdateExpiry`, and `BulkMoveDomain` follow the same shape.
+`BulkDelete`, `BulkUpdateExpiry`, `BulkMoveDomain`, and `BulkUpdateTags` follow
+the same shape.
+
+## Tags
+
+Tags are account-wide labels with a color and an icon. A link carries up to
+ten of them, by id:
+
+```go
+tag, err := client.CreateTag(ctx, spoo.CreateTagParams{Name: "launch", Color: "violet"})
+
+link, err := client.Shorten(ctx, spoo.ShortenRequest{
+    LongURL: "https://example.com/launch",
+    TagIDs:  []string{tag.ID},
+})
+
+// on update the list replaces the stored one; spoo.Null clears it
+_, err = client.UpdateURL(ctx, link.ID, spoo.UpdateURLParams{
+    TagIDs: spoo.Set([]string{tag.ID}),
+})
+```
+
+Filter the link list by tag id or name, and pick whether a link needs any or
+all of them:
+
+```go
+page, err := client.ListURLs(ctx, spoo.ListURLsOptions{
+    TagNames:  []string{"launch", "q3"},
+    TagsMatch: "all",
+})
+```
+
+Tag or untag up to 100 links at once; the result has the same per-item shape
+as the other bulk operations:
+
+```go
+res, err := client.BulkUpdateTags(ctx, ids, spoo.BulkTagChange{Add: []string{tag.ID}})
+```
+
+Stats and exports take `tag` (names) and `tag_id` filters on the aggregate
+routes, covering the whole click history of the tagged links:
+
+```go
+stats, err := client.Stats(ctx, spoo.StatsQuery{
+    Filters: map[string][]string{"tag": {"launch"}},
+})
+```
+
+`ListTags`, `UpdateTag`, and `DeleteTag` round out the set. Deleting a tag
+removes it from every link and reports how many were touched.
 
 ## Stats and exports
 
@@ -243,8 +292,9 @@ file, or database, and rotated tokens persist through it.
 ## Scope
 
 The SDK covers the v1 data plane end to end: shortening, link management,
-claiming, bulk operations, stats, exports, public stats and previews, the
-emoji alias policy, identity (`Me`), and the Sign in with Spoo device flow.
+claiming, tags, bulk operations, stats, exports, public stats and previews,
+the emoji alias policy, identity (`Me`), and the Sign in with Spoo device
+flow.
 Deliberately out of scope: API key management, health checks, the contact
 endpoint, profile management, and all legacy v0 routes. Anything the API
 grows before the SDK does is reachable through the raw request methods
@@ -260,7 +310,9 @@ below.
 | `UpdateURL`, `SetURLStatus` | `PATCH /api/v1/urls/{id}`, `PATCH /api/v1/urls/{id}/status` |
 | `DeleteURL`, `DeleteURLsByDomain` | `DELETE /api/v1/urls/{id}`, `DELETE /api/v1/urls?domain=` |
 | `ClaimURLs` | `POST /api/v1/urls/claim` |
-| `BulkDelete`, `BulkUpdateStatus`, `BulkUpdateExpiry`, `BulkMoveDomain` | `POST /api/v1/urls/bulk/*` |
+| `BulkDelete`, `BulkUpdateStatus`, `BulkUpdateExpiry`, `BulkMoveDomain`, `BulkUpdateTags` | `POST /api/v1/urls/bulk/*` |
+| `ListTags`, `CreateTag` | `GET /api/v1/tags`, `POST /api/v1/tags` |
+| `UpdateTag`, `DeleteTag` | `PATCH /api/v1/tags/{id}`, `DELETE /api/v1/tags/{id}` |
 | `Stats`, `LinkStats`, `StatsByAlias` | `GET /api/v1/stats`, `GET /api/v1/stats/links/{id}` |
 | `PublicStats`, `PublicPreview` | `GET or POST /api/v1/public/stats/{code}`, `GET /api/v1/public/preview/{code}` |
 | `Export`, `ExportLink` | `GET /api/v1/export`, `GET /api/v1/export/links/{id}` |

bulk.go

@@ -79,6 +79,27 @@ func (c *Client) BulkMoveDomain(ctx context.Context, ids []string, domain string
 	return c.bulk(ctx, "/api/v1/urls/bulk/domain", body)
 }
 
+// BulkTagChange names the tag ids to add to and remove from every link
+// in a [Client.BulkUpdateTags] call. At least one side must name a tag,
+// and no tag may appear on both.
+type BulkTagChange struct {
+	Add    []string `json:"add,omitempty"`
+	Remove []string `json:"remove,omitempty"`
+}
+
+// BulkUpdateTags adds and removes tags, by tag id, on up to 100 owned
+// links by url id. Each link ends up with its current tags minus Remove
+// plus Add (kept once, order preserved). An unknown id in Add rejects
+// the whole request; a link that would exceed 10 tags fails per-item
+// with validation_error.
+func (c *Client) BulkUpdateTags(ctx context.Context, ids []string, change BulkTagChange) (*BulkResult, error) {
+	body := struct {
+		IDs []string `json:"ids"`
+		BulkTagChange
+	}{IDs: ids, BulkTagChange: change}
+	return c.bulk(ctx, "/api/v1/urls/bulk/tags", body)
+}
+
 func (c *Client) bulk(ctx context.Context, path string, body any) (*BulkResult, error) {
 	var out BulkResult
 	if err := c.do(ctx, http.MethodPost, path, nil, body, &out); err != nil {

bulk_test.go

@@ -122,3 +122,36 @@ func TestBulkMoveDomainWire(t *testing.T) {
 		t.Fatalf("clear body = %s", bodies[1])
 	}
 }
+
+// Empty add or remove lists are omitted; the server requires at least
+// one of them to name a tag.
+func TestBulkUpdateTagsBody(t *testing.T) {
+	var bodies []string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/v1/urls/bulk/tags" || r.Method != http.MethodPost {
+			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
+		}
+		data, _ := io.ReadAll(r.Body)
+		bodies = append(bodies, string(data))
+		w.Write([]byte(`{"summary":{"total":2,"succeeded":1,"failed":1},"results":[{"id":"a","alias":"x","ok":true},{"id":"b","alias":"y","ok":false,"error_code":"validation_error","error":"too many tags"}]}`))
+	}))
+	defer srv.Close()
+
+	c := NewClient(option.WithBaseURL(srv.URL))
+	res, err := c.BulkUpdateTags(context.Background(), []string{"a", "b"}, BulkTagChange{Add: []string{"t1", "t2"}, Remove: []string{"t3"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := c.BulkUpdateTags(context.Background(), []string{"a", "b"}, BulkTagChange{Remove: []string{"t3"}}); err != nil {
+		t.Fatal(err)
+	}
+	if bodies[0] != `{"ids":["a","b"],"add":["t1","t2"],"remove":["t3"]}` {
+		t.Fatalf("body = %s", bodies[0])
+	}
+	if bodies[1] != `{"ids":["a","b"],"remove":["t3"]}` {
+		t.Fatalf("remove-only body = %s", bodies[1])
+	}
+	if res.Summary.Failed != 1 || res.Results[1].ErrorCode != "validation_error" {
+		t.Fatalf("res = %+v", res)
+	}
+}

doc.go

@@ -2,8 +2,8 @@
 // API.
 //
 // The package covers the v1 HTTP API: shortening, link management,
-// claiming, bulk operations, stats, exports, public previews, the emoji
-// alias policy, and the connected-apps device flow. It has no
+// claiming, tags, bulk operations, stats, exports, public previews, the
+// emoji alias policy, and the connected-apps device flow. It has no
 // dependencies outside the standard library. Endpoints without a typed
 // method yet are reachable through the raw [Client.Get], [Client.Post],
 // [Client.Put], [Client.Patch] and [Client.Delete] passthroughs, which

export.go

@@ -27,9 +27,10 @@ type ExportFile struct {
 
 // Export downloads account-wide stats in the given format (json, csv,
 // xlsx, xml). Auth is required — anonymous export no longer exists.
-// Slice to specific links with the short_code / url_id filters on
-// [StatsQuery]; note the aggregate route reports a generic filename
-// regardless of slicing, so single-link exports belong on ExportLink.
+// Slice to specific links with the short_code / url_id / tag / tag_id
+// filters on [StatsQuery]; note the aggregate route reports a generic
+// filename regardless of slicing, so single-link exports belong on
+// ExportLink.
 func (c *Client) Export(ctx context.Context, q StatsQuery, format string) (*ExportFile, error) {
 	return c.export(ctx, "/api/v1/export", q.values(), format)
 }
@@ -39,7 +40,8 @@ func (c *Client) Export(ctx context.Context, q StatsQuery, format string) (*Expo
 // identity (the aggregate route names every download the same, so
 // saved files would silently overwrite each other). Resolve an alias
 // with ResolveAlias first; unknown and foreign ids both 404. The
-// short_code / url_id slicing filters are aggregate-only here too.
+// short_code / url_id / tag / tag_id slicing filters are not accepted on
+// the per-link routes and are rejected client-side here too.
 func (c *Client) ExportLink(ctx context.Context, urlID string, q StatsQuery, format string) (*ExportFile, error) {
 	if err := q.validatePerLink(); err != nil {
 		return nil, err