@strav/payment 1.0.0-alpha.24

package/src/drivers/omise/omise_mappers.ts

@@ -0,0 +1,180 @@
+/**
+ * Omise ↔ normalized-DTO mappers. The Omise type surface lives in
+ * the SDK namespace; we use structural shapes here to keep the
+ * mappers tolerant of SDK version drift.
+ */
+
+import type {
+  ChargeStatus,
+  PaymentCharge,
+  PaymentCustomer,
+  PaymentMethod,
+} from '../../dto/index.ts'
+import { omiseNextAction } from './omise_next_action_mapper.ts'
+
+const PROVIDER = 'omise'
+
+interface OmiseTimestamps {
+  created_at?: string
+  created?: string
+}
+
+interface OmiseCustomer extends OmiseTimestamps {
+  id: string
+  email?: string
+  description?: string
+  metadata?: Record<string, unknown>
+}
+
+interface OmiseCharge extends OmiseTimestamps {
+  id: string
+  amount: number
+  currency: string
+  status: 'failed' | 'reversed' | 'expired' | 'pending' | 'successful'
+  paid?: boolean
+  capture?: boolean
+  refunded?: number
+  refunded_amount?: number
+  customer?: string | OmiseCustomer | null
+  card?: OmiseCard | null
+  source?: OmiseSource | null
+  authorize_uri?: string | null
+  return_uri?: string | null
+  expires_at?: string
+  failure_code?: string | null
+  failure_message?: string | null
+  metadata?: Record<string, unknown>
+}
+
+interface OmiseSource {
+  id: string
+  type?: string
+  flow?: string
+  amount?: number
+  currency?: string
+  scannable_code?: {
+    type?: string
+    image?: { download_uri?: string }
+  }
+  references?: { expires_at?: string }
+}
+
+interface OmiseCard extends OmiseTimestamps {
+  id: string
+  brand?: string
+  last_digits?: string
+  expiration_month?: number
+  expiration_year?: number
+  customer?: string | null
+}
+
+function metadata(m: Record<string, unknown> | undefined): Record<string, string> {
+  if (!m) return {}
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(m)) {
+    if (v === null || v === undefined) continue
+    out[k] = String(v)
+  }
+  return out
+}
+
+function createdAt(r: OmiseTimestamps): Date {
+  const ts = r.created_at ?? r.created
+  return ts ? new Date(ts) : new Date()
+}
+
+export function toPaymentCustomer(c: OmiseCustomer): PaymentCustomer {
+  return {
+    id: c.id,
+    provider: PROVIDER,
+    email: c.email ?? '',
+    metadata: metadata(c.metadata),
+    createdAt: createdAt(c),
+    raw: c,
+  }
+}
+
+const CHARGE_STATUS_MAP: Record<OmiseCharge['status'], ChargeStatus> = {
+  successful: 'succeeded',
+  pending: 'pending',
+  failed: 'failed',
+  reversed: 'refunded',
+  expired: 'failed',
+}
+
+export function toPaymentCharge(c: OmiseCharge): PaymentCharge {
+  let status: ChargeStatus = CHARGE_STATUS_MAP[c.status] ?? 'pending'
+  if ((c.refunded ?? 0) > 0) {
+    status = (c.refunded ?? 0) >= c.amount ? 'refunded' : 'partial_refunded'
+  }
+  return {
+    id: c.id,
+    provider: PROVIDER,
+    customerId: typeof c.customer === 'string' ? c.customer : c.customer?.id ?? null,
+    amount: c.amount,
+    currency: c.currency.toLowerCase(),
+    status,
+    paymentMethodId: c.card?.id ?? null,
+    failureCode: c.failure_code ?? null,
+    failureMessage: c.failure_message ?? null,
+    // Source-backed charges (PromptPay / TrueMoney / Alipay /
+    // GrabPay / etc.) carry the next-action shape on the
+    // attached source (QR image URL) or the charge itself
+    // (`authorize_uri`). Card-only / settled charges produce
+    // `null`.
+    nextAction: omiseNextAction(c),
+    metadata: metadata(c.metadata),
+    createdAt: createdAt(c),
+    raw: c,
+  }
+}
+
+export function toPaymentMethod(card: OmiseCard): PaymentMethod {
+  return {
+    id: card.id,
+    provider: PROVIDER,
+    customerId: card.customer ?? null,
+    kind: 'card',
+    ...(card.brand ? { brand: card.brand } : {}),
+    ...(card.last_digits ? { last4: card.last_digits } : {}),
+    ...(card.expiration_month ? { expMonth: card.expiration_month } : {}),
+    ...(card.expiration_year ? { expYear: card.expiration_year } : {}),
+    metadata: {},
+    createdAt: createdAt(card),
+    raw: card,
+  }
+}
+
+interface OmiseLink extends OmiseTimestamps {
+  id: string
+  amount: number
+  currency: string
+  title?: string
+  description?: string
+  used?: boolean
+  multiple?: boolean
+  payment_uri: string
+  metadata?: Record<string, unknown>
+}
+
+export function toPaymentLink(l: OmiseLink): import('../../dto/index.ts').PaymentLink {
+  return {
+    id: l.id,
+    provider: PROVIDER,
+    url: l.payment_uri,
+    amount: l.amount,
+    currency: l.currency.toLowerCase(),
+    // Omise marks a link as `used` after the first payment when
+    // `multiple: false`. We treat `used && !multiple` as inactive
+    // since the link can't take more payments.
+    active: !(l.used === true && l.multiple !== true),
+    reusable: l.multiple === true,
+    ...(l.title ? { title: l.title } : {}),
+    ...(l.description ? { description: l.description } : {}),
+    metadata: metadata(l.metadata),
+    createdAt: createdAt(l),
+    raw: l,
+  }
+}
+
+export type { OmiseCard, OmiseCharge, OmiseCustomer, OmiseLink, OmiseSource }

