feat: POST /api/catalogs (create + materialize from valuation snapshot)

[sweetmantech]

What

Implements POST /api/catalogs per the contract in recoupable/docs#243. Creates a catalog owned by the authenticated account, and optionally materializes it from a completed valuation snapshot — closing the "catalog empty after sign-in" gap from recoupable/chat#1801 (Phase 2).

• Account from credentials, never the body. validateAuthContext resolves the owner from the Privy bearer JWT or x-api-key. No account_id is read from the request → no IDOR.
• from.snapshot_id materialization. Verifies the snapshot is owned by the caller (403 otherwise), then creates the catalogs row, links account_catalogs, adds the snapshot's measured ISRCs as catalog_songs, and records the catalog on the snapshot.
• Idempotent. The snapshot's existing catalog FK is the dedupe key — re-claiming returns the catalog already created for that run (songs_added: 0), no duplicates. No DB migration needed (the column already exists).

Contract

POST /api/catalogs → { name?, from?: { snapshot_id } } (≥1 required)

• 200 → { status, catalog, songs_added } (also the idempotent re-claim response)
• 400 neither name nor from / bad snapshot_id · 401 unauth · 403 snapshot owned by another account · 404 snapshot not found

TDD

Red → green, one unit at a time:

• validateCreateCatalogBody — 6 tests (name-only, from-only, both, empty→400, bad uuid→400, null→400)
• createCatalogHandler — 8 tests (validator/auth short-circuits, plain create, materialize happy path, 404, 403, idempotent re-claim, generic 500)

SRP: one exported fn/file. New supabase wrappers (insertCatalog, selectCatalogById, insertAccountCatalog, updateSnapshotCatalog) mirror the existing insertCatalogSongs style; materializeSnapshotCatalog extracted from the handler.

pnpm exec vitest run lib/catalog → 24 passed. eslint clean on all new files. tsc --noEmit: my files type-clean (pre-existing unrelated __tests__ type-drift in lib/tasks/lib/trigger/etc. is unchanged by this PR; next build excludes test files).

Merge order

docs#243 (contract) first, then this. Verification against the preview to follow in a comment.

🤖 Generated with Claude Code

---

Summary by cubic

Adds POST /api/catalogs to create a catalog for the authenticated account, with optional materialization from a valuation snapshot via the snapshot field. Returns the catalog and songs_added; re-claiming a snapshot is idempotent.

• New Features

  • Auth via credentials (Privy bearer JWT or x-api-key); no account_id in the body.
  • Materialize from an owned snapshot: create catalogs, link account_catalogs, load measured ISRCs from song_measurements into catalog_songs, and record the catalog on the snapshot.
  • Defaults to "Valuation Catalog" when name isn’t provided; CORS OPTIONS added.

• Refactors

  • Flattened request body to { name?, snapshot? } to match the merged contract.
  • Reused shared successResponse; renamed to createSnapshotCatalog; replaced a redundant update helper with updatePlaycountSnapshot.
  • Reused selectSongMeasurements with a new snapshot filter (dropped the dedicated helper) and deduped ISRCs before insert.

^{Written for commit b7e49ba. Summary will update on new commits.}

Summary by CodeRabbit

• New Features
  • Users can now create new catalogs with optional custom names through a dedicated API endpoint.
  • Support for creating catalogs from existing playcount snapshots, with automatic linking of measured songs from those snapshots to the new catalog.
  • Implemented comprehensive request validation and error handling to ensure proper data submission for catalog creation operations.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Ready	Preview	Jun 18, 2026 7:54pm

[coderabbitai]

Warning

Review limit reached

@sweetmantech, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 52 minutes and 7 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2ba1cc55-39ad-41ad-a63a-e748a11d3b6c

📥 Commits

Reviewing files that changed from the base of the PR and between 66c61b0 and b7e49ba.

⛔ Files ignored due to path filters (1)

• lib/catalog/__tests__/createSnapshotCatalog.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**

📒 Files selected for processing (2)

• lib/catalog/createSnapshotCatalog.ts
• lib/supabase/song_measurements/selectSongMeasurements.ts

📝 Walkthrough

Walkthrough

Adds a new POST /api/catalogs Next.js API route. The route supports two catalog creation paths: a direct creation (by name) and snapshot-driven materialization that reads ISRCs from song_measurements, inserts catalog_songs, and updates the snapshot record. Idempotent re-claim is handled when a snapshot already references an existing catalog. A Zod validator enforces that at least one of name or snapshot is present in the request body.

Changes

POST /api/catalogs endpoint

