@strav/payment 1.0.0-alpha.24

package/src/ledger/payment_ledger_models.ts

@@ -0,0 +1,66 @@
+/**
+ * Ledger model classes — typed row shapes the ledger repositories
+ * hydrate into. Apps query these for "show me this tenant's
+ * billing state" UIs.
+ */
+
+import { Model } 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'
+
+export class PaymentCustomerRow extends Model {
+  static override readonly schema = paymentCustomerSchema
+
+  id!: string
+  provider!: string
+  provider_id!: string
+  email!: string
+  name!: string | null
+  phone!: string | null
+  metadata!: Record<string, string>
+  created_at!: Date
+  updated_at!: Date
+}
+
+export class PaymentSubscriptionRow extends Model {
+  static override readonly schema = paymentSubscriptionSchema
+
+  id!: string
+  provider!: string
+  provider_id!: string
+  customer_provider_id!: string
+  price_provider_id!: string
+  status!: string
+  current_period_start!: Date
+  current_period_end!: Date
+  cancel_at!: Date | null
+  canceled_at!: Date | null
+  trial_start!: Date | null
+  trial_end!: Date | null
+  metadata!: Record<string, string>
+  created_at!: Date
+  updated_at!: Date
+}
+
+export class PaymentInvoiceRow extends Model {
+  static override readonly schema = paymentInvoiceSchema
+
+  id!: string
+  provider!: string
+  provider_id!: string
+  customer_provider_id!: string
+  subscription_provider_id!: string | null
+  status!: string
+  amount!: number
+  amount_paid!: number
+  amount_due!: number
+  currency!: string
+  hosted_url!: string | null
+  pdf_url!: string | null
+  due_at!: Date | null
+  paid_at!: Date | null
+  metadata!: Record<string, string>
+  created_at!: Date
+  updated_at!: Date
+}

package/src/ledger/schemas/payment_customer_schema.ts

