@strav/payment 1.0.0-alpha.24

package/src/drivers/stripe/webhook/stripe_normalize.ts

@@ -0,0 +1,139 @@
+/**
+ * `stripeNormalize(event)` — map a `Stripe.Event` onto the
+ * framework's `NormalizedWebhookEvent` (or `null` for events
+ * outside the closed union).
+ *
+ * The mapping table covers the events apps most often care
+ * about. Extending it is additive — adding a new case never
+ * breaks an existing handler, and unmapped events still flow
+ * through the dedup ledger (with no user dispatch).
+ *
+ * `_fields` carries the parsed shape the `PaymentLedger`
+ * consumes when ledger sync is on. Keys mirror the matching
+ * DTO field names so the ledger can write directly.
+ */
+
+import type Stripe from 'stripe'
+import type {
+  NormalizedWebhookEvent,
+  PaymentEventType,
+} from '../../../dto/index.ts'
+import { readTenantId } from '../../../tenant_metadata.ts'
+import {
+  toPaymentCustomer,
+  toPaymentInvoice,
+  toPaymentSubscription,
+} from '../mappers/stripe_mappers.ts'
+
+const TYPE_MAP: Record<string, PaymentEventType> = {
+  'customer.created': 'customer.created',
+  'customer.updated': 'customer.updated',
+  'customer.deleted': 'customer.deleted',
+  'customer.subscription.created': 'subscription.created',
+  'customer.subscription.updated': 'subscription.updated',
+  'customer.subscription.deleted': 'subscription.canceled',
+  'customer.subscription.trial_will_end': 'subscription.trial_will_end',
+  'charge.succeeded': 'charge.succeeded',
+  'charge.failed': 'charge.failed',
+  'charge.refunded': 'charge.refunded',
+  'invoice.created': 'invoice.created',
+  'invoice.paid': 'invoice.paid',
+  'invoice.payment_failed': 'invoice.payment_failed',
+  'invoice.voided': 'invoice.voided',
+  'checkout.session.completed': 'checkout.completed',
+  'checkout.session.expired': 'checkout.expired',
+  'payment_method.attached': 'payment_method.attached',
+  'payment_method.detached': 'payment_method.detached',
+}
+
+export function stripeNormalize(event: Stripe.Event): NormalizedWebhookEvent | null {
+  const type = TYPE_MAP[event.type]
+  if (!type) return null
+
+  const data: NormalizedWebhookEvent['data'] = {}
+  let fields: Record<string, unknown> | undefined
+
+  switch (type) {
+    case 'customer.created':
+    case 'customer.updated': {
+      const c = event.data.object as Stripe.Customer
+      data.customerId = c.id
+      const dto = toPaymentCustomer(c)
+      fields = { ...dto }
+      break
+    }
+    case 'customer.deleted': {
+      const c = event.data.object as Stripe.Customer
+      data.customerId = c.id
+      break
+    }
+    case 'subscription.created':
+    case 'subscription.updated':
+    case 'subscription.canceled':
+    case 'subscription.trial_will_end': {
+      const s = event.data.object as Stripe.Subscription
+      const dto = toPaymentSubscription(s)
+      data.subscriptionId = dto.id
+      data.customerId = dto.customerId
+      fields = { ...dto }
+      break
+    }
+    case 'charge.succeeded':
+    case 'charge.failed':
+    case 'charge.refunded': {
+      const c = event.data.object as Stripe.Charge
+      data.chargeId = c.id
+      if (typeof c.customer === 'string') data.customerId = c.customer
+      break
+    }
+    case 'invoice.created':
+    case 'invoice.paid':
+    case 'invoice.payment_failed':
+    case 'invoice.voided': {
+      const i = event.data.object as Stripe.Invoice
+      const dto = toPaymentInvoice(i)
+      data.invoiceId = dto.id
+      data.customerId = dto.customerId
+      if (dto.subscriptionId) data.subscriptionId = dto.subscriptionId
+      fields = { ...dto }
+      break
+    }
+    case 'checkout.completed':
+    case 'checkout.expired': {
+      const s = event.data.object as Stripe.Checkout.Session
+      data.checkoutId = s.id
+      if (typeof s.customer === 'string') data.customerId = s.customer
+      if (typeof s.subscription === 'string') data.subscriptionId = s.subscription
+      break
+    }
+    case 'payment_method.attached':
+    case 'payment_method.detached': {
+      const pm = event.data.object as Stripe.PaymentMethod
+      data.paymentMethodId = pm.id
+      if (typeof pm.customer === 'string') data.customerId = pm.customer
+      break
+    }
+  }
+
+  // Read the framework's tenant key off whatever resource the
+  // event carries. Stripe echoes `metadata` on every resource
+  // type, so the same lookup works across customer / subscription
+  // / invoice / charge / checkout payloads.
+  const resourceMeta =
+    (event.data.object as { metadata?: Record<string, unknown> } | undefined)
+      ?.metadata ?? null
+  const tenantId = readTenantId(resourceMeta)
+
+  const normalized: NormalizedWebhookEvent = {
+    id: event.id,
+    type,
+    provider: 'stripe',
+    raw: event,
+    data,
+    ...(tenantId ? { tenantId } : {}),
+  }
+  if (fields) {
+    ;(normalized as { _fields?: unknown })._fields = fields
+  }
+  return normalized
+}

