@strav/payment 1.0.0-alpha.24

package/src/dto/payment_method.ts

@@ -0,0 +1,43 @@
+/**
+ * `PaymentMethod` — normalized payment-instrument record. The
+ * actual card number / bank account isn't exposed — only the
+ * presentational fields apps render in receipts and account
+ * pages.
+ */
+
+export type PaymentMethodKind =
+  | 'card'
+  | 'bank_account'
+  | 'sepa_debit'
+  | 'promptpay'
+  | 'truemoney'
+  | 'paypal'
+  | 'other'
+
+export interface PaymentMethod {
+  id: string
+  provider: string
+  customerId: string | null
+  kind: PaymentMethodKind
+  /** Card brand / bank name / wallet provider. Always present. */
+  brand?: string
+  /** Last 4 digits / account suffix. */
+  last4?: string
+  expMonth?: number
+  expYear?: number
+  metadata: Record<string, string>
+  createdAt: Date
+  raw: unknown
+}
+
+export interface ListPaymentMethodsOptions {
+  /** Filter to one kind. */
+  kind?: PaymentMethodKind
+  cursor?: string
+  limit?: number
+}
+
+export interface PaginatedPaymentMethods {
+  data: PaymentMethod[]
+  nextCursor: string | null
+}

package/src/dto/payment_price.ts

@@ -0,0 +1,47 @@
+/**
+ * `PaymentPrice` — normalized price (recurring or one-shot) record.
+ * Money is represented in the provider's minor unit (cents,
+ * satang, …) to avoid floating-point drift. Currencies use the
+ * ISO 4217 three-letter code, lowercase to match Stripe.
+ */
+
+export interface PaymentPrice {
+  id: string
+  provider: string
+  productId: string
+  /** Amount in the provider's minor unit (e.g. cents). */
+  amount: number
+  currency: string
+  /** `'one_time'` for single charges; recurring carries `interval`. */
+  type: 'one_time' | 'recurring'
+  interval?: 'day' | 'week' | 'month' | 'year'
+  /** Number of `interval` units per billing period (default 1). */
+  intervalCount?: number
+  active: boolean
+  metadata: Record<string, string>
+  createdAt: Date
+  raw: unknown
+}
+
+export interface CreatePriceInput {
+  product: string
+  amount: number
+  currency: string
+  type?: 'one_time' | 'recurring'
+  interval?: 'day' | 'week' | 'month' | 'year'
+  intervalCount?: number
+  active?: boolean
+  metadata?: Record<string, string>
+}
+
+export interface ListPricesOptions {
+  product?: string
+  cursor?: string
+  limit?: number
+  active?: boolean
+}
+
+export interface PaginatedPrices {
+  data: PaymentPrice[]
+  nextCursor: string | null
+}

package/src/dto/payment_product.ts

@@ -0,0 +1,40 @@
+/**
+ * `PaymentProduct` — normalized product (catalogue entry) record.
+ * Prices attach to products and carry the actual billing terms.
+ */
+
+export interface PaymentProduct {
+  id: string
+  provider: string
+  name: string
+  description?: string
+  active: boolean
+  metadata: Record<string, string>
+  createdAt: Date
+  raw: unknown
+}
+
+export interface CreateProductInput {
+  name: string
+  description?: string
+  active?: boolean
+  metadata?: Record<string, string>
+}
+
+export interface UpdateProductInput {
+  name?: string
+  description?: string
+  active?: boolean
+  metadata?: Record<string, string>
+}
+
+export interface ListProductsOptions {
+  cursor?: string
+  limit?: number
+  active?: boolean
+}
+
+export interface PaginatedProducts {
+  data: PaymentProduct[]
+  nextCursor: string | null
+}

package/src/dto/payment_subscription.ts