@@ -0,0 +1,34 @@
+/**
+ * `paymentCustomerSchema` — local mirror of provider customers.
+ *
+ * Tenanted via RLS — apps that wrap calls in
+ * `tenants.withTenant(...)` get per-tenant isolation. The
+ * framework upserts into this table from webhook deliveries when
+ * `config.payment.ledger.syncOnWebhook` is true; apps read from
+ * it instead of round-tripping to the provider for the common
+ * "show me this user's billing info" UI.
+ *
+ * `provider` + `provider_id` together are the natural key; the
+ * composite unique constraint is added by
+ * `applyPaymentLedgerMigration` (the schema builder only exposes
+ * per-column `.unique()`).
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const paymentCustomerSchema = defineSchema(
+  'payment_customer',
+  Archetype.Entity,
+  (t) => {
+    t.id()
+    t.string('provider').max(64).notNull()
+    t.string('provider_id').max(255).notNull()
+    t.string('email').max(320).notNull()
+    t.string('name').max(255).nullable()
+    t.string('phone').max(64).nullable()
+    t.json('metadata').notNull().default({})
+    t.timestamp('created_at').notNull()
+    t.timestamp('updated_at').notNull()
+  },
+  { tenanted: true },
+)

package/src/ledger/schemas/payment_invoice_schema.ts

@@ -0,0 +1,39 @@
+/**
+ * `paymentInvoiceSchema` — local mirror of provider invoices.
+ * Tenanted via RLS.
+ *
+ * Apps query this for "last 12 invoices for this tenant" without
+ * paginating the provider's invoice listing on every render.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const paymentInvoiceSchema = defineSchema(
+  'payment_invoice',
+  Archetype.Entity,
+  (t) => {
+    t.id()
+    t.string('provider').max(64).notNull()
+    t.string('provider_id').max(255).notNull()
+    t.string('customer_provider_id').max(255).notNull()
+    t.string('subscription_provider_id').max(255).nullable()
+    t.string('status').max(32).notNull()
+    // Amounts are in the provider's minor unit (cents/satang).
+    // `integer` is int32 — caps each line at ~$21M USD which is
+    // well above the per-invoice ceiling for normal apps. Apps
+    // that bill nation-state contracts swap this for a decimal
+    // column in a follow-up migration.
+    t.integer('amount').notNull()
+    t.integer('amount_paid').notNull()
+    t.integer('amount_due').notNull()
+    t.string('currency').max(8).notNull()
+    t.string('hosted_url').max(1024).nullable()
+    t.string('pdf_url').max(1024).nullable()
+    t.timestamp('due_at').nullable()
+    t.timestamp('paid_at').nullable()
+    t.json('metadata').notNull().default({})
+    t.timestamp('created_at').notNull()
+    t.timestamp('updated_at').notNull()
+  },
+  { tenanted: true },
+)

package/src/ledger/schemas/payment_subscription_schema.ts

@@ -0,0 +1,34 @@
+/**
+ * `paymentSubscriptionSchema` — local mirror of provider
+ * subscriptions. Tenanted via RLS.
+ *
+ * Apps query this table for "active subscriptions for tenant X"
+ * without paying a network round-trip to the provider on every
+ * dashboard render. Mirror rows are upserted on webhook delivery
+ * (when ledger sync is on).
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const paymentSubscriptionSchema = defineSchema(
+  'payment_subscription',
+  Archetype.Entity,
+  (t) => {
+    t.id()
+    t.string('provider').max(64).notNull()
+    t.string('provider_id').max(255).notNull()
+    t.string('customer_provider_id').max(255).notNull()
+    t.string('price_provider_id').max(255).notNull()
+    t.string('status').max(32).notNull()
+    t.timestamp('current_period_start').notNull()
+    t.timestamp('current_period_end').notNull()
+    t.timestamp('cancel_at').nullable()
+    t.timestamp('canceled_at').nullable()
+    t.timestamp('trial_start').nullable()
+    t.timestamp('trial_end').nullable()
+    t.json('metadata').notNull().default({})
+    t.timestamp('created_at').notNull()
+    t.timestamp('updated_at').notNull()
+  },
+  { tenanted: true },
+)

package/src/payment_capabilities.ts

@@ -0,0 +1,91 @@
+/**
+ * `PaymentCapability` — granular feature flags every driver
+ * declares in `driver.capabilities`. Apps that build provider-
+ * neutral flows check capability before calling:
+ *
+ *   if (payment.use('omise').capabilities.has('checkout')) { ... }
+ *
+ * Drivers omit a capability when they can't fulfil it
+ * faithfully — partial / surprising implementations are worse
+ * than `ProviderUnsupportedError`. Apps reach `.raw` when they
+ * need provider-specific behaviour that doesn't map to a
+ * capability.
+ *
+ * Capability granularity is intentionally fine-grained (one per
+ * non-trivial *Ops method, not one per *Ops group) so e.g.
+ * Paddle can support `subscriptions.create` but not
+ * `subscriptions.changePlan` without losing the rest.
+ */
+
+export type PaymentCapability =
+  // customers
+  | 'customers.create'
+  | 'customers.update'
+  | 'customers.retrieve'
+  | 'customers.list'
+  | 'customers.delete'
+  // products + prices
+  | 'products.create'
+  | 'products.update'
+  | 'products.list'
+  | 'prices.create'
+  | 'prices.list'
+  // subscriptions
+  | 'subscriptions.create'
+  | 'subscriptions.retrieve'
+  | 'subscriptions.update'
+  | 'subscriptions.cancel'
+  | 'subscriptions.changePlan'
+  | 'subscriptions.trials'
+  // payment methods
+  | 'paymentMethods.attach'
+  | 'paymentMethods.detach'
+  | 'paymentMethods.list'
+  // charges
+  | 'charges.create'
+  | 'charges.refund'
+  | 'charges.capture'
+  // charges — payment-method specs the driver accepts as input.
+  // Fine-grained so apps can build method pickers that only show
+  // what the routed driver can take.
+  | 'charges.method.card'
+  | 'charges.method.promptpay'
+  | 'charges.method.paynow'
+  | 'charges.method.fps'
+  | 'charges.method.truemoney'
+  | 'charges.method.alipay'
+  | 'charges.method.wechat_pay'
+  | 'charges.method.grabpay'
+  | 'charges.method.kakaopay'
+  | 'charges.method.rabbit_linepay'
+  | 'charges.method.konbini'
+  // charges — next-action kinds the driver can emit. Apps that
+  // host their own QR / redirect UI check these to know what
+  // shapes they need to handle.
+  | 'charges.nextAction.display_qr'
+  | 'charges.nextAction.redirect'
+  | 'charges.nextAction.authorize'
+  | 'charges.nextAction.voucher'
+  | 'charges.nextAction.wait'
+  // invoices
+  | 'invoices.list'
+  | 'invoices.retrieve'
+  | 'invoices.finalize'
+  | 'invoices.void'
+  // checkout (hosted)
+  | 'checkout.create'
+  | 'checkout.retrieve'
+  // payment links — shareable hosted pay URLs.
+  | 'links.create'
+  | 'links.deactivate'
+  // Driver enforces server-side idempotency when `idempotencyKey`
+  // is set on supported create-style inputs. When NOT declared,
+  // the driver silently ignores the field — apps that need
+  // guaranteed dedup build it app-side (claim the key in a DB
+  // table before calling). Single flag covers every supported
+  // method (charges, refunds, subscriptions, links, checkout,
+  // customers).
+  | 'idempotency'
+  // webhooks
+  | 'webhook.verify'
+  | 'webhook.normalize'