package/src/drivers/unsupported.ts

@@ -0,0 +1,20 @@
+/**
+ * `unsupported(provider, operation)` — helper for drivers to
+ * stub out *Ops methods they can't fulfil. Returns a function
+ * that throws `ProviderUnsupportedError` synchronously when
+ * called. Drivers attach the returned function to the relevant
+ * `*Ops` key and omit the matching `PaymentCapability` from
+ * `capabilities`.
+ */
+
+import { ProviderUnsupportedError } from '../payment_error.ts'
+
+export function unsupported(
+  provider: string,
+  operation: string,
+  reason?: string,
+): (...args: unknown[]) => never {
+  return () => {
+    throw new ProviderUnsupportedError(provider, operation, reason ? { reason } : {})
+  }
+}

package/src/dto/index.ts

@@ -0,0 +1,72 @@
+/** Barrel for normalized DTOs + input shapes. */
+
+export type {
+  CreateCustomerInput,
+  ListCustomersOptions,
+  PaginatedCustomers,
+  PaymentCustomer,
+  UpdateCustomerInput,
+} from './payment_customer.ts'
+export type {
+  CreateProductInput,
+  ListProductsOptions,
+  PaginatedProducts,
+  PaymentProduct,
+  UpdateProductInput,
+} from './payment_product.ts'
+export type {
+  CreatePriceInput,
+  ListPricesOptions,
+  PaginatedPrices,
+  PaymentPrice,
+} from './payment_price.ts'
+export type {
+  CancelSubscriptionOptions,
+  CreateSubscriptionInput,
+  ListSubscriptionsOptions,
+  PaginatedSubscriptions,
+  PaymentSubscription,
+  SubscriptionStatus,
+  UpdateSubscriptionInput,
+} from './payment_subscription.ts'
+export type {
+  ListPaymentMethodsOptions,
+  PaginatedPaymentMethods,
+  PaymentMethod,
+  PaymentMethodKind,
+} from './payment_method.ts'
+export type {
+  ChargeStatus,
+  CreateChargeInput,
+  CreateRefundInput,
+  PaymentCharge,
+  PaymentMethodSpec,
+  PaymentNextAction,
+  PaymentRefund,
+} from './payment_charge.ts'
+export type {
+  InvoiceStatus,
+  ListInvoicesOptions,
+  PaginatedInvoices,
+  PaymentInvoice,
+} from './payment_invoice.ts'
+export type {
+  CheckoutLineItem,
+  CheckoutMode,
+  CheckoutStatus,
+  CreateCheckoutInput,
+  PaymentCheckoutSession,
+} from './payment_checkout.ts'
+export type {
+  CreatePaymentLinkInput,
+  ListPaymentLinksOptions,
+  PaginatedPaymentLinks,
+  PaymentLink,
+} from './payment_link.ts'
+export type {
+  NormalizedWebhookEvent,
+  PaymentEventType,
+  WebhookHandler,
+  WebhookHandlerContext,
+  WebhookHandlerFilter,
+} from './payment_event.ts'

package/src/dto/payment_charge.ts

