tapimo 0.2.0 → 0.4.0

package/src/apps/{platform → management}/App.ts

@@ -1,14 +1,18 @@
 import { Hono } from 'hono'
+import type Stripe from 'stripe'
 
 import type * as App from '../../App.js'
 import * as Metadata from '../metadata.js'
 
 import { apiKeys } from './routes/api-keys.js'
+import { billing } from './routes/billing.js'
 import { invitations } from './routes/invitations.js'
 import { me } from './routes/me.js'
 import { members } from './routes/members.js'
 import { orgs } from './routes/orgs.js'
 import { projects } from './routes/projects.js'
+import { scopes } from './routes/scopes.js'
+import { usage } from './routes/usage.js'
 
 /**
  * Minimal transactional email sender. Cloudflare deployments wrap the Email
@@ -18,7 +22,7 @@ import { projects } from './routes/projects.js'
 export type Email = {
   /** Console URL embedded in email links (e.g. sign-in URLs). Defaults to the hosted console; self-hosts point it at their own. */
   consoleUrl?: string | undefined
-  /** Sender address for platform emails (e.g. `noreply@tempo.xyz`). */
+  /** Sender address for management emails (e.g. `noreply@tempo.xyz`). */
   from: string
   /** Sends one message. */
   send: (message: Email.Message) => Promise<unknown>
@@ -40,60 +44,91 @@ export declare namespace Email {
   }
 }
 
+/** Billing capability, one bag per billing source; Stripe is the sole source today. */
+export type Billing = {
+  /**
+   * Stripe billing source.
+   */
+  stripe: {
+    /** Constructed Stripe client. */
+    client: Stripe
+    /** Console URL for Checkout/portal return links when the request carries no `Origin`. Defaults to the hosted console. */
+    consoleUrl?: string | undefined
+    /** Test-mode Stripe backing sandbox billing; omit to keep sandbox billing 501. */
+    sandbox?:
+      | {
+          /** Constructed test-mode Stripe client. */
+          client: Stripe
+          /** Test-mode webhook endpoint signing secret (`whsec_…`). */
+          webhookSecret: string
+        }
+      | undefined
+    /** Webhook endpoint signing secret (`whsec_…`). */
+    webhookSecret: string
+  }
+}
+
 /**
- * Request environment for platform routes: the shared app environment plus the
- * `email` sender this group publishes on context. Owned here, not in core
- * `App.Environment`, since email is a platform concern.
+ * Request environment for management routes: the shared app environment plus the
+ * capabilities this group publishes on context (`billing`, `email`). Owned
+ * here, not in core `App.Environment`, since these are management concerns.
  */
 export type Environment = {
   Variables: App.Environment['Variables'] & {
-    /** Transactional email sender for platform emails; undefined when dispatch is disabled. */
+    /** Stripe billing capability; undefined when billing is unconfigured. */
+    billing: Billing | undefined
+    /** Transactional email sender for management emails; undefined when dispatch is disabled. */
     email: Email | undefined
   }
 }
 
 /**
- * The tenant-platform route group: the current user, orgs, projects, members,
+ * The management route group: the current user, orgs, projects, members,
  * invitations, and API-key management. Every route reads its dependencies from
  * request context set by {@link App.create}.
  *
  * The session-auth surface (`/v1/auth/siwe` + `session` capability) is owned by
- * {@link App.create}, so platform routes gate on a session without owning it.
+ * {@link App.create}, so management routes gate on a session without owning it.
  *
  * ```ts
- * App.create(options).route('/', platform())
+ * App.create(options).route('/', management())
  * ```
  */