Layer / File(s)	Summary
Request body validation schema lib/catalog/validateCreateCatalogBody.ts	Defines createCatalogBodySchema (Zod, optional name and snapshot, at least one required), exports CreateCatalogBody type, and implements validateCreateCatalogBody returning a CORS-enabled 400 on failure or the typed body on success.
Supabase data-access helpers lib/supabase/catalogs/insertCatalog.ts, lib/supabase/account_catalogs/insertAccountCatalog.ts, lib/supabase/catalogs/selectCatalogById.ts, lib/supabase/song_measurements/selectSnapshotIsrcs.ts	Four new helpers: insert a catalog row, link account↔catalog, look up a catalog by id, and fetch distinct ISRCs from song_measurements for a given snapshot.
Snapshot catalog materialization lib/catalog/createSnapshotCatalog.ts	createSnapshotCatalog creates a catalog, links it to the account, conditionally inserts catalog_songs rows from the snapshot's ISRCs, updates the snapshot's catalog reference, and returns { catalog, songsAdded }.
Request handler logic lib/catalog/createCatalogHandler.ts	Parses JSON, validates body and auth, branches on snapshot presence: direct creation returns songs_added: 0; snapshot path enforces 404/403 ownership, performs idempotent re-claim if snapshot already has a catalog, otherwise calls createSnapshotCatalog. Errors are caught and returned as 500.
Next.js route wiring app/api/catalogs/route.ts	Exports OPTIONS (CORS preflight, 200) and POST (delegates to createCatalogHandler) handlers.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant CatalogsRoute as app/api/catalogs
  participant createCatalogHandler
  participant validateCreateCatalogBody
  participant validateAuthContext
  participant createSnapshotCatalog
  participant Supabase

  Client->>CatalogsRoute: POST /api/catalogs
  CatalogsRoute->>createCatalogHandler: forward request
  createCatalogHandler->>validateCreateCatalogBody: parse + validate body
  validateCreateCatalogBody-->>createCatalogHandler: 400 or CreateCatalogBody
  createCatalogHandler->>validateAuthContext: resolve accountId
  validateAuthContext-->>createCatalogHandler: 401 or accountId

  alt No snapshot in body
    createCatalogHandler->>Supabase: insertCatalog(name)
    createCatalogHandler->>Supabase: insertAccountCatalog(accountId, catalog)
    createCatalogHandler-->>Client: 200 {catalog, songs_added: 0}
  else Snapshot provided
    createCatalogHandler->>Supabase: selectPlaycountSnapshots(snapshotId)
    Supabase-->>createCatalogHandler: snapshot row or null
    createCatalogHandler-->>Client: 404 (not found) / 403 (wrong account)
    alt Snapshot already has catalog
      createCatalogHandler->>Supabase: selectCatalogById(snapshot.catalog)
      createCatalogHandler-->>Client: 200 existing catalog
    else No catalog yet
      createCatalogHandler->>createSnapshotCatalog: accountId + snapshot + name?
      createSnapshotCatalog->>Supabase: insertCatalog + insertAccountCatalog
      createSnapshotCatalog->>Supabase: selectSnapshotIsrcs(snapshotId)
      createSnapshotCatalog->>Supabase: insert catalog_songs + updatePlaycountSnapshot
      createSnapshotCatalog-->>createCatalogHandler: {catalog, songsAdded}
      createCatalogHandler-->>Client: 200 {catalog, songs_added}
    end
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Close the valuation → onboarding loop: cross-subdomain Privy auth + materialize valuation as catalog + authenticated /catalogs handoff chat#1801 — The changes directly implement the POST /api/catalogs endpoint with snapshot materialization and idempotent catalog creation logic described in that issue.

Poem

A catalog blooms from a snapshot's seed,
With ISRCs fetched at idempotent speed,
Zod guards the gate, auth checks the key,
403, 404, or a bright 200 — free!
Clean helpers compose, each single in role,
SOLID and tidy, the endpoint is whole. 🎵

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Solid & Clean Code	⚠️ Warning	PR has good SRP (file-function naming, appropriate lengths, consistent patterns) but fails Clean Code error handling: selectSnapshotIsrcs returns [] on failure (masking errors), and multi-step writ...	Fix selectSnapshotIsrcs to throw on query errors instead of returning []. Wrap createSnapshotCatalog writes in a transaction or implement rollback logic to prevent partial state on failure.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/create-catalog-endpoint

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sweetmantech]

Preview verification

Tested against the preview built from this PR's HEAD (c2c0b63) → https://api-cflbqby4n-recoup.vercel.app.