@@ -0,0 +1,71 @@
+/**
+ * `PaymentSubscription` — normalized subscription state.
+ *
+ * `status` is the framework union — drivers translate from their
+ * native status (`'incomplete_expired'` etc.) onto this set. Apps
+ * that need the precise provider value read `raw`.
+ */
+
+export type SubscriptionStatus =
+  | 'trialing'
+  | 'active'
+  | 'past_due'
+  | 'canceled'
+  | 'paused'
+  | 'incomplete'
+
+export interface PaymentSubscription {
+  id: string
+  provider: string
+  customerId: string
+  priceId: string
+  status: SubscriptionStatus
+  currentPeriodStart: Date
+  currentPeriodEnd: Date
+  cancelAt: Date | null
+  canceledAt: Date | null
+  trialStart: Date | null
+  trialEnd: Date | null
+  metadata: Record<string, string>
+  createdAt: Date
+  raw: unknown
+}
+
+export interface CreateSubscriptionInput {
+  customer: string
+  price: string
+  /** Days of free trial. Drivers without trial support throw `ProviderUnsupportedError`. */
+  trialDays?: number
+  metadata?: Record<string, string>
+  /** Optional payment-method id to charge for renewals. */
+  paymentMethod?: string
+  /** See `CreateChargeInput.idempotencyKey`. */
+  idempotencyKey?: string
+}
+
+export interface UpdateSubscriptionInput {
+  price?: string
+  metadata?: Record<string, string>
+  paymentMethod?: string
+}
+
+export interface CancelSubscriptionOptions {
+  /**
+   * `'now'` — cancel immediately, refund/credit per provider rules.
+   * `'period_end'` — let the current period finish, then stop renewals.
+   * Default: `'period_end'`.
+   */
+  at?: 'now' | 'period_end'
+}
+
+export interface ListSubscriptionsOptions {
+  customer?: string
+  status?: SubscriptionStatus
+  cursor?: string
+  limit?: number
+}
+
+export interface PaginatedSubscriptions {
+  data: PaymentSubscription[]
+  nextCursor: string | null
+}

package/src/index.ts

@@ -0,0 +1,78 @@
+// Public API of `@strav/payment`.
+//
+// V1: provider-agnostic payment abstraction — normalized DTOs +
+// multi-provider routing + ledger schema + webhook dispatcher.
+// Composes with `@strav/database` for the ledger tables and
+// `@strav/http` for the webhook route.
+//
+// Drivers ship as separate adapter packages:
+//   `@strav/payment-stripe`, `@strav/payment-paddle`,
+//   `@strav/payment-omise`. The `MockDriver` in `./drivers` is
+//   for tests and as the reference implementation.
+
+export type * from './dto/index.ts'
+export {
+  extractCardToken,
+  MockDriver,
+  type MockDriverOptions,
+  paymentMethodKind,
+  unsupported,
+} from './drivers/index.ts'
+export {
+  applyPaymentLedgerMigration,
+  type ApplyPaymentLedgerMigrationOptions,
+  PaymentCustomerRow,
+  PaymentInvoiceRow,
+  PaymentLedger,
+  PaymentSubscriptionRow,
+  paymentCustomerSchema,
+  paymentInvoiceSchema,
+  paymentSubscriptionSchema,
+} from './ledger/index.ts'
+export type { PaymentCapability } from './payment_capabilities.ts'
+export type {
+  ChargeOps,
+  CheckoutOps,
+  CustomerOps,
+  InvoiceOps,
+  LinkOps,
+  PaymentDriver,
+  PaymentDriverFactory,
+  PaymentMethodOps,
+  PriceOps,
+  ProductOps,
+  SubscriptionOps,
+  WebhookOps,
+} from './payment_driver.ts'
+export {
+  PaymentConfigError,
+  PaymentError,
+  PaymentProviderError,
+  ProviderUnsupportedError,
+  UnknownProviderError,
+  WebhookIdempotencyError,
+  WebhookSignatureError,
+} from './payment_error.ts'
+export {
+  PaymentManager,
+  type PaymentManagerOptions,
+} from './payment_manager.ts'
+export { PaymentProvider } from './payment_provider.ts'
+export {
+  readTenantId,
+  TENANT_METADATA_KEY,
+  tenantedMetadata,
+} from './tenant_metadata.ts'
+export type {
+  LedgerConfig,
+  PaymentConfig,
+  ProviderConfig,
+} from './types.ts'
+export {
+  paymentWebhook,
+  type PaymentWebhookOptions,
+  PaymentWebhookEvent,
+  PaymentWebhookEventRepository,
+  paymentWebhookEventSchema,
+  PaymentWebhookRegistry,
+} from './webhook/index.ts'