@@ -0,0 +1,158 @@
+/**
+ * `PaymentCharge` — normalized one-shot charge result.
+ *
+ * Both successful and failed attempts are returned via this DTO
+ * (use `status` to distinguish). Vendor exceptions for invalid
+ * input — bad currency code, missing customer — are still raised
+ * as `PaymentProviderError`.
+ *
+ * Async payment methods (PromptPay, PayNow, redirect wallets,
+ * 3DS bank challenges, convenience-store vouchers) settle in two
+ * steps: the framework returns `status: 'requires_action'` plus a
+ * `nextAction` discriminator the app uses to drive the UI (show
+ * QR, redirect to URL, render voucher). Settlement arrives via
+ * the provider's `charge.succeeded` / `charge.failed` webhook.
+ */
+
+export type ChargeStatus =
+  | 'succeeded'
+  | 'pending'
+  | 'failed'
+  | 'refunded'
+  | 'partial_refunded'
+  | 'requires_action'
+
+/**
+ * What the app must do next to drive an async charge to
+ * settlement. Null on synchronous (card) charges.
+ *
+ * - `display_qr`  show a QR the customer scans with their banking app
+ *                 (PromptPay, PayNow, FPS, WeChat Pay in some flows).
+ *                 `qrData` is the encoded string; `qrImageUrl` is a
+ *                 hosted PNG when the provider gives one.
+ * - `redirect`    send the customer to a wallet / bank page
+ *                 (TrueMoney, Alipay, GrabPay, KakaoPay, …).
+ *                 Returns to `CreateChargeInput.returnUrl`.
+ * - `authorize`   3DS bank challenge — same shape as `redirect` but
+ *                 semantically distinct (card holder verification,
+ *                 not a wallet handoff).
+ * - `voucher`     convenience-store voucher / Boleto — show the
+ *                 reference number + barcode for the customer to
+ *                 pay at a physical counter.
+ * - `wait`        the charge is in flight on bank rails; nothing
+ *                 to display. Apps poll or wait for the webhook.
+ */
+export type PaymentNextAction =
+  | { kind: 'display_qr'; qrData: string; qrImageUrl?: string; expiresAt?: Date }
+  | { kind: 'redirect'; url: string; expiresAt?: Date }
+  | { kind: 'authorize'; url: string; expiresAt?: Date }
+  | { kind: 'voucher'; reference: string; barcodeImageUrl?: string; expiresAt?: Date }
+  | { kind: 'wait' }
+
+/**
+ * Structured payment-method spec — drivers materialize the
+ * underlying source / token / etc. server-side. Apps that have
+ * a pre-tokenized card id can keep passing a string for
+ * back-compatibility; the spec is required for QR / wallet /
+ * voucher methods because there's no single id to pass.
+ *
+ * Open-by-extension via the framework's `PaymentMethodSpec`
+ * union: when a future driver supports a method not listed here,
+ * the union grows and existing drivers throw
+ * `ProviderUnsupportedError` until they implement it.
+ */
+export type PaymentMethodSpec =
+  | { kind: 'card'; token: string }
+  | { kind: 'promptpay' }
+  | { kind: 'paynow' }
+  | { kind: 'fps' }
+  | { kind: 'truemoney'; phoneNumber: string }
+  | { kind: 'alipay' }
+  | { kind: 'wechat_pay' }
+  | { kind: 'grabpay' }
+  | { kind: 'kakaopay' }
+  | { kind: 'rabbit_linepay' }
+  | { kind: 'konbini'; phoneNumber?: string }
+
+export interface PaymentCharge {
+  id: string
+  provider: string
+  customerId: string | null
+  amount: number
+  currency: string
+  status: ChargeStatus
+  paymentMethodId: string | null
+  /** Failure code from the provider — `'card_declined'`, etc. Stable across drivers when possible. */
+  failureCode: string | null
+  failureMessage: string | null
+  /**
+   * Populated when `status === 'requires_action'` (and sometimes
+   * `'pending'`). Null for synchronous charges that settled
+   * immediately.
+   */
+  nextAction: PaymentNextAction | null
+  metadata: Record<string, string>
+  createdAt: Date
+  raw: unknown
+}
+
+export interface CreateChargeInput {
+  amount: number
+  currency: string
+  customer?: string
+  /**
+   * Either a pre-tokenized payment-method id (`'pm_xxx'` /
+   * `'tokn_xxx'`) — the v1 shape, kept for back-compat — or a
+   * structured spec (`{ kind: 'promptpay' }`, `{ kind: 'card',
+   * token: 'tokn_xxx' }`, …). Specs are required for methods
+   * that have no single id to reference (QR / wallet / voucher).
+   */
+  paymentMethod?: string | PaymentMethodSpec
+  description?: string
+  metadata?: Record<string, string>
+  /**
+   * Stripe-style: `true` triggers immediate capture; `false`
+   * authorises only (apps call `capture` later). Drivers without
+   * holds throw `ProviderUnsupportedError` when `false`.
+   */
+  capture?: boolean
+  /**
+   * Where the provider returns the customer after a `redirect`
+   * or `authorize` next-action. Required for redirect wallets +
+   * 3DS challenges; ignored for synchronous card charges.
+   * Apps usually set a global default via
+   * `config.payment.returnUrl` and override per-call when
+   * needed.
+   */
+  returnUrl?: string
+  /**
+   * Provider-side idempotency key. Drivers with the `idempotency`
+   * capability dedup retried calls with the same key for ~24h
+   * (Stripe). Drivers without the capability silently ignore
+   * — apps that need guaranteed dedup on those providers build
+   * it app-side (claim the key in a DB table before calling).
+   */
+  idempotencyKey?: string
+}
+
+export interface CreateRefundInput {
+  charge: string
+  /** Amount in minor unit. Omitted = full refund. */
+  amount?: number
+  reason?: string
+  metadata?: Record<string, string>
+  /** See `CreateChargeInput.idempotencyKey`. */
+  idempotencyKey?: string
+}
+
+export interface PaymentRefund {
+  id: string
+  provider: string
+  chargeId: string
+  amount: number
+  currency: string
+  status: 'pending' | 'succeeded' | 'failed'
+  reason: string | null
+  createdAt: Date
+  raw: unknown
+}