package/src/drivers/omise/omise_method_spec.ts

@@ -0,0 +1,88 @@
+/**
+ * Build an Omise source-creation request from a `PaymentMethodSpec`.
+ *
+ * Omise's async flow is two-step: create a `source` (type +
+ * amount + currency + per-kind extras), then create a `charge`
+ * that references the source. This module owns the mapping from
+ * framework spec kind → Omise source `type` string + the extras
+ * each kind needs (e.g. `phone_number` for TrueMoney).
+ *
+ * `card` short-circuits to the existing single-step flow.
+ * Unsupported kinds return `'unsupported'` and the driver throws
+ * `ProviderUnsupportedError`.
+ */
+
+import type { PaymentMethodSpec } from '../../dto/index.ts'
+
+export interface OmiseSourceRequest {
+  type: string
+  amount: number
+  currency: string
+  /** TrueMoney: customer mobile in international format. */
+  phone_number?: string
+  /** Optional billing-display name. */
+  name?: string
+  /** Optional email for sources that ask for it. */
+  email?: string
+}
+
+export type OmiseMethodBuildResult =
+  | { kind: 'card_token' }
+  | { kind: 'unsupported' }
+  | { kind: 'source'; request: Omit<OmiseSourceRequest, 'amount' | 'currency'> }
+
+/**
+ * Closed map of supported `PaymentMethodSpec.kind` values to the
+ * Omise source `type` strings. Driver capabilities + the create
+ * path both derive from this table so they stay in sync.
+ */
+const OMISE_TYPES: Partial<Record<PaymentMethodSpec['kind'], string>> = {
+  promptpay: 'promptpay',
+  truemoney: 'truemoney',
+  alipay: 'alipay',
+  wechat_pay: 'wechat_pay',
+  grabpay: 'grabpay',
+  rabbit_linepay: 'rabbit_linepay',
+}
+
+export function buildOmiseMethodSpec(
+  spec: PaymentMethodSpec,
+  amount: number,
+  currency: string,
+): OmiseMethodBuildResult {
+  if (spec.kind === 'card') return { kind: 'card_token' }
+  const omiseType = OMISE_TYPES[spec.kind]
+  if (!omiseType) return { kind: 'unsupported' }
+
+  const request: Omit<OmiseSourceRequest, 'amount' | 'currency'> = { type: omiseType }
+  if (spec.kind === 'truemoney') {
+    request.phone_number = spec.phoneNumber
+  }
+  return { kind: 'source', request }
+}
+
+/** Flag the source's `flow` — used by the next-action mapper. */
+export function omiseSourceFlowFor(kind: PaymentMethodSpec['kind']): 'offline' | 'redirect' | 'unknown' {
+  switch (kind) {
+    case 'promptpay':
+      return 'offline'
+    case 'truemoney':
+    case 'alipay':
+    case 'wechat_pay':
+    case 'grabpay':
+    case 'rabbit_linepay':
+      return 'redirect'
+    default:
+      return 'unknown'
+  }
+}
+
+export const OMISE_SUPPORTED_METHOD_KINDS: ReadonlyArray<PaymentMethodSpec['kind']> = [
+  'card',
+  'promptpay',
+  'truemoney',
+  'alipay',
+  'wechat_pay',
+  'grabpay',
+  'rabbit_linepay',
+]

