feat: status endpoint, password stats, domain sweep, derived short URLs

- SetURLStatus hits PATCH /urls/{id}/status and returns the same
  UpdatedURL shape as UpdateURL.
- PublicStats now returns the full envelope (PublicStatsResult with
  PublicLinkFacts + stats) instead of discarding the link half, and
  PublicStatsQuery.Password routes the call as a POST with the
  password in the JSON body, the only channel the API reads
  (query-string passwords are ignored by design). Wrong passwords
  keep the typed ErrLinkPasswordProtected semantics.
- DeleteURLsByDomain sweeps one owned custom domain; the server
  refuses the system default domain.
- URLItem.ShortURL is derived client-side on list/get/resolve from
  alias + domain, falling back to the client base URL.

Author: Zingzy

README.md

@@ -126,8 +126,15 @@ stats, err := client.Stats(ctx, spoo.StatsQuery{
 // one link, addressed by alias
 stats, err = client.StatsByAlias(ctx, "launch", "spoo.me", spoo.StatsQuery{})
 
-// anyone's public stats, no auth
-stats, err = client.PublicStats(ctx, "launch", spoo.PublicStatsQuery{})
+// anyone's public stats, no auth; the result pairs link facts with stats
+public, err := client.PublicStats(ctx, "launch", spoo.PublicStatsQuery{})
+fmt.Println(public.Link.Status, public.Stats.Summary.TotalClicks)
+
+// password-protected stats: the password travels in a POST body, never
+// the query string
+public, err = client.PublicStats(ctx, "secret", spoo.PublicStatsQuery{
+    Password: "the-link-password",
+})
 ```
 
 Without explicit dates the API returns only the last 7 days; request up to
@@ -231,11 +238,12 @@ file, or database, and rotated tokens persist through it.
 | `Shorten`, `CheckAlias` | `POST /api/v1/shorten`, `GET /api/v1/shorten/check-alias` |
 | `ListURLs`, `ListURLsAll` | `GET /api/v1/urls` |
 | `GetURL`, `ResolveAlias` | `GET /api/v1/urls/{id}`, `GET /api/v1/urls/{domain}/{alias}` |
-| `UpdateURL`, `DeleteURL` | `PATCH /api/v1/urls/{id}`, `DELETE /api/v1/urls/{id}` |
+| `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/*` |
 | `Stats`, `LinkStats`, `StatsByAlias` | `GET /api/v1/stats`, `GET /api/v1/stats/links/{id}` |
-| `PublicStats`, `PublicPreview` | `GET /api/v1/public/stats/{code}`, `GET /api/v1/public/preview/{code}` |
+| `PublicStats`, `PublicPreview` | `GET or POST /api/v1/public/stats/{code}`, `GET /api/v1/public/preview/{code}` |
 | `Export`, `ExportLink` | `GET /api/v1/export` |
 | `EmojiSet` | `GET /api/v1/emoji-set` (ETag-cached) |
 | `Me` | `GET /auth/me` |

stats.go

@@ -148,13 +148,40 @@ type PublicStatsQuery struct {
 	StartDate time.Time
 	EndDate   time.Time
 	Timezone  string // IANA name
+	// Password unlocks a password-protected link's stats. When set,
+	// the request goes as a POST with the password in the JSON body:
+	// the body is the only channel the API reads (query-string
+	// passwords are ignored so they cannot land in URLs, logs, or
+	// referrers). A wrong password answers 401 invalid_password,
+	// surfaced as ErrLinkPasswordProtected.
+	Password string
+}
+
+// PublicLinkFacts is the link half of the public stats envelope: what
+// the link is, alongside how it performs.
+type PublicLinkFacts struct {
+	Alias    string `json:"alias"`
+	ShortURL string `json:"short_url"`
+	// LongURL is withheld (empty) when the link is not active.
+	LongURL           string    `json:"long_url"`
+	CreatedAt         Timestamp `json:"created_at"`
+	Status            string    `json:"status"` // active | inactive | expired | blocked (lowercase)
+	MaxClicks         *int      `json:"max_clicks"`
+	BlockBots         bool      `json:"block_bots"`
+	PasswordProtected bool      `json:"password_protected"`
+}
+
+// PublicStatsResult is the full public stats envelope.
+type PublicStatsResult struct {
+	Generation string          `json:"generation"` // v1 | v2
+	Link       PublicLinkFacts `json:"link"`
+	Stats      StatsResponse   `json:"stats"`
 }
 
 // PublicStats returns anyone's per-link stats without auth. Private
-// links 404 and password-protected ones 401 (ErrLinkPasswordProtected).
-// The {generation, link, stats} envelope is unwrapped to the standard
-// stats wire.
-func (c *Client) PublicStats(ctx context.Context, shortCode string, q PublicStatsQuery) (*StatsResponse, error) {
+// links 404; password-protected ones 401 (ErrLinkPasswordProtected)
+// unless the query carries the link password.
+func (c *Client) PublicStats(ctx context.Context, shortCode string, q PublicStatsQuery) (*PublicStatsResult, error) {
 	v := url.Values{}
 	if !q.StartDate.IsZero() {
 		v.Set("start_date", q.StartDate.UTC().Format(time.RFC3339))
@@ -165,12 +192,14 @@ func (c *Client) PublicStats(ctx context.Context, shortCode string, q PublicStat
 	if q.Timezone != "" {
 		v.Set("timezone", q.Timezone)
 	}
-	var out struct {
-		Stats StatsResponse `json:"stats"`
+	method, body := http.MethodGet, any(nil)
+	if q.Password != "" {
+		method, body = http.MethodPost, map[string]string{"password": q.Password}
 	}
+	var out PublicStatsResult
 	path := "/api/v1/public/stats/" + url.PathEscape(shortCode)
-	if err := c.do(ctx, http.MethodGet, path, v, nil, &out); err != nil {
+	if err := c.do(ctx, method, path, v, body, &out); err != nil {
 		return nil, err
 	}
-	return &out.Stats, nil
+	return &out, nil
 }

stats_test.go

@@ -113,21 +113,24 @@ func TestStatsByAlias(t *testing.T) {
 	}
 }
 
-func TestPublicStatsUnwrapsEnvelope(t *testing.T) {
+func TestPublicStatsReturnsEnvelope(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != "/api/v1/public/stats/launch" {
 			t.Errorf("path = %s", r.URL.Path)
 		}
+		if r.Method != http.MethodGet {
+			t.Errorf("method = %s, want GET without a password", r.Method)
+		}
 		q := r.URL.Query()
 		if q.Get("start_date") != "2026-01-01T00:00:00Z" || q.Get("timezone") != "UTC" {
 			t.Errorf("unexpected query: %v", q)
 		}
-		if q.Has("group_by") || q.Has("scope") {
+		if q.Has("group_by") || q.Has("scope") || q.Has("password") {
 			t.Errorf("public endpoint takes only a range and timezone: %v", q)
 		}
 		w.Write([]byte(`{
 			"generation": "v2",
-			"link": {"alias": "launch", "domain": "spoo.me"},
+			"link": {"alias": "launch", "short_url": "https://spoo.me/launch", "long_url": "https://example.com/x", "status": "active", "password_protected": false, "block_bots": true},
 			"stats": {
 				"scope": "anon",
 				"summary": {"total_clicks": 9, "unique_clicks": 5},
@@ -145,11 +148,72 @@ func TestPublicStatsUnwrapsEnvelope(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if res.Summary.TotalClicks != 9 || len(res.Metrics["clicks_by_browser"]) != 1 {
+	if res.Stats.Summary.TotalClicks != 9 || len(res.Stats.Metrics["clicks_by_browser"]) != 1 {
+		t.Fatalf("stats = %+v", res.Stats)
+	}
+	link := res.Link
+	if link.Alias != "launch" || link.ShortURL != "https://spoo.me/launch" || link.Status != "active" || !link.BlockBots {
+		t.Fatalf("link facts = %+v", link)
+	}
+	if res.Generation != "v2" {
+		t.Fatalf("generation = %q", res.Generation)
+	}
+}
+
+// A password rides in a POST body, never the query string (the API
+// ignores query-string passwords so they cannot land in URLs or logs).
+func TestPublicStatsPasswordGoesInPOSTBody(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			t.Errorf("method = %s, want POST with a password", r.Method)
+		}
+		if r.URL.Query().Has("password") {
+			t.Errorf("password leaked into the query string: %v", r.URL.Query())
+		}
+		if r.URL.Query().Get("timezone") != "UTC" {
+			t.Errorf("query params must still ride the URL: %v", r.URL.Query())
+		}
+		body, _ := io.ReadAll(r.Body)
+		if string(body) != `{"password":"hunter22"}` {
+			t.Errorf("body = %s", body)
+		}
+		w.Write([]byte(`{
+			"generation": "v2",
+			"link": {"alias": "secret", "short_url": "https://spoo.me/secret", "status": "active", "password_protected": true, "block_bots": false},
+			"stats": {"summary": {"total_clicks": 3, "unique_clicks": 2}, "metrics": {}}
+		}`))
+	}))
+	defer srv.Close()
+
+	c := NewClient(WithBaseURL(srv.URL))
+	res, err := c.PublicStats(context.Background(), "secret", PublicStatsQuery{
+		Timezone: "UTC",
+		Password: "hunter22",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Link.PasswordProtected || res.Stats.Summary.TotalClicks != 3 {
 		t.Fatalf("res = %+v", res)
 	}
 }
 
+// A wrong password keeps the typed 401 semantics.
+func TestPublicStatsWrongPassword(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("X-Error-Code", "invalid_password")
+		w.WriteHeader(http.StatusUnauthorized)
+		w.Write([]byte(`{"error":"Invalid password","code":"invalid_password"}`))
+	}))
+	defer srv.Close()
+
+	c := NewClient(WithBaseURL(srv.URL))
+	_, err := c.PublicStats(context.Background(), "secret", PublicStatsQuery{Password: "wrong"})
+	if !errors.Is(err, ErrLinkPasswordProtected) {
+		t.Fatalf("err = %v, want ErrLinkPasswordProtected", err)
+	}
+}
+
 func TestExportStreamsFilenameAndBody(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != "/api/v1/export" || r.URL.Query().Get("format") != "xlsx" {

urls.go

@@ -17,9 +17,15 @@ import (
 // seconds and created_at/last_click as ISO strings — all normalized to
 // [Timestamp].
 type URLItem struct {
-	ID           string    `json:"id"`
-	Alias        string    `json:"alias"`
-	LongURL      string    `json:"long_url"`
+	ID      string `json:"id"`
+	Alias   string `json:"alias"`
+	LongURL string `json:"long_url"`
+	// ShortURL is derived client-side (the management wire carries no
+	// short_url): https://<Domain>/<Alias> when the link lives on a
+	// custom domain, else the client's base URL plus the alias. Empty
+	// when Alias is empty. Emoji aliases appear unencoded, matching
+	// the shorten response.
+	ShortURL     string    `json:"-"`
 	CreatedAt    Timestamp `json:"created_at"`
 	LastClick    Timestamp `json:"last_click"`
 	TotalClicks  int       `json:"total_clicks"`
@@ -93,9 +99,23 @@ func (c *Client) ListURLs(ctx context.Context, opts ListURLsOptions) (*URLPage,
 	if err := c.do(ctx, http.MethodGet, "/api/v1/urls", q, nil, &out); err != nil {
 		return nil, err
 	}
+	for i := range out.Items {
+		out.Items[i].ShortURL = c.shortURLFor(out.Items[i])
+	}
 	return &out, nil
 }
 
+// shortURLFor derives an item's public short URL; see URLItem.ShortURL.
+func (c *Client) shortURLFor(item URLItem) string {
+	if item.Alias == "" {
+		return ""
+	}
+	if item.Domain != "" {
+		return "https://" + item.Domain + "/" + item.Alias
+	}
+	return c.base + "/" + item.Alias
+}
+
 // ListURLsAll pages through every link matching opts, lazily fetching
 // pages as the caller ranges. opts.Page picks the starting page (1 when
 // zero); on a fetch error the iterator yields it once and stops:
@@ -137,6 +157,7 @@ func (c *Client) GetURL(ctx context.Context, id string) (*URLItem, error) {
 	if err := c.do(ctx, http.MethodGet, "/api/v1/urls/"+url.PathEscape(id), nil, nil, &out); err != nil {
 		return nil, err
 	}
+	out.ShortURL = c.shortURLFor(out)
 	return &out, nil
 }
 
@@ -157,6 +178,7 @@ func (c *Client) ResolveAlias(ctx context.Context, alias, domain string) (*URLIt
 	if err := c.do(ctx, http.MethodGet, path, nil, nil, &out); err != nil {
 		return nil, err
 	}
+	out.ShortURL = c.shortURLFor(out)
 	return &out, nil
 }
 
@@ -204,7 +226,42 @@ func (c *Client) UpdateURL(ctx context.Context, id string, params UpdateURLParam
 	return &out, nil
 }
 
+// SetURLStatus flips one owned link between ACTIVE and INACTIVE via
+// the dedicated status endpoint. BLOCKED and EXPIRED are server-owned
+// states and not caller-settable.
+func (c *Client) SetURLStatus(ctx context.Context, id, status string) (*UpdatedURL, error) {
+	body := struct {
+		Status string `json:"status"`
+	}{Status: status}
+	var out UpdatedURL
+	path := "/api/v1/urls/" + url.PathEscape(id) + "/status"
+	if err := c.do(ctx, http.MethodPatch, path, nil, body, &out); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}
+
 // DeleteURL permanently deletes one owned link by its url id.
 func (c *Client) DeleteURL(ctx context.Context, id string) error {
 	return c.do(ctx, http.MethodDelete, "/api/v1/urls/"+url.PathEscape(id), nil, nil, nil)
 }
+
+// DomainDeletion reports a delete-by-domain sweep.
+type DomainDeletion struct {
+	Message string `json:"message"`
+	Count   int    `json:"count"`
+	Domain  string `json:"domain"`
+}
+
+// DeleteURLsByDomain deletes every link the account owns on the given
+// custom domain. The server refuses the system default domain, so one
+// call can never wipe the account's spoo.me inventory; the caller must
+// own the domain.
+func (c *Client) DeleteURLsByDomain(ctx context.Context, domain string) (*DomainDeletion, error) {
+	q := url.Values{"domain": {domain}}
+	var out DomainDeletion
+	if err := c.do(ctx, http.MethodDelete, "/api/v1/urls", q, nil, &out); err != nil {
+		return nil, err
+	}
+	return &out, nil
+}