#	Case	Request	Documented	Actual	✓
1	CORS preflight	OPTIONS /api/catalogs	200	200	✅
2	Neither name nor from	POST {}	400	400 "Provide at least one of name or from"	✅
3	Invalid snapshot_id	POST {"from":{"snapshot_id":"not-a-uuid"}}	400	400 "snapshot_id must be a valid UUID"	✅
4	No credentials	POST {"name":"Test Catalog"}	401	401 "Exactly one of x-api-key or Authorization must be provided"	✅
5	Bad credentials	POST + bogus x-api-key	401	401 "Unauthorized"	✅

Validation runs before auth, so the 400 cases are confirmable without a key. No secret is echoed in any response (case 5 returns a generic "Unauthorized", not the supplied key).

Not exercised live (needs a real credential + owned snapshot)

The authenticated paths — name-only create (200), materialize from from.snapshot_id (200 + songs_added), the 403 (snapshot owned by another account), 404 (snapshot missing), and the idempotent re-claim — are covered by the 8 createCatalogHandler unit tests but were not run against the preview (no API key in my environment, and materialize needs a real snapshot owned by that account). @sweetmantech can validate end-to-end with a real key, or I can if you drop one in.

Docs ↔ API reconciled: the live error envelope, status codes, and the {status, catalog, songs_added} success shape match recoupable/docs#243. One refinement I'll push to the docs PR: the catalog-name fallback when from is supplied without name is the constant "Valuation Catalog" (the snapshot has no artist-name column); marketing passes the display name explicitly.

[cubic-dev-ai]

3 issues found across 10 files

Confidence score: 2/5

• The highest risk is in lib/catalog/createCatalogHandler.ts: the current idempotency check is not concurrency-safe, so two simultaneous claims for the same snapshot can both pass and create duplicate catalogs, leading to data integrity and downstream reconciliation problems—add an atomic claim step (conditional update/transaction) before materialization.
• lib/catalog/materializeSnapshotCatalog.ts can leave partially written catalog state on failure because materialization is not atomic; merging as-is risks inconsistent records that also undermine later idempotent re-claims—wrap the write sequence in a transaction (or equivalent all-or-nothing guard) before merge.
• In lib/supabase/playcount_snapshots/updateSnapshotCatalog.ts, the update path can report success even when no snapshot row exists, which can mask failed operations and make callers believe a catalog was updated when it was not—check affected-row count and return an explicit not-found/error outcome before merging.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lib/catalog/createCatalogHandler.ts">

<violation number="1" location="lib/catalog/createCatalogHandler.ts:66">
P1: Idempotency is not concurrency-safe; concurrent claims of the same snapshot can create duplicate catalogs. Use an atomic claim (conditional update/transaction) before materialization.</violation>
</file>

<file name="lib/catalog/materializeSnapshotCatalog.ts">

<violation number="1" location="lib/catalog/materializeSnapshotCatalog.ts:30">
P1: Materialization is not atomic; partial failures can persist inconsistent state and break idempotent re-claim behavior.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Client as Client
    participant API as POST /api/catalogs
    participant Auth as validateAuthContext
    participant Validator as validateCreateCatalogBody
    participant Handler as createCatalogHandler
    participant DB as Supabase DB

    Note over Client,DB: Catalog Creation Flow (name-only)
    Client->>API: POST /api/catalogs { name: "My Catalog" }
    API->>Handler: createCatalogHandler(request)
    Handler->>Validator: validateCreateCatalogBody(body)
    Validator-->>Handler: { name: "My Catalog" }
    Handler->>Auth: validateAuthContext(request)
    Auth->>Auth: Resolve from Privy JWT or x-api-key
    Auth-->>Handler: { accountId }
    Handler->>DB: insertCatalog("My Catalog")
    DB-->>Handler: catalog row
    Handler->>DB: insertAccountCatalog({ account, catalog })
    DB-->>Handler: ok
    Handler-->>API: 200 { status, catalog, songs_added: 0 }
    API-->>Client: 200 Response

    Note over Client,DB: Materialized from Snapshot Flow
    Client->>API: POST /api/catalogs { from: { snapshot_id } }
    API->>Handler: createCatalogHandler(request)
    Handler->>Validator: validateCreateCatalogBody(body)
    Validator-->>Handler: { from: { snapshot_id } }
    Handler->>Auth: validateAuthContext(request)
    Auth-->>Handler: { accountId }
    Handler->>DB: selectPlaycountSnapshots({ id: snapshotId })
    DB-->>Handler: snapshot row

    alt Snapshot not found
        Handler-->>API: 404 Snapshot not found
    else Snapshot owned by different account
        Handler-->>API: 403 Snapshot belongs to a different account
    else Snapshot already has a catalog (idempotent reclaim)
        Handler->>DB: selectCatalogById(snapshot.catalog)
        DB-->>Handler: existing catalog
        Handler-->>API: 200 { status, catalog, songs_added: 0 }
    else Happy path: owned + unclaimed snapshot
        Handler->>Handler: materializeSnapshotCatalog({ accountId, snapshot, name })
        Handler->>DB: insertCatalog(name ?? "Valuation Catalog")
        DB-->>Handler: new catalog row
        Handler->>DB: insertAccountCatalog({ account, catalog })
        DB-->>Handler: ok
        opt snapshot has ISRCs
            Handler->>DB: insertCatalogSongs(isrcs mapped to catalog)
            DB-->>Handler: ok
        end
        Handler->>DB: updateSnapshotCatalog({ snapshotId, catalogId })
        DB-->>Handler: ok
        Handler-->>Handler: return { catalog, songsAdded }
        Handler-->>API: 200 { status, catalog, songs_added }
    end
    API-->>Client: Response