package/src/drivers/omise/omise_next_action_mapper.ts

@@ -0,0 +1,89 @@
+/**
+ * Map an Omise source + charge pair onto `PaymentNextAction`.
+ *
+ * Omise splits the async-payment surface across two objects:
+ *
+ *   - **QR-based** (PromptPay, FPS, DuitNow QR, …):
+ *     `source.scannable_code.image.download_uri` is the PNG.
+ *     The charge has no `authorize_uri`. Apps display the
+ *     image; the customer pays via banking app; the webhook
+ *     fires when settlement lands.
+ *
+ *   - **Redirect-based** (TrueMoney, Alipay, GrabPay, Rabbit
+ *     LINE Pay, WeChat Pay): `charge.authorize_uri` is the
+ *     URL the app sends the customer to. Omise routes back to
+ *     `return_uri` (passed when creating the charge).
+ *
+ * Omise doesn't expose the raw EMV / SGQR string the way Stripe
+ * does — only the rendered PNG. We mirror it into both
+ * `qrData` and `qrImageUrl` so apps using either field work; the
+ * raw image url is what they actually display.
+ */
+
+import type { PaymentNextAction } from '../../dto/index.ts'
+
+interface OmiseSourceLike {
+  flow?: string
+  scannable_code?: {
+    image?: { download_uri?: string }
+  }
+  references?: { expires_at?: string }
+}
+
+interface OmiseChargeLike {
+  authorize_uri?: string | null
+  expires_at?: string
+  source?: OmiseSourceLike | null
+}
+
+function parseDate(v: string | undefined): Date | undefined {
+  if (!v) return undefined
+  const d = new Date(v)
+  return Number.isNaN(d.getTime()) ? undefined : d
+}
+
+export function omiseNextAction(
+  charge: OmiseChargeLike,
+  source?: OmiseSourceLike,
+): PaymentNextAction | null {
+  const src = source ?? charge.source ?? undefined
+  const flow = src?.flow
+
+  // Redirect-based — charge.authorize_uri is the URL to send the
+  // customer to. Some flows (wechat_pay) carry both a QR and a
+  // redirect; if both are present we prefer the QR (universal for
+  // desktop checkout).
+  const qrImage = src?.scannable_code?.image?.download_uri
+  if (qrImage) {
+    const action: PaymentNextAction = {
+      kind: 'display_qr',
+      // Omise gives the rendered PNG URL, not the raw EMV string.
+      // Mirroring it into both slots lets either app handler work.
+      qrData: qrImage,
+      qrImageUrl: qrImage,
+    }
+    const expires = parseDate(src?.references?.expires_at ?? charge.expires_at)
+    if (expires) action.expiresAt = expires
+    return action
+  }
+
+  if (charge.authorize_uri) {
+    const action: PaymentNextAction = {
+      kind: 'redirect',
+      url: charge.authorize_uri,
+    }
+    const expires = parseDate(charge.expires_at)
+    if (expires) action.expiresAt = expires
+    return action
+  }
+
+  // Source flow declared but neither field surfaced — Omise hasn't
+  // populated the charge yet; the app waits for the webhook.
+  if (flow === 'offline' || flow === 'redirect') {
+    return { kind: 'wait' }
+  }
+
+  return null
+}
+
+export type { OmiseChargeLike, OmiseSourceLike }

package/src/drivers/omise/omise_price_spec.ts

