tapimo 0.14.0 → 0.15.0

package/src/apps/management/Billing.ts

@@ -1,5 +1,5 @@
 import { Hash, Hex, Value } from 'ox'
-import type Stripe from 'stripe'
+import Stripe from 'stripe'
 
 import * as ApiKey from '../../ApiKey.js'
 import * as ApiKeys from '../../ApiKeys.js'
@@ -7,6 +7,8 @@ import type * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Db from '../../db/Db.js'
 import * as Fees from '../../internal/Fees.js'
 import * as RequestUsage from '../../db/tables/requestUsage.js'
+import * as RoutesDeposits from '../../db/tables/routesDeposits.js'
+import * as RoutesTransfers from '../../db/tables/routesTransfers.js'
 import type * as Scope from '../../Scope.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import type * as Store from '../../internal/Store.js'
@@ -87,7 +89,7 @@ export function periodStart(period: BillingSettings.Record['period'], now = new
  * A metered billing dimension: a Stripe meter plus its metered monthly price.
  * Each kind bills as a distinct invoice line item on one shared subscription.
  */
-export type MeterKind = 'apiRequests' | 'feePayerSpend'
+export type MeterKind = 'apiRequests' | 'feePayerSpend' | 'routeSubsidy'
 
 /** Descriptor for one metered dimension. */
 export type MeterDescriptor = {
@@ -120,6 +122,13 @@ export const meters = {
     // Meter values are 6-decimal base units: 100¢ per 1e6 units.
     unitAmountDecimal: '0.0001',
   },
+  routeSubsidy: {
+    displayName: 'Route Subsidy',
+    eventName: 'route_subsidy_spend',
+    lookupKey: 'route-subsidy-spend-v1',
+    // Meter values are 6-decimal base units: 100¢ per 1e6 units.
+    unitAmountDecimal: '0.0001',
+  },
 } as const satisfies Record<MeterKind, MeterDescriptor>
 
 /**
@@ -130,7 +139,9 @@ export const meters = {
  * @returns The metered dimensions for that environment.
  */
 export function kindsFor(environment: StripeCustomers.Record['environment']): readonly MeterKind[] {
-  return environment === 'production' ? ['feePayerSpend', 'apiRequests'] : ['apiRequests']
+  return environment === 'production'
+    ? ['feePayerSpend', 'routeSubsidy', 'apiRequests']
+    : ['apiRequests']
 }
 
 /** Back-compat: the fee-payer meter event name. */
@@ -205,6 +216,134 @@ export declare namespace ensureFixtures {
 /** Subscription statuses that no longer bill; a new subscription must be created. */
 const terminalStatuses = ['canceled', 'incomplete_expired']
 
+/** Reads the next managed invoice without provisioning billing resources or reporting usage. */
+export async function previewInvoice(stripe: Stripe, options: previewInvoice.Options) {
+  const managedMeters = new Map<string, MeterKind>()
+  for await (const meter of stripe.billing.meters.list({ limit: 100 }))
+    for (const kind of kindsFor(options.environment))
+      if (meter.event_name === meters[kind].eventName) managedMeters.set(meter.id, kind)
+
+  const priceKinds = new Map<string, MeterKind | null>()
+  const managed: Stripe.Subscription[] = []
+  for await (const subscription of stripe.subscriptions.list({
+    customer: options.customer,
+    limit: 100,
+    status: 'all',
+  })) {
+    if (terminalStatuses.includes(subscription.status)) continue
+    const items = subscription.items.has_more
+      ? await stripe.subscriptionItems
+          .list({ limit: 100, subscription: subscription.id })
+          .autoPagingToArray({ limit: 10_000 })
+      : subscription.items.data
+    for (const { price } of items)
+      priceKinds.set(price.id, managedMeters.get(price.recurring?.meter ?? '') ?? null)
+    if (items.some(({ price }) => managedMeters.has(price.recurring?.meter ?? '')))
+      managed.push(subscription)
+  }
+  if (managed.length > 1) throw new DuplicateSubscriptionError(options.customer)
+  const subscription = managed[0]
+  if (!subscription) return null
+
+  const invoice = await stripe.invoices
+    .createPreview({ customer: options.customer, subscription: subscription.id })
+    .catch((cause: unknown) => {
+      if (
+        cause instanceof Stripe.errors.StripeInvalidRequestError &&
+        cause.code === 'invoice_upcoming_none'
+      )
+        return null
+      throw cause
+    })
+  if (!invoice) return null
+  if (invoice.currency !== 'usd') throw new Error('Unsupported managed invoice currency')
+
+  // Preview ids support the same line pagination API as issued invoices.
+  const lines = invoice.lines.has_more
+    ? await stripe.invoices
+        .listLineItems(invoice.id, { limit: 100 })
+        .autoPagingToArray({ limit: 10_000 })
+    : invoice.lines.data
+  // Historical prices can appear on invoice lines after leaving the subscription.
+  for (const line of lines) {
+    const priceId = line.pricing?.price_details?.price
+    if (!priceId || priceKinds.has(priceId)) continue
+    const price = await stripe.prices.retrieve(priceId)
+    priceKinds.set(priceId, managedMeters.get(price.recurring?.meter ?? '') ?? null)
+  }
+  const products = new Map<string, Pick<Stripe.Product, 'id' | 'name'>>()
+  for (const line of lines) {
+    const productId = line.pricing?.price_details?.product
+    if (!productId || products.has(productId)) continue
+    const { id, name } = await stripe.products.retrieve(productId)
+    products.set(id, { id, name })
+  }
+  return {
+    amountDue: Value.format(BigInt(invoice.amount_due), 2),
+    billingCredits: Value.format(
+      (invoice.total_pretax_credit_amounts ?? []).reduce(
+        (sum, credit) =>
+          sum + (credit.type === 'credit_balance_transaction' ? BigInt(credit.amount) : 0n),
+        0n,
+      ),
+      2,
+    ),
+    currency: 'usd' as const,
+    discounts: Value.format(
+      (invoice.total_discount_amounts ?? []).reduce(
+        (sum, discount) => sum + BigInt(discount.amount),
+        0n,
+      ),
+      2,
+    ),
+    exclusiveTax: Value.format(
+      (invoice.total_taxes ?? []).reduce(
+        (sum, tax) => sum + (tax.tax_behavior === 'exclusive' ? BigInt(tax.amount) : 0n),
+        0n,
+      ),
+      2,
+    ),
+    lineItems: lines.map((line) => ({
+      amount: Value.format(BigInt(line.amount), 2),
+      description: line.description ?? 'Invoice item',
+      id: line.id,
+      kind: priceKinds.get(line.pricing?.price_details?.price ?? '') ?? null,
+      period: {
+        end: new Date(line.period.end * 1_000).toISOString(),
+        start: new Date(line.period.start * 1_000).toISOString(),
+      },
+      priceId: line.pricing?.price_details?.price ?? null,
+      product: products.get(line.pricing?.price_details?.product ?? '') ?? null,
+      quantity: line.quantity,
+      // Stripe permits 12 fractional minor-unit digits; USD adds two decimal places.
+      unitAmount:
+        line.pricing?.unit_amount_decimal == null
+          ? null
+          : Value.format(Value.from(line.pricing.unit_amount_decimal, 12), 14),
+    })),
+    retrievedAt: new Date().toISOString(),
+    startingBalance: Value.format(BigInt(invoice.starting_balance), 2),
+    taxIncluded: Value.format(
+      (invoice.total_taxes ?? []).reduce(
+        (sum, tax) => sum + (tax.tax_behavior === 'inclusive' ? BigInt(tax.amount) : 0n),
+        0n,
+      ),
+      2,
+    ),
+    total: Value.format(BigInt(invoice.total), 2),
+  }
+}
+
+export declare namespace previewInvoice {
+  /** Customer and environment whose managed subscription is previewed. */
+  type Options = {
+    /** Stripe customer belonging to the authorized organization and environment. */
+    customer: string
+    /** Environment selecting the managed meters. */
+    environment: StripeCustomers.Record['environment']
+  }
+}
+
 /**
  * Ensures the customer holds exactly one live subscription carrying one metered
  * item per requested {@link MeterKind}, creating the subscription or adding
@@ -246,29 +385,30 @@ export async function ensureSubscription(
   const items: Record<string, ensureSubscription.ItemResult> = {}
   const subscription = liveManaged[0]
   if (subscription) {
-    const present = new Set(
-      subscription.items.data
-        .map((item) => priceToKind.get(item.price.id))
-        .filter((kind): kind is MeterKind => kind !== undefined),
-    )
+    const present = new Map<MeterKind, Stripe.SubscriptionItem>()
+    for (const item of subscription.items.data) {
+      const kind = priceToKind.get(item.price.id)
+      if (kind) present.set(kind, item)
+    }
     for (const kind of requested) {
-      if (present.has(kind)) {
-        items[kind] = { created: false }
+      const item = present.get(kind)
+      if (item) {
+        items[kind] = { created: false, createdAt: item.created }
         continue
       }
       // Add the missing item; the idempotency key absorbs concurrent adds.
-      await stripe.subscriptionItems.create(
+      const created = await stripe.subscriptionItems.create(
         { price: fixtures.get(kind)!.priceId, subscription: subscription.id },
         { idempotencyKey: `${customerId}-item-${meters[kind].lookupKey}` },
       )
-      items[kind] = { created: true }
+      items[kind] = { created: true, createdAt: created.created }
     }
     return { created: false, items }
   }
 
   // The idempotency key absorbs concurrent activations: a duplicate metered
   // subscription would double-bill the same meter usage.
-  await stripe.subscriptions.create(
+  const created = await stripe.subscriptions.create(
     {
       collection_method: 'charge_automatically',
       customer: customerId,
@@ -276,7 +416,10 @@ export async function ensureSubscription(
     },
     { idempotencyKey: `${customerId}-metered-sub-v2` },
   )
-  for (const kind of requested) items[kind] = { created: true }
+  for (const item of created.items.data) {
+    const kind = priceToKind.get(item.price.id)
+    if (kind) items[kind] = { created: true, createdAt: item.created }
+  }
   return { created: true, items }
 }
 
@@ -285,6 +428,8 @@ export declare namespace ensureSubscription {
   type ItemResult = {
     /** Whether this call added the item (a fresh item bills nothing before its start). */
     created: boolean
+    /** Stripe item creation time in Unix seconds. */
+    createdAt: number
   }
 
   /** Outcome of {@link ensureSubscription}. */
@@ -305,10 +450,8 @@ export class DuplicateSubscriptionError extends Error {
 }
 
 /**
- * Creates the metering job: each tick reports finalized, unreported billable
- * mainnet spend to the Stripe meter and marks rows reported. A host runtime
- * drives {@link createReporter.Reporter.tick} on a timer, like the
- * sponsorship finalizer.
+ * Creates the sponsorship and Route Subsidy metering job. Each tick reports
+ * finalized usage, then marks each row after Stripe acknowledges it.
  */
 export function createReporter(options: createReporter.Options): createReporter.Reporter {
   const { batchSize = 100, chainIds = [Viem.chainId.mainnet], db, stripe } = options
@@ -317,10 +460,43 @@ export function createReporter(options: createReporter.Options): createReporter.
       // Resolve per tick so Workers factories build a fresh Hyperdrive-pooled
       // connection each run.
       const database = Db.get(db)
-      const rows = await SponsoredTransactions.listUnreported(database, {
-        chainIds,
-        limit: batchSize,
-      })
+      const [depositSubsidies, sponsorships, transferSubsidies] = await Promise.all([
+        RoutesDeposits.listUnreportedSubsidies(database, { limit: batchSize }),
+        SponsoredTransactions.listUnreported(database, { chainIds, limit: batchSize }),
+        RoutesTransfers.listUnreportedSubsidies(database, { limit: batchSize }),
+      ])
+      const rows: UsageRow[] = [
+        ...sponsorships.map(
+          (row): UsageRow => ({
+            amount: row.feeAmount!,
+            finalizedAt: row.finalizedAt!,
+            id: row.id,
+            orgId: row.orgId,
+            source: 'sponsorship',
+          }),
+        ),
+        ...depositSubsidies.map(
+          (row): UsageRow => ({
+            amount: RoutesDeposits.subsidies(row).map((subsidy) => subsidy.amount),
+            finalizedAt: row.statusUpdatedAt ?? row.updatedAt,
+            id: row.id,
+            orgId: row.orgId,
+            source: 'routes-deposit',
+          }),
+        ),
+        ...transferSubsidies.map(
+          (row): UsageRow => ({
+            amount: RoutesTransfers.subsidies(row).map((subsidy) => subsidy.amount),
+            finalizedAt: row.statusUpdatedAt ?? row.updatedAt,
+            id: row.id,
+            orgId: row.orgId,
+            source: 'routes-transfer',
+          }),
+        ),
+      ].toSorted(
+        (left, right) =>
+          left.finalizedAt.localeCompare(right.finalizedAt) || left.id.localeCompare(right.id),
+      )
       // One customer lookup and one subscription ensure per org per tick.
       const customers = new Map<string, StripeCustomers.Record | undefined>()
       const subscriptions = new Map<string, ensureSubscription.Result>()
@@ -328,6 +504,7 @@ export function createReporter(options: createReporter.Options): createReporter.
       let reported = 0
       let skipped = 0
       for (const row of rows) {
+        let meteredAt: string | undefined
         // One poisoned row must not stall the queue: it stays unmarked for
         // retry while the rest keep reporting.
         try {
@@ -337,6 +514,7 @@ export function createReporter(options: createReporter.Options): createReporter.
             customers.set(row.orgId, customer)
           }
           if (customer && customer.status !== 'canceled') {
+            const kind = row.source === 'sponsorship' ? 'feePayerSpend' : 'routeSubsidy'
             // Self-heal: guarantee the metered subscription before reporting;
             // meter events without one never reach an invoice. Pass the full
             // production kind set so concurrent creates share idempotency.
@@ -351,19 +529,29 @@ export function createReporter(options: createReporter.Options): createReporter.
             }
             // Meter timestamps must fall inside Stripe's 35-day ingestion
             // window; older backlog bills into the current period instead. A
-            // just-created fee-payer item bills nothing before its start, so
+            // just-created meter item bills nothing before its start, so
             // its backlog stamps at now too.
             const finalizedAt = new Date(row.finalizedAt!).getTime()
             const recent = Date.now() - finalizedAt < 34 * 24 * 60 * 60 * 1000
-            const stamp = recent && !subscription.items.feePayerSpend?.created
+            const item = subscription.items[kind]
+            const stamp =
+              recent && item !== undefined && !item.created && finalizedAt >= item.createdAt * 1_000
+            const timestamp = stamp ? Math.floor(finalizedAt / 1_000) : undefined
+            meteredAt = new Date(
+              (timestamp ?? Math.floor(Date.now() / 1_000)) * 1_000,
+            ).toISOString()
             // The row id makes short-window retries idempotent on Stripe's
             // side; `meter_reported_at` is the durable exactly-once guard.
             try {
               await stripe.billing.meterEvents.create({
-                event_name: meterEventName,
+                event_name: meters[kind].eventName,
                 identifier: row.id,
-                payload: { stripe_customer_id: customer.stripeCustomerId, value: row.feeAmount! },
-                ...(stamp ? { timestamp: Math.floor(finalizedAt / 1000) } : {}),
+                payload: {
+                  stripe_customer_id: customer.stripeCustomerId,
+                  value:
+                    row.source === 'sponsorship' ? row.amount : routeSubsidyMeterUnits(row.amount),
+                },
+                ...(timestamp !== undefined ? { timestamp } : {}),
               })
             } catch (error) {
               // Stripe may persist the event before the Worker records its ack.
@@ -371,13 +559,28 @@ export function createReporter(options: createReporter.Options): createReporter.
               if (!isDuplicateMeterEvent(error, row.id)) throw error
             }
             reported++
+          } else if (row.source === 'routes-deposit' && row.orgId.startsWith('key_')) {
+            // One-off keys use their id as temporary ownership and have no
+            // Stripe customer. Provider subsidies on those routes are non-billable.
+            meteredAt = new Date().toISOString()
+            skipped++
+          } else if (row.source !== 'sponsorship') {
+            // Production Routes subsidies were authorized against active billing.
+            // Keep the liability durable if that customer disappears before reporting.
+            throw new Error(`Stripe customer unavailable for Routes subsidy ${row.id}`)
           } else {
             // Deleted orgs and Stripe-deleted (canceled) customers keep their
             // ledger rows; nobody remains to invoice.
             skipped++
           }
           // Mark only after the Stripe ack (or a definitive no-customer skip).
-          await SponsoredTransactions.markReported(database, row.id, new Date().toISOString())
+          const reportedAt = new Date().toISOString()
+          if (row.source !== 'sponsorship') {
+            if (!meteredAt) throw new Error(`Routes subsidy ${row.id} has no meter timestamp`)
+            if (row.source === 'routes-deposit')
+              await RoutesDeposits.markSubsidyReported(database, row.id, meteredAt)
+            else await RoutesTransfers.markSubsidyReported(database, row.id, meteredAt)
+          } else await SponsoredTransactions.markReported(database, row.id, reportedAt)
         } catch (error) {
           failed++
           console.error(`Billing.createReporter: reporting row ${row.id} failed`, error)
@@ -388,6 +591,39 @@ export function createReporter(options: createReporter.Options): createReporter.
   }
 }
 