Loading

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Idempotency is not concurrency-safe; concurrent claims of the same snapshot can create duplicate catalogs. Use an atomic claim (conditional update/transaction) before materialization.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/catalog/createCatalogHandler.ts, line 66:

<comment>Idempotency is not concurrency-safe; concurrent claims of the same snapshot can create duplicate catalogs. Use an atomic claim (conditional update/transaction) before materialization.</comment>

<file context>
@@ -0,0 +1,83 @@
+    }
+
+    // Idempotent re-claim: the run already produced a catalog.
+    if (snapshot.catalog) {
+      const existing = await selectCatalogById(snapshot.catalog);
+      if (existing) {
</file context>

[cubic-dev-ai]

P1: Materialization is not atomic; partial failures can persist inconsistent state and break idempotent re-claim behavior.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/catalog/materializeSnapshotCatalog.ts, line 30:

<comment>Materialization is not atomic; partial failures can persist inconsistent state and break idempotent re-claim behavior.</comment>

<file context>
@@ -0,0 +1,41 @@
+}): Promise<{ catalog: Tables<"catalogs">; songsAdded: number }> {
+  const { accountId, snapshot, name } = params;
+
+  const catalog = await insertCatalog(name ?? DEFAULT_CATALOG_NAME);
+  await insertAccountCatalog({ account: accountId, catalog: catalog.id });
+
</file context>

[sweetmantech]

SRP

• actual: success defined in createCatalogHandler
• required: new lib file for the success function

[sweetmantech]

DRY - we should already have a shared lib for this. reference existing endpoints.

[sweetmantech]

Done in 7de73dd — dropped the inline success() helper and now use the shared successResponse({ catalog, songs_added }) from lib/networking/successResponse.ts (the existing helper, same one the research handlers use). SRP + DRY both addressed.

[sweetmantech]

KISS

• actual: updateSnapshotCatalog
• required: updatePlaycountSnapshot

[sweetmantech]

Done in 7de73dd — turned out there's already a generic updatePlaycountSnapshot(id, fields) in lib/supabase/playcount_snapshots/, so I deleted my redundant updateSnapshotCatalog and reuse that helper: updatePlaycountSnapshot(snapshot.id, { catalog: catalog.id }). DRY win.

[cubic-dev-ai]

2 issues found across 6 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lib/catalog/validateCreateCatalogBody.ts">

<violation number="1" location="lib/catalog/validateCreateCatalogBody.ts:8">
P1: Request schema no longer matches the POST /api/catalogs contract; documented `from.snapshot_id` payloads now 400. Restore `from: { snapshot_id }` validation (or accept both shapes) to avoid breaking existing clients.</violation>
</file>

<file name="lib/catalog/createCatalogHandler.ts">

<violation number="1" location="lib/catalog/createCatalogHandler.ts:42">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**

PR description claims body uses `from.snapshot_id` and function `materializeSnapshotCatalog`, but code uses flat `snapshot` property and `createSnapshotCatalog` — PR description does not match implemented code</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Request schema no longer matches the POST /api/catalogs contract; documented from.snapshot_id payloads now 400. Restore from: { snapshot_id } validation (or accept both shapes) to avoid breaking existing clients.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/catalog/validateCreateCatalogBody.ts, line 8:

<comment>Request schema no longer matches the POST /api/catalogs contract; documented `from.snapshot_id` payloads now 400. Restore `from: { snapshot_id }` validation (or accept both shapes) to avoid breaking existing clients.</comment>

<file context>
@@ -2,27 +2,24 @@ import { NextResponse } from "next/server";
   .object({
     name: z.string().min(1, "name must not be empty").optional(),
-    from: materializationSourceSchema.optional(),
+    snapshot: z.string().uuid("snapshot must be a valid UUID").optional(),
   })
-  .refine(data => data.name !== undefined || data.from !== undefined, {
</file context>

[cubic-dev-ai]

P2: Custom agent: Flag AI Slop and Fabricated Changes

PR description claims body uses from.snapshot_id and function materializeSnapshotCatalog, but code uses flat snapshot property and createSnapshotCatalog — PR description does not match implemented code

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/catalog/createCatalogHandler.ts, line 42:

<comment>PR description claims body uses `from.snapshot_id` and function `materializeSnapshotCatalog`, but code uses flat `snapshot` property and `createSnapshotCatalog` — PR description does not match implemented code</comment>

<file context>
@@ -47,14 +39,13 @@ export async function createCatalogHandler(request: NextRequest): Promise<NextRe
     const { accountId } = authResult;
 
-    if (!validated.from) {
+    if (!validated.snapshot) {
       const catalog = await insertCatalog(validated.name ?? DEFAULT_CATALOG_NAME);
       await insertAccountCatalog({ account: accountId, catalog: catalog.id });
</file context>

[sweetmantech]

Preview verification — re-anchored snapshot contract

Re-tested against the preview built from HEAD (7de73dd) → https://api-7mrswkzi4-recoup.vercel.app. CI on this commit: lint / test / format all green.

#	Case	Request	Expected	Actual	✓
1	CORS preflight	OPTIONS /api/catalogs	200	200	✅
2	Neither field	POST {}	400	400 "Provide at least one of name or snapshot"	✅
3	Invalid snapshot	POST {"snapshot":"not-a-uuid"}	400	400 "snapshot must be a valid UUID", missing_fields:["snapshot"]	✅
4	Old from shape rejected	POST {"from":{"snapshot_id":"<uuid>"}}	400	400 "Provide at least one of name or snapshot"	✅
5	Valid snapshot, no creds	POST {"snapshot":"<uuid>"}	401	401 "Exactly one of x-api-key or Authorization…"	✅
6	name-only, no creds	POST {"name":"Test Catalog"}	401	401 (same)	✅
7	Bad x-api-key	POST + bogus key	401	401 "Unauthorized" (no key echoed)	✅

Key result: case 3 shows the field is now a flat root snapshot (missing_fields:["snapshot"], not ["from","snapshot_id"]), and case 4 confirms the old nested from shape is no longer accepted — both match the merged docs#243 contract. Validation still runs before auth, so the 400s are confirmable without a key; no secret is echoed (case 7).

Not exercised live (needs a real credential + owned snapshot)

The authenticated paths — name-only create (200), materialize from snapshot (200 + songs_added), 403 (snapshot owned by another account), 404 (snapshot missing), and the idempotent re-claim — are covered by the 8 createCatalogHandler unit tests (24 in lib/catalog, all green) but were not run against the preview (no API key in my env; materialize needs a real owned snapshot). Happy to run them end-to-end if you drop a key in.

Also verified the review-fix refactors didn't regress the contract: shared successResponse envelope ({status, catalog, songs_added}) is unchanged in the responses above.

[sweetmantech]

Preview verification — authenticated success path ✅

Followed up on the earlier (validation/auth-rejection only) run by testing the authenticated paths against the preview (https://api-7mrswkzi4-recoup.vercel.app, HEAD 7de73dd), using a Privy Bearer minted from the preview's Privy app.

#	Case	Request	Result
B	Create (success)	POST {"name":"…"} + Bearer	200 {"status":"success","catalog":{"id":"a281df58-…","name":"Preview Verify Catalog 7de73dd","created_at":…,"updated_at":…},"songs_added":0} ✅
C	Catalog is real	GET /api/catalogs/songs?catalog_id=a281df58-…	200 {"status":"success","songs":[],"pagination":{"total_count":0,…}} ✅
D	Snapshot not found	POST {"snapshot":"00000000-…"} + Bearer	404 {"status":"error","error":"Snapshot not found"} ✅
E	Invalid snapshot (authed)	POST {"snapshot":"nope"} + Bearer	400 "snapshot must be a valid UUID", missing_fields:["snapshot"] ✅

Case B is the real success path I was missing before — it exercises the full chain end-to-end: validate → validateAuthContext (Bearer) → insertCatalog → insertAccountCatalog → the shared successResponse envelope (the refactor from the review). The response shape {status, catalog, songs_added} is exactly the merged contract. Case D confirms the authenticated snapshot-lookup branch (selectPlaycountSnapshots → empty → 404).

Still not exercised live (needs a snapshot owned by the test account)

The materialize-with-songs 200 (songs_added > 0 via createSnapshotCatalog), the 403 (snapshot owned by another account), and the idempotent re-claim need a real playcount_snapshots row owned by the authenticated account — the preview test account has none (hence the 404 in D). These three are covered by the createCatalogHandler unit tests (24 green in lib/catalog). I can run them live too if you want me to kick off a measurement-job to mint a snapshot for that account (it spends a research/scrape run).

Note: case B created a real catalog row (a281df58-…) under the preview test account — there's no delete-catalog endpoint, so it's left as a harmless test artifact.

[sweetmantech]

KISS

• actual: selectSnapshotIsrcs
• required: selectSongMeasurements

[sweetmantech]

Done in b7e49ba9 — deleted selectSnapshotIsrcs and instead added an optional snapshot filter to the existing selectSongMeasurements. createSnapshotCatalog now calls selectSongMeasurements({ snapshot: snapshot.id }) and dedupes the ISRCs. 36 tests green.

[sweetmantech]

Full materialize path — tested live (minted a real snapshot)

Minted a real album-scoped snapshot and exercised the materialize + idempotency paths end-to-end. This surfaced — and I fixed — a real bug.

🐞 Bug found & fixed (commit 66c61b0)

createSnapshotCatalog read snapshot.isrcs, but a valuation snapshot is album-scoped (scope:{album_ids}), so that column is null — materialize would link an empty catalog. The measured ISRCs live in song_measurements (snapshot lineage). Fix: new selectSnapshotIsrcs(snapshotId) (distinct song_measurements.song for the snapshot); createSnapshotCatalog now sources from it. TDD: new createSnapshotCatalog.test.ts (3 tests) red→green; lib/catalog 27 pass.

Live test (preview api-grt4b9ggq, commit 66c61b0)

1. POST /api/research/measurement-jobs {source:"current", scope:{album_ids:["3RQQmkQEvNCY4prGKE6oc5"]}} → 202, snapshot_id=0bb34668-…. Capture ran on the preview (Apify) → fresh song_measurements for 23 tracks (Callaita, Tití Me Preguntó, …).
2. Materialize: POST /api/catalogs {"snapshot":"0bb34668-…"} → 200 {catalog:{id:"929814d1-…","Valuation Catalog"}, songs_added:23} ✅ — 23 measured ISRCs upserted as catalog_songs (no error → FK to songs.isrc satisfied).
3. Idempotent re-claim: same POST again → 200, same catalog 929814d1-…, songs_added:0 ✅ (snapshot's catalog FK short-circuits; no duplicate).

So POST /api/catalogs now does its job correctly across create / materialize / idempotent.

⚠️ Separate gap found (NOT this PR's scope) — blocks the issue's GET Done-when

GET /api/catalogs/songs?catalog_id=929814d1-… returns total_count: 0 despite the 23 rows. Cause: selectCatalogSongsWithArtists uses song_artists!inner → accounts!inner, and the valuation-capture pipeline writes songs + song_measurements but no song_artists for these tracks (confirmed: GET /api/songs?isrc=QM6N21919851 also returns 0). So the tracks are real and linked to the catalog, but invisible to both artist-inner-joined read endpoints.

This is outside POST /api/catalogs (which correctly created the catalog_songs). The issue's Done-when "GET /api/catalogs/songs returns the measured tracks" needs a follow-up: either the capture writes song_artists, or the GET endpoints LEFT-join artists so artist-less tracks still surface. Recommend tracking on chat#1801. Happy to take whichever direction you prefer.

Note: this left two test catalogs (a281df58-…, 929814d1-…) + a snapshot under the preview Privy-app account; no delete-catalog endpoint exists to clean them up.

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (2)

lib/catalog/createCatalogHandler.ts (2)

12-12: ⚡ Quick win

Use a single source of truth for the default catalog name.

DEFAULT_CATALOG_NAME is duplicated here and in lib/catalog/createSnapshotCatalog.ts. If one value changes and the other does not, direct creation and snapshot materialization will diverge unexpectedly.

As per coding guidelines, "Use constants for repeated values."

Also applies to: 43-44, 64-68

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/catalog/createCatalogHandler.ts` at line 12, The constant
DEFAULT_CATALOG_NAME is duplicated across createCatalogHandler.ts and
createSnapshotCatalog.ts, which violates the single source of truth principle.
Extract DEFAULT_CATALOG_NAME to a shared constants file (such as
lib/catalog/constants.ts or lib/constants.ts), then import and use this constant
in both createCatalogHandler.ts and createSnapshotCatalog.ts, removing the local
duplicate definitions to ensure consistency across direct creation and snapshot
materialization.

Source: Coding guidelines

---

27-74: ⚡ Quick win

Split createCatalogHandler into smaller branch-specific helpers.

This function currently handles multiple responsibilities in one >20-line unit (parse/validate/auth/direct-create/snapshot flow/response mapping). Extracting the direct-create and snapshot-create paths will make changes safer and easier to reason about.

As per coding guidelines, "Flag functions longer than 20 lines" and "Keep functions small and focused."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/catalog/createCatalogHandler.ts` around lines 27 - 74, The
createCatalogHandler function exceeds 20 lines and handles multiple
responsibilities including direct catalog creation and snapshot-based creation.
Extract the direct-create path (the block starting with "if
(!validated.snapshot)" that calls insertCatalog and insertAccountCatalog) into a
separate helper function like createDirectCatalog. Extract the snapshot-creation
path (the block that validates the snapshot, handles the idempotent re-claim
case, and calls createSnapshotCatalog) into a separate helper function like
createSnapshotBasedCatalog. Refactor the main createCatalogHandler to
orchestrate these helpers after validating the body and auth context, keeping
the main function focused on request/response handling only.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/catalog/createSnapshotCatalog.ts`:
- Around line 33-41: The write sequence in createSnapshotCatalog is not atomic,
meaning if any operation fails after some succeed, you'll have partial data
persisted (orphaned catalog records) and inconsistent state. Wrap all four
database operations (insertCatalog, insertAccountCatalog, insertCatalogSongs,
and updatePlaycountSnapshot) in a single database transaction so that either all
operations complete successfully or all are rolled back if any step fails,
preventing partial catalog creation and duplicate catalog issues on retry.
- Around line 36-43: The selectSnapshotIsrcs function returns an empty array
both when no ISRCs are found and when a query error occurs, making it impossible
to distinguish between a legitimate empty result and a failure. This causes the
code to proceed with updatePlaycountSnapshot and return success even when the
ISRC lookup failed. Modify selectSnapshotIsrcs to throw an error on query
failure instead of silently returning an empty array, or add error handling in
the calling code to catch and propagate query failures before
updatePlaycountSnapshot is called. This ensures that materialization fails when
data retrieval fails rather than treating the failure as an empty successful
catalog.

In `@lib/supabase/song_measurements/selectSnapshotIsrcs.ts`:
- Around line 18-21: The error handling in the selectSnapshotIsrcs function at
the if (error) block is masking failures by returning an empty array instead of
propagating the error. Replace the return statement with a throw statement to
propagate the error up to the handler, allowing it to properly fail the request
rather than continuing with partial or missing data, which would result in
incorrect catalog materialization and false reporting.

---

Nitpick comments:
In `@lib/catalog/createCatalogHandler.ts`:
- Line 12: The constant DEFAULT_CATALOG_NAME is duplicated across
createCatalogHandler.ts and createSnapshotCatalog.ts, which violates the single
source of truth principle. Extract DEFAULT_CATALOG_NAME to a shared constants
file (such as lib/catalog/constants.ts or lib/constants.ts), then import and use
this constant in both createCatalogHandler.ts and createSnapshotCatalog.ts,
removing the local duplicate definitions to ensure consistency across direct
creation and snapshot materialization.
- Around line 27-74: The createCatalogHandler function exceeds 20 lines and
handles multiple responsibilities including direct catalog creation and
snapshot-based creation. Extract the direct-create path (the block starting with
"if (!validated.snapshot)" that calls insertCatalog and insertAccountCatalog)
into a separate helper function like createDirectCatalog. Extract the
snapshot-creation path (the block that validates the snapshot, handles the
idempotent re-claim case, and calls createSnapshotCatalog) into a separate
helper function like createSnapshotBasedCatalog. Refactor the main
createCatalogHandler to orchestrate these helpers after validating the body and
auth context, keeping the main function focused on request/response handling
only.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5795046d-a4ed-4344-ace3-8323f18d36af

📥 Commits

Reviewing files that changed from the base of the PR and between 5472795 and 66c61b0.

⛔ Files ignored due to path filters (3)

• lib/catalog/__tests__/createCatalogHandler.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**
• lib/catalog/__tests__/createSnapshotCatalog.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**
• lib/catalog/__tests__/validateCreateCatalogBody.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**

📒 Files selected for processing (8)

• app/api/catalogs/route.ts
• lib/catalog/createCatalogHandler.ts
• lib/catalog/createSnapshotCatalog.ts
• lib/catalog/validateCreateCatalogBody.ts
• lib/supabase/account_catalogs/insertAccountCatalog.ts
• lib/supabase/catalogs/insertCatalog.ts
• lib/supabase/catalogs/selectCatalogById.ts
• lib/supabase/song_measurements/selectSnapshotIsrcs.ts

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Make the write sequence atomic to prevent partial catalog creation.

Catalog insert, account link insert, song inserts, and snapshot update are independent writes. If a later step fails, earlier rows persist, leaving inconsistent state and allowing duplicate catalogs on retry because the snapshot may remain unclaimed.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/catalog/createSnapshotCatalog.ts` around lines 33 - 41, The write
sequence in createSnapshotCatalog is not atomic, meaning if any operation fails
after some succeed, you'll have partial data persisted (orphaned catalog
records) and inconsistent state. Wrap all four database operations
(insertCatalog, insertAccountCatalog, insertCatalogSongs, and
updatePlaycountSnapshot) in a single database transaction so that either all
operations complete successfully or all are rolled back if any step fails,
preventing partial catalog creation and duplicate catalog issues on retry.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Do not swallow snapshot-measurement query failures.

At Line 18, returning [] on query error turns a backend failure into a false successful materialization path, which can create an incomplete catalog and report songs_added: 0 incorrectly. Throw here so the handler can fail the request instead of persisting partial results.

Suggested fix

   if (error) {
-    console.error("Error fetching snapshot ISRCs:", error);
-    return [];
+    throw new Error(`Failed to fetch snapshot ISRCs: ${error.message}`);
   }

As per coding guidelines, "Handle errors gracefully" means surfacing operational failures instead of silently degrading write-path outcomes.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if (error) {
	console.error("Error fetching snapshot ISRCs:", error);
	return [];
	}
	if (error) {
	throw new Error(`Failed to fetch snapshot ISRCs: ${error.message}`);
	}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/supabase/song_measurements/selectSnapshotIsrcs.ts` around lines 18 - 21,
The error handling in the selectSnapshotIsrcs function at the if (error) block
is masking failures by returning an empty array instead of propagating the
error. Replace the return statement with a throw statement to propagate the
error up to the handler, allowing it to properly fail the request rather than
continuing with partial or missing data, which would result in incorrect catalog
materialization and false reporting.

Source: Coding guidelines

[sweetmantech]

Re-test on latest preview (b7e49ba → api-mh958bc9m)

Re-ran the full matrix after the selectSongMeasurements refactor — all green, including a fresh materialize.

#	Case	Result
1	OPTIONS	200 ✅
2	POST {}	400 "Provide at least one of name or snapshot" ✅
3	POST {"snapshot":"nope"}	400 "snapshot must be a valid UUID" ✅
4	POST {"from":{"snapshot_id":…}} (old shape)	400 rejected ✅
5	name-only, no creds	401 ✅
6	name-only + Bearer	200 {catalog:{id:"94074fa7-…"}, songs_added:0} ✅
7	{"snapshot":"<random uuid>"} + Bearer	404 "Snapshot not found" ✅
8	Idempotent re-claim of already-claimed snapshot	200, same catalog 929814d1-…, songs_added:0 ✅
9	Materialize (fresh) — mint snapshot 45efd92c-… → capture → claim	200 {catalog:{id:"2f06a67d-…","Materialize Re-test b7e49ba"}, songs_added:23} ✅

Case 9 is the key reconfirmation: minted a new album-scoped snapshot, the preview captured 23 tracks into song_measurements, and the claim sourced them through the refactored selectSongMeasurements({ snapshot }) → 23 catalog songs. Create / materialize / idempotent all correct on the latest commit.

Unchanged (separate, still open): GET /api/catalogs/songs still returns total_count: 0 for materialized catalogs — the song_artists!inner join + valuation-captured tracks lacking song_artists. Needs the follow-up discussed earlier; not in this endpoint's scope.

(Left a few more test catalogs/snapshots under the preview account — no delete-catalog endpoint to clean them up.)

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lib/catalog/createSnapshotCatalog.ts">

<violation number="1" location="lib/catalog/createSnapshotCatalog.ts:36">
P1: Materialization can silently succeed with zero songs when measurement query fails. This can permanently claim a snapshot with incomplete catalog data.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Materialization can silently succeed with zero songs when measurement query fails. This can permanently claim a snapshot with incomplete catalog data.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/catalog/createSnapshotCatalog.ts, line 36:

<comment>Materialization can silently succeed with zero songs when measurement query fails. This can permanently claim a snapshot with incomplete catalog data.</comment>

<file context>
@@ -30,7 +33,8 @@ export async function createSnapshotCatalog(params: {
   await insertAccountCatalog({ account: accountId, catalog: catalog.id });
 
-  const isrcs = snapshot.isrcs ?? [];
+  const measurements = await selectSongMeasurements({ snapshot: snapshot.id });
+  const isrcs = [...new Set(measurements.map(m => m.song))];
   if (isrcs.length > 0) {
</file context>