tapimo 0.13.0 → 0.15.0

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

@@ -5,15 +5,18 @@ 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 Cache from '../../../internal/Cache.js'
 import * as Db from '../../../db/Db.js'
 import * as EnabledBillingSources from '../../../db/tables/enabledBillingSources.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 Store from '../../../internal/Store.js'
 import * as StripeCustomers from '../../../db/tables/stripeCustomers.js'
 import * as Viem from '../../../internal/Viem.js'
 import * as core_Billing from '../Billing.js'
+import * as Zones from '../../Zones.js'
 import type { Billing, Environment } from '../App.js'
 
 /** Zod schemas owned by the billing resource. */
@@ -35,6 +38,187 @@ export namespace schema {
     .strictObject({ environment: Schema.Environment })
     .check(z.describe("Query parameters for one organization's billing."))
 
+  const Amount = z
+    .string()
+    .check(
+      z.describe('Stripe amount as a decimal string in USD; negative values are credits.'),
+      z.meta({ examples: ['12.34'] }),
+    )
+
+  /** Stripe's next invoice estimate, or an explicit absence of an account or invoice. */
+  export const InvoicePreview = OpenApi.component(
+    z
+      .union([
+        z.object({
+          amountDue: Amount.check(
+            z.describe('Amount Stripe expects to collect after applying the customer balance.'),
+          ),
+          billingCredits: Amount.check(
+            z.describe('Pretax billing credits applied to this invoice, excluding discounts.'),
+          ),
+          currency: z
+            .literal('usd')
+            .check(z.describe('Invoice currency.'), z.meta({ examples: ['usd'] })),
+          discounts: Amount.check(z.describe('Total discounts applied across invoice lines.')),
+          exclusiveTax: Amount.check(z.describe('Exclusive tax added to the invoice.')),
+          lineItems: z
+            .array(
+              z
+                .object({
+                  amount: Amount,
+                  description: z
+                    .string()
+                    .check(
+                      z.describe('Stripe line description.'),
+                      z.meta({ examples: ['Route Subsidy'] }),
+                    ),
+                  id: z
+                    .string()
+                    .check(
+                      z.describe('Stripe line identifier, valid for this preview.'),
+                      z.meta({ examples: ['il_tmp_1Nzo1ZGgdF1VjufLzD1UUn9R'] }),
+                    ),
+                  kind: z
+                    .nullable(z.enum(['apiRequests', 'feePayerSpend', 'routeSubsidy']))
+                    .check(
+                      z.describe(
+                        'Charge category identified by the Stripe meter, or null for other invoice items.',
+                      ),
+                      z.meta({ examples: ['routeSubsidy'] }),
+                    ),
+                  period: z
+                    .object({
+                      end: z.iso
+                        .datetime()
+                        .check(
+                          z.describe('Inclusive end of this line’s service period.'),
+                          z.meta({ examples: ['2026-10-04T00:00:00.000Z'] }),
+                        ),
+                      start: z.iso
+                        .datetime()
+                        .check(
+                          z.describe('Inclusive start of this line’s service period.'),
+                          z.meta({ examples: ['2026-09-04T00:00:00.000Z'] }),
+                        ),
+                    })
+                    .check(
+                      z.describe('Service dates for this invoice line, as reported by Stripe.'),
+                    ),
+                  priceId: z
+                    .nullable(z.string())
+                    .check(
+                      z.describe('Stripe price identifier, or null when no price is attached.'),
+                      z.meta({ examples: ['price_1NzlYfGgdF1VjufL0cVjLJVI'] }),
+                    ),
+                  product: z
+                    .nullable(
+                      z.object({
+                        id: z
+                          .string()
+                          .check(
+                            z.describe('Stripe product identifier.'),
+                            z.meta({ examples: ['prod_NWjs8kKbJWmuuc'] }),
+                          ),
+                        name: z
+                          .string()
+                          .check(
+                            z.describe('Current customer-facing product name from Stripe.'),
+                            z.meta({ examples: ['Route Subsidy'] }),
+                          ),
+                      }),
+                    )
+                    .check(
+                      z.describe(
+                        'Stripe product for this line, or null when no product is attached.',
+                      ),
+                    ),
+                  quantity: z
+                    .nullable(z.number().check(z.int()))
+                    .check(
+                      z.describe(
+                        'Quantity in Stripe price units, not necessarily a transaction count; null when unavailable.',
+                      ),
+                      z.meta({ examples: [1000] }),
+                    ),
+                  unitAmount: z
+                    .nullable(z.string())
+                    .check(
+                      z.describe(
+                        'Exact decimal unit price in USD, preserving sub-cent precision; null when unavailable.',
+                      ),
+                      z.meta({ examples: ['0.000001'] }),
+                    ),
+                })
+                .check(
+                  z.describe(
+                    'An invoice line before discounts, billing credits, and exclusive taxes.',
+                  ),
+                ),
+            )
+            .check(
+              z.describe('Complete invoice lines in Stripe order.'),
+              z.meta({
+                examples: [
+                  [
+                    {
+                      amount: '12.34',
+                      description: 'Route Subsidy',
+                      id: 'il_tmp_1Nzo1ZGgdF1VjufLzD1UUn9R',
+                      kind: 'routeSubsidy',
+                      period: {
+                        end: '2026-10-04T00:00:00.000Z',
+                        start: '2026-09-04T00:00:00.000Z',
+                      },
+                      priceId: 'price_1NzlYfGgdF1VjufL0cVjLJVI',
+                      product: { id: 'prod_NWjs8kKbJWmuuc', name: 'Route Subsidy' },
+                      quantity: 12_340_000,
+                      unitAmount: '0.000001',
+                    },
+                  ],
+                ],
+              }),
+            ),
+          retrievedAt: z.iso
+            .datetime()
+            .check(
+              z.describe('Time the estimate was read, not a meter aggregation watermark.'),
+              z.meta({ examples: ['2026-09-05T00:00:00.000Z'] }),
+            ),
+          startingBalance: Amount.check(
+            z.describe('Customer balance before this invoice; negative amounts are credit.'),
+          ),
+          status: z
+            .literal('ready')
+            .check(
+              z.describe('A Stripe estimate is available, including zero-valued estimates.'),
+              z.meta({ examples: ['ready'] }),
+            ),
+          taxIncluded: Amount.check(
+            z.describe('Tax already included in invoice line amounts; do not add it again.'),
+          ),
+          total: Amount.check(
+            z.describe(
+              'Stripe invoice total after discounts, billing credits, and taxes, before customer balance adjustments.',
+            ),
+          ),
+        }),
+        z.object({
+          status: z
+            .enum(['no_account', 'no_invoice'])
+            .check(
+              z.describe(
+                'No Stripe billing account exists, or the account has no upcoming managed invoice.',
+              ),
+              z.meta({ examples: ['no_account'] }),
+            ),
+        }),
+      ])
+      .check(
+        z.describe('The organization-wide Stripe invoice preview for the selected environment.'),
+      ),
+    'BillingInvoicePreview',
+  )
+
   /** Path parameters addressing one payment method. */
   export const MethodParams = z
     .object({
@@ -324,6 +508,106 @@ export function billing() {
         }
       },
     )
+    .get(
+      '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing/invoice-preview',
+      Auth.policy({ apiKey: { scopes: ['management:read'] }, 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: 'getBillingInvoicePreview',
+        responses: OpenApi.responses({
+          errors: {
+            400: {
+              codes: ['param_invalid', 'query_invalid'],
+              description: 'Invalid path or query.',
+            },
+            403: {
+              codes: ['forbidden'],
+              description: 'Project credentials cannot read organization financial information.',
+            },
+            404: {
+              codes: ['organization_not_found'],
+              description: 'No accessible organization was found.',
+            },
+            501: {
+              codes: ['billing_unconfigured'],
+              description: 'Stripe is not configured for this environment.',
+            },
+          },
+          success: {
+            description: 'The next managed Stripe invoice estimate.',
+            schema: schema.InvoicePreview,
+          },
+        }),
+        summary: 'Preview billing invoice',
+        tags: ['Billing'],
+      }),
+      async (c) => {
+        if (Auth.narrowAccess) return Auth.accessError(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 principal = Auth.getPrincipal(c)
+        if (principal?.type === 'api_key' && principal.projectId !== undefined)
+          return Response.error(c, {
+            code: 'forbidden',
+            message: 'Requires organization-scoped access',
+            status: 403,
+          })
+        const billing = c.get('billing')
+        const environment = c.req.valid('query').environment
+        const source = billing && stripeFor(billing, environment)
+        if (!source) return billingUnconfigured(c)
+
+        try {
+          const orgId = Auth.org(c).id
+          const record = await StripeCustomers.get(Db.get(c.get('db')), orgId, environment)
+          if (!record) {
+            c.header('Cache-Control', Cache.policies.noStore)
+            return c.json(Response.validated(schema.InvoicePreview, { status: 'no_account' }), 200)
+          }
+          const preview = await Store.memoize(
+            () =>
+              core_Billing.previewInvoice(source.client, {
+                customer: record.stripeCustomerId,
+                environment,
+              }),
+            {
+              key: `billing:invoice:v4:${orgId}:${environment}:${record.stripeCustomerId}`,
+              store: c.get('store'),
+              ttl: 60_000,
+            },
+          )
+          c.header('Cache-Control', Cache.policies.billing)
+          c.header('Vary', 'Accept-Encoding, Authorization, Tempo-API-Key, X-API-Key, Cookie')
+          return c.json(
+            Response.validated(
+              schema.InvoicePreview,
+              preview ? { ...preview, status: 'ready' } : { status: 'no_invoice' },
+            ),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
     .patch(
       '/v1/orgs/:orgId{org_[A-Za-z0-9_-]+}/billing',
       Auth.policy({ apiKey: { scopes: ['management:write'] }, session: true }),
@@ -749,17 +1033,27 @@ export function billing() {
         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 })
+          // Hold the customer lock through detachment and refresh so older
+          // webhook snapshots cannot reactivate billing afterward.
+          const response = await StripeCustomers.withLock(db, {
+            async fn(tx, record) {
+              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(tx, record.orgId, status, environment)
+              await syncKeyBilling(c, { environment, orgId: record.orgId, status })
+              return undefined
+            },
+            stripeCustomerId: record.stripeCustomerId,
+          })
+          if (response) return response
           return c.json(
             Response.validated(schema.Billing, await billingBody(c, org.id, environment)),
             200,
@@ -804,44 +1098,54 @@ export function billing() {
 
         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)
+          // Acquire the lock before reading Stripe and keep it through
+          // provisioning, persistence, and the API-key snapshot update.
+          return await StripeCustomers.withLock(db, {
+            async fn(tx, record) {
+              // Unknown customers ack with 200: other environments may share the
+              // Stripe account, and their events are not ours to fail.
+              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
+              // 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 },
-                })
-            }
-          }
+              // 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,
-              core_Billing.kindsFor(record.environment),
-            )
-          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)
+              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,
+                  core_Billing.kindsFor(record.environment),
+                )
+              await StripeCustomers.setStatus(tx, record.orgId, status, record.environment)
+              await syncKeyBilling(c, {
+                environment: record.environment,
+                orgId: record.orgId,
+                status,
+              })
+              return c.json({ received: true }, 200)
+            },
+            stripeCustomerId: customer,
+          })
         } catch (cause) {
           return Response.upstream(c, cause)
         }
