BillingPage: discount code input on checkout flow with validate-and-apply UX (P3)

Adds a "Have a discount code?" toggle on BillingPage that expands to an
input + Apply button. Valid codes show a green applied chip; invalid codes
show a red error with the api's message; network errors show a friendly
fallback. Once applied, the code persists into createCheckout() as
promotion_code so the api can attach it to the Razorpay subscription.

The validate endpoint (POST /api/v1/billing/promotion/validate) isn't on
the api yet — its engine already exists in internal/plans/promotion_test.go.
Until the http handler ships, validatePromotion() falls back on 404 to
three seed codes (TWITTER15 / LAUNCH50 / COMEBACK10) so the upgrade flow
is demo-able end-to-end. Follow-up: api PR adds the handler that calls the
existing plans.validatePromotion engine.

Existing single-arg createCheckout('pro') call sites stay byte-identical —
the second-arg opts only attach when a code is actually applied, so all
209 baseline tests still pass with strict-arg matchers. Adds 19 new tests
(10 BillingPage component, 9 api/index unit).

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

Author: mastermanas805

src/api/index.test.ts

@@ -30,6 +30,7 @@ import {
   fetchStackFamily,
   listDeployments,
   getDeployment,
+  validatePromotion,
 } from './index'
 // §10.21: FIXTURE_BILLING / FIXTURE_INVOICES imports retired. The 503
 // fallback paths in fetchBilling() and listInvoices() were removed —
@@ -347,6 +348,120 @@ describe('createCheckout()', () => {
     const init = m.mock.calls[0][1]
     expect(init.body).toBe(JSON.stringify({ plan: 'team' }))
   })
+
+  // P3: opts.promotion_code only appears in the body when actually passed.
+  it('includes promotion_code in the body when supplied (P3)', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({ ok: true, short_url: 'https://rzp.io/i/p3' }))
+    await createCheckout('pro', { promotion_code: 'TWITTER15' })
+    const init = m.mock.calls[0][1]
+    expect(JSON.parse(init.body as string)).toEqual({
+      plan: 'pro', promotion_code: 'TWITTER15',
+    })
+  })
+
+  it('drops promotion_code from the body when not supplied (P3)', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({ ok: true, short_url: 'https://rzp.io/i/p3' }))
+    await createCheckout('pro')
+    const init = m.mock.calls[0][1]
+    const body = JSON.parse(init.body as string)
+    expect(body).toEqual({ plan: 'pro' })
+    expect('promotion_code' in body).toBe(false)
+  })
+
+  it('drops an empty / whitespace-only promotion_code (P3)', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({ ok: true, short_url: 'https://rzp.io/i/p3' }))
+    await createCheckout('pro', { promotion_code: '   ' })
+    const init = m.mock.calls[0][1]
+    const body = JSON.parse(init.body as string)
+    expect('promotion_code' in body).toBe(false)
+  })
+})
+
+// ─── validatePromotion() (P3) ────────────────────────────────────────────
+// Until api ships POST /api/v1/billing/promotion/validate, this helper
+// falls back to a small set of seed codes on a 404. The mock + fallback
+// path together must:
+//   - return a Promotion shape when the api responds 200
+//   - return the seed Promotion for a known seed code when the api 404s
+//   - throw promotion_not_found for an unknown code when the api 404s
+//   - propagate non-404 errors (e.g. 410 expired) untouched
+describe('validatePromotion() (P3)', () => {
+  it('returns the api Promotion on a 200 response', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({
+      ok: true,
+      code: 'PARTNER25',
+      discount: { kind: 'percent_off', value: 25, applies_to: 6, unit: 'months' },
+      valid_until: '2026-12-31T00:00:00Z',
+    }))
+    const r = await validatePromotion('PARTNER25', 'pro')
+    expect(r.promotion.code).toBe('PARTNER25')
+    expect(r.promotion.discount).toEqual({ kind: 'percent_off', value: 25, applies_to: 6, unit: 'months' })
+    expect(r.promotion.valid_until).toBe('2026-12-31T00:00:00Z')
+  })
+
+  it('POSTs {code, plan} to /api/v1/billing/promotion/validate (uppercased + trimmed)', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse({
+      ok: true,
+      code: 'TWITTER15',
+      discount: { kind: 'percent_off', value: 15, applies_to: 3, unit: 'months' },
+      valid_until: '2026-09-01T00:00:00Z',
+    }))
+    await validatePromotion('  twitter15  ', 'pro')
+    const [url, init] = m.mock.calls[0]
+    expect(String(url)).toContain('/api/v1/billing/promotion/validate')
+    expect(init.method).toBe('POST')
+    expect(JSON.parse(init.body as string)).toEqual({ code: 'TWITTER15', plan: 'pro' })
+  })
+
+  it('falls back to the seed table when the api 404s on a known seed code', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse(
+      { error: 'not_found', message: 'no such route' },
+      { status: 404, statusText: 'Not Found' },
+    ))
+    const r = await validatePromotion('TWITTER15', 'pro')
+    expect(r.promotion.code).toBe('TWITTER15')
+    expect(r.promotion.discount.kind).toBe('percent_off')
+    expect(r.promotion.discount.value).toBe(15)
+  })
+
+  it('throws promotion_not_found on 404 for an unknown code', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse(
+      { error: 'not_found' },
+      { status: 404, statusText: 'Not Found' },
+    ))
+    await expect(validatePromotion('NONEXISTENT', 'pro')).rejects.toMatchObject({
+      status: 404,
+      code: 'promotion_not_found',
+    })
+  })
+
+  it('propagates 410 expired errors with the api message', async () => {
+    const m = installFetch()
+    m.mockResolvedValueOnce(jsonResponse(
+      { error: 'promotion_expired', message: 'This code has expired.' },
+      { status: 410, statusText: 'Gone' },
+    ))
+    await expect(validatePromotion('OLDCODE', 'pro')).rejects.toMatchObject({
+      status: 410,
+      code: 'promotion_expired',
+    })
+  })
+
+  it('rejects with promotion_invalid for an empty input (no api call)', async () => {
+    const m = installFetch()
+    await expect(validatePromotion('   ', 'pro')).rejects.toMatchObject({
+      status: 400,
+      code: 'promotion_invalid',
+    })
+    expect(m).not.toHaveBeenCalled()
+  })
 })
 
 // ─── cancelSubscription() ────────────────────────────────────────────────

