@strav/payment 1.0.0-alpha.24

package/src/drivers/omise/omise_webhook.ts

@@ -0,0 +1,162 @@
+/**
+ * Omise webhook signature verification + event normalization.
+ *
+ * Omise signs webhook deliveries with HMAC SHA-256 over the raw
+ * body using the webhook secret from the Dashboard. The signature
+ * is sent in `X-Omise-Signature` as a hex digest. The SDK doesn't
+ * bundle a verifier — we implement it here.
+ *
+ * Event shape: `{ id, object: 'event', key, created_at, data }`
+ * where `key` is the event name (`'charge.complete'`,
+ * `'customer.create'`, …). We map the common keys onto the
+ * framework's `PaymentEventType` union.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { WebhookSignatureError } from '../../payment_error.ts'
+import type {
+  NormalizedWebhookEvent,
+  PaymentEventType,
+} from '../../dto/payment_event.ts'
+import { readTenantId } from '../../tenant_metadata.ts'
+import {
+  toPaymentCharge,
+  toPaymentCustomer,
+  type OmiseCharge,
+  type OmiseCustomer,
+} from './omise_mappers.ts'
+import {
+  toPaymentSubscription as toPaymentSubscriptionFromSchedule,
+  type OmiseSchedule,
+} from './omise_schedule_mapper.ts'
+
+interface OmiseEvent {
+  id: string
+  object: 'event'
+  key: string
+  created_at?: string
+  created?: string
+  data: { object?: unknown; [k: string]: unknown }
+}
+
+const TYPE_MAP: Record<string, PaymentEventType> = {
+  'customer.create': 'customer.created',
+  'customer.update': 'customer.updated',
+  'customer.destroy': 'customer.deleted',
+  'charge.create': 'charge.succeeded',
+  'charge.complete': 'charge.succeeded',
+  'charge.update': 'charge.succeeded',
+  'charge.capture': 'charge.succeeded',
+  'charge.expire': 'charge.failed',
+  'refund.create': 'charge.refunded',
+  'schedule.create': 'subscription.created',
+  'schedule.update': 'subscription.updated',
+  'schedule.destroy': 'subscription.canceled',
+}
+
+/**
+ * Verify an Omise webhook signature against the raw body using
+ * the configured secret. Throws `WebhookSignatureError` on
+ * mismatch or missing secret. Returns the parsed event payload
+ * on success.
+ */
+export async function omiseVerify(
+  rawBody: string,
+  signature: string,
+  webhookSecret: string | undefined,
+): Promise<OmiseEvent> {
+  if (!webhookSecret) {
+    throw new WebhookSignatureError(
+      'OmisePaymentDriver.webhook.verify: `webhookSecret` is not set on the provider config.',
+    )
+  }
+  const expected = createHmac('sha256', webhookSecret).update(rawBody).digest('hex')
+  const provided = signature.trim()
+  // Use Uint8Array views to dodge the Buffer<ArrayBufferLike>
+  // mismatch with `timingSafeEqual`'s `ArrayBufferView`-typed
+  // params. Hex strings of unequal length are always rejected.
+  const expectedBuf = new Uint8Array(Buffer.from(expected, 'hex'))
+  const providedBuf = new Uint8Array(Buffer.from(provided, 'hex'))
+  if (
+    expectedBuf.length === 0 ||
+    expectedBuf.length !== providedBuf.length ||
+    !timingSafeEqual(expectedBuf, providedBuf)
+  ) {
+    throw new WebhookSignatureError(
+      'OmisePaymentDriver.webhook.verify: signature mismatch.',
+    )
+  }
+  try {
+    return JSON.parse(rawBody) as OmiseEvent
+  } catch (cause) {
+    throw new WebhookSignatureError(
+      'OmisePaymentDriver.webhook.verify: body is not valid JSON.',
+      { cause },
+    )
+  }
+}
+
+export function omiseNormalize(event: OmiseEvent): NormalizedWebhookEvent | null {
+  const type = TYPE_MAP[event.key]
+  if (!type) return null
+  const data: NormalizedWebhookEvent['data'] = {}
+  let fields: Record<string, unknown> | undefined
+  const object = event.data.object
+
+  switch (type) {
+    case 'customer.created':
+    case 'customer.updated':
+      if (object && typeof object === 'object') {
+        const dto = toPaymentCustomer(object as OmiseCustomer)
+        data.customerId = dto.id
+        fields = { ...dto }
+      }
+      break
+    case 'customer.deleted':
+      if (object && typeof object === 'object' && 'id' in (object as { id?: string })) {
+        data.customerId = (object as { id: string }).id
+      }
+      break
+    case 'charge.succeeded':
+    case 'charge.failed':
+    case 'charge.refunded':
+      if (object && typeof object === 'object') {
+        const dto = toPaymentCharge(object as OmiseCharge)
+        data.chargeId = dto.id
+        if (dto.customerId) data.customerId = dto.customerId
+      }
+      break
+    case 'subscription.created':
+    case 'subscription.updated':
+    case 'subscription.canceled':
+      if (object && typeof object === 'object') {
+        const dto = toPaymentSubscriptionFromSchedule(object as OmiseSchedule)
+        data.subscriptionId = dto.id
+        if (dto.customerId) data.customerId = dto.customerId
+        fields = { ...dto }
+      }
+      break
+  }
+
+  // Same convention as Stripe: read `strav_tenant_id` off the
+  // event's underlying resource metadata. Omise echoes metadata
+  // verbatim on every event the framework cares about.
+  const resourceMeta =
+    (object as { metadata?: Record<string, unknown> } | undefined)?.metadata ?? null
+  const tenantId = readTenantId(resourceMeta)
+
+  const normalized: NormalizedWebhookEvent = {
+    id: event.id,
+    type,
+    provider: 'omise',
+    raw: event,
+    data,
+    ...(tenantId ? { tenantId } : {}),
+  }
+  if (fields) {
+    ;(normalized as { _fields?: unknown })._fields = fields
+  }
+  return normalized
+}
+
+export type { OmiseEvent }