@@ -924,8 +1228,13 @@ const handledEvents: ReadonlySet<Stripe.Event['type']> = new Set([
   'customer.subscription.deleted',
   'customer.subscription.updated',
   'customer.updated',
+  'invoice.finalized',
+  'invoice.marked_uncollectible',
+  'invoice.overdue',
   'invoice.paid',
   'invoice.payment_failed',
+  'invoice.updated',
+  'invoice.voided',
   'payment_method.attached',
   'payment_method.detached',
   'setup_intent.succeeded',
@@ -941,9 +1250,8 @@ function eventCustomer(event: Stripe.Event): string | 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`.
+ * Derives billing eligibility from Stripe customers, subscriptions, outstanding
+ * invoices, and payment methods. Unsettled debt keeps billing past due after cancellation.
  */
 async function deriveStatus(stripe: Stripe, customerId: string): Promise<StripeCustomers.Status> {
   const customer = await stripe.customers.retrieve(customerId)
@@ -951,6 +1259,22 @@ async function deriveStatus(stripe: Stripe, customerId: string): Promise<StripeC
   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'
+  // Cancellation ends subscription delinquency, but its invoices remain owed.
+  // Paginate unpaid invoices so newer invoices cannot hide older debt.
+  for (const status of ['open', 'uncollectible'] as const) {
+    const invoices = stripe.invoices.list({ customer: customerId, limit: 100, status })
+    for await (const invoice of invoices)
+      if (
+        invoice.amount_remaining > 0 &&
+        (status === 'uncollectible' ||
+          invoice.attempted ||
+          // Paused automatic collection has no future due date to protect eligibility.
+          (invoice.collection_method === 'charge_automatically' &&
+            invoice.auto_advance === false) ||
+          (invoice.due_date !== null && invoice.due_date * 1_000 <= Date.now()))
+      )
+        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'
@@ -973,7 +1297,10 @@ async function billingBody(
   // 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],
+    chainIds: Zones.chainIds({
+      sourceId: environment === 'production' ? Viem.chainId.mainnet : Viem.chainId.testnet,
+      zones: c.get('zones').values(),
+    }),
     environment,
     orgId,
     since: core_Billing.periodStart(period),

package/src/apps/management/routes/faucet.test.ts

@@ -68,7 +68,7 @@ test('publishes a generator-ready OpenAPI contract', async () => {
 })
 
 describe('faucet', () => {
-  test('funds a member account and rate limits repeated funding', async () => {
+  test('funds a member account and rate limits repeated routes', async () => {
     const app = createApp()
     const cookie = await session(app)
     const org = await organization(app, cookie)

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

@@ -87,7 +87,7 @@ export namespace schema {
             z.meta({ examples: [[]] }),
           ),
       }),
-      'Test tokens minted while funding the account.',
+      'Test tokens minted while routes the account.',
     ),
     'FundTestnetAccountResponse',
   )