@@ -0,0 +1,85 @@
+/**
+ * Omise has no `prices` catalog — but the framework's
+ * `SubscriptionOps.create` takes a `price: string` (Stripe's model).
+ *
+ * We bridge that gap with an in-band encoded "price spec" that
+ * carries everything the Omise schedules API needs: amount,
+ * currency, recurrence period, count per period, optional
+ * description, optional default card.
+ *
+ * Apps build the spec with `omisePriceSpec({...})` and pass the
+ * result as `subscriptions.create({ price: spec, ... })`. The
+ * driver parses on the way in and rebuilds on the way out (so
+ * `PaymentSubscription.priceId` round-trips cleanly).
+ *
+ * Wire format: `omise_spec:<base64-url JSON>`. The prefix lets
+ * the driver detect the format and reject opaque ids that look
+ * like Stripe `price_…` early with a clear error.
+ *
+ * Period values match Omise's API: `'day' | 'week' | 'month'`.
+ */
+
+export type OmisePeriod = 'day' | 'week' | 'month'
+
+export interface OmisePriceSpec {
+  amount: number
+  currency: string
+  period: OmisePeriod
+  /** Every N periods between charges. Default 1. */
+  every?: number
+  description?: string
+  /** Default card on the customer. Apps that want to charge a specific token id pass it here. */
+  card?: string
+}
+
+const PREFIX = 'omise_spec:'
+
+export function omisePriceSpec(spec: OmisePriceSpec): string {
+  if (!Number.isFinite(spec.amount) || spec.amount <= 0) {
+    throw new TypeError('omisePriceSpec: `amount` must be a positive number (in minor units).')
+  }
+  if (!spec.currency) {
+    throw new TypeError('omisePriceSpec: `currency` is required.')
+  }
+  if (!spec.period) {
+    throw new TypeError('omisePriceSpec: `period` is required (day | week | month).')
+  }
+  const payload = {
+    a: spec.amount,
+    c: spec.currency.toLowerCase(),
+    p: spec.period,
+    ...(spec.every !== undefined ? { e: spec.every } : {}),
+    ...(spec.description ? { d: spec.description } : {}),
+    ...(spec.card ? { card: spec.card } : {}),
+  }
+  return PREFIX + Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url')
+}
+
+export function parseOmisePriceSpec(value: string): OmisePriceSpec | null {
+  if (!value.startsWith(PREFIX)) return null
+  const rest = value.slice(PREFIX.length)
+  let parsed: { a: number; c: string; p: OmisePeriod; e?: number; d?: string; card?: string }
+  try {
+    const json = Buffer.from(rest, 'base64url').toString('utf8')
+    parsed = JSON.parse(json)
+  } catch {
+    return null
+  }
+  if (
+    typeof parsed.a !== 'number' ||
+    typeof parsed.c !== 'string' ||
+    typeof parsed.p !== 'string'
+  ) {
+    return null
+  }
+  return {
+    amount: parsed.a,
+    currency: parsed.c,
+    period: parsed.p,
+    ...(parsed.e !== undefined ? { every: parsed.e } : {}),
+    ...(parsed.d ? { description: parsed.d } : {}),
+    ...(parsed.card ? { card: parsed.card } : {}),
+  }
+}
+
+export const OMISE_PRICE_SPEC_PREFIX = PREFIX

package/src/drivers/omise/omise_provider.ts

@@ -0,0 +1,33 @@
+/**
+ * `OmisePaymentProvider` — `ServiceProvider` that registers the
+ * Omise driver factory on the `PaymentManager`.
+ *
+ * Apps list this AFTER `PaymentProvider` in
+ * `bootstrap/providers.ts`. Driver instances construct lazily on
+ * first `payment.use(name)` call.
+ */
+
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { PaymentManager } from '../../payment_manager.ts'
+import { PaymentConfigError } from '../../payment_error.ts'
+import type { OmiseProviderConfig } from './omise_config.ts'
+import { OmisePaymentDriver } from './omise_driver.ts'
+
+export class OmisePaymentProvider extends ServiceProvider {
+  override readonly name = 'payment-omise'
+  override readonly dependencies = ['payment']
+
+  override register(app: Application): void {
+    const manager = app.resolve(PaymentManager)
+    manager.extend('omise', ({ instanceName, config }) => {
+      const cfg = config as OmiseProviderConfig
+      if (!cfg.publicKey || !cfg.secretKey) {
+        throw new PaymentConfigError(
+          `OmisePaymentProvider: \`publicKey\` and \`secretKey\` are required for provider "${instanceName}".`,
+          { context: { instanceName } },
+        )
+      }
+      return new OmisePaymentDriver({ instanceName, config: cfg })
+    })
+  }
+}

package/src/drivers/omise/omise_schedule_mapper.ts