package/src/ledger/apply_payment_ledger_migration.ts

@@ -0,0 +1,106 @@
+/**
+ * `applyPaymentLedgerMigration` — emit DDL for every framework-
+ * owned payment table in one call. Apps drop one statement into
+ * their migration:
+ *
+ * ```ts
+ * export const migration: Migration = {
+ *   name: '20260601000000_create_payment_ledger',
+ *   async up(db) {
+ *     await applyPaymentLedgerMigration(db, { registry })
+ *   },
+ *   async down(db) {
+ *     await db.execute(emitDropTable(paymentInvoiceSchema.name).sql)
+ *     await db.execute(emitDropTable(paymentSubscriptionSchema.name).sql)
+ *     await db.execute(emitDropTable(paymentCustomerSchema.name).sql)
+ *     await db.execute(emitDropTable(paymentWebhookEventSchema.name).sql)
+ *   },
+ * }
+ * ```
+ *
+ * The helper attaches composite unique constraints + secondary
+ * indexes on top of the framework-emitted table DDL. Composite
+ * constraints aren't expressible through the schema builder yet
+ * — handled here.
+ */
+
+import {
+  emitCreateTable,
+  type DatabaseExecutor,
+  type SchemaRegistry,
+} from '@strav/database'
+import { paymentCustomerSchema } from './schemas/payment_customer_schema.ts'
+import { paymentInvoiceSchema } from './schemas/payment_invoice_schema.ts'
+import { paymentSubscriptionSchema } from './schemas/payment_subscription_schema.ts'
+import { paymentWebhookEventSchema } from '../webhook/payment_webhook_event_schema.ts'
+
+export interface ApplyPaymentLedgerMigrationOptions {
+  /** Required for emitCreateTable to resolve tenant FK refs. */
+  registry: SchemaRegistry
+  /**
+   * Skip ledger tables (customers / subscriptions / invoices).
+   * When false (default), the full ledger lands. When true, only
+   * the dedup table is created — for apps that opt out of local
+   * mirroring via `config.payment.ledger.enabled = false`.
+   */
+  ledgerEnabled?: boolean
+}
+
+export async function applyPaymentLedgerMigration(
+  db: DatabaseExecutor,
+  options: ApplyPaymentLedgerMigrationOptions,
+): Promise<void> {
+  const { registry, ledgerEnabled = true } = options
+
+  // Dedup ledger — always created, the webhook route depends on it.
+  await db.execute(emitCreateTable(paymentWebhookEventSchema, { registry }).sql)
+  await db.execute(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "idx_payment_webhook_event_provider_event"
+     ON "${paymentWebhookEventSchema.name}" ("provider", "provider_event_id")`,
+  )
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_payment_webhook_event_type"
+     ON "${paymentWebhookEventSchema.name}" ("event_type")`,
+  )
+
+  if (!ledgerEnabled) return
+
+  await db.execute(emitCreateTable(paymentCustomerSchema, { registry }).sql)
+  await db.execute(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "idx_payment_customer_provider_id"
+     ON "${paymentCustomerSchema.name}" ("provider", "provider_id")`,
+  )
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_payment_customer_email"
+     ON "${paymentCustomerSchema.name}" ("email")`,
+  )
+
+  await db.execute(emitCreateTable(paymentSubscriptionSchema, { registry }).sql)
+  await db.execute(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "idx_payment_subscription_provider_id"
+     ON "${paymentSubscriptionSchema.name}" ("provider", "provider_id")`,
+  )
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_payment_subscription_customer"
+     ON "${paymentSubscriptionSchema.name}" ("provider", "customer_provider_id")`,
+  )
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_payment_subscription_status"
+     ON "${paymentSubscriptionSchema.name}" ("status")`,
+  )
+
+  await db.execute(emitCreateTable(paymentInvoiceSchema, { registry }).sql)
+  await db.execute(
+    `CREATE UNIQUE INDEX IF NOT EXISTS "idx_payment_invoice_provider_id"
+     ON "${paymentInvoiceSchema.name}" ("provider", "provider_id")`,
+  )
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_payment_invoice_customer"
+     ON "${paymentInvoiceSchema.name}" ("provider", "customer_provider_id")`,
+  )
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_payment_invoice_subscription"
+     ON "${paymentInvoiceSchema.name}" ("provider", "subscription_provider_id")
+     WHERE "subscription_provider_id" IS NOT NULL`,
+  )
+}

package/src/ledger/index.ts

@@ -0,0 +1,13 @@
+export {
+  applyPaymentLedgerMigration,
+  type ApplyPaymentLedgerMigrationOptions,
+} from './apply_payment_ledger_migration.ts'
+export { PaymentLedger } from './payment_ledger.ts'
+export {
+  PaymentCustomerRow,
+  PaymentInvoiceRow,
+  PaymentSubscriptionRow,
+} from './payment_ledger_models.ts'
+export { paymentCustomerSchema } from './schemas/payment_customer_schema.ts'
+export { paymentInvoiceSchema } from './schemas/payment_invoice_schema.ts'
+export { paymentSubscriptionSchema } from './schemas/payment_subscription_schema.ts'

package/src/ledger/payment_ledger.ts

@@ -0,0 +1,260 @@
+/**
+ * `PaymentLedger` — applies normalized webhook events into the
+ * local ledger tables.
+ *
+ * Sync flow (when `config.payment.ledger.syncOnWebhook` is true):
+ *
+ *   1. Webhook handler verifies + dedups + normalizes.
+ *   2. Before firing user handlers, the dispatcher calls
+ *      `ledger.applyEvent(event)` — this upserts the matching
+ *      row(s) in `payment_customer` / `payment_subscription` /
+ *      `payment_invoice`.
+ *   3. User handlers run against an already-up-to-date ledger.
+ *
+ * Why per-event upserts (not periodic full sync): webhooks are
+ * the source-of-truth signal for change. Polling is wasteful and
+ * lossy. Apps that miss a webhook (signature secret rotation,
+ * downtime) backfill via a `payment:resync` admin command in a
+ * follow-up slice.
+ *
+ * Tenancy: tables are tenanted, but webhooks arrive without
+ * tenant context. The ledger resolves the tenant by matching on
+ * `(provider, provider_id)` from `payment_customer` rows seeded
+ * at customer-creation time (when tenant context IS available).
+ * Subscriptions / invoices then inherit the customer's tenant.
+ *
+ * Events for which no `payment_customer` row exists are skipped
+ * with a logged warning — likely a webhook for a customer
+ * created outside the framework, or a missed seed.
+ */
+
+// biome-ignore lint/style/useImportType: PostgresDatabase value import for @inject() metadata.
+import {
+  PostgresDatabase,
+  quoteIdent,
+  type DatabaseExecutor,
+} from '@strav/database'
+import { inject, ulid } from '@strav/kernel'
+import type { NormalizedWebhookEvent } from '../dto/payment_event.ts'
+import { paymentCustomerSchema } from './schemas/payment_customer_schema.ts'
+import { paymentInvoiceSchema } from './schemas/payment_invoice_schema.ts'
+import { paymentSubscriptionSchema } from './schemas/payment_subscription_schema.ts'
+
+@inject()
+export class PaymentLedger {
+  // biome-ignore lint/complexity/noUselessConstructor: explicit constructor forces TS to emit `design:paramtypes` for @inject().
+  constructor(private readonly db: PostgresDatabase) {}
+
+  /**
+   * Apply a normalized event. Idempotent — re-running with the
+   * same event yields the same row state.
+   *
+   * `executor` is an optional database handle — the webhook
+   * dispatcher passes the transaction returned by
+   * `TenantManager.withTenant(tenantId, async (tx) => ...)` so
+   * the INSERTs see `current_setting('app.tenant_id')` set by
+   * `withTenant`'s `set_config(..., true)` (LOCAL = transaction
+   * scope). When omitted (direct calls outside webhook flow),
+   * the ledger falls back to the pooled `PostgresDatabase`, which
+   * is correct only when the caller has already SET the session
+   * setting on that connection.
+   *
+   * Implementation note for v1: customers / subscriptions /
+   * invoices each have a partial-payload upsert path that reads
+   * the structured fields off `event._fields` (drivers stamp it
+   * during `normalize`). When `_fields` is absent the upsert
+   * no-ops (apps still get the event, just no local mirror).
+   */
+  async applyEvent(
+    event: NormalizedWebhookEvent,
+    executor?: DatabaseExecutor,
+  ): Promise<void> {
+    const fields = (event as { _fields?: Record<string, unknown> })._fields
+    if (!fields) return
+    const exec = executor ?? this.db
+
+    switch (event.type) {
+      case 'customer.created':
+      case 'customer.updated':
+        await this.upsertCustomer(exec, event.provider, fields)
+        return
+      case 'customer.deleted':
+        if (event.data.customerId) {
+          await this.deleteCustomer(exec, event.provider, event.data.customerId)
+        }
+        return
+      case 'subscription.created':
+      case 'subscription.updated':
+      case 'subscription.canceled':
+      case 'subscription.trial_will_end':
+        await this.upsertSubscription(exec, event.provider, fields)
+        return
+      case 'invoice.created':
+      case 'invoice.paid':
+      case 'invoice.payment_failed':
+      case 'invoice.voided':
+        await this.upsertInvoice(exec, event.provider, fields)
+        return
+      default:
+        return
+    }
+  }
+
+  private async upsertCustomer(
+    exec: DatabaseExecutor,
+    provider: string,
+    fields: Record<string, unknown>,
+  ): Promise<void> {
+    const table = quoteIdent(paymentCustomerSchema.name)
+    // `tenant_id` is pulled from the session setting (`app.tenant_id`)
+    // set by `TenantManager.withTenant(...)` around the webhook
+    // dispatcher. Same pattern as `@strav/rag`'s pgvector driver.
+    await exec.execute(
+      `INSERT INTO ${table}
+        ("id","tenant_id","provider","provider_id","email","name","phone","metadata","created_at","updated_at")
+       VALUES ($1, current_setting('app.tenant_id', true), $2, $3, $4, $5, $6, $7::jsonb, $8, NOW())
+       ON CONFLICT ("provider","provider_id") DO UPDATE SET
+         "email"      = EXCLUDED."email",
+         "name"       = EXCLUDED."name",
+         "phone"      = EXCLUDED."phone",
+         "metadata"   = EXCLUDED."metadata",
+         "updated_at" = NOW()`,
+      [
+        ulid(),
+        provider,
+        str(fields.id),
+        str(fields.email),
+        nullable(fields.name),
+        nullable(fields.phone),
+        JSON.stringify(fields.metadata ?? {}),
+        toDate(fields.createdAt) ?? new Date(),
+      ],
+    )
+  }
+
+  private async deleteCustomer(
+    exec: DatabaseExecutor,
+    provider: string,
+    providerId: string,
+  ): Promise<void> {
+    const table = quoteIdent(paymentCustomerSchema.name)
+    await exec.execute(
+      `DELETE FROM ${table} WHERE "provider" = $1 AND "provider_id" = $2`,
+      [provider, providerId],
+    )
+  }
+
+  private async upsertSubscription(
+    exec: DatabaseExecutor,
+    provider: string,
+    fields: Record<string, unknown>,
+  ): Promise<void> {
+    const table = quoteIdent(paymentSubscriptionSchema.name)
+    await exec.execute(
+      `INSERT INTO ${table}
+        ("id","tenant_id","provider","provider_id","customer_provider_id","price_provider_id",
+         "status","current_period_start","current_period_end","cancel_at","canceled_at",
+         "trial_start","trial_end","metadata","created_at","updated_at")
+       VALUES ($1, current_setting('app.tenant_id', true), $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13::jsonb, $14, NOW())
+       ON CONFLICT ("provider","provider_id") DO UPDATE SET
+         "status"               = EXCLUDED."status",
+         "current_period_start" = EXCLUDED."current_period_start",
+         "current_period_end"   = EXCLUDED."current_period_end",
+         "cancel_at"            = EXCLUDED."cancel_at",
+         "canceled_at"          = EXCLUDED."canceled_at",
+         "trial_start"          = EXCLUDED."trial_start",
+         "trial_end"            = EXCLUDED."trial_end",
+         "metadata"             = EXCLUDED."metadata",
+         "updated_at"           = NOW()`,
+      [
+        ulid(),
+        provider,
+        str(fields.id),
+        str(fields.customerId),
+        str(fields.priceId),
+        str(fields.status),
+        toDate(fields.currentPeriodStart) ?? new Date(),
+        toDate(fields.currentPeriodEnd) ?? new Date(),
+        toDate(fields.cancelAt),
+        toDate(fields.canceledAt),
+        toDate(fields.trialStart),
+        toDate(fields.trialEnd),
+        JSON.stringify(fields.metadata ?? {}),
+        toDate(fields.createdAt) ?? new Date(),
+      ],
+    )
+  }
+
+  private async upsertInvoice(
+    exec: DatabaseExecutor,
+    provider: string,
+    fields: Record<string, unknown>,
+  ): Promise<void> {
+    const table = quoteIdent(paymentInvoiceSchema.name)
+    await exec.execute(
+      `INSERT INTO ${table}
+        ("id","tenant_id","provider","provider_id","customer_provider_id","subscription_provider_id",
+         "status","amount","amount_paid","amount_due","currency",
+         "hosted_url","pdf_url","due_at","paid_at","metadata","created_at","updated_at")
+       VALUES ($1, current_setting('app.tenant_id', true), $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15::jsonb, $16, NOW())
+       ON CONFLICT ("provider","provider_id") DO UPDATE SET
+         "status"      = EXCLUDED."status",
+         "amount"      = EXCLUDED."amount",
+         "amount_paid" = EXCLUDED."amount_paid",
+         "amount_due"  = EXCLUDED."amount_due",
+         "hosted_url"  = EXCLUDED."hosted_url",
+         "pdf_url"     = EXCLUDED."pdf_url",
+         "due_at"      = EXCLUDED."due_at",
+         "paid_at"     = EXCLUDED."paid_at",
+         "metadata"    = EXCLUDED."metadata",
+         "updated_at"  = NOW()`,
+      [
+        ulid(),
+        provider,
+        str(fields.id),
+        str(fields.customerId),
+        nullable(fields.subscriptionId),
+        str(fields.status),
+        num(fields.amount),
+        num(fields.amountPaid),
+        num(fields.amountDue),
+        str(fields.currency),
+        nullable(fields.hostedUrl),
+        nullable(fields.pdfUrl),
+        toDate(fields.dueAt),
+        toDate(fields.paidAt),
+        JSON.stringify(fields.metadata ?? {}),
+        toDate(fields.createdAt) ?? new Date(),
+      ],
+    )
+  }
+}
+
+function str(v: unknown): string {
+  if (typeof v !== 'string') {
+    throw new TypeError(`PaymentLedger: expected string field, got ${typeof v}`)
+  }
+  return v
+}
+
+function num(v: unknown): number {
+  if (typeof v !== 'number' || !Number.isFinite(v)) {
+    throw new TypeError(`PaymentLedger: expected finite number, got ${typeof v}`)
+  }
+  return v
+}
+
+function nullable(v: unknown): string | null {
+  if (v === null || v === undefined) return null
+  if (typeof v !== 'string') {
+    throw new TypeError(`PaymentLedger: expected string or null, got ${typeof v}`)
+  }
+  return v
+}
+
+function toDate(v: unknown): Date | null {
+  if (v === null || v === undefined) return null
+  if (v instanceof Date) return v
+  if (typeof v === 'string' || typeof v === 'number') return new Date(v)
+  return null
+}