src/api/index.ts

@@ -732,14 +732,108 @@ export async function listInvoices(): Promise<{ ok: true; invoices: Invoice[] }>
 
 export async function createCheckout(
   plan: string,
+  opts?: { promotion_code?: string },
 ): Promise<{ ok: true; short_url: string; subscription_id?: string }> {
+  const body: Record<string, unknown> = { plan }
+  // Only include the promotion_code field when the caller actually passed
+  // one — sending an empty string would cause the api to treat it as an
+  // invalid promo and reject the checkout. Trimming guards against UI
+  // whitespace leaks (the dashboard already trims, this is belt+braces).
+  const code = opts?.promotion_code?.trim()
+  if (code) body.promotion_code = code
   const r = await call<{ ok: boolean; short_url: string; subscription_id?: string }>(
     '/api/v1/billing/checkout',
-    { method: 'POST', body: JSON.stringify({ plan }) },
+    { method: 'POST', body: JSON.stringify(body) },
   )
   return { ok: true, short_url: r.short_url, subscription_id: r.subscription_id }
 }
 
+// ─── Promotion validation (P3 — mocked until api ships endpoint) ────────
+//
+// Contract proposed for `POST /api/v1/billing/promotion/validate`:
+//   request:  { code: string, plan: string }
+//   response: { ok: true, code, discount: { kind: "percent_off" | "amount_off"
+//                                          | "free_period",
+//                                          value: number,
+//                                          applies_to?: number,
+//                                          unit?: "months" | "days" },
+//              valid_until: string /* ISO */ }
+//   errors:   404 { error: "promotion_not_found", message: "Code not found." }
+//             410 { error: "promotion_expired",   message: "This code has expired." }
+//             409 { error: "promotion_not_applicable",
+//                   message: "Code can't be applied to this plan." }
+//
+// api/internal/plans/promotion_test.go already has the engine
+// (`plans.validatePromotion(code, plan) (Promotion, error)`) — the missing
+// piece is the HTTP handler. Until that ships, this function transparently
+// falls back to a small in-memory table of three seed codes so the upgrade
+// flow is testable end-to-end. The mock activates on 404 (endpoint not
+// registered) OR on a network error to /api/v1/billing/promotion/validate.
+export type Promotion = {
+  code: string
+  discount: {
+    kind: 'percent_off' | 'amount_off' | 'free_period'
+    value: number
+    applies_to?: number
+    unit?: 'months' | 'days'
+  }
+  valid_until: string
+}
+
+const PROMOTION_SEEDS: Record<string, Promotion['discount']> = {
+  TWITTER15: { kind: 'percent_off', value: 15, applies_to: 3, unit: 'months' },
+  LAUNCH50:  { kind: 'percent_off', value: 50, applies_to: 1, unit: 'months' },
+  COMEBACK10: { kind: 'percent_off', value: 10, applies_to: 1, unit: 'months' },
+}
+
+export async function validatePromotion(
+  code: string,
+  plan: string,
+): Promise<{ ok: true; promotion: Promotion }> {
+  const normalized = code.trim().toUpperCase()
+  if (!normalized) {
+    throw new APIError(400, 'promotion_invalid', 'Enter a code.')
+  }
+  try {
+    const r = await call<{
+      ok: boolean
+      code: string
+      discount: Promotion['discount']
+      valid_until: string
+    }>('/api/v1/billing/promotion/validate', {
+      method: 'POST',
+      body: JSON.stringify({ code: normalized, plan }),
+    })
+    return {
+      ok: true,
+      promotion: { code: r.code, discount: r.discount, valid_until: r.valid_until },
+    }
+  } catch (e: any) {
+    // 404 = endpoint not yet shipped on api → fall back to local seeds so
+    // the upgrade flow is demo-able. Any other status (400/410/409/etc.)
+    // is a real validation error and propagates so the UI can show it.
+    const status = e?.status
+    if (status === 404 || status === undefined || status === 0) {
+      const seed = PROMOTION_SEEDS[normalized]
+      if (!seed) {
+        throw new APIError(404, 'promotion_not_found', 'Code not found.')
+      }
+      return {
+        ok: true,
+        promotion: {
+          code: normalized,
+          discount: seed,
+          // Mocked seeds are valid through 2026-09-01 — matches the spec
+          // example in the P3 brief. Replace with server response once the
+          // endpoint ships.
+          valid_until: '2026-09-01T00:00:00Z',
+        },
+      }
+    }
+    throw e
+  }
+}
+
 export async function cancelSubscription(): Promise<{ ok: true }> {
   await call<{ ok: boolean }>('/api/v1/billing/cancel', { method: 'POST' })
   return { ok: true }