package/src/payment_driver.ts

@@ -0,0 +1,167 @@
+/**
+ * `PaymentDriver` — the driver contract every adapter implements.
+ *
+ * One `PaymentDriver` represents a configured provider instance
+ * (`config.payment.providers['stripe']`). The manager holds one
+ * driver per configured name and routes resource calls into it.
+ *
+ * Methods drivers don't support throw `ProviderUnsupportedError`
+ * synchronously. The driver's `capabilities` set declares the
+ * supported method names — apps that branch on capability avoid
+ * the throw by checking first.
+ */
+
+import type {
+  CancelSubscriptionOptions,
+  CreateChargeInput,
+  CreateCheckoutInput,
+  CreateCustomerInput,
+  CreatePaymentLinkInput,
+  CreatePriceInput,
+  CreateProductInput,
+  CreateRefundInput,
+  CreateSubscriptionInput,
+  ListCustomersOptions,
+  ListInvoicesOptions,
+  ListPaymentLinksOptions,
+  ListPaymentMethodsOptions,
+  ListPricesOptions,
+  ListProductsOptions,
+  ListSubscriptionsOptions,
+  NormalizedWebhookEvent,
+  PaginatedCustomers,
+  PaginatedInvoices,
+  PaginatedPaymentLinks,
+  PaginatedPaymentMethods,
+  PaginatedPrices,
+  PaginatedProducts,
+  PaginatedSubscriptions,
+  PaymentCharge,
+  PaymentCheckoutSession,
+  PaymentCustomer,
+  PaymentInvoice,
+  PaymentLink,
+  PaymentMethod,
+  PaymentPrice,
+  PaymentProduct,
+  PaymentRefund,
+  PaymentSubscription,
+  UpdateCustomerInput,
+  UpdateSubscriptionInput,
+} from './dto/index.ts'
+import type { PaymentCapability } from './payment_capabilities.ts'
+
+export interface CustomerOps {
+  create(input: CreateCustomerInput): Promise<PaymentCustomer>
+  retrieve(id: string): Promise<PaymentCustomer>
+  update(id: string, input: UpdateCustomerInput): Promise<PaymentCustomer>
+  list(options?: ListCustomersOptions): Promise<PaginatedCustomers>
+  delete(id: string): Promise<void>
+}
+
+export interface ProductOps {
+  create(input: CreateProductInput): Promise<PaymentProduct>
+  retrieve(id: string): Promise<PaymentProduct>
+  update(id: string, input: Partial<CreateProductInput>): Promise<PaymentProduct>
+  list(options?: ListProductsOptions): Promise<PaginatedProducts>
+}
+
+export interface PriceOps {
+  create(input: CreatePriceInput): Promise<PaymentPrice>
+  retrieve(id: string): Promise<PaymentPrice>
+  list(options?: ListPricesOptions): Promise<PaginatedPrices>
+}
+
+export interface SubscriptionOps {
+  create(input: CreateSubscriptionInput): Promise<PaymentSubscription>
+  retrieve(id: string): Promise<PaymentSubscription>
+  update(id: string, input: UpdateSubscriptionInput): Promise<PaymentSubscription>
+  cancel(id: string, options?: CancelSubscriptionOptions): Promise<PaymentSubscription>
+  list(options?: ListSubscriptionsOptions): Promise<PaginatedSubscriptions>
+}
+
+export interface PaymentMethodOps {
+  /** Attach a payment method (typically a tokenized card) to a customer. */
+  attach(paymentMethodId: string, customerId: string): Promise<PaymentMethod>
+  /**
+   * Detach a payment method. `customerId` is optional for providers
+   * that can look up the customer from the payment method itself
+   * (Stripe), required for providers that store cards under a
+   * customer scope (Omise). Drivers throw `ProviderUnsupportedError`
+   * when they need `customerId` and the caller omits it.
+   */
+  detach(paymentMethodId: string, customerId?: string): Promise<PaymentMethod>
+  list(customerId: string, options?: ListPaymentMethodsOptions): Promise<PaginatedPaymentMethods>
+}
+
+export interface ChargeOps {
+  create(input: CreateChargeInput): Promise<PaymentCharge>
+  retrieve(id: string): Promise<PaymentCharge>
+  capture(id: string, options?: { amount?: number }): Promise<PaymentCharge>
+  refund(input: CreateRefundInput): Promise<PaymentRefund>
+}
+
+export interface InvoiceOps {
+  retrieve(id: string): Promise<PaymentInvoice>
+  list(options?: ListInvoicesOptions): Promise<PaginatedInvoices>
+  finalize(id: string): Promise<PaymentInvoice>
+  void(id: string): Promise<PaymentInvoice>
+}
+
+export interface CheckoutOps {
+  create(input: CreateCheckoutInput): Promise<PaymentCheckoutSession>
+  retrieve(id: string): Promise<PaymentCheckoutSession>
+}
+
+export interface LinkOps {
+  create(input: CreatePaymentLinkInput): Promise<PaymentLink>
+  retrieve(id: string): Promise<PaymentLink>
+  list(options?: ListPaymentLinksOptions): Promise<PaginatedPaymentLinks>
+  /** Stop accepting new payments via this link. Throws `ProviderUnsupportedError` on drivers that can't (Omise). */
+  deactivate(id: string): Promise<PaymentLink>
+}
+
+export interface WebhookOps {
+  /**
+   * Verify the provider signature against the raw body. Returns
+   * the parsed provider-native event. Throws
+   * `WebhookSignatureError` on failure.
+   */
+  verify(rawBody: string, signature: string): Promise<unknown>
+  /**
+   * Map a provider-native event onto the framework's
+   * `NormalizedWebhookEvent`. Drivers translate the closed
+   * union of types they support; events outside the union map
+   * to `null` and the dispatcher skips user handlers (but still
+   * records the dedup row).
+   */
+  normalize(event: unknown): NormalizedWebhookEvent | null
+}
+
+export interface PaymentDriver {
+  /** Driver identifier — matches the `driver:` discriminator in `ProviderConfig`. */
+  readonly name: string
+  /** App-chosen instance name (`config.payment.providers[name]`). */
+  readonly instanceName: string
+  /** Declared feature set. Apps check this to branch around `ProviderUnsupportedError`. */
+  readonly capabilities: ReadonlySet<PaymentCapability>
+
+  readonly customers: CustomerOps
+  readonly products: ProductOps
+  readonly prices: PriceOps
+  readonly subscriptions: SubscriptionOps
+  readonly paymentMethods: PaymentMethodOps
+  readonly charges: ChargeOps
+  readonly invoices: InvoiceOps
+  readonly checkout: CheckoutOps
+  readonly links: LinkOps
+  readonly webhook: WebhookOps
+}
+
+/** Factory the manager invokes for each configured provider. */
+export type PaymentDriverFactory = (config: {
+  /** App-chosen instance name (`'stripe'`, `'asia'`, …). */
+  instanceName: string
+  /** Provider-config object with `driver:` + driver-specific fields. */
+  config: Record<string, unknown> & { driver: string }
+}) => PaymentDriver

