fix(billing): unstub checkout / invoices / cancel — upgrade flow now works (#20)

Before this commit the dashboard's billing surface had three
fixture-only API functions despite the real agent-API endpoints
existing and working:

  createCheckout()      → returned https://rzp.io/p/stub-${plan}
                          (a 404 — no real Razorpay session was
                          created). Clicking "Upgrade to Pro"
                          took customers to a broken URL.
  listInvoices()        → returned FIXTURE_INVOICES regardless of
                          the team's actual subscription.
  handleCancel()        → console.log('not yet wired')

After:

  createCheckout(plan)  → POST /api/v1/billing/checkout on the
                          agent API. Receives a real
                          razorpay-hosted short_url and
                          subscription_id. BillingPage redirects
                          window.location to short_url so the
                          customer completes payment on Razorpay,
                          which fires the subscription.activated
                          webhook back to /razorpay/webhook on the
                          agent API and the team tier elevates
                          via models.UpdatePlanTier +
                          ElevateResourceTiersByTeam.

  listInvoices()        → GET /api/v1/billing/invoices on the
                          agent API. Falls back to fixtures only
                          on 503 (billing_not_configured) so
                          local-dev without Razorpay keys still
                          shows usable data.

  cancelSubscription()  → POST /api/v1/billing/cancel on the
                          agent API. handleCancel re-reads the
                          billing card and surfaces a notice that
                          the downgrade is in flight pending
                          Razorpay's async subscription.cancelled
                          webhook.

fetchBilling() stays partial-fixture: the plan TIER is real (from
/api/v1/whoami via fetchMe), but the next-renewal-date and
payment-method fields are still FIXTURE_BILLING because the agent
API doesn't yet expose a GET /api/v1/billing endpoint that
aggregates this. Open follow-up: add that endpoint to the agent
API, then drop FIXTURE_BILLING from this file entirely.

Verified locally:
  npm run build → 116 HTML + 116 .md mirrors, no errors
  npm test → 26/26 markdown renderer tests pass
  Security scan on the diff: zero secrets, zero cluster
  hostnames, zero customer identifiers

This is the smaller of the two paths I offered:
  ✓ ship the billing unstub now (this PR)
  ⏳ kill dashboard-api as a separate session (~3000 lines of
    dead code in the dashboard-api repo since the frontend talks
    directly to the agent API)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mastermanas805

src/api/index.ts

@@ -396,26 +396,67 @@ export async function deleteCustomDomain(stackSlug: string, id: string): Promise
   )
 }
 
-// ─── Billing (fixture — backend has /api/v1/billing/* but the dashboard
-//     needs a richer shape than today's API exposes) ─────────────────────
+// ─── Billing (LIVE for checkout + invoices; partial-fixture for state) ───
+//
+// fetchBilling   — plan tier is REAL (from /api/v1/whoami). Renewal date,
+//                  payment method, billing email all come from fixtures
+//                  because the agent API doesn't yet expose a GET
+//                  /api/v1/billing endpoint that aggregates this. Open
+//                  follow-up: add the endpoint, then drop FIXTURE_BILLING
+//                  here. See `dashboard/AGENT_API_NOTES.md` for the
+//                  expected shape.
+//
+// listInvoices   — LIVE. Calls GET /api/v1/billing/invoices on the agent
+//                  API; falls back to FIXTURE_INVOICES on 503 (billing
+//                  not configured, e.g. local dev without Razorpay keys)
+//                  so the UI stays usable. Returns an empty list when
+//                  the team has no subscription yet.
+//
+// createCheckout — LIVE. Calls POST /api/v1/billing/checkout, creates a
+//                  real Razorpay subscription, and returns the hosted
+//                  payment short_url. The caller (BillingPage) redirects
+//                  the user to short_url to complete payment. Errors
+//                  propagate as APIError so the page's checkoutErr state
+//                  can surface them inline.
+
 export async function fetchBilling(): Promise<{ ok: true; plan: string; billing: BillingDetails }> {
   try {
     const me = await fetchMe()
-    return fake({ ok: true as const, plan: me.user.tier, billing: FIXTURE_BILLING })
+    return { ok: true as const, plan: me.user.tier, billing: FIXTURE_BILLING }
   } catch {
-    return fake({ ok: true as const, plan: 'hobby', billing: FIXTURE_BILLING })
+    return { ok: true as const, plan: 'hobby', billing: FIXTURE_BILLING }
   }
 }
 
+type InvoicesResp = { ok: boolean; invoices?: Invoice[] }
+
 export async function listInvoices(): Promise<{ ok: true; invoices: Invoice[] }> {
-  return fake({ ok: true as const, invoices: FIXTURE_INVOICES })
+  try {
+    const r = await call<InvoicesResp>('/api/v1/billing/invoices')
+    return { ok: true, invoices: r.invoices ?? [] }
+  } catch (e: any) {
+    // 503 = billing_not_configured (no Razorpay keys in this env). Fall
+    // back to the fixture list so the page renders something usable in
+    // local dev. Any other error propagates so the UI shows a real
+    // failure state.
+    if (e?.status === 503) return { ok: true, invoices: FIXTURE_INVOICES }
+    throw e
+  }
 }
 
-export async function createCheckout(plan: string): Promise<{ ok: true; short_url: string }> {
-  // [FIXTURE] backend /api/v1/billing/checkout exists but currently returns
-  // either a short_url or a 503 when Razorpay is unconfigured. Stubbed for
-  // now so the UI flow is testable in isolation.
-  return fake({ ok: true as const, short_url: `https://rzp.io/p/stub-${plan}` })
+export async function createCheckout(
+  plan: string,
+): Promise<{ ok: true; short_url: string; subscription_id?: string }> {
+  const r = await call<{ ok: boolean; short_url: string; subscription_id?: string }>(
+    '/api/v1/billing/checkout',
+    { method: 'POST', body: JSON.stringify({ plan }) },
+  )
+  return { ok: true, short_url: r.short_url, subscription_id: r.subscription_id }
+}
+
+export async function cancelSubscription(): Promise<{ ok: true }> {
+  await call<{ ok: boolean }>('/api/v1/billing/cancel', { method: 'POST' })
+  return { ok: true }
 }
 
 // ─── Vault (LIVE — listing keys works, value reveal lives on detail) ────

src/pages/BillingPage.tsx

@@ -118,10 +118,22 @@ export function BillingPage() {
     }
   }
 
-  function handleCancel() {
+  async function handleCancel() {
     if (!window.confirm('Cancel your subscription? You will keep access until the end of the current period.')) return
-    // TODO: wire to POST /api/v1/billing/cancel on the server.
-    console.log('cancel: not yet wired to backend')
+    setCheckoutErr(null)
+    try {
+      await api.cancelSubscription()
+      // Razorpay processes the cancellation asynchronously and emits a
+      // subscription.cancelled webhook that downgrades the team. The new
+      // tier won't appear until the next page reload picks up the
+      // updated whoami, so re-read the billing card and tell the user
+      // that the downgrade is in flight.
+      const b = await api.fetchBilling()
+      setBilling(b.billing)
+      window.alert('Cancellation requested. Your tier downgrades when Razorpay finalises (usually within seconds). Refresh the page in a moment.')
+    } catch (e: any) {
+      setCheckoutErr(e?.message ?? 'cancel failed')
+    }
   }
 
   return (