+type UsageRow =
+  | {
+      amount: readonly NonNullable<RoutesDeposits.Record['subsidyAmount']>[]
+      finalizedAt: string
+      id: string
+      orgId: string
+      source: 'routes-deposit' | 'routes-transfer'
+    }
+  | {
+      amount: string
+      finalizedAt: string
+      id: string
+      orgId: string
+      source: 'sponsorship'
+    }
+
+/** Converts a verified USD token amount to the Route Subsidy meter's microdollars. */
+function routeSubsidyMeterUnits(
+  amounts: readonly NonNullable<RoutesDeposits.Record['subsidyAmount']>[],
+): string {
+  return amounts
+    .reduce((total, amount) => {
+      if (amount.currency !== 'USD')
+        throw new Error(`unsupported subsidy currency ${amount.currency}`)
+      const units = BigInt(amount.baseUnits)
+      const difference = Fees.tokenDecimals - amount.decimals
+      if (difference >= 0) return total + units * 10n ** BigInt(difference)
+      const divisor = 10n ** BigInt(-difference)
+      return total + (units + divisor - 1n) / divisor
+    }, 0n)
+    .toString()
+}
+
 /** Whether Stripe confirms that the exact meter event identifier already exists. */
 function isDuplicateMeterEvent(error: unknown, identifier: string): boolean {
   return (
@@ -399,7 +635,7 @@ function isDuplicateMeterEvent(error: unknown, identifier: string): boolean {
 export declare namespace createReporter {
   /** Options for {@link createReporter}. */
   type Options = {
-    /** Maximum rows reported per tick. @default 100 */
+    /** Maximum rows reported per source per tick. @default 100 */
     batchSize?: number | undefined
     /** Chains whose spend is metered. @default mainnet */
     chainIds?: readonly number[] | undefined