-export function platform(options: platform.Options = {}) {
+export function management(options: management.Options = {}) {
   const app = new Hono<Environment>()
-    // Publish the transactional email sender for this group's handlers
-    // (invitations read it off context); undefined disables dispatch.
+    // Publish this group's capabilities for handlers; undefined disables each.
     .use('*', async (c, next) => {
+      c.set('billing', options.billing)
       c.set('email', options.email)
       await next()
     })
     .route('/', apiKeys({ enabled: options.apiKeys !== false }))
+    .route('/', billing())
     .route('/', invitations())
     .route('/', me())
     .route('/', members())
     .route('/', orgs())
     .route('/', projects())
+    .route('/', scopes())
+    .route('/', usage())
   return Metadata.attach(app, openapi)
 }
 
-export declare namespace platform {
-  /** Options for the platform route group. */
+export declare namespace management {
+  /** Options for the management route group. */
   type Options = {
     /** Expose the API-key management routes in the OpenAPI document. @default true */
     apiKeys?: boolean | undefined
-    /** Transactional email sender for platform emails (e.g. invitations); omit to disable dispatch — notified flows still work in-product. */
+    /** Stripe billing capability; omit to disable billing routes (501) and keep production sponsorship closed. */
+    billing?: Billing | undefined
+    /** Transactional email sender for management emails (e.g. invitations); omit to disable dispatch — notified flows still work in-product. */
     email?: Email | undefined
   }
 }
 
 /**
- * The OpenAPI metadata this group owns: platform operation tags and the
- * `session` security scheme. Tagged onto the {@link platform} instance so
+ * The OpenAPI metadata this group owns: management operation tags and the
+ * `session` security scheme. Tagged onto the {@link management} instance so
  * `App.create` collects it.
  */
 const openapi = {
@@ -107,22 +142,26 @@ const openapi = {
   },
   tags: [
     { name: 'API Keys', description: 'Credentials for accessing the Tempo API.' },
+    { name: 'Billing', description: 'Organization billing backed by Stripe.' },
     { name: 'Invitations', description: 'Pending organization invitations.' },
     { name: 'Members', description: 'Organization team membership.' },
     { name: 'Organizations', description: 'Teams that own application workspaces and members.' },
     { name: 'Projects', description: 'Application workspaces within an organization.' },
+    { name: 'Usage', description: 'Request and sponsorship usage for organizations.' },
     { name: 'Users', description: 'Users on the Tempo Platform.' },
   ],
   'x-tagGroups': [
     {
-      name: 'Platform API',
+      name: 'Management API',
       tags: [
         'API Keys',
         'Authentication',
+        'Billing',
         'Invitations',
         'Members',
         'Organizations',
         'Projects',
+        'Usage',
         'Users',
       ],
     },

package/src/apps/management/Billing.test.ts

@@ -0,0 +1,530 @@
+import { nanoid } from 'nanoid'
+import type Stripe from 'stripe'
+
+import { postgresUrl } from '../../../test/containers.js'
+import * as ApiKeys from '../../ApiKeys.js'
+import * as Db from '../../db/Db.js'
+import * as RequestUsage from '../../db/tables/requestUsage.js'
+import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
+import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
+import * as Store from '../../internal/Store.js'
+import * as Viem from '../../internal/Viem.js'
+import * as Billing from './Billing.js'
+
+const create = () => Db.postgres({ connectionString: postgresUrl, schema: `t_${nanoid()}` })
+
+/** Baseline billable mainnet sponsorship input; tests override per case. */
+const input = {
+  apiKeyId: 'key_1',
+  billable: true,
+  chainId: Viem.chainId.mainnet,
+  environment: 'production',
+  orgId: 'org_1',
+  projectId: 'prj_1',
+  transaction: `0x76${'cc'.repeat(16)}`,
+} satisfies Omit<SponsoredTransactions.upsert.Input, 'signPayload'>
+
+/** Inserts and finalizes one billable row; `seed` derives a unique sign payload. */
+async function finalized(
+  db: Db.Db,
+  options: { feeAmount: string; orgId?: string; seed: string },
+): Promise<SponsoredTransactions.Record> {
+  const row = await SponsoredTransactions.upsert(db, {
+    ...input,
+    ...(options.orgId ? { orgId: options.orgId } : {}),
+    signPayload: `0x${options.seed.repeat(32)}`,
+  })
+  await SponsoredTransactions.finalize(db, row.id, {
+    feeAmount: options.feeAmount,
+    finalizedAt: new Date().toISOString(),
+  })
+  return row
+}
+
+/** Managed meter/price ids per kind, keyed by lookup key. */
+const priceByLookup: Record<string, string> = {
+  [Billing.meters.apiRequests.lookupKey]: 'price_req',
+  [Billing.meters.feePayerSpend.lookupKey]: 'price_fee',
+}
+const meterByEvent: Record<string, string> = {
+  [Billing.meters.apiRequests.eventName]: 'mtr_req',
+  [Billing.meters.feePayerSpend.eventName]: 'mtr_fee',
+}
+
+/** A stubbed subscription: live status plus which managed kinds it carries as items. */
+type StubSubscription = { items?: readonly Billing.MeterKind[]; status: string }
+
+/**
+ * A Stripe stub covering the reporter/subscription surface: fixtures resolve
+ * per kind, subscriptions carry per-kind items, and meter-event and
+ * item/subscription creation are captured for assertions.
+ */
+function stubStripe(options: {
+  meterEvent?: ((params: { identifier: string }) => void) | undefined
+  subscriptions?: readonly StubSubscription[] | undefined
+}) {
+  const meterEvents: {
+    event_name: string
+    identifier: string
+    payload?: { stripe_customer_id: string; value: string }
+    timestamp?: number
+  }[] = []
+  const subscriptionsCreated: { items: { price: string }[] }[] = []
+  const itemsCreated: { price: string; subscription: string }[] = []
+  const expand = (subscription: StubSubscription) => ({
+    id: `sub_${subscriptionsCreated.length}_${Math.random().toString(36).slice(2, 8)}`,
+    items: {
+      data: (subscription.items ?? ['feePayerSpend']).map((kind) => ({
+        price: { id: priceByLookup[Billing.meters[kind].lookupKey] },
+      })),
+    },
+    status: subscription.status,
+  })
+  const subscriptions = (options.subscriptions ?? []).map(expand)
+  const stripe = {
+    billing: {
+      meterEvents: {
+        create: async (params: {
+          event_name: string
+          identifier: string
+          payload?: { stripe_customer_id: string; value: string }
+          timestamp?: number
+        }) => {
+          options.meterEvent?.(params)
+          meterEvents.push(params)
+          return {}
+        },
+      },
+      meters: {
+        create: async (params: { event_name: string }) => ({
+          event_name: params.event_name,
+          id: meterByEvent[params.event_name] ?? 'mtr_new',
+        }),
+        list: async () => ({
+          data: Object.entries(meterByEvent).map(([event_name, id]) => ({ event_name, id })),
+        }),
+      },
+    },
+    prices: {
+      create: async (params: { lookup_key: string }) => ({
+        id: priceByLookup[params.lookup_key] ?? 'price_new',
+      }),
+      list: async (params: { lookup_keys: string[] }) => ({
+        data: params.lookup_keys
+          .map((key) => priceByLookup[key])
+          .filter(Boolean)
+          .map((id) => ({ id })),
+      }),
+    },
+    subscriptionItems: {
+      create: async (params: { price: string; subscription: string }) => {
+        itemsCreated.push(params)
+        return {}
+      },
+    },
+    subscriptions: {
+      create: async (params: { items: { price: string }[] }) => {
+        subscriptionsCreated.push(params)
+        return {}
+      },
+      list: async () => ({ data: subscriptions }),
+    },
+  }
+  return { itemsCreated, meterEvents, stripe: stripe as never as Stripe, subscriptionsCreated }
+}
+
+describe('periodStart', () => {
+  test('behavior: anchors to the UTC calendar month start', () => {
+    expect(Billing.periodStart('month', new Date('2026-03-15T12:34:56.789Z'))).toBe('2026-03-01T00:00:00.000Z') // prettier-ignore
+  })
+
+  test('behavior: month boundaries, year rollovers, and leap years resolve in UTC', () => {
+    expect(Billing.periodStart('month', new Date('2025-12-31T23:59:59.999Z'))).toBe('2025-12-01T00:00:00.000Z') // prettier-ignore
+    expect(Billing.periodStart('month', new Date('2026-01-01T00:00:00.000Z'))).toBe('2026-01-01T00:00:00.000Z') // prettier-ignore
+    expect(Billing.periodStart('month', new Date('2028-02-29T10:00:00.000Z'))).toBe('2028-02-01T00:00:00.000Z') // prettier-ignore
+    // A UTC month starts while western timezones still sit in the prior one.
+    expect(Billing.periodStart('month', new Date('2026-07-01T03:00:00.000Z'))).toBe('2026-07-01T00:00:00.000Z') // prettier-ignore
+  })
+})
+
+describe('toBaseUnits', () => {
+  test('behavior: round-trips decimal strings through fee-token base units', () => {
+    expect(Billing.toBaseUnits('0.35')).toBe(350_000n)
+    expect(Billing.toBaseUnits('250')).toBe(250_000_000n)
+    expect(Billing.fromBaseUnits(350_000n)).toBe('0.35')
+    expect(Billing.fromBaseUnits(250_000_000n)).toBe('250')
+  })
+})
+
+describe('status', () => {
+  test('behavior: reflects the stored billing source status', async () => {
+    const db = create()
+    await db.migrate()
+    expect(await Billing.status(db, 'org_1')).toBeUndefined()
+    expect(await Billing.active(db, 'org_1')).toBe(false)
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    await StripeCustomers.setStatus(db, 'org_1', 'past_due')
+    expect(await Billing.status(db, 'org_1')).toBe('past_due')
+    expect(await Billing.active(db, 'org_1')).toBe(false)
+    await StripeCustomers.setStatus(db, 'org_1', 'active')
+    expect(await Billing.active(db, 'org_1')).toBe(true)
+    await db.close()
+  })
+})
+
+describe('createReporter', () => {
+  test('behavior: a poisoned row never stalls the queue', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    const poison = await finalized(db, { feeAmount: '100000', seed: '01' })
+    const good = await finalized(db, { feeAmount: '250000', seed: '02' })
+
+    const { stripe } = stubStripe({
+      meterEvent: (params) => {
+        if (params.identifier === poison.id) throw new Error('boom')
+      },
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    const reporter = Billing.createReporter({ db, stripe })
+    expect(await reporter.tick()).toStrictEqual({ failed: 1, reported: 1, skipped: 0 })
+    // The good row marked; the poisoned row stays unmarked for retry.
+    expect((await SponsoredTransactions.get(db, good.id))?.meterReportedAt).not.toBeNull()
+    expect((await SponsoredTransactions.get(db, poison.id))?.meterReportedAt).toBeNull()
+    expect(await reporter.tick()).toStrictEqual({ failed: 1, reported: 0, skipped: 0 })
+    await db.close()
+  })
+
+  test('behavior: canceled customers skip without meter events', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    await StripeCustomers.setStatus(db, 'org_1', 'canceled')
+    const row = await finalized(db, { feeAmount: '100000', seed: '03' })
+
+    const { meterEvents, stripe } = stubStripe({ subscriptions: [{ status: 'active' }] })
+    expect(await Billing.createReporter({ db, stripe }).tick()).toStrictEqual({
+      failed: 0,
+      reported: 0,
+      skipped: 1,
+    })
+    expect(meterEvents).toHaveLength(0)
+    // Skipped rows still mark: nobody remains to invoice, ever.
+    expect((await SponsoredTransactions.get(db, row.id))?.meterReportedAt).not.toBeNull()
+    await db.close()
+  })
+
+  test('behavior: ensures the metered subscription once and stamps its backlog at now', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    await finalized(db, { feeAmount: '100000', seed: '04' })
+    await finalized(db, { feeAmount: '250000', seed: '05' })
+
+    const { meterEvents, stripe, subscriptionsCreated } = stubStripe({ subscriptions: [] })
+    expect(await Billing.createReporter({ db, stripe }).tick()).toStrictEqual({
+      failed: 0,
+      reported: 2,
+      skipped: 0,
+    })
+    // One ensure per org per tick, not per row.
+    expect(subscriptionsCreated).toHaveLength(1)
+    // The just-created subscription bills nothing before its start, so the
+    // backlog carries no timestamp and lands on the first invoice.
+    expect(meterEvents).toHaveLength(2)
+    for (const event of meterEvents) expect(event.timestamp).toBeUndefined()
+    await db.close()
+  })
+
+  test('behavior: an existing subscription keeps finalization timestamps', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    const row = await finalized(db, { feeAmount: '100000', seed: '06' })
+
+    const { meterEvents, stripe, subscriptionsCreated } = stubStripe({
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    expect(await Billing.createReporter({ db, stripe }).tick()).toStrictEqual({
+      failed: 0,
+      reported: 1,
+      skipped: 0,
+    })
+    expect(subscriptionsCreated).toHaveLength(0)
+    const finalizedAt = new Date((await SponsoredTransactions.get(db, row.id))!.finalizedAt!)
+    expect(meterEvents[0]?.timestamp).toBe(Math.floor(finalizedAt.getTime() / 1000))
+    await db.close()
+  })
+})
+
+describe('createKeyBillingSyncer', () => {
+  test('behavior: converges drifted sandbox key snapshots to the billing table', async () => {
+    const db = create()
+    await db.migrate()
+    const kv = Store.memory()
+
+    // A sandbox key minted while billing was inactive; billing later activates
+    // but the webhook re-sync never lands, so the record snapshot is stale.
+    const { token } = await ApiKeys.mint(kv, {
+      billingActive: false,
+      environment: 'sandbox',
+      orgId: 'org_1',
+      scopes: ['data:read'],
+    })
+    await StripeCustomers.create(db, {
+      environment: 'sandbox',
+      orgId: 'org_1',
+      stripeCustomerId: 'cus_1',
+    })
+    await StripeCustomers.setStatus(db, 'org_1', 'active', 'sandbox')
+
+    const syncer = Billing.createKeyBillingSyncer({ db, kv })
+    expect(await syncer.tick()).toStrictEqual({ checked: 1, updated: 1 })
+    expect((await ApiKeys.resolve(kv, token))?.billingActive).toBe(true)
+
+    // A converged fleet re-reads but writes nothing.
+    expect(await syncer.tick()).toStrictEqual({ checked: 1, updated: 0 })
+    await db.close()
+  })
+
+  test('behavior: reconciles a lapse back to the public quota', async () => {
+    const db = create()
+    await db.migrate()
+    const kv = Store.memory()
+
+    const { token } = await ApiKeys.mint(kv, {
+      billingActive: true,
+      environment: 'sandbox',
+      orgId: 'org_1',
+      scopes: ['data:read'],
+    })
+    await StripeCustomers.create(db, {
+      environment: 'sandbox',
+      orgId: 'org_1',
+      stripeCustomerId: 'cus_1',
+    })
+    await StripeCustomers.setStatus(db, 'org_1', 'past_due', 'sandbox')
+
+    expect(await Billing.createKeyBillingSyncer({ db, kv }).tick()).toStrictEqual({
+      checked: 1,
+      updated: 1,
+    })
+    // Non-`active` billing throttles: the snapshot flips back to false.
+    expect((await ApiKeys.resolve(kv, token))?.billingActive).toBe(false)
+    await db.close()
+  })
+
+  test('behavior: leaves production billing sources untouched', async () => {
+    const db = create()
+    await db.migrate()
+    const kv = Store.memory()
+
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    await StripeCustomers.setStatus(db, 'org_1', 'active')
+
+    // The default syncer reconciles sandbox only; a production-only org is
+    // outside its driver set.
+    expect(await Billing.createKeyBillingSyncer({ db, kv }).tick()).toStrictEqual({
+      checked: 0,
+      updated: 0,
+    })
+    await db.close()
+  })
+})
+
+describe('ensureSubscription', () => {
+  test('behavior: adds the missing item to a live subscription', async () => {
+    const { itemsCreated, stripe, subscriptionsCreated } = stubStripe({
+      subscriptions: [{ items: ['feePayerSpend'], status: 'active' }],
+    })
+    const result = await Billing.ensureSubscription(stripe, 'cus_1', [
+      'feePayerSpend',
+      'apiRequests',
+    ])
+    expect(result.created).toBe(false)
+    expect(subscriptionsCreated).toHaveLength(0)
+    expect(itemsCreated).toEqual([{ price: 'price_req', subscription: expect.any(String) }])
+    expect(result.items.apiRequests?.created).toBe(true)
+    expect(result.items.feePayerSpend?.created).toBe(false)
+  })
+
+  test('behavior: creates a subscription carrying every requested item', async () => {
+    const { stripe, subscriptionsCreated } = stubStripe({ subscriptions: [] })
+    const result = await Billing.ensureSubscription(stripe, 'cus_1', [
+      'feePayerSpend',
+      'apiRequests',
+    ])
+    expect(result.created).toBe(true)
+    expect(subscriptionsCreated).toHaveLength(1)
+    expect(subscriptionsCreated[0]!.items.map((item) => item.price).sort()).toEqual([
+      'price_fee',
+      'price_req',
+    ])
+  })
+
+  test('behavior: fails closed on multiple live managed subscriptions', async () => {
+    const { stripe } = stubStripe({
+      subscriptions: [
+        { items: ['feePayerSpend'], status: 'active' },
+        { items: ['apiRequests'], status: 'active' },
+      ],
+    })
+    await expect(
+      Billing.ensureSubscription(stripe, 'cus_1', ['feePayerSpend', 'apiRequests']),
+    ).rejects.toBeInstanceOf(Billing.DuplicateSubscriptionError)
+  })
+})
+
+describe('createRequestUsageReporter', () => {
+  // A closed hour inside the settlement window for the fixed clock below.
+  const bucketStart = '2026-01-01T12:00:00.000Z'
+  const now = () => Date.parse('2026-01-02T00:20:00.000Z')
+
+  test('behavior: seals the initial count, then bills only the delta on growth', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    await StripeCustomers.setStatus(db, 'org_1', 'active')
+
+    // Tick 1: fresh customer, initial seal of 5. The just-created item bills at
+    // now (no backdate).
+    const first = stubStripe({ subscriptions: [] })
+    const reporter1 = Billing.createRequestUsageReporter({
+      db,
+      now,
+      readCounts: async () => [{ bucketStart, count: 5, orgId: 'org_1' }],
+      stripe: first.stripe,
+    })
+    expect(await reporter1.tick()).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect(first.meterEvents).toEqual([
+      { event_name: 'api_request_count', identifier: expect.any(String), payload: expect.objectContaining({ value: '5' }) }, // prettier-ignore
+    ])
+    expect(first.meterEvents[0]!.timestamp).toBeUndefined()
+    expect((await RequestUsage.getBucket(db, { bucketStart, environment: 'production', orgId: 'org_1' }))?.reportedCount).toBe(5) // prettier-ignore
+
+    // Tick 2: count grows to 8; only the delta of 3 bills, backdated (item exists).
+    const second = stubStripe({
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    const reporter2 = Billing.createRequestUsageReporter({
+      db,
+      now,
+      readCounts: async () => [{ bucketStart, count: 8, orgId: 'org_1' }],
+      stripe: second.stripe,
+    })
+    expect(await reporter2.tick()).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect(second.meterEvents[0]?.payload).toMatchObject({ value: '3' })
+    expect(second.meterEvents[0]?.timestamp).toBe(Math.floor(Date.parse(bucketStart) / 1000))
+    expect((await RequestUsage.getBucket(db, { bucketStart, environment: 'production', orgId: 'org_1' }))?.reportedCount).toBe(8) // prettier-ignore
+
+    // Tick 3: no growth; nothing bills.
+    const third = stubStripe({
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now,
+        readCounts: async () => [{ bucketStart, count: 8, orgId: 'org_1' }],
+        stripe: third.stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 0, reported: 0, skipped: 0 })
+    expect(third.meterEvents).toHaveLength(0)
+    await db.close()
+  })
+
+  test('behavior: seals only hours older than the settlement delay', async () => {
+    const db = create()
+    await db.migrate()
+    const readCounts = vi.fn(async () => [] as { bucketStart: string; count: number; orgId: string }[]) // prettier-ignore
+    const { stripe } = stubStripe({ subscriptions: [] })
+    await Billing.createRequestUsageReporter({ db, now, readCounts, stripe }).tick()
+    // Cutoff is the start of the hour 15 minutes before `now`.
+    expect(readCounts).toHaveBeenCalledWith({
+      environment: 'production',
+      from: '2025-12-31T00:00:00.000Z',
+      to: '2026-01-02T00:00:00.000Z',
+    })
+    await db.close()
+  })
+
+  test('behavior: an org without a billing source is skipped and never sealed', async () => {
+    const db = create()
+    await db.migrate()
+    const { meterEvents, stripe } = stubStripe({ subscriptions: [] })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now,
+        readCounts: async () => [{ bucketStart, count: 4, orgId: 'org_1' }],
+        stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 0, reported: 0, skipped: 1 })
+    expect(meterEvents).toHaveLength(0)
+    expect(await RequestUsage.getBucket(db, { bucketStart, environment: 'production', orgId: 'org_1' })).toBeUndefined() // prettier-ignore
+    await db.close()
+  })
+
+  test('behavior: bills sandbox usage on the sandbox client', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, {
+      environment: 'sandbox',
+      orgId: 'org_1',
+      stripeCustomerId: 'cus_sandbox',
+    })
+    await StripeCustomers.setStatus(db, 'org_1', 'active', 'sandbox')
+
+    const production = stubStripe({ subscriptions: [] })
+    const sandbox = stubStripe({ subscriptions: [] })
+    const reporter = Billing.createRequestUsageReporter({
+      db,
+      now,
+      readCounts: async ({ environment }) =>
+        environment === 'sandbox' ? [{ bucketStart, count: 7, orgId: 'org_1' }] : [],
+      sandboxStripe: sandbox.stripe,
+      stripe: production.stripe,
+    })
+    expect(await reporter.tick()).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect(production.meterEvents).toHaveLength(0)
+    expect(sandbox.meterEvents[0]?.payload).toMatchObject({
+      stripe_customer_id: 'cus_sandbox',
+      value: '7',
+    })
+    expect((await RequestUsage.getBucket(db, { bucketStart, environment: 'sandbox', orgId: 'org_1' }))?.reportedCount).toBe(7) // prettier-ignore
+    await db.close()
+  })
+
+  test('behavior: re-sends a stranded pending event and advances the watermark', async () => {
+    const db = create()
+    await db.migrate()
+    await StripeCustomers.create(db, { orgId: 'org_1', stripeCustomerId: 'cus_1' })
+    await StripeCustomers.setStatus(db, 'org_1', 'active')
+    // Simulate a crash after sealing but before the Stripe ack.
+    await RequestUsage.insertPending(db, {
+      bucketStart,
+      deltaCount: 6,
+      environment: 'production',
+      identifier: 'rq_production_deadbeef0001_0_0',
+      orgId: 'org_1',
+      sequence: 0,
+      stripeCustomerId: 'cus_1',
+    })
+
+    const { meterEvents, stripe } = stubStripe({
+      subscriptions: [{ items: ['feePayerSpend', 'apiRequests'], status: 'active' }],
+    })
+    expect(
+      await Billing.createRequestUsageReporter({
+        db,
+        now,
+        // No new counts; recovery must still drain the pending event.
+        readCounts: async () => [],
+        stripe,
+      }).tick(),
+    ).toStrictEqual({ failed: 0, reported: 1, skipped: 0 })
+    expect(meterEvents[0]?.payload).toMatchObject({ value: '6' })
+    expect((await RequestUsage.getBucket(db, { bucketStart, environment: 'production', orgId: 'org_1' }))?.reportedCount).toBe(6) // prettier-ignore
+    await db.close()
+  })
+})