package/src/drivers/payment_method_helpers.ts

@@ -0,0 +1,35 @@
+/**
+ * Helpers for handling `CreateChargeInput.paymentMethod` —
+ * `string | PaymentMethodSpec`.
+ *
+ * `extractCardToken` collapses both back-compat shapes (raw
+ * tokenized id string, `{ kind: 'card', token }` spec) onto a
+ * single token id. Specs of any other kind are not card flows;
+ * the helper signals that with `null`. Drivers then decide
+ * whether to route into their async-method pipeline (slices
+ * 7.2 / 7.3) or throw `ProviderUnsupportedError`.
+ *
+ * Drivers that don't yet support async methods can:
+ *   const token = extractCardToken(input.paymentMethod)
+ *   if (input.paymentMethod && !token) throw new ProviderUnsupportedError(...)
+ *   // …pass `token` as before
+ */
+
+import type { PaymentMethodSpec } from '../dto/payment_charge.ts'
+
+export function extractCardToken(
+  pm: string | PaymentMethodSpec | undefined,
+): string | null {
+  if (pm === undefined) return null
+  if (typeof pm === 'string') return pm
+  if (pm.kind === 'card') return pm.token
+  return null
+}
+
+export function paymentMethodKind(
+  pm: string | PaymentMethodSpec | undefined,
+): PaymentMethodSpec['kind'] | 'unspecified' {
+  if (pm === undefined) return 'unspecified'
+  if (typeof pm === 'string') return 'card'
+  return pm.kind
+}

package/src/drivers/stripe/index.ts

