@strav/payment 1.0.0-alpha.38 → 1.0.0-alpha.40

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@strav/payment",
-  "version": "1.0.0-alpha.38",
-  "description": "Strav payment module — provider-agnostic payment abstraction. Normalized DTOs, multi-provider routing, ledger schema, webhook dispatcher, Cashier-style Billable mixin. Stripe and Omise drivers ship as subpath imports (`@strav/payment/stripe`, `@strav/payment/omise`). Paddle support comes in a later release.",
+  "version": "1.0.0-alpha.40",
+  "description": "Strav payment module — provider-agnostic payment abstraction. Normalized DTOs, multi-provider routing, ledger schema, webhook dispatcher, Cashier-style Billable mixin. Stripe, Omise, and Xendit drivers ship as subpath imports (`@strav/payment/stripe`, `@strav/payment/omise`, `@strav/payment/xendit`). Paddle support comes in a later release.",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./stripe": "./src/drivers/stripe/index.ts",
-    "./omise": "./src/drivers/omise/index.ts"
+    "./omise": "./src/drivers/omise/index.ts",
+    "./xendit": "./src/drivers/xendit/index.ts"
   },
   "files": [
     "src",
@@ -21,9 +22,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@strav/database": "1.0.0-alpha.38",
-    "@strav/http": "1.0.0-alpha.38",
-    "@strav/kernel": "1.0.0-alpha.38",
+    "@strav/database": "1.0.0-alpha.40",
+    "@strav/http": "1.0.0-alpha.40",
+    "@strav/kernel": "1.0.0-alpha.40",
     "stripe": "^18.0.0",
     "omise": "^0.12.0"
   },

package/src/drivers/mock_driver.ts