package/src/dto/payment_checkout.ts

@@ -0,0 +1,46 @@
+/**
+ * `PaymentCheckoutSession` — normalized hosted-checkout session.
+ * Apps redirect the customer to `url`; the provider walks them
+ * through payment and posts back a `checkout.completed` webhook
+ * when done.
+ */
+
+export type CheckoutMode = 'payment' | 'subscription' | 'setup'
+
+export type CheckoutStatus = 'open' | 'complete' | 'expired'
+
+export interface CheckoutLineItem {
+  price: string
+  quantity?: number
+}
+
+export interface PaymentCheckoutSession {
+  id: string
+  provider: string
+  mode: CheckoutMode
+  status: CheckoutStatus
+  /** Hosted-checkout URL. Apps redirect the user here. */
+  url: string
+  customerId: string | null
+  /** Once `complete`, the resulting subscription / payment id (driver-specific shape). */
+  paymentIntentId: string | null
+  subscriptionId: string | null
+  expiresAt: Date | null
+  metadata: Record<string, string>
+  createdAt: Date
+  raw: unknown
+}
+
+export interface CreateCheckoutInput {
+  mode: CheckoutMode
+  items: readonly CheckoutLineItem[]
+  successUrl: string
+  cancelUrl: string
+  customer?: string
+  customerEmail?: string
+  /** Trial days when `mode === 'subscription'`. */
+  trialDays?: number
+  metadata?: Record<string, string>
+  /** See `CreateChargeInput.idempotencyKey`. */
+  idempotencyKey?: string
+}

package/src/dto/payment_customer.ts