@@ -0,0 +1,40 @@
+// Public API of `@strav/payment/stripe`.
+//
+// Subpath barrel for the Stripe driver. Apps import from here to
+// register the adapter:
+//
+// ```ts
+// import { StripePaymentProvider } from '@strav/payment/stripe'
+//
+// export default [PaymentProvider, StripePaymentProvider, ...]
+// ```
+//
+// `StripePaymentDriver` + mapper exports are advanced — used by
+// tests and by apps that hand-wire a driver instance via
+// `manager.useDriver(name, driver)`.
+
+export {
+  toPaymentCharge,
+  toPaymentCheckoutSession,
+  toPaymentCustomer,
+  toPaymentInvoice,
+  toPaymentLink,
+  toPaymentMethod,
+  toPaymentPrice,
+  toPaymentProduct,
+  toPaymentSubscription,
+} from './mappers/stripe_mappers.ts'
+export {
+  buildStripeMethodWiring,
+  STRIPE_SUPPORTED_METHOD_KINDS,
+  type StripeMethodBuildResult,
+  type StripeMethodWiring,
+} from './mappers/stripe_method_spec.ts'
+export { stripeNextAction } from './mappers/stripe_next_action_mapper.ts'
+export type { StripeProviderConfig } from './stripe_config.ts'
+export {
+  StripePaymentDriver,
+  type StripeDriverOptions,
+} from './stripe_driver.ts'
+export { StripePaymentProvider } from './stripe_provider.ts'
+export { stripeNormalize } from './webhook/stripe_normalize.ts'

package/src/drivers/stripe/mappers/stripe_mappers.ts

