docs: POST /api/valuation — Spotify handle → catalog + value band (chat#1867)

Merged
SW
3mo ago
+133-1

Contract (docs-first)

The consolidated valuation endpoint for chat#1867. One bearer-authed call turns a Spotify artist id into an account-owned catalog + estimated value band — the same pipeline marketing/lib/valuation/runValuationFlow currently orchestrates client-side, moved behind a single shared endpoint so both marketing and chat (onboarding "Claim your catalog") call it.

POST /api/valuation { spotify_artist_id } → resolve releases → capture play counts (spends the account's credits) → materialize a catalog from the snapshot (idempotent — reuses Create Catalog) → return { catalog, band, songs_measured }.

Changes (additive)

  • releases.json: new POST /api/valuation operation + RunValuationRequest / RunValuationResponse schemas. Reuses existing Catalog, ValuationBand, and CatalogSongsErrorResponse schemas (no duplication). Diff is additive (+128/−1); JSON re-validated.
  • New reference page api-reference/songs/valuation-run.mdx + nav entry after Create Catalog.

Documented responses (match the planned handler)

200 catalog + band · 400 missing/invalid spotify_artist_id · 401 unauthorized · 402 insufficient credits · 404 no releases for the artist · 504 measurement not ready in the wait window (retry).

Merge order: docs → api (this leads). The api PR implements this exact contract by composing existing internals (getArtistAlbums → createMeasurementJob → poll album measurements → createCatalogHandler → computeValuationBand).

Tracking: chat#1867.

Summary by cubic

Adds docs for a consolidated valuation endpoint: POST /api/valuation turns a Spotify artist id into an account-owned catalog and an estimated value band. Supports chat#1867 and replaces marketing’s client-side orchestration.

  • New Features
    • OpenAPI: new POST /api/valuation path with RunValuationRequest and RunValuationResponse; reuses Catalog, ValuationBand, and CatalogSongsErrorResponse.
    • Behavior: bearer-auth; resolves releases, captures play counts (spends account credits), materializes the catalog idempotently via Create Catalog; synchronous wait for capture.
    • Docs: added api-reference/songs/valuation-run.mdx and a nav entry. Responses documented: 200, 400 (invalid/missing spotify_artist_id), 401, 402, 404, 504 (retry).

Summary by CodeRabbit

  • New Features
    • Added a valuation API that generates a catalog and returns an estimated value band for a Spotify artist.
    • Added authentication, credit, validation, and timeout response details.
    • Added request and response schemas for valuation requests.
  • Documentation
    • Added a “Run Valuation” API reference page and included it in the Songs documentation navigation.