@@ -0,0 +1,52 @@
+/**
+ * `PaymentCustomer` — normalized view of a customer record
+ * across providers. Provider-specific shape lives in `.raw`.
+ */
+
+export interface PaymentCustomer {
+  /** Provider-native id (`cus_xxx` for Stripe, `ctm_xxx` for Stripe, etc.). */
+  id: string
+  /** Driver name — `'stripe'`, `'paddle'`, `'omise'`, … */
+  provider: string
+  email: string
+  name?: string
+  phone?: string
+  metadata: Record<string, string>
+  createdAt: Date
+  /** Native provider object. Use only when you need a field the normalized DTO doesn't expose. */
+  raw: unknown
+}
+
+export interface CreateCustomerInput {
+  email: string
+  name?: string
+  phone?: string
+  metadata?: Record<string, string>
+  /**
+   * Provider-side idempotency key. Drivers with the `idempotency`
+   * capability dedup retried calls with the same key for ~24h
+   * (Stripe). Drivers without the capability silently ignore.
+   */
+  idempotencyKey?: string
+}
+
+export interface UpdateCustomerInput {
+  email?: string
+  name?: string
+  phone?: string
+  metadata?: Record<string, string>
+}
+
+export interface ListCustomersOptions {
+  /** Driver-defined cursor — passed through verbatim to the next page call. */
+  cursor?: string
+  limit?: number
+  /** Email filter — exact match. Drivers that don't support filtering ignore this and apps filter client-side. */
+  email?: string
+}
+
+export interface PaginatedCustomers {
+  data: PaymentCustomer[]
+  /** Opaque cursor for the next page. `null` when the listing is exhausted. */
+  nextCursor: string | null
+}

package/src/dto/payment_event.ts

@@ -0,0 +1,83 @@
+/**
+ * Normalized webhook event types. Drivers map their native event
+ * shapes (`invoice.paid`, `subscription_created`, …) onto this
+ * closed union. Apps register handlers by normalized type; the
+ * native event is on `ctx.raw`.
+ */
+
+export type PaymentEventType =
+  | 'customer.created'
+  | 'customer.updated'
+  | 'customer.deleted'
+  | 'subscription.created'
+  | 'subscription.updated'
+  | 'subscription.canceled'
+  | 'subscription.trial_will_end'
+  | 'charge.succeeded'
+  | 'charge.failed'
+  | 'charge.refunded'
+  | 'invoice.created'
+  | 'invoice.paid'
+  | 'invoice.payment_failed'
+  | 'invoice.voided'
+  | 'checkout.completed'
+  | 'checkout.expired'
+  | 'payment_method.attached'
+  | 'payment_method.detached'
+
+export interface NormalizedWebhookEvent {
+  /** Driver-assigned id; the dedup key. */
+  id: string
+  /** Normalized type from the closed union above. */
+  type: PaymentEventType
+  /**
+   * After the dispatcher routes the event, this is the app-chosen
+   * **instance name** (the `:provider` route param, matches
+   * `payment.use(name)`). Drivers' `normalize` set it to the
+   * driver name (`'stripe'` / `'omise'`); the dispatcher
+   * overrides with the instance name.
+   */
+  provider: string
+  /**
+   * Strav tenant id pulled from the original create call's
+   * metadata (`metadata.strav_tenant_id`). When set, the
+   * dispatcher wraps ledger writes + user handlers in
+   * `TenantManager.withTenant(tenantId, ...)`. Undefined when
+   * the originating call didn't stamp a tenant — multi-tenant
+   * apps that forget the stamp see ledger writes skipped + a
+   * one-shot warning.
+   */
+  tenantId?: string
+  /** Native provider event payload. */
+  raw: unknown
+  /** Convenience accessors for the most common downstream resources. */
+  data: {
+    customerId?: string
+    subscriptionId?: string
+    invoiceId?: string
+    chargeId?: string
+    checkoutId?: string
+    paymentMethodId?: string
+  }
+}
+
+export interface WebhookHandlerContext {
+  event: NormalizedWebhookEvent
+  /** Convenience shortcut for `event.id`. */
+  eventId: string
+  /** Convenience shortcut for `event.type`. */
+  eventType: PaymentEventType
+  /** Convenience shortcut for `event.provider`. */
+  provider: string
+  /** Convenience shortcut for `event.tenantId`. */
+  tenantId?: string
+  /** Convenience shortcut for `event.raw`. */
+  raw: unknown
+}
+
+export type WebhookHandler = (ctx: WebhookHandlerContext) => void | Promise<void>
+
+export interface WebhookHandlerFilter {
+  /** Restrict the handler to one provider. Omitted = fires for any provider that emits the type. */
+  provider?: string
+}

package/src/dto/payment_invoice.ts