@@ -0,0 +1,312 @@
+/**
+ * Stripe ↔ normalized-DTO mappers. One function per resource;
+ * each converts a `Stripe.<X>` SDK object into the framework's
+ * `Payment<X>` DTO with the native object on `.raw`.
+ *
+ * Field name conventions:
+ *   - Stripe timestamps are unix seconds; we multiply by 1000.
+ *   - Stripe metadata is `Record<string, string>` directly.
+ *   - Missing-from-Stripe-but-required-by-DTO falls back to
+ *     sensible defaults (empty string, `{}`); never invent ids.
+ */
+
+import type Stripe from 'stripe'
+import type {
+  ChargeStatus,
+  InvoiceStatus,
+  PaymentCharge,
+  PaymentCheckoutSession,
+  PaymentCustomer,
+  PaymentInvoice,
+  PaymentMethod,
+  PaymentPrice,
+  PaymentProduct,
+  PaymentSubscription,
+  SubscriptionStatus,
+} from '../../../dto/index.ts'
+
+const PROVIDER = 'stripe'
+
+function toDate(unix: number | null | undefined): Date | null {
+  if (unix === null || unix === undefined) return null
+  return new Date(unix * 1000)
+}
+
+function metadata(m: Stripe.Metadata | null | undefined): Record<string, string> {
+  if (!m) return {}
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(m)) {
+    if (v === null) continue
+    out[k] = String(v)
+  }
+  return out
+}
+
+export function toPaymentCustomer(c: Stripe.Customer): PaymentCustomer {
+  return {
+    id: c.id,
+    provider: PROVIDER,
+    email: c.email ?? '',
+    ...(c.name ? { name: c.name } : {}),
+    ...(c.phone ? { phone: c.phone } : {}),
+    metadata: metadata(c.metadata),
+    createdAt: new Date(c.created * 1000),
+    raw: c,
+  }
+}
+
+export function toPaymentProduct(p: Stripe.Product): PaymentProduct {
+  return {
+    id: p.id,
+    provider: PROVIDER,
+    name: p.name,
+    ...(p.description ? { description: p.description } : {}),
+    active: p.active,
+    metadata: metadata(p.metadata),
+    createdAt: new Date(p.created * 1000),
+    raw: p,
+  }
+}
+
+export function toPaymentPrice(p: Stripe.Price): PaymentPrice {
+  return {
+    id: p.id,
+    provider: PROVIDER,
+    productId: typeof p.product === 'string' ? p.product : (p.product as { id: string }).id,
+    amount: p.unit_amount ?? 0,
+    currency: p.currency,
+    type: p.type === 'recurring' ? 'recurring' : 'one_time',
+    ...(p.recurring?.interval
+      ? { interval: p.recurring.interval as PaymentPrice['interval'] }
+      : {}),
+    ...(p.recurring?.interval_count
+      ? { intervalCount: p.recurring.interval_count }
+      : {}),
+    active: p.active,
+    metadata: metadata(p.metadata),
+    createdAt: new Date(p.created * 1000),
+    raw: p,
+  }
+}
+
+const SUBSCRIPTION_STATUS_MAP: Record<Stripe.Subscription.Status, SubscriptionStatus> = {
+  active: 'active',
+  trialing: 'trialing',
+  past_due: 'past_due',
+  canceled: 'canceled',
+  unpaid: 'past_due',
+  incomplete: 'incomplete',
+  incomplete_expired: 'canceled',
+  paused: 'paused',
+}
+
+export function toPaymentSubscription(s: Stripe.Subscription): PaymentSubscription {
+  // Stripe sometimes nests the actual price on items.data[0].price.
+  const firstItem = s.items.data[0]
+  const priceId = firstItem
+    ? typeof firstItem.price === 'string'
+      ? firstItem.price
+      : firstItem.price.id
+    : ''
+  // `current_period_start/end` moved to the item level in recent API
+  // versions; fall back across both shapes.
+  const sAny = s as unknown as { current_period_start?: number; current_period_end?: number }
+  const itemAny = firstItem as unknown as
+    | { current_period_start?: number; current_period_end?: number }
+    | undefined
+  const periodStart = sAny.current_period_start ?? itemAny?.current_period_start ?? s.start_date
+  const periodEnd = sAny.current_period_end ?? itemAny?.current_period_end ?? s.start_date
+  return {
+    id: s.id,
+    provider: PROVIDER,
+    customerId: typeof s.customer === 'string' ? s.customer : (s.customer as { id: string }).id,
+    priceId,
+    status: SUBSCRIPTION_STATUS_MAP[s.status] ?? 'active',
+    currentPeriodStart: new Date(periodStart * 1000),
+    currentPeriodEnd: new Date(periodEnd * 1000),
+    cancelAt: toDate(s.cancel_at),
+    canceledAt: toDate(s.canceled_at),
+    trialStart: toDate(s.trial_start),
+    trialEnd: toDate(s.trial_end),
+    metadata: metadata(s.metadata),
+    createdAt: new Date(s.created * 1000),
+    raw: s,
+  }
+}
+
+function paymentMethodKind(kind: string): PaymentMethod['kind'] {
+  switch (kind) {
+    case 'card':
+      return 'card'
+    case 'us_bank_account':
+    case 'bank_account':
+      return 'bank_account'
+    case 'sepa_debit':
+      return 'sepa_debit'
+    case 'paypal':
+      return 'paypal'
+    default:
+      return 'other'
+  }
+}
+
+export function toPaymentMethod(pm: Stripe.PaymentMethod): PaymentMethod {
+  const card = pm.card
+  return {
+    id: pm.id,
+    provider: PROVIDER,
+    customerId:
+      typeof pm.customer === 'string'
+        ? pm.customer
+        : pm.customer
+          ? (pm.customer as { id: string }).id
+          : null,
+    kind: paymentMethodKind(pm.type),
+    ...(card?.brand ? { brand: card.brand } : {}),
+    ...(card?.last4 ? { last4: card.last4 } : {}),
+    ...(card?.exp_month ? { expMonth: card.exp_month } : {}),
+    ...(card?.exp_year ? { expYear: card.exp_year } : {}),
+    metadata: metadata(pm.metadata),
+    createdAt: new Date(pm.created * 1000),
+    raw: pm,
+  }
+}
+
+const CHARGE_STATUS_MAP: Record<Stripe.Charge.Status, ChargeStatus> = {
+  succeeded: 'succeeded',
+  pending: 'pending',
+  failed: 'failed',
+}
+
+export function toPaymentCharge(c: Stripe.Charge): PaymentCharge {
+  const status: ChargeStatus = c.refunded
+    ? c.amount_refunded === c.amount
+      ? 'refunded'
+      : 'partial_refunded'
+    : (CHARGE_STATUS_MAP[c.status] ?? 'pending')
+  return {
+    id: c.id,
+    provider: PROVIDER,
+    customerId: typeof c.customer === 'string' ? c.customer : (c.customer as { id: string } | null)?.id ?? null,
+    amount: c.amount,
+    currency: c.currency,
+    status,
+    paymentMethodId:
+      typeof c.payment_method === 'string'
+        ? c.payment_method
+        : (c.payment_method as { id: string } | null)?.id ?? null,
+    failureCode: c.failure_code,
+    failureMessage: c.failure_message,
+    // Settled charges don't carry a next-action. The intent-level
+    // mapper used by `charges.create` populates `nextAction` from
+    // `PaymentIntent.next_action` when the charge is still in
+    // `requires_action`; that lands in slice 7.2.
+    nextAction: null,
+    metadata: metadata(c.metadata),
+    createdAt: new Date(c.created * 1000),
+    raw: c,
+  }
+}
+
+const INVOICE_STATUS_MAP: Record<NonNullable<Stripe.Invoice.Status>, InvoiceStatus> = {
+  draft: 'draft',
+  open: 'open',
+  paid: 'paid',
+  uncollectible: 'uncollectible',
+  void: 'void',
+}
+
+export function toPaymentInvoice(i: Stripe.Invoice): PaymentInvoice {
+  // Stripe invoices carry the subscription reference on a nested
+  // line-item property; fall back to a top-level field on older
+  // shapes.
+  const iAny = i as unknown as {
+    subscription?: string | { id: string } | null
+    customer?: string | { id: string } | null
+    hosted_invoice_url?: string | null
+    invoice_pdf?: string | null
+  }
+  const subId =
+    typeof iAny.subscription === 'string'
+      ? iAny.subscription
+      : iAny.subscription
+        ? (iAny.subscription as { id: string }).id
+        : null
+  return {
+    id: i.id ?? '',
+    provider: PROVIDER,
+    customerId:
+      typeof iAny.customer === 'string'
+        ? iAny.customer
+        : iAny.customer
+          ? (iAny.customer as { id: string }).id
+          : '',
+    subscriptionId: subId,
+    status: i.status ? (INVOICE_STATUS_MAP[i.status] ?? 'open') : 'draft',
+    amount: i.amount_due,
+    amountPaid: i.amount_paid,
+    amountDue: i.amount_remaining ?? i.amount_due,
+    currency: i.currency,
+    hostedUrl: iAny.hosted_invoice_url ?? null,
+    pdfUrl: iAny.invoice_pdf ?? null,
+    dueAt: toDate(i.due_date),
+    paidAt: i.status === 'paid' ? toDate(i.status_transitions?.paid_at) : null,
+    metadata: metadata(i.metadata),
+    createdAt: new Date(i.created * 1000),
+    raw: i,
+  }
+}
+
+export function toPaymentLink(l: Stripe.PaymentLink): import('../../../dto/index.ts').PaymentLink {
+  // Stripe Payment Links carry their amount/currency on the
+  // attached line_items.data[0].price — when the SDK doesn't
+  // expand it, those fields are `null` on our DTO and apps
+  // resolve the price separately. The link itself doesn't
+  // expose a top-level amount.
+  return {
+    id: l.id,
+    provider: PROVIDER,
+    url: l.url,
+    amount: null,
+    currency: null,
+    active: l.active,
+    reusable: true, // Stripe links are reusable by default; single-use is rare.
+    metadata: metadata(l.metadata),
+    createdAt: new Date(0), // PaymentLink.created not on Stripe.PaymentLink — apps that need it read from the dashboard.
+    raw: l,
+  }
+}
+
+export function toPaymentCheckoutSession(
+  s: Stripe.Checkout.Session,
+): PaymentCheckoutSession {
+  return {
+    id: s.id,
+    provider: PROVIDER,
+    mode: s.mode === 'subscription' ? 'subscription' : s.mode === 'setup' ? 'setup' : 'payment',
+    status: s.status === 'complete' ? 'complete' : s.status === 'expired' ? 'expired' : 'open',
+    url: s.url ?? '',
+    customerId:
+      typeof s.customer === 'string'
+        ? s.customer
+        : s.customer
+          ? (s.customer as { id: string }).id
+          : null,
+    paymentIntentId:
+      typeof s.payment_intent === 'string'
+        ? s.payment_intent
+        : s.payment_intent
+          ? (s.payment_intent as { id: string }).id
+          : null,
+    subscriptionId:
+      typeof s.subscription === 'string'
+        ? s.subscription
+        : s.subscription
+          ? (s.subscription as { id: string }).id
+          : null,
+    expiresAt: toDate(s.expires_at),
+    metadata: metadata(s.metadata),
+    createdAt: new Date(s.created * 1000),
+    raw: s,
+  }
+}

