feat(measurement-jobs): free-tier card gate (setup mode) + instant backfill drain (chat#1796)

[sweetmantech]

Two in-scope refinements to the historical measurement-job path from chat#1796, both TDD.

1. Free-tier card-on-file link (was billing $99/mo)

The card gate was issuing createStripeSession — the paid subscription flow (mode: "subscription" on the $99/mo price, 30-day trial). New createCardOnFileSession uses Stripe Checkout mode: "setup": it collects a card for $0, no subscription, no price/product (so no Stripe dashboard/CLI work). The account saves a payment method and pays only for metered usage via the existing credits system (which auto-recharges off the saved card). Gate now points at it.

2. Instant drain (no 24h wait)

After a historical job enqueues, it now fires start(songstatsBackfillWorkflow) immediately — the same workflow the daily cron runs — so backfill begins right away. Safe by reuse, not new machinery:

• the workflow's getBackfillBudgetStep caps it to the rolling Songstats quota (limit − reserve − 30-day ledger) and stops when dry — the rate-limit lesson is already enforced;
• FOR UPDATE SKIP LOCKED claims prevent double-processing alongside the cron;
• the daily cron stays as the backstop (multi-day draining when capped, retries, orphan reclaim);
• only kicks when something was actually enqueued (all-skipped → no-op); fire-and-forget so a scheduling hiccup can't fail the job.

Testing

26 new/updated unit tests (setup-mode session, gate → setup session, instant-drain trigger fires when enqueued / not when all-skipped). Full research+stripe+workflows suite 453 green; tsc/lint/format clean.

Verify on preview: a cardless key on historical → 402 + a mode:setup ($0) checkout link; and the enqueued tracks should start draining within minutes (budget permitting) rather than next day.

---

Summary by cubic

Add a free‑tier card-on-file gate for historical measurement jobs and start backfills immediately after enqueue. This removes the paid subscription requirement and reduces the wait from up to 24h to minutes.

• New Features
  • Free-tier card gate: use createCardOnFileSession (Stripe Checkout mode: "setup") to save a card for $0. Replaces the subscription checkout; 402 now returns a setup link when no card is on file.
  • Instant backfill: call start(songstatsBackfillWorkflow) right after enqueue. Only when items are enqueued; budget gate and SKIP LOCKED prevent double work; the daily cron remains the backstop.

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
api	Ready	Preview	Jun 16, 2026 3:57pm

[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 38 minutes and 20 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.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

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: 0b270795-1dcf-41a1-9f4d-31a172eafb10

📥 Commits

Reviewing files that changed from the base of the PR and between dfd9004 and 9a0a4ed.

⛔ Files ignored due to path filters (3)

• lib/research/measurement_jobs/__tests__/enqueueHistoricalBackfill.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**
• lib/research/measurement_jobs/__tests__/ensureSongstatsPaymentMethod.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**
• lib/stripe/__tests__/createCardOnFileSession.test.ts is excluded by !**/*.test.*, !**/__tests__/** and included by lib/**

📒 Files selected for processing (3)

• lib/research/measurement_jobs/enqueueHistoricalBackfill.ts
• lib/research/measurement_jobs/ensureSongstatsPaymentMethod.ts
• lib/stripe/createCardOnFileSession.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/measurement-jobs-free-tier-instant-drain

---

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.}

[cubic-dev-ai]

3 issues found across 6 files

Confidence score: 3/5

• In lib/stripe/createCardOnFileSession.ts, metadata is set on the Checkout Session but not forwarded to the SetupIntent (setup_intent_data.metadata), so downstream SetupIntent/webhook logic may lose tenant/user context and mis-associate events after merge — add setup_intent_data: { metadata } before merging to keep behavior aligned with createStripeSession.
• In lib/research/measurement_jobs/enqueueHistoricalBackfill.ts, the code currently awaits start(...) despite the “fire-and-forget” intent, so scheduler slowness or hangs can delay the caller’s success response and make enqueue operations feel unreliable — remove the blocking await (or bound it with timeout/error isolation) to preserve non-blocking behavior.
• In lib/research/measurement_jobs/ensureSongstatsPaymentMethod.ts, the JSDoc still describes a subscription/trial flow while the code now creates a setup-mode card-on-file session, which can mislead future edits and increase regression risk — update the docstring to match the current payment-method-only flow.

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/research/measurement_jobs/ensureSongstatsPaymentMethod.ts">

<violation number="1" location="lib/research/measurement_jobs/ensureSongstatsPaymentMethod.ts:25">
P2: JSDoc still references "subscription + trial" but the call site now uses createCardOnFileSession (mode: "setup", $0, no subscription). Docstring is misleading after this change.</violation>
</file>

<file name="lib/research/measurement_jobs/enqueueHistoricalBackfill.ts">

<violation number="1" location="lib/research/measurement_jobs/enqueueHistoricalBackfill.ts:73">
P2: Comment says "fire-and-forget" but `await start(...)` blocks the response on the workflow-scheduling call. A scheduling delay/hang in `start()` delays the already-successful enqueue result from reaching the caller.</violation>
</file>

<file name="lib/stripe/createCardOnFileSession.ts">

<violation number="1" location="lib/stripe/createCardOnFileSession.ts:28">
P2: Missing setup_intent_data: { metadata } — the session-level metadata is set but not propagated to the SetupIntent sub-resource, unlike createStripeSession which propagates metadata via subscription_data. Any future webhook on setup_intent events won't have accountId.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Client
    participant API as POST /measurements/jobs
    participant Gate as ensureSongstatsPaymentMethod
    participant Stripe as Stripe Checkout
    participant Enqueuer as enqueueHistoricalBackfill
    participant DB as Supabase (Backfill Queue)
    participant Temporal as Temporal Workflow
    participant Workflow as songstatsBackfillWorkflow
    participant Cron as Daily Cron (backstop)

    Note over Client,Cron: NEW: Free-tier card gate (setup mode) + instant drain

    Client->>API: POST /measurements/jobs (source=historical)
    API->>Gate: ensureSongstatsPaymentMethod(accountId)

    alt No payment method on file
        Gate->>Stripe: NEW: createCardOnFileSession (mode=setup, $0, no subscription)
        Stripe-->>Gate: session URL (free-tier checkout)
        Gate-->>API: 402 + checkout_link
        API-->>Client: 402 (prompt to save card)
    else Payment method exists
        Gate-->>API: null (proceed)
    end

    Note over API,Workflow: Instant backfill drain (only when items enqueued)

    API->>Enqueuer: enqueueHistoricalBackfill(data)
    Enqueuer->>DB: upsertSongstatsBackfillQueue(batch)
    DB-->>Enqueuer: success

    alt enqueued > 0
        Enqueuer->>Temporal: NEW: start(songstatsBackfillWorkflow)  (fire-and-forget)
        Temporal-->>Enqueuer: ack
    else enqueued === 0
        Enqueuer->>Enqueuer: no-op (no drain kicked)
    end

    Enqueuer-->>API: { enqueued, skipped }
    API-->>Client: 200 (job accepted)

    Note over Temporal,Cron: Workflow execution (budget-gated, SKIP LOCKED)
    Temporal->>Workflow: execute
    Workflow->>DB: fetch next batch (FOR UPDATE SKIP LOCKED)
    DB-->>Workflow: rows
    Workflow->>Workflow: getBackfillBudgetStep (limit - reserve - 30d ledger)
    alt budget remaining
        Workflow->>Stripe: fetch Songstats data
        Workflow->>DB: update measurements
    else budget exhausted
        Workflow->>Workflow: stop (cron will resume later)
    end

    Cron->>Cron: daily run (backstop for leftovers, retries, orphan reclaim)

Loading

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: JSDoc still references "subscription + trial" but the call site now uses createCardOnFileSession (mode: "setup", $0, no subscription). Docstring is misleading after this change.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/research/measurement_jobs/ensureSongstatsPaymentMethod.ts, line 25:

<comment>JSDoc still references "subscription + trial" but the call site now uses createCardOnFileSession (mode: "setup", $0, no subscription). Docstring is misleading after this change.</comment>

<file context>
@@ -22,7 +22,10 @@ export async function ensureSongstatsPaymentMethod(
   if (paymentMethod) return null;
 
-  const session = await createStripeSession(accountId, CREDIT_AUTO_RECHARGE_FALLBACK_SUCCESS_URL);
+  const session = await createCardOnFileSession(
+    accountId,
+    CREDIT_AUTO_RECHARGE_FALLBACK_SUCCESS_URL,
</file context>

[cubic-dev-ai]

P2: Comment says "fire-and-forget" but await start(...) blocks the response on the workflow-scheduling call. A scheduling delay/hang in start() delays the already-successful enqueue result from reaching the caller.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/research/measurement_jobs/enqueueHistoricalBackfill.ts, line 73:

<comment>Comment says "fire-and-forget" but `await start(...)` blocks the response on the workflow-scheduling call. A scheduling delay/hang in `start()` delays the already-successful enqueue result from reaching the caller.</comment>

<file context>
@@ -61,5 +63,18 @@ export async function enqueueHistoricalBackfill(
+  // forget — a scheduling hiccup must not fail the (already-enqueued) job.
+  if (enqueued > 0) {
+    try {
+      await start(songstatsBackfillWorkflow);
+    } catch (error) {
+      console.error("[measurement-jobs] failed to kick backfill drain:", error);
</file context>

[cubic-dev-ai]

P2: Missing setup_intent_data: { metadata } — the session-level metadata is set but not propagated to the SetupIntent sub-resource, unlike createStripeSession which propagates metadata via subscription_data. Any future webhook on setup_intent events won't have accountId.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/stripe/createCardOnFileSession.ts, line 28:

<comment>Missing setup_intent_data: { metadata } — the session-level metadata is set but not propagated to the SetupIntent sub-resource, unlike createStripeSession which propagates metadata via subscription_data. Any future webhook on setup_intent events won't have accountId.</comment>

<file context>
@@ -0,0 +1,31 @@
+    mode: "setup",
+    currency: "usd",
+    client_reference_id: accountId,
+    metadata,
+    success_url: successUrl,
+  });
</file context>

[sweetmantech]

Preview verification (head 9a0a4ed9, api-88ij2efwd-recoup.vercel.app)

✅ Change 2 — instant drain: verified live

Enqueued an un-backfilled track (USA2P2015956) via POST /measurement-jobs {source:"historical"} → 202 {enqueued:1}, and the backfill ran immediately, not next-day:

t	event
16:10:11	enqueue (202)
16:10:21	queue row → done (~10 s later); 1,827 songstats rows written

• Songstats quota ledger 4 → 5 (exactly one hit — budget gate respected).
• 0 other pending rows beforehand, so only the enqueued track drained (SKIP LOCKED + budget gate behaving). Side effect: that track is now genuinely backfilled (kept — it's real data, 1 quota hit).

⚠️ Change 1 — free-tier setup link: unit-verified, couldn't mint a live link on preview

The gate fires correctly (carded key → 202, gate passes). To see the 402 + setup-mode link I need a cardless account that authenticates on the preview, and I can't get one here: prod-minted keys 401 on the preview (separate auth env), preview agents/signup returns 500 (pre-existing), and the provided test key is carded.

So Change 1 is verified by unit test (createCardOnFileSession → mode:"setup", no subscription / no line_items). To eyeball the live link, hit this preview with any cardless key:

curl -X POST "https://api-88ij2efwd-recoup.vercel.app/api/research/measurement-jobs" \
  -H "x-api-key: <CARDLESS_KEY>" -H "Content-Type: application/json" \
  -d '{"scope":{"album_ids":["70Zkfb99ladZ3q0JVg97co"]},"source":"historical"}'

→ 402 with a checkoutUrl that should now open a $0 "save card" (setup) page, not the $99/mo subscription. (On prod today the link is still the old $99 one until this PR promotes.)

[sweetmantech]

✅ Both changes verified live (prod, after #672 promotion)

Change 1 — free-tier setup link: generated the prod link from a fresh cardless agent key and opened it in a browser. It renders the Stripe mode:"setup" page — heading "Save payment information", a "Save" button, and "…allow Recoupable, LLC to charge you for future payments…" — with no $99/mo, no trial, no charge. The old subscription checkout is gone.

Change 2 — instant drain: (verified on preview) enqueue → queue row done in ~10 s, 1,827 history rows written, one quota hit — no 24h wait, budget respected.

Both are now on main (prod) via #672.