package/src/payment_error.ts

@@ -0,0 +1,159 @@
+/**
+ * `PaymentError` hierarchy — typed wrappers for failures across
+ * the payment stack. Driver-native exceptions (Stripe API errors,
+ * Paddle rate limits, Omise card declines) are preserved on
+ * `.cause` so apps can still `instanceof` the vendor class for
+ * retry / recovery logic; the wrapping just gives the framework a
+ * consistent `StravError` to render through the standard
+ * exception handler.
+ *
+ * Concrete subclasses:
+ *
+ *   - `PaymentConfigError` — `config.payment` missing required
+ *     fields. Thrown at boot from `PaymentProvider`.
+ *
+ *   - `ProviderUnsupportedError` — a driver doesn't implement the
+ *     requested operation (e.g., `omise.checkout.create` when
+ *     hosted checkout isn't available). Thrown synchronously from
+ *     the *Ops call so apps fail fast rather than after a network
+ *     round-trip.
+ *
+ *   - `UnknownProviderError` — `payment.use('x')` for a name not
+ *     configured. 400 — apps usually have a config bug.
+ *
+ *   - `WebhookSignatureError` — provider signature header missing
+ *     or doesn't verify. Webhook route returns 400; the provider
+ *     retries per its backoff schedule.
+ *
+ *   - `WebhookIdempotencyError` — malformed / missing event id.
+ *     400 — apps that hit this usually have a non-provider payload
+ *     reaching the route.
+ *
+ *   - `PaymentProviderError` — generic wrapper around a vendor
+ *     exception that doesn't map to a specific subclass.
+ *     Preserves `.cause`; default status 502 (upstream failure).
+ */
+
+import { StravError } from '@strav/kernel'
+
+export class PaymentError extends StravError {
+  constructor(
+    message: string,
+    options: {
+      code?: string
+      status?: number
+      context?: Record<string, unknown>
+      cause?: unknown
+    } = {},
+  ) {
+    super(
+      message,
+      { code: options.code ?? 'payment.error', status: options.status ?? 500 },
+      {
+        ...(options.context ? { context: options.context } : {}),
+        ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      },
+    )
+  }
+}
+
+export class PaymentConfigError extends PaymentError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'payment.config',
+      status: 500,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}
+
+export class UnknownProviderError extends PaymentError {
+  constructor(name: string, available: readonly string[]) {
+    super(
+      `Payment provider "${name}" is not configured. Available: ${available.join(', ') || '<none>'}.`,
+      {
+        code: 'payment.unknown_provider',
+        status: 400,
+        context: { requested: name, available },
+      },
+    )
+  }
+}
+
+/**
+ * Thrown when a driver doesn't implement the requested operation.
+ * The driver's `capabilities` set declares what it can do; calls
+ * to unsupported operations throw this synchronously so apps fail
+ * fast rather than after the network round-trip.
+ */
+export class ProviderUnsupportedError extends PaymentError {
+  constructor(provider: string, operation: string, options: { reason?: string } = {}) {
+    const trailer = options.reason ? ` ${options.reason}` : ''
+    super(
+      `Payment provider "${provider}" does not support "${operation}".${trailer}`,
+      {
+        code: 'payment.provider_unsupported',
+        status: 400,
+        context: { provider, operation, ...(options.reason ? { reason: options.reason } : {}) },
+      },
+    )
+  }
+}
+
+export class WebhookSignatureError extends PaymentError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'payment.webhook_signature',
+      status: 400,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}
+
+export class WebhookIdempotencyError extends PaymentError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'payment.webhook_idempotency',
+      status: 400,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}
+
+/**
+ * Generic wrapper around a vendor exception. Drivers throw this
+ * for failures that don't map to a more specific subclass —
+ * declined cards, rate limits, etc. The original vendor error is
+ * preserved on `.cause`.
+ */
+export class PaymentProviderError extends PaymentError {
+  constructor(
+    message: string,
+    options: {
+      provider: string
+      operation: string
+      context?: Record<string, unknown>
+      cause?: unknown
+      status?: number
+    },
+  ) {
+    super(message, {
+      code: 'payment.provider_error',
+      status: options.status ?? 502,
+      context: {
+        provider: options.provider,
+        operation: options.operation,
+        ...(options.context ?? {}),
+      },
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}