@@ -0,0 +1,156 @@
+/**
+ * Map an Omise `schedule` onto a `PaymentSubscription`.
+ *
+ * Omise + framework data models differ; we make the following
+ * choices:
+ *
+ *   - **`status`** — Omise statuses: `running`, `active`,
+ *     `expiring`, `expired`, `deleted`, `suspended`. We collapse
+ *     active recurrences to `active`, expired / deleted to
+ *     `canceled`, suspended to `paused`.
+ *
+ *   - **`currentPeriodStart` / `currentPeriodEnd`** — Omise gives
+ *     `start_date` + `end_date` + an array `next_occurrence_dates`.
+ *     We treat the most recently passed occurrence as period
+ *     start, and the next upcoming occurrence as period end.
+ *
+ *   - **`priceId`** — synthesized via `omisePriceSpec` so the
+ *     round-trip stays portable. Apps reading the DTO see the
+ *     same spec they sent on `create`.
+ *
+ *   - **`trialStart` / `trialEnd`** — always null. Omise schedules
+ *     don't have a trial concept.
+ *
+ *   - **`cancelAt` / `canceledAt`** — `end_date` becomes
+ *     `cancelAt`; `ended_at` becomes `canceledAt` once the
+ *     schedule has actually stopped.
+ */
+
+import type { PaymentSubscription, SubscriptionStatus } from '../../dto/index.ts'
+import { omisePriceSpec, type OmisePeriod } from './omise_price_spec.ts'
+
+export interface OmiseScheduleCharge {
+  amount: number
+  currency: string
+  customer: string | { id: string }
+  card?: string | { id: string } | null
+  description?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface OmiseSchedule {
+  id: string
+  status?: string
+  active?: boolean
+  every: number
+  period: string
+  start_date?: string
+  end_date?: string
+  start_on?: string
+  end_on?: string
+  ended_at?: string
+  created?: string
+  created_at?: string
+  next_occurrence_dates?: string[]
+  charge?: OmiseScheduleCharge
+  metadata?: Record<string, unknown>
+}
+
+function statusFor(s: OmiseSchedule): SubscriptionStatus {
+  const raw = s.status?.toLowerCase()
+  if (raw === 'suspended') return 'paused'
+  if (raw === 'expired' || raw === 'deleted') return 'canceled'
+  if (s.active === false) return 'canceled'
+  return 'active'
+}
+
+function parseDate(v: string | undefined): Date | null {
+  if (!v) return null
+  const d = new Date(v)
+  return Number.isNaN(d.getTime()) ? null : d
+}
+
+function metadata(m: Record<string, unknown> | undefined): Record<string, string> {
+  if (!m) return {}
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(m)) {
+    if (v === null || v === undefined) continue
+    out[k] = String(v)
+  }
+  return out
+}
+
+function periodBoundary(s: OmiseSchedule, now = new Date()): { start: Date; end: Date } {
+  const nowMs = now.getTime()
+  const upcoming = (s.next_occurrence_dates ?? [])
+    .map(parseDate)
+    .filter((d): d is Date => d !== null)
+    .sort((a, b) => a.getTime() - b.getTime())
+  const next = upcoming.find((d) => d.getTime() >= nowMs)
+  const start =
+    upcoming.filter((d) => d.getTime() < nowMs).pop() ??
+    parseDate(s.start_date) ??
+    parseDate(s.created_at) ??
+    now
+  const end = next ?? parseDate(s.end_date) ?? start
+  return { start, end }
+}
+
+export function toPaymentSubscription(s: OmiseSchedule): PaymentSubscription {
+  const charge = s.charge
+  if (!charge) {
+    // Transfer-only schedules don't map onto subscriptions. Surface
+    // a meaningful row so apps can still see them, but the price spec
+    // can't be reconstructed.
+    const { start, end } = periodBoundary(s)
+    return {
+      id: s.id,
+      provider: 'omise',
+      customerId: '',
+      priceId: '',
+      status: statusFor(s),
+      currentPeriodStart: start,
+      currentPeriodEnd: end,
+      cancelAt: parseDate(s.end_date),
+      canceledAt: parseDate(s.ended_at),
+      trialStart: null,
+      trialEnd: null,
+      metadata: metadata(s.metadata),
+      createdAt: parseDate(s.created_at) ?? parseDate(s.created) ?? new Date(),
+      raw: s,
+    }
+  }
+  const customerId =
+    typeof charge.customer === 'string' ? charge.customer : charge.customer.id
+  const cardId =
+    typeof charge.card === 'string'
+      ? charge.card
+      : charge.card
+        ? charge.card.id
+        : undefined
+  const priceId = omisePriceSpec({
+    amount: charge.amount,
+    currency: charge.currency,
+    period: s.period as OmisePeriod,
+    every: s.every,
+    ...(charge.description ? { description: charge.description } : {}),
+    ...(cardId ? { card: cardId } : {}),
+  })
+  const { start, end } = periodBoundary(s)
+  return {
+    id: s.id,
+    provider: 'omise',
+    customerId,
+    priceId,
+    status: statusFor(s),
+    currentPeriodStart: start,
+    currentPeriodEnd: end,
+    cancelAt: parseDate(s.end_date),
+    canceledAt: parseDate(s.ended_at),
+    trialStart: null,
+    trialEnd: null,
+    metadata: metadata(s.metadata),
+    createdAt: parseDate(s.created_at) ?? parseDate(s.created) ?? new Date(),
+    raw: s,
+  }
+}