tapimo 0.2.0 → 0.4.0

package/src/apps/management/routes/billing.ts

@@ -0,0 +1,966 @@
+import { type Context, Hono } from 'hono'
+import Stripe from 'stripe'
+import * as z from 'zod/mini'
+
+import * as ApiKeys from '../../../ApiKeys.js'
+import * as Auth from '../../../internal/Auth.js'
+import * as BillingSettings from '../../../db/tables/billingSettings.js'
+import * as Db from '../../../db/Db.js'
+import * as OpenApi from '../../../internal/OpenApi.js'
+import * as Response from '../../../internal/Response.js'
+import * as Schema from '../../../internal/Schema.js'
+import * as SponsoredTransactions from '../../../db/tables/sponsoredTransactions.js'
+import * as StripeCustomers from '../../../db/tables/stripeCustomers.js'
+import * as Viem from '../../../internal/Viem.js'
+import * as core_Billing from '../Billing.js'
+import type { Billing, Environment } from '../App.js'
+
+/** Zod schemas owned by the billing resource. */
+export namespace schema {
+  const OrgId = z
+    .string()
+    .check(
+      z.describe('The organization id (`org_…`).'),
+      z.meta({ examples: ['org_1a2b3c4d5e6f7g8h9j0k1m2n'] }),
+    )
+
+  /** Path parameters addressing one organization's billing. */
+  export const Params = z
+    .object({ orgId: OrgId })
+    .check(z.describe("Path parameters for one organization's billing."))
+
+  /** Query parameters selecting the billing environment. */
+  export const Query = z
+    .strictObject({ environment: Schema.Environment })
+    .check(z.describe("Query parameters for one organization's billing."))
+
+  /** Path parameters addressing one payment method. */
+  export const MethodParams = z
+    .object({
+      methodId: z
+        .string()
+        .check(
+          z.describe('The payment method id (`pm_…`).'),
+          z.meta({ examples: ['pm_1NVChw2eZvKYlo2CHxiM5E2N'] }),
+        ),
+      orgId: OrgId,
+    })
+    .check(z.describe('Path parameters addressing one payment method.'))
+
+  /** A per-period spend limit. */
+  export const SpendLimit = Schema.describe(
+    z.object({
+      amount: z.string().check(
+        // The lookahead rejects zero: a zero limit would refuse all
+        // sponsorship, which `null` (clear) already expresses.
+        z.regex(/^(?!0+(\.0+)?$)\d{1,9}(\.\d{1,2})?$/),
+        z.describe('Limit as a positive decimal string in `currency` units.'),
+        z.meta({ examples: ['250'] }),
+      ),
+      currency: z
+        ._default(z.enum(BillingSettings.currencies), 'usd')
+        .check(
+          z.describe('Currency the limit is denominated in; `usd` only today.'),
+          z.meta({ examples: ['usd'] }),
+        ),
+      period: z
+        ._default(z.enum(BillingSettings.periods), 'month')
+        .check(
+          z.describe('Window the limit applies over; `month` (UTC calendar) only today.'),
+          z.meta({ examples: ['month'] }),
+        ),
+    }),
+    'A per-period spend limit.',
+  )
+
+  /** A per-transaction fee cap. */
+  export const TxFeeLimit = Schema.describe(
+    z.object({
+      amount: z.string().check(
+        // The lookahead rejects zero: a zero cap would refuse every
+        // transaction, which is not a supported configuration.
+        z.regex(/^(?!0+(\.0+)?$)\d{1,9}(\.\d{1,2})?$/),
+        z.describe('Cap as a positive decimal string in `currency` units.'),
+        z.meta({ examples: ['0.50'] }),
+      ),
+      currency: z
+        ._default(z.enum(BillingSettings.currencies), 'usd')
+        .check(
+          z.describe('Currency the cap is denominated in; `usd` only today.'),
+          z.meta({ examples: ['usd'] }),
+        ),
+    }),
+    'A per-transaction fee cap.',
+  )
+
+  /** PATCH body; absent fields stay unchanged, null clears a limit. */
+  export const Patch = Schema.describe(
+    z.object({
+      spendLimit: z
+        .optional(z.nullable(SpendLimit))
+        .check(
+          z.describe('Spend limit per period; absent leaves it unchanged, null removes it.'),
+          z.meta({ examples: [{ amount: '250', currency: 'usd', period: 'month' }] }),
+        ),
+      txFeeLimit: z.optional(z.nullable(TxFeeLimit)).check(
+        z.describe('Per-transaction fee cap; absent leaves it unchanged, null restores the platform default.'), // prettier-ignore
+        z.meta({ examples: [{ amount: '0.50', currency: 'usd' }] }),
+      ),
+    }),
+    'Billing settings to apply.',
+  )
+
+  /** An organization's billing state. */
+  export const Billing = Schema.describe(
+    z.object({
+      spend: z
+        .optional(
+          z.object({
+            amount: z.string().check(
+              z.describe('Committed spend as a decimal string: finalized fees plus in-flight fee caps.'), // prettier-ignore
+              z.meta({ examples: ['12.34'] }),
+            ),
+            currency: z
+              .enum(BillingSettings.currencies)
+              .check(z.describe('Currency of the spend figure.'), z.meta({ examples: ['usd'] })),
+            period: z
+              .enum(BillingSettings.periods)
+              .check(z.describe('Window the figure covers.'), z.meta({ examples: ['month'] })),
+          }),
+        )
+        .check(
+          z.describe('Billable production spend committed in the current window.'),
+          z.meta({ examples: [{ amount: '12.34', currency: 'usd', period: 'month' }] }),
+        ),
+      spendLimit: z
+        .optional(SpendLimit)
+        .check(
+          z.describe('Configured spend limit; absent when the organization has none.'),
+          z.meta({ examples: [{ amount: '250', currency: 'usd', period: 'month' }] }),
+        ),
+      status: z.enum(StripeCustomers.statuses).check(
+        z.describe("Billing status derived from the organization's billing source; `active` opens production fee sponsorship."), // prettier-ignore
+        z.meta({ examples: ['active'] }),
+      ),
+      txFeeLimit: z
+        .optional(TxFeeLimit)
+        .check(
+          z.describe(
+            'Configured per-transaction fee cap; absent when the platform default applies.',
+          ),
+          z.meta({ examples: [{ amount: '0.50', currency: 'usd' }] }),
+        ),
+      updatedAt: z.optional(z.string()).check(
+        z.describe('When the billing status last changed (ISO 8601); absent before first checkout.'), // prettier-ignore
+        z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+      ),
+    }),
+    "An organization's billing state.",
+  )
+
+  /** A hosted Stripe session link. */
+  export const Session = Schema.describe(
+    z.object({
+      url: z
+        .url()
+        .check(
+          z.describe('Hosted Stripe session URL; navigate the browser here.'),
+          z.meta({ examples: ['https://checkout.stripe.com/c/pay/cs_test_a1b2c3'] }),
+        ),
+    }),
+    'A hosted Stripe session link.',
+  )
+
+  /** A payment method on file. */
+  export const PaymentMethod = Schema.describe(
+    z.object({
+      card: z
+        .optional(
+          z.object({
+            brand: z
+              .string()
+              .check(z.describe('Card brand (e.g. `visa`).'), z.meta({ examples: ['visa'] })),
+            expMonth: z
+              .number()
+              .check(z.describe('Expiry month (1-12).'), z.meta({ examples: [12] })),
+            expYear: z.number().check(z.describe('Expiry year.'), z.meta({ examples: [2030] })),
+            last4: z
+              .string()
+              .check(z.describe('Last four digits.'), z.meta({ examples: ['4242'] })),
+          }),
+        )
+        .check(
+          z.describe('Card details; present when `type` is `card`.'),
+          z.meta({ examples: [{ brand: 'visa', expMonth: 12, expYear: 2030, last4: '4242' }] }),
+        ),
+      createdAt: z
+        .string()
+        .check(
+          z.describe('When the method was attached (ISO 8601).'),
+          z.meta({ examples: ['2026-01-01T00:00:00.000Z'] }),
+        ),
+      default: z
+        .boolean()
+        .check(z.describe('Whether invoices charge this method.'), z.meta({ examples: [true] })),
+      id: z
+        .string()
+        .check(
+          z.describe('The payment method id (`pm_…`).'),
+          z.meta({ examples: ['pm_1NVChw2eZvKYlo2CHxiM5E2N'] }),
+        ),
+      provider: z
+        .literal('stripe')
+        .check(
+          z.describe('Payment provider; `stripe` only today.'),
+          z.meta({ examples: ['stripe'] }),
+        ),
+      type: z
+        .string()
+        .check(
+          z.describe('Method type (e.g. `card`, `us_bank_account`).'),
+          z.meta({ examples: ['card'] }),
+        ),
+    }),
+    'A payment method on file.',
+  )
+
+  /** An organization's payment methods. */
+  export const PaymentMethods = Schema.describe(
+    z.object({
+      data: z.array(PaymentMethod).check(z.describe('Payment methods on file, newest first.')),
+    }),
+    "An organization's payment methods.",
+  )
+}
+
+/**
+ * Mounts the billing surface: an organization's billing status. Orgs without
+ * a Stripe billing source read as `none`. Session lane; reads for members.
+ */
+export function billing() {
+  return new Hono<Environment>()
+    .get(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg(),
+      OpenApi.validate('param', schema.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.validate('query', schema.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'getBilling',
+        responses: OpenApi.responses({
+          errors: {
+            404: 'No accessible organization was found for this id.',
+            501: 'Billing is not configured on this deployment.',
+          },
+          success: { description: "The organization's billing state.", schema: schema.Billing },
+        }),
+        summary: 'Get billing',
+        tags: ['Billing'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Check the query parameters and try again.',
+          })
+
+        const billing = c.get('billing')
+        if (!billing) return billingUnconfigured(c)
+        const environment = c.req.valid('query').environment
+        if (!stripeFor(billing, environment)) return billingUnconfigured(c)
+
+        try {
+          return c.json(
+            Response.validated(schema.Billing, await billingBody(c, Auth.org(c).id, environment)),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .patch(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg({ role: 'owner' }),
+      OpenApi.validate('param', schema.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.validate('query', schema.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.validate('json', schema.Patch, {
+        code: 'body_invalid',
+        message: 'Check the request body and try again.',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'updateBilling',
+        responses: OpenApi.responses({
+          errors: {
+            403: 'Requires the owner role.',
+            404: 'No accessible organization was found for this id.',
+            501: 'Billing is not configured on this deployment.',
+          },
+          success: {
+            description: "The organization's updated billing state.",
+            schema: schema.Billing,
+          },
+        }),
+        summary: 'Update billing',
+        tags: ['Billing'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Check the query parameters and try again.',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'body_invalid',
+            message: 'Check the request body and try again.',
+          })
+
+        const billing = c.get('billing')
+        if (!billing) return billingUnconfigured(c)
+        const environment = c.req.valid('query').environment
+        if (!stripeFor(billing, environment)) return billingUnconfigured(c)
+
+        const body = c.req.valid('json')
+        const org = Auth.org(c)
+        const db = Db.get(c.get('db'))
+        try {
+          await BillingSettings.upsert(db, {
+            environment,
+            orgId: org.id,
+            ...(body.spendLimit !== undefined
+              ? body.spendLimit === null
+                ? { spendLimit: null }
+                : {
+                    currency: body.spendLimit.currency,
+                    period: body.spendLimit.period,
+                    spendLimit: body.spendLimit.amount,
+                  }
+              : {}),
+            ...(body.txFeeLimit !== undefined
+              ? body.txFeeLimit === null
+                ? { txFeeLimit: null }
+                : { currency: body.txFeeLimit.currency, txFeeLimit: body.txFeeLimit.amount }
+              : {}),
+          })
+          return c.json(
+            Response.validated(schema.Billing, await billingBody(c, org.id, environment)),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing/stripe/checkout',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg({ role: 'owner' }),
+      OpenApi.validate('param', schema.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.validate('query', schema.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'createStripeCheckout',
+        responses: OpenApi.responses({
+          errors: {
+            403: 'Requires the owner role.',
+            404: 'No accessible organization was found for this id.',
+            501: 'Billing is not configured on this deployment.',
+          },
+          success: {
+            description: 'A Stripe Checkout (setup mode) session for attaching a payment method.',
+            schema: schema.Session,
+          },
+        }),
+        summary: 'Create checkout session',
+        tags: ['Billing'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Check the query parameters and try again.',
+          })
+
+        const billing = c.get('billing')
+        if (!billing) return billingUnconfigured(c)
+        const environment = c.req.valid('query').environment
+        const source = stripeFor(billing, environment)
+        if (!source) return billingUnconfigured(c)
+
+        const { client } = source
+        const org = Auth.org(c)
+        const db = Db.get(c.get('db'))
+        try {
+          const existing = await StripeCustomers.get(db, org.id, environment)
+          const customerId = existing
+            ? existing.stripeCustomerId
+            : await (async () => {
+                const customer = await client.customers.create({
+                  metadata: { orgId: org.id },
+                  name: org.name,
+                })
+                // The insert resolves a concurrent first-checkout race to the
+                // winning row; always use its customer, not the one just made.
+                const record = await StripeCustomers.create(db, {
+                  environment,
+                  orgId: org.id,
+                  stripeCustomerId: customer.id,
+                })
+                return record.stripeCustomerId
+              })()
+          const session = await client.checkout.sessions.create({
+            cancel_url: returnUrl(c, { environment, orgId: org.id, status: 'canceled', stripe: source }), // prettier-ignore
+            // Setup mode with dynamic payment methods requires a currency;
+            // fee-payer spend bills in USD.
+            currency: 'usd',
+            customer: customerId,
+            mode: 'setup',
+            success_url: returnUrl(c, { environment, orgId: org.id, status: 'success', stripe: source }), // prettier-ignore
+          })
+          if (!session.url) return Response.upstream(c, new Error('checkout session has no url'))
+          return c.json(Response.validated(schema.Session, { url: session.url }), 200)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing/stripe/manage',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg({ role: 'owner' }),
+      OpenApi.validate('param', schema.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.validate('query', schema.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'createStripeManage',
+        responses: OpenApi.responses({
+          errors: {
+            403: 'Requires the owner role.',
+            404: 'No accessible organization, or no billing to manage yet.',
+            501: 'Billing is not configured on this deployment.',
+          },
+          success: {
+            description: 'A Stripe billing-portal session for managing payment methods and invoices.', // prettier-ignore
+            schema: schema.Session,
+          },
+        }),
+        summary: 'Create manage session',
+        tags: ['Billing'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Check the query parameters and try again.',
+          })
+
+        const billing = c.get('billing')
+        if (!billing) return billingUnconfigured(c)
+        const environment = c.req.valid('query').environment
+        const source = stripeFor(billing, environment)
+        if (!source) return billingUnconfigured(c)
+
+        const org = Auth.org(c)
+        const db = Db.get(c.get('db'))
+        try {
+          const record = await StripeCustomers.get(db, org.id, environment)
+          if (!record) return billingNotFound(c)
+          const session = await source.client.billingPortal.sessions.create({
+            customer: record.stripeCustomerId,
+            return_url: returnUrl(c, { environment, orgId: org.id, stripe: source }),
+          })
+          return c.json(Response.validated(schema.Session, { url: session.url }), 200)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .get(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing/payment-methods',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg(),
+      OpenApi.validate('param', schema.Params, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.validate('query', schema.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'getBillingPaymentMethods',
+        responses: OpenApi.responses({
+          errors: {
+            404: 'No accessible organization was found for this id.',
+            501: 'Billing is not configured on this deployment.',
+          },
+          success: {
+            description: "The organization's payment methods.",
+            schema: schema.PaymentMethods,
+          },
+        }),
+        summary: 'Get payment methods',
+        tags: ['Billing'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Check the query parameters and try again.',
+          })
+
+        const billing = c.get('billing')
+        if (!billing) return billingUnconfigured(c)
+        const environment = c.req.valid('query').environment
+        const source = stripeFor(billing, environment)
+        if (!source) return billingUnconfigured(c)
+
+        const { client } = source
+        const org = Auth.org(c)
+        const db = Db.get(c.get('db'))
+        try {
+          // Orgs that never checked out simply have no methods yet.
+          const record = await StripeCustomers.get(db, org.id, environment)
+          if (!record) return c.json(Response.validated(schema.PaymentMethods, { data: [] }), 200)
+          const customer = await client.customers.retrieve(record.stripeCustomerId)
+          if (customer.deleted)
+            return c.json(Response.validated(schema.PaymentMethods, { data: [] }), 200)
+          const fallback = customer.invoice_settings.default_payment_method
+          const methods = await client.customers.listPaymentMethods(record.stripeCustomerId, { limit: 100 }) // prettier-ignore
+          return c.json(
+            Response.validated(schema.PaymentMethods, {
+              data: methods.data.map((method) => ({
+                ...(method.card
+                  ? {
+                      card: {
+                        brand: method.card.brand,
+                        expMonth: method.card.exp_month,
+                        expYear: method.card.exp_year,
+                        last4: method.card.last4,
+                      },
+                    }
+                  : {}),
+                createdAt: new Date(method.created * 1000).toISOString(),
+                default: method.id === fallback,
+                id: method.id,
+                provider: 'stripe' as const,
+                type: method.type,
+              })),
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .delete(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing/payment-methods/:methodId{pm_[A-Za-z0-9_-]+}',
+      Auth.policy({ session: true }),
+      Auth.ensureOrg({ role: 'owner' }),
+      OpenApi.validate('param', schema.MethodParams, {
+        code: 'param_invalid',
+        message: 'Check the path parameters and try again.',
+      }),
+      OpenApi.validate('query', schema.Query, {
+        code: 'query_invalid',
+        message: 'Check the query parameters and try again.',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'deleteBillingPaymentMethod',
+        responses: OpenApi.responses({
+          errors: {
+            403: 'Requires the owner role.',
+            404: 'No accessible organization, billing, or payment method for this id.',
+            501: 'Billing is not configured on this deployment.',
+          },
+          success: {
+            description: "The organization's updated billing state.",
+            schema: schema.Billing,
+          },
+        }),
+        summary: 'Remove payment method',
+        tags: ['Billing'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.superAdminAccessError(c)
+        if (Auth.narrowScope) return Auth.ensureOrgError(c)
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'param_invalid',
+            message: 'Check the path parameters and try again.',
+          })
+        if (OpenApi.narrowValidation)
+          return OpenApi.validationError(c, {
+            code: 'query_invalid',
+            message: 'Check the query parameters and try again.',
+          })
+
+        const billing = c.get('billing')
+        if (!billing) return billingUnconfigured(c)
+        const environment = c.req.valid('query').environment
+        const source = stripeFor(billing, environment)
+        if (!source) return billingUnconfigured(c)
+
+        const { client } = source
+        const org = Auth.org(c)
+        const db = Db.get(c.get('db'))
+        try {
+          const record = await StripeCustomers.get(db, org.id, environment)
+          if (!record) return billingNotFound(c)
+          // Scoping the lookup to the org's own list is the ownership check;
+          // ids belonging to other customers read as absent.
+          const methods = await client.customers.listPaymentMethods(record.stripeCustomerId, { limit: 100 }) // prettier-ignore
+          const method = methods.data.find((m) => m.id === c.req.valid('param').methodId)
+          if (!method) return paymentMethodNotFound(c)
+          await client.paymentMethods.detach(method.id)
+          // The metered subscription stays: accrued usage still invoices at
+          // period end, and re-adding a method reuses it.
+          const status = await deriveStatus(client, record.stripeCustomerId)
+          await StripeCustomers.setStatus(db, record.orgId, status, environment)
+          await syncKeyBilling(c, { environment, orgId: record.orgId, status })
+          return c.json(
+            Response.validated(schema.Billing, await billingBody(c, org.id, environment)),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .post(
+      '/stripe/webhook',
+      // Inbound Stripe callback: the signature is the gate; the public quota
+      // only absorbs delivery bursts. Never a partner-facing API route.
+      Auth.policy({
+        apiKey: false,
+        mpp: false,
+        public: { rateLimit: { perMinute: 600 } },
+        session: false,
+      }),
+      OpenApi.describeRoute({ hide: true, summary: 'Stripe webhook' }),
+      async (c) => {
+        const billing = c.get('billing')
+        if (!billing) return billingUnconfigured(c)
+
+        const signature = c.req.header('stripe-signature')
+        if (!signature) return signatureInvalid(c)
+        const payload = await c.req.text()
+        // One endpoint, two secrets: verify against the live secret, then the
+        // sandbox secret. Test and live events are signed by different endpoint
+        // secrets, so try-both is unambiguous; the customer row's environment
+        // (below) picks the client for follow-up calls.
+        const event = await verifyEvent(billing, payload, signature)
+        if (!event) return signatureInvalid(c)
+
+        // Events are triggers, not state carriers: on every handled event the
+        // status re-derives from fetched Stripe truth, so duplicates and
+        // out-of-order delivery are harmless. Unhandled types ack immediately.
+        if (!handledEvents.has(event.type)) return c.json({ received: true }, 200)
+
+        const customer = eventCustomer(event)
+        if (!customer) return c.json({ received: true }, 200)
+
+        const db = Db.get(c.get('db'))
+        try {
+          // Unknown customers ack with 200: other environments may share the
+          // Stripe account, and their events are not ours to fail.
+          const record = await StripeCustomers.getByCustomer(db, customer)
+          if (!record) return c.json({ received: true }, 200)
+
+          // The row's environment picks the mode's client; a sandbox row with
+          // no sandbox source configured acks untouched.
+          const source = stripeFor(billing, record.environment)
+          if (!source) return c.json({ received: true }, 200)
+          const { client } = source
+
+          // A completed setup Checkout promotes its payment method to the
+          // customer default; invoicing charges the default.
+          if (event.type === 'checkout.session.completed') {
+            const session = event.data.object
+            if (session.mode === 'setup' && typeof session.setup_intent === 'string') {
+              const intent = await client.setupIntents.retrieve(session.setup_intent)
+              if (typeof intent.payment_method === 'string')
+                await client.customers.update(customer, {
+                  invoice_settings: { default_payment_method: intent.payment_method },
+                })
+            }
+          }
+
+          const status = await deriveStatus(client, customer)
+          // Provision the metered subscription before persisting `active`, so
+          // the gate never opens (`Billing.status` reads the stored status)
+          // without a subscription to invoice the spend against. A failure
+          // here surfaces as 5xx and Stripe redelivers.
+          if (status === 'active') await core_Billing.ensureSubscription(client, customer)
+          await StripeCustomers.setStatus(db, record.orgId, status, record.environment)
+          await syncKeyBilling(c, { environment: record.environment, orgId: record.orgId, status })
+          return c.json({ received: true }, 200)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+}
+
+/** Web Crypto signature verification; Workers have no Node `crypto` module. */
+const cryptoProvider = Stripe.createSubtleCryptoProvider()
+
+/** Resource environment a billing request targets. */
+type ResourceEnvironment = StripeCustomers.Record['environment']
+
+/** A resolved Stripe billing source: the live bag or the test-mode sandbox bag. */
+type StripeSource = { client: Stripe; consoleUrl?: string | undefined; webhookSecret: string }
+
+/**
+ * Resolves the Stripe source for an environment: the live bag for `production`,
+ * the test-mode `sandbox` bag otherwise. Returns undefined when sandbox billing
+ * is unconfigured, which the caller maps to `billing_unconfigured` (501).
+ */
+function stripeFor(billing: Billing, environment: ResourceEnvironment): StripeSource | undefined {
+  return environment === 'production' ? billing.stripe : billing.stripe.sandbox
+}
+
+/**
+ * Re-stamps `billingActive` onto the org's sandbox key records after a status
+ * change, so the auth throttle reflects the new state without a per-request
+ * billing read. Only sandbox is gated, and re-stamping is a no-op when the KV
+ * store is unconfigured.
+ */
+async function syncKeyBilling(
+  c: Context<Environment>,
+  options: { environment: ResourceEnvironment; orgId: string; status: StripeCustomers.Status },
+): Promise<void> {
+  if (options.environment !== 'sandbox') return
+  const kv = c.get('kv')
+  if (!kv) return
+  await ApiKeys.setBillingActive(kv.store, {
+    active: options.status === 'active',
+    environment: 'sandbox',
+    orgId: options.orgId,
+  })
+}
+
+/**
+ * Verifies a webhook signature against the live secret, then the sandbox
+ * secret; returns the parsed event on the first match, or undefined. The
+ * client instance is irrelevant to verification (the secret is the gate), so
+ * both attempts reuse the live client.
+ */
+async function verifyEvent(
+  billing: Billing,
+  payload: string,
+  signature: string,
+): Promise<Stripe.Event | undefined> {
+  const secrets = [
+    billing.stripe.webhookSecret,
+    ...(billing.stripe.sandbox ? [billing.stripe.sandbox.webhookSecret] : []),
+  ]
+  for (const secret of secrets) {
+    try {
+      return await billing.stripe.client.webhooks.constructEventAsync(
+        payload,
+        signature,
+        secret,
+        undefined,
+        cryptoProvider,
+      )
+    } catch {}
+  }
+  return undefined
+}
+
+/** Event types that funnel into status derivation; everything else acks untouched. */
+const handledEvents: ReadonlySet<Stripe.Event['type']> = new Set([
+  'checkout.session.completed',
+  'customer.deleted',
+  'customer.subscription.deleted',
+  'customer.subscription.updated',
+  'customer.updated',
+  'invoice.paid',
+  'invoice.payment_failed',
+  'payment_method.attached',
+  'payment_method.detached',
+  'setup_intent.succeeded',
+] satisfies Stripe.Event['type'][])
+
+/** Stripe customer id an event concerns; detached payment methods only carry it in `previous_attributes`. */
+function eventCustomer(event: Stripe.Event): string | undefined {
+  const object = event.data.object as { customer?: unknown; id?: string; object?: string }
+  if (object.object === 'customer') return object.id
+  if (typeof object.customer === 'string') return object.customer
+  const previous = event.data.previous_attributes as { customer?: unknown } | undefined
+  return typeof previous?.customer === 'string' ? previous.customer : undefined
+}
+
+/**
+ * Billing status from live Stripe state: deleted customers are `canceled`; an
+ * unpaid metered subscription parks the org at `past_due`; a default payment
+ * method or any attached card is `active`; else `none`.
+ */
+async function deriveStatus(stripe: Stripe, customerId: string): Promise<StripeCustomers.Status> {
+  const customer = await stripe.customers.retrieve(customerId)
+  if (customer.deleted) return 'canceled'
+  const subscriptions = await stripe.subscriptions.list({ customer: customerId, limit: 100 })
+  if (subscriptions.data.some((s) => s.status === 'past_due' || s.status === 'unpaid'))
+    return 'past_due'
+  if (customer.invoice_settings.default_payment_method) return 'active'
+  const methods = await stripe.customers.listPaymentMethods(customerId, { limit: 1, type: 'card' }) // prettier-ignore
+  return methods.data.length > 0 ? 'active' : 'none'
+}
+
+/** Builds the billing response body: source status, configured limits, current-window spend. */
+async function billingBody(
+  c: Context<Environment>,
+  orgId: string,
+  environment: ResourceEnvironment,
+) {
+  const db = Db.get(c.get('db'))
+  const [record, settings] = await Promise.all([
+    StripeCustomers.get(db, orgId, environment),
+    BillingSettings.get(db, orgId, environment),
+  ])
+  const currency = settings?.currency ?? 'usd'
+  const period = settings?.period ?? 'month'
+  // Mirrors the sponsorship gate's scope so the console shows the figure the
+  // limit is enforced against; sandbox spend is testnet, display-only.
+  const spend = await SponsoredTransactions.spend(Db.get(c.get('dbCached')), {
+    chainIds: [environment === 'production' ? Viem.chainId.mainnet : Viem.chainId.testnet],
+    environment,
+    orgId,
+    since: core_Billing.periodStart(period),
+  })
+  return {
+    spend: { amount: core_Billing.fromBaseUnits(spend), currency, period },
+    ...(settings?.spendLimit != null
+      ? { spendLimit: { amount: settings.spendLimit, currency, period } }
+      : {}),
+    status: record?.status ?? 'none',
+    ...(settings?.txFeeLimit != null
+      ? { txFeeLimit: { amount: settings.txFeeLimit, currency } }
+      : {}),
+    ...(record ? { updatedAt: record.updatedAt } : {}),
+  }
+}
+
+/**
+ * Console billing page a Stripe session returns to: the caller's `Origin` when
+ * present, else the configured console URL. Sandbox sessions carry `env=sandbox`
+ * so the full-page Stripe round-trip returns to the same console mode (the
+ * client-side `retainSearchParams` can't survive it); `status` sets `billing`.
+ */
+function returnUrl(
+  c: Context<Environment>,
+  options: {
+    environment: ResourceEnvironment
+    orgId: string
+    status?: 'success' | 'canceled' | undefined
+    stripe: StripeSource
+  },
+) {
+  const { environment, orgId, status, stripe } = options
+  // Origin is safe to trust: SameSite=Lax session cookies never authenticate
+  // cross-site POSTs, so a forged Origin only redirects the caller themselves.
+  const origin = c.req.header('origin')
+  const base = (() => {
+    try {
+      if (origin) return new URL(origin).origin
+    } catch {}
+    return (stripe.consoleUrl ?? 'https://console.tempo.xyz').replace(/\/$/, '')
+  })()
+  const url = new URL(`${base}/${orgId}/billing`)
+  if (environment === 'sandbox') url.searchParams.set('env', 'sandbox')
+  if (status) url.searchParams.set('billing', status)
+  return url.toString()
+}
+
+function signatureInvalid(c: Context<Environment>) {
+  return Response.error(c, {
+    code: 'signature_invalid',
+    message: 'Missing or invalid Stripe signature',
+    status: 400,
+  })
+}
+
+function billingNotFound(c: Context<Environment>) {
+  return Response.error(c, {
+    code: 'billing_not_found',
+    message: 'No billing to manage; attach a payment method first',
+    status: 404,
+  })
+}
+
+function billingUnconfigured(c: Context<Environment>) {
+  return Response.error(c, {
+    code: 'billing_unconfigured',
+    message: 'Billing is not configured on this deployment',
+    status: 501,
+  })
+}
+
+function paymentMethodNotFound(c: Context<Environment>) {
+  return Response.error(c, {
+    code: 'payment_method_not_found',
+    message: 'No payment method was found for this id',
+    status: 404,
+  })
+}