@@ -78,6 +78,10 @@ const ALL_CAPS: readonly PaymentCapability[] = [
   '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.method.qris', 'charges.method.gcash', 'charges.method.paymaya',
+  'charges.method.momo', 'charges.method.ovo', 'charges.method.dana',
+  'charges.method.shopeepay', 'charges.method.linkaja', 'charges.method.astrapay',
+  'charges.method.fpx', 'charges.method.direct_debit', 'charges.method.atome',
   'charges.nextAction.display_qr', 'charges.nextAction.redirect',
   'charges.nextAction.authorize', 'charges.nextAction.voucher',
   'charges.nextAction.wait',
@@ -497,6 +501,7 @@ function mockNextActionFor(
     case 'promptpay':
     case 'paynow':
     case 'fps':
+    case 'qris':
       return {
         kind: 'display_qr',
         qrData: `mock-qr:${pm.kind}:${ulid()}`,
@@ -510,6 +515,17 @@ function mockNextActionFor(
     case 'grabpay':
     case 'kakaopay':
     case 'rabbit_linepay':
+    case 'gcash':
+    case 'paymaya':
+    case 'momo':
+    case 'ovo':
+    case 'dana':
+    case 'shopeepay':
+    case 'linkaja':
+    case 'astrapay':
+    case 'fpx':
+    case 'direct_debit':
+    case 'atome':
       return { kind: 'redirect', url }
     default:
       return { kind: 'wait' }

package/src/drivers/omise/omise_method_spec.ts

@@ -43,6 +43,9 @@ const OMISE_TYPES: Partial<Record<PaymentMethodSpec['kind'], string>> = {
   wechat_pay: 'wechat_pay',
   grabpay: 'grabpay',
   rabbit_linepay: 'rabbit_linepay',
+  // Atome BNPL — Omise bridged in 2024. Redirect flow; the
+  // customer completes the instalment split inside the Atome app.
+  atome: 'atome',
 }
 
 export function buildOmiseMethodSpec(
@@ -71,6 +74,7 @@ export function omiseSourceFlowFor(kind: PaymentMethodSpec['kind']): 'offline' |
     case 'wechat_pay':
     case 'grabpay':
     case 'rabbit_linepay':
+    case 'atome':
       return 'redirect'
     default:
       return 'unknown'
@@ -85,4 +89,5 @@ export const OMISE_SUPPORTED_METHOD_KINDS: ReadonlyArray<PaymentMethodSpec['kind
   'wechat_pay',
   'grabpay',
   'rabbit_linepay',
+  'atome',
 ]

package/src/drivers/xendit/index.ts

@@ -0,0 +1,38 @@
+// `@strav/payment/xendit` — SEA-coverage driver (Xendit / Opn Payments).
+
+export { XenditClient, type XenditClientOptions, type XenditRequestOptions } from './xendit_client.ts'
+export {
+  XENDIT_DEFAULT_BASE_URL,
+  type XenditCountry,
+  type XenditProviderConfig,
+} from './xendit_config.ts'
+export {
+  type XenditDriverOptions,
+  XenditPaymentDriver,
+} from './xendit_driver.ts'
+export type {
+  XenditCardCharge,
+  XenditCustomer,
+  XenditEwalletCharge,
+  XenditInvoice,
+  XenditQrCharge,
+  XenditRefund,
+} from './xendit_mappers.ts'
+export {
+  type XenditChannel,
+  type XenditMethodPlan,
+  XENDIT_SUPPORTED_KINDS,
+  planXenditCharge,
+} from './xendit_method_spec.ts'
+export {
+  xenditEwalletNextAction,
+  type XenditEwalletResponse,
+  type XenditQrResponse,
+  xenditQrNextAction,
+} from './xendit_next_action_mapper.ts'
+export { XenditPaymentProvider } from './xendit_provider.ts'
+export {
+  type XenditEvent,
+  xenditNormalize,
+  xenditVerify,
+} from './xendit_webhook.ts'

package/src/drivers/xendit/xendit_client.ts

@@ -0,0 +1,129 @@
+/**
+ * Minimal Xendit REST client — HTTP Basic auth, JSON envelopes, structured
+ * error wrapping. We intentionally do NOT depend on the official `xendit-node`
+ * SDK: it's CommonJS, has a heavy class-per-resource layout that doesn't
+ * compose well with the framework's driver pattern, and lags real API
+ * surfaces (e-wallets, QR codes) by months on its public release schedule.
+ *
+ * Auth: `Authorization: Basic base64(secret:)`. Yes, the trailing colon is
+ * required — Xendit follows the HTTP Basic convention even though only the
+ * username slot is used.
+ *
+ * Errors: Xendit returns 4xx/5xx with a JSON envelope:
+ *
+ *   { "error_code": "INVALID_API_KEY", "message": "..." }
+ *
+ * We surface this verbatim on `cause` and pick a typed `PaymentProviderError`
+ * subclass based on the error_code class.
+ */
+
+import { PaymentProviderError, ProviderUnsupportedError } from '../../payment_error.ts'
+
+export interface XenditClientOptions {
+  secretKey: string
+  baseUrl: string
+  fetchFn: typeof fetch
+}
+
+export interface XenditRequestOptions {
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE'
+  path: string
+  body?: Record<string, unknown>
+  query?: Record<string, string | number | undefined>
+  headers?: Record<string, string>
+  /** Sent on POST as `idempotency-key`. */
+  idempotencyKey?: string
+  /** Required by Xendit's e-wallet + QR APIs for the "for-user" sub-account flow. */
+  forUserId?: string
+}
+
+interface XenditErrorEnvelope {
+  error_code?: string
+  message?: string
+  errors?: unknown
+}
+
+export class XenditClient {
+  private readonly auth: string
+  private readonly baseUrl: string
+  private readonly fetchFn: typeof fetch
+
+  constructor(options: XenditClientOptions) {
+    if (!options.secretKey || options.secretKey.length === 0) {
+      throw new ProviderUnsupportedError(
+        'xendit',
+        'init',
+        { reason: 'secretKey is required on the provider config.' },
+      )
+    }
+    this.auth = `Basic ${btoa(`${options.secretKey}:`)}`
+    this.baseUrl = options.baseUrl.replace(/\/+$/, '')
+    this.fetchFn = options.fetchFn
+  }
+
+  async request<T = unknown>(options: XenditRequestOptions): Promise<T> {
+    const url = this.buildUrl(options.path, options.query)
+    const headers: Record<string, string> = {
+      authorization: this.auth,
+      'content-type': 'application/json',
+      accept: 'application/json',
+      ...(options.headers ?? {}),
+    }
+    if (options.idempotencyKey) headers['idempotency-key'] = options.idempotencyKey
+    if (options.forUserId) headers['for-user-id'] = options.forUserId
+    const init: RequestInit = {
+      method: options.method,
+      headers,
+    }
+    if (options.body !== undefined && options.method !== 'GET') {
+      init.body = JSON.stringify(options.body)
+    }
+    const res = await this.fetchFn(url, init)
+    if (!res.ok) throw await this.toError(res, options)
+    if (res.status === 204) return undefined as T
+    return (await res.json()) as T
+  }
+
+  private buildUrl(path: string, query?: Record<string, string | number | undefined>): string {
+    const url = new URL(`${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`)
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined) url.searchParams.set(k, String(v))
+      }
+    }
+    return url.toString()
+  }
+
+  private async toError(res: Response, req: XenditRequestOptions): Promise<Error> {
+    let body: XenditErrorEnvelope | string
+    try {
+      body = (await res.json()) as XenditErrorEnvelope
+    } catch {
+      body = await res.text()
+    }
+    const code =
+      typeof body === 'object' && body && 'error_code' in body
+        ? String(body.error_code ?? '')
+        : ''
+    const message =
+      typeof body === 'object' && body && 'message' in body
+        ? String(body.message ?? '')
+        : `Xendit ${req.method} ${req.path} returned ${res.status}.`
+
+    const baseCtx: Record<string, unknown> = {
+      provider: 'xendit',
+      status: res.status,
+      path: req.path,
+      method: req.method,
+    }
+    if (code) baseCtx['errorCode'] = code
+
+    return new PaymentProviderError(message, {
+      provider: 'xendit',
+      operation: `${req.method} ${req.path}`,
+      status: res.status >= 500 ? 502 : res.status,
+      context: baseCtx,
+      cause: body,
+    })
+  }
+}

package/src/drivers/xendit/xendit_config.ts

@@ -0,0 +1,47 @@
+/**
+ * Xendit-specific provider config.
+ *
+ * Xendit's REST API uses HTTP Basic auth: the `secretKey` is the user, the
+ * password is empty (note the trailing colon in the Authorization header).
+ * Webhooks are *not* HMAC-signed — instead Xendit echoes a static
+ * `x-callback-token` header set in the dashboard, which the driver compares
+ * against `webhookToken` in constant time.
+ *
+ * `defaultCountry` is the ISO 3166-1 alpha-2 country code used as a default
+ * for endpoints that require one (e-wallet charges, QRIS). Apps that route
+ * payments per market pass `countryCode` on each create call to override.
+ */
+
+import type { ProviderConfig } from '../../types.ts'
+
+export interface XenditProviderConfig extends ProviderConfig {
+  driver: 'xendit'
+  /** `xnd_development_...` / `xnd_production_...` — server-side secret. */
+  secretKey: string
+  /**
+   * Static webhook verification token from the Xendit dashboard. Compared
+   * verbatim against the `x-callback-token` header in constant time.
+   * Required for the webhook route; without it `webhook.verify` throws.
+   */
+  webhookToken?: string
+  /**
+   * Default country for the multi-country APIs (e-wallets, QRIS, retail
+   * outlets). Per-call overrides via `paymentMethod` specifics still win.
+   * Defaults to `'ID'` when omitted — Xendit's largest market.
+   */
+  defaultCountry?: XenditCountry
+  /**
+   * Default currency for charges. Indonesian Rupiah (`'IDR'`) when omitted.
+   * Set explicitly when the provider is bound for PH/MY/VN/TH/SG so apps
+   * don't have to repeat the currency on every call.
+   */
+  defaultCurrency?: string
+  /** Override the API base URL (tests; sandbox vs production endpoints are the same URL). */
+  baseUrl?: string
+  /** Injectable `fetch` for tests. */
+  fetch?: typeof fetch
+}
+
+export type XenditCountry = 'ID' | 'PH' | 'VN' | 'MY' | 'TH' | 'SG'
+
+export const XENDIT_DEFAULT_BASE_URL = 'https://api.xendit.co'