package/src/drivers/stripe/mappers/stripe_method_spec.ts

@@ -0,0 +1,77 @@
+/**
+ * Build a Stripe `payment_method_data` (plus matching
+ * `payment_method_options` extras) from a `PaymentMethodSpec`.
+ *
+ * Returns `null` when the spec is a card token (the caller passes
+ * `payment_method: <token>` directly), or `undefined` when the
+ * driver should reject the kind via `ProviderUnsupportedError`.
+ *
+ * Stripe supports a different set of methods than Omise — this
+ * function is the single place where the mapping lives so the
+ * capability set + the create-call wiring stay in sync.
+ */
+
+import type Stripe from 'stripe'
+import type { PaymentMethodSpec } from '../../../dto/index.ts'
+
+export interface StripeMethodWiring {
+  payment_method_data: Stripe.PaymentIntentCreateParams.PaymentMethodData
+  payment_method_options?: Stripe.PaymentIntentCreateParams.PaymentMethodOptions
+}
+
+export type StripeMethodBuildResult =
+  | { kind: 'card_token' }
+  | { kind: 'unsupported' }
+  | { kind: 'wired'; wiring: StripeMethodWiring }
+
+/**
+ * Closed set of `PaymentMethodSpec.kind` values Stripe accepts.
+ * `card` is handled separately (caller passes the token id);
+ * everything else routes through `payment_method_data.type`.
+ */
+const STRIPE_TYPES: Partial<Record<PaymentMethodSpec['kind'], string>> = {
+  promptpay: 'promptpay',
+  paynow: 'paynow',
+  alipay: 'alipay',
+  wechat_pay: 'wechat_pay',
+  grabpay: 'grabpay',
+  kakaopay: 'kakao_pay',
+  konbini: 'konbini',
+}
+
+export function buildStripeMethodWiring(
+  spec: PaymentMethodSpec,
+): StripeMethodBuildResult {
+  if (spec.kind === 'card') return { kind: 'card_token' }
+  const stripeType = STRIPE_TYPES[spec.kind]
+  if (!stripeType) return { kind: 'unsupported' }
+
+  const data = { type: stripeType } as Stripe.PaymentIntentCreateParams.PaymentMethodData
+
+  const wiring: StripeMethodWiring = { payment_method_data: data }
+
+  // Per-kind extras. WeChat needs a client hint; Konbini takes
+  // a confirmation_number setting via payment_method_options.
+  if (spec.kind === 'wechat_pay') {
+    wiring.payment_method_options = {
+      wechat_pay: { client: 'web' },
+    } as Stripe.PaymentIntentCreateParams.PaymentMethodOptions
+  }
+
+  return { kind: 'wired', wiring }
+}
+
+/**
+ * The `PaymentCapability` flag corresponding to a spec kind. Used
+ * by the driver to declare its supported set + by tests.
+ */
+export const STRIPE_SUPPORTED_METHOD_KINDS: ReadonlyArray<PaymentMethodSpec['kind']> = [
+  'card',
+  'promptpay',
+  'paynow',
+  'alipay',
+  'wechat_pay',
+  'grabpay',
+  'kakaopay',
+  'konbini',
+]