@@ -0,0 +1,39 @@
+/**
+ * `PaymentInvoice` — normalized invoice record (whether issued
+ * by a subscription cycle or manually drafted).
+ */
+
+export type InvoiceStatus = 'draft' | 'open' | 'paid' | 'uncollectible' | 'void'
+
+export interface PaymentInvoice {
+  id: string
+  provider: string
+  customerId: string
+  subscriptionId: string | null
+  status: InvoiceStatus
+  amount: number
+  amountPaid: number
+  amountDue: number
+  currency: string
+  /** Provider-hosted invoice URL — null when not hosted (e.g., draft state). */
+  hostedUrl: string | null
+  pdfUrl: string | null
+  dueAt: Date | null
+  paidAt: Date | null
+  metadata: Record<string, string>
+  createdAt: Date
+  raw: unknown
+}
+
+export interface ListInvoicesOptions {
+  customer?: string
+  subscription?: string
+  status?: InvoiceStatus
+  cursor?: string
+  limit?: number
+}
+
+export interface PaginatedInvoices {
+  data: PaymentInvoice[]
+  nextCursor: string | null
+}

package/src/dto/payment_link.ts

@@ -0,0 +1,81 @@
+/**
+ * `PaymentLink` — normalized shareable payment URL.
+ *
+ * A payment link is a one-shot hosted page the customer opens to
+ * pay. Distinct from `PaymentCheckoutSession` because links are
+ * meant to be shared (email, SMS, QR code on a poster) and reused
+ * across customers; checkout sessions are tied to a single
+ * customer journey.
+ *
+ * Provider divergence the framework intentionally surfaces:
+ *
+ *   - **Stripe** requires a catalogue Price id (`items` input);
+ *     ad-hoc amounts aren't supported. Apps create a Price first
+ *     via `payment.prices.create({...})` then pass `items`.
+ *   - **Omise** has no Prices catalogue. Apps pass `amount`,
+ *     `currency`, `title`, `description` directly.
+ *
+ * Both inputs are optional on `CreatePaymentLinkInput`; drivers
+ * validate which shape they need and throw a clear
+ * `PaymentConfigError` when the wrong one is passed.
+ *
+ * Lifecycle:
+ *
+ *   - `active === true` — link accepts new payments.
+ *   - `active === false` — link is deactivated; existing
+ *     in-flight payments still settle.
+ *   - `reusable === false` — single-use; the link becomes
+ *     `used` after the first successful payment (Omise's default).
+ *   - `reusable === true` — repeatable; Stripe's default.
+ */
+
+export interface PaymentLink {
+  id: string
+  provider: string
+  /** Hosted-checkout URL the customer opens to pay. */
+  url: string
+  /** Ad-hoc amount in minor units. `null` when Stripe link references a Price. */
+  amount: number | null
+  /** ISO 4217 (lowercase). `null` when Stripe link is multi-price. */
+  currency: string | null
+  active: boolean
+  /** True when the link can take multiple payments. */
+  reusable: boolean
+  title?: string
+  description?: string
+  metadata: Record<string, string>
+  createdAt: Date
+  raw: unknown
+}
+
+export interface CreatePaymentLinkInput {
+  /** Stripe path: required. Omise: throw ProviderUnsupportedError if passed. */
+  items?: ReadonlyArray<{ price: string; quantity?: number }>
+  /** Omise path: amount + currency + title + description. Stripe: throw if used without `items`. */
+  amount?: number
+  currency?: string
+  title?: string
+  description?: string
+  /**
+   * Whether the link can take multiple payments. Stripe defaults
+   * to `true`; Omise to `false`. Apps that need uniform behaviour
+   * pass an explicit value.
+   */
+  reusable?: boolean
+  metadata?: Record<string, string>
+  /** Stripe: redirect URL after completion. Ignored by Omise (uses provider-default success page). */
+  afterCompletionRedirect?: string
+  /** See `CreateChargeInput.idempotencyKey`. */
+  idempotencyKey?: string
+}
+
+export interface ListPaymentLinksOptions {
+  cursor?: string
+  limit?: number
+  active?: boolean
+}
+
+export interface PaginatedPaymentLinks {
+  data: PaymentLink[]
+  nextCursor: string | null
+}