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

package/src/drivers/xendit/xendit_driver.ts

@@ -0,0 +1,566 @@
+/**
+ * `XenditPaymentDriver` — `PaymentDriver` for Xendit (Southeast-Asia PSP).
+ *
+ * Covers the SEA-payment surface Strav cares about — QRIS (Indonesia),
+ * GCash / PayMaya (Philippines), MoMo (Vietnam), OVO / Dana / LinkAja /
+ * AstraPay / ShopeePay (Indonesia), GrabPay (cross-SEA), Alipay / WeChat
+ * Pay (cross-border), and cards via Xendit.js token tokenisation. Hosted
+ * payment pages + payment links both ride Xendit's `/v2/invoices` resource.
+ *
+ * Capability scope:
+ *   - **customers**    CRUD (create / retrieve / update / list / delete).
+ *   - **charges**      create / retrieve / refund. Capture is unsupported
+ *                      (Xendit's e-wallet + QR flows are auth-and-settle;
+ *                      cards capture immediately).
+ *   - **links**        create / retrieve / list / deactivate via the
+ *                      invoices API. `deactivate` calls Xendit's
+ *                      "expire invoice" endpoint.
+ *   - **checkout**     create / retrieve — same invoice resource viewed
+ *                      under the hosted-checkout name.
+ *   - **invoices**     retrieve / list. No `finalize` (Xendit invoices
+ *                      are immediately open) — `void` maps to expire.
+ *   - **webhook**      verify (x-callback-token) + normalize.
+ *
+ * Out of v1:
+ *   - **subscriptions**     Xendit's recurring API exists but is
+ *                           multi-step (plan + cycles + cards) and
+ *                           doesn't fit the framework's
+ *                           SubscriptionOps shape cleanly.
+ *   - **products / prices** No native Xendit concept — apps use the
+ *                           charge `description` + metadata instead.
+ *   - **paymentMethods**    Xendit's `/v2/payment_methods` resource
+ *                           is shaped for the newer Payments API
+ *                           which we don't use here. Card flows go
+ *                           through the legacy `/credit_card_charges`
+ *                           endpoint instead.
+ *   - **fpx / direct_debit** Xendit's direct-debit flow requires
+ *                            linked-account onboarding (a multi-step
+ *                            dance). Apps call `driver.client` directly
+ *                            for now; the framework will add a typed
+ *                            wrapper in a later slice.
+ */
+
+import type { PaymentCapability } from '../../payment_capabilities.ts'
+import type {
+  CreateChargeInput,
+  CreateCustomerInput,
+  CreatePaymentLinkInput,
+  CreateRefundInput,
+  ListCustomersOptions,
+  ListPaymentLinksOptions,
+  NormalizedWebhookEvent,
+  PaginatedCustomers,
+  PaginatedInvoices,
+  PaginatedPaymentLinks,
+  PaymentCharge,
+  PaymentCheckoutSession,
+  PaymentCustomer,
+  PaymentLink,
+  PaymentMethodSpec,
+  PaymentRefund,
+  UpdateCustomerInput,
+} from '../../dto/index.ts'
+import { ProviderUnsupportedError } from '../../payment_error.ts'
+import type {
+  ChargeOps,
+  CheckoutOps,
+  CustomerOps,
+  InvoiceOps,
+  LinkOps,
+  PaymentDriver,
+  PaymentMethodOps,
+  PriceOps,
+  ProductOps,
+  SubscriptionOps,
+  WebhookOps,
+} from '../../payment_driver.ts'
+import { unsupported } from '../unsupported.ts'
+import {
+  XENDIT_DEFAULT_BASE_URL,
+  type XenditCountry,
+  type XenditProviderConfig,
+} from './xendit_config.ts'
+import { XenditClient } from './xendit_client.ts'
+import {
+  toPaymentChargeFromCard,
+  toPaymentChargeFromEwallet,
+  toPaymentChargeFromQr,
+  toPaymentCustomer,
+  toPaymentInvoice,
+  toPaymentLink,
+  toPaymentRefund,
+  type XenditCardCharge,
+  type XenditCustomer,
+  type XenditEwalletCharge,
+  type XenditInvoice,
+  type XenditQrCharge,
+  type XenditRefund,
+} from './xendit_mappers.ts'
+import { planXenditCharge, XENDIT_SUPPORTED_KINDS } from './xendit_method_spec.ts'
+import { xenditNormalize, xenditVerify, type XenditEvent } from './xendit_webhook.ts'
+
+const PROVIDER = 'xendit'
+
+const BASE_CAPS: readonly PaymentCapability[] = [
+  'customers.create',
+  'customers.retrieve',
+  'customers.update',
+  'customers.list',
+  'customers.delete',
+  'charges.create',
+  'charges.refund',
+  'charges.nextAction.redirect',
+  'charges.nextAction.display_qr',
+  'charges.nextAction.wait',
+  'links.create',
+  'links.deactivate',
+  'invoices.list',
+  'invoices.retrieve',
+  'invoices.void',
+  'webhook.verify',
+  'webhook.normalize',
+  'idempotency',
+]
+
+export interface XenditDriverOptions {
+  instanceName: string
+  config: XenditProviderConfig
+}
+
+export class XenditPaymentDriver implements PaymentDriver {
+  readonly name = PROVIDER
+  readonly instanceName: string
+  readonly capabilities: ReadonlySet<PaymentCapability>
+
+  readonly client: XenditClient
+  private readonly cfg: XenditProviderConfig
+  private readonly country: XenditCountry
+
+  constructor(opts: XenditDriverOptions) {
+    this.instanceName = opts.instanceName
+    this.cfg = opts.config
+    this.country = opts.config.defaultCountry ?? 'ID'
+    this.client = new XenditClient({
+      secretKey: opts.config.secretKey,
+      baseUrl: opts.config.baseUrl ?? XENDIT_DEFAULT_BASE_URL,
+      fetchFn: opts.config.fetch ?? fetch,
+    })
+    const caps: PaymentCapability[] = [...BASE_CAPS]
+    for (const kind of XENDIT_SUPPORTED_KINDS) {
+      caps.push(`charges.method.${kind}` as PaymentCapability)
+    }
+    this.capabilities = new Set(caps)
+  }
+
+  // ─── customers ──────────────────────────────────────────────────────────────
+
+  readonly customers: CustomerOps = {
+    create: (input: CreateCustomerInput): Promise<PaymentCustomer> => this.createCustomer(input),
+    retrieve: (id) => this.client.request<XenditCustomer>({ method: 'GET', path: `/customers/${id}` }).then(toPaymentCustomer),
+    update: (id, input) => this.updateCustomer(id, input),
+    list: (options) => this.listCustomers(options),
+    delete: async (id) => {
+      // Xendit doesn't delete customers — we soft-archive by stamping
+      // `metadata.archived = 'true'`. Apps that want a hard delete call
+      // `driver.client` directly.
+      await this.updateCustomer(id, { metadata: { archived: 'true' } })
+    },
+  }
+
+  private async createCustomer(input: CreateCustomerInput): Promise<PaymentCustomer> {
+    const body: Record<string, unknown> = {
+      reference_id: input.metadata?.['reference_id'] ?? `ref_${Date.now()}_${input.email}`,
+      type: 'INDIVIDUAL',
+      email: input.email,
+    }
+    if (input.name) body['individual_detail'] = { given_names: input.name }
+    if (input.phone) body['mobile_number'] = input.phone
+    if (input.metadata) body['metadata'] = input.metadata
+    const req: { method: 'POST'; path: string; body: Record<string, unknown>; idempotencyKey?: string } = {
+      method: 'POST',
+      path: '/customers',
+      body,
+    }
+    if (input.idempotencyKey) req.idempotencyKey = input.idempotencyKey
+    const res = await this.client.request<XenditCustomer>(req)
+    return toPaymentCustomer(res)
+  }
+
+  private async updateCustomer(id: string, input: UpdateCustomerInput): Promise<PaymentCustomer> {
+    const body: Record<string, unknown> = {}
+    if (input.email) body['email'] = input.email
+    if (input.phone) body['mobile_number'] = input.phone
+    if (input.name) body['individual_detail'] = { given_names: input.name }
+    if (input.metadata) body['metadata'] = input.metadata
+    const res = await this.client.request<XenditCustomer>({
+      method: 'PATCH',
+      path: `/customers/${id}`,
+      body,
+    })
+    return toPaymentCustomer(res)
+  }
+
+  private async listCustomers(options?: ListCustomersOptions): Promise<PaginatedCustomers> {
+    const query: Record<string, string | number | undefined> = {}
+    if (options?.email) query['email'] = options.email
+    if (options?.cursor) query['after_id'] = options.cursor
+    if (options?.limit) query['limit'] = options.limit
+    const res = await this.client.request<{ data: XenditCustomer[]; has_more?: boolean }>({
+      method: 'GET',
+      path: '/customers',
+      query,
+    })
+    const data = (res.data ?? []).map(toPaymentCustomer)
+    const last = data[data.length - 1]
+    return {
+      data,
+      nextCursor: res.has_more && last ? last.id : null,
+    }
+  }
+
+  // ─── charges ────────────────────────────────────────────────────────────────
+
+  readonly charges: ChargeOps = {
+    create: (input) => this.createCharge(input),
+    retrieve: (id) => this.retrieveCharge(id),
+    capture: () => {
+      throw new ProviderUnsupportedError(PROVIDER, 'charges.capture', {
+        reason: "Xendit's flows authorise and settle in one step (or via webhook).",
+      })
+    },
+    refund: (input) => this.refundCharge(input),
+  }
+
+  private async createCharge(input: CreateChargeInput): Promise<PaymentCharge> {
+    const spec = this.resolveMethodSpec(input.paymentMethod)
+    const plan = planXenditCharge(spec, this.country)
+
+    const reference = `ch_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+    const currency = input.currency ?? this.cfg.defaultCurrency ?? 'IDR'
+
+    if (plan.channel === 'unsupported') {
+      throw new ProviderUnsupportedError(PROVIDER, `charges.method.${spec.kind}`, {
+        reason:
+          spec.kind === 'fpx' || spec.kind === 'direct_debit'
+            ? 'Use Xendit\'s linked-account flow via driver.client (deferred to a later slice).'
+            : 'Method not supported by the Xendit driver.',
+      })
+    }
+
+    if (plan.channel === 'ewallet') {
+      const body: Record<string, unknown> = {
+        reference_id: reference,
+        currency,
+        amount: input.amount,
+        checkout_method: 'ONE_TIME_PAYMENT',
+        channel_code: plan.channelCode,
+        channel_properties: {
+          ...(plan.channelProperties ?? {}),
+          ...(input.returnUrl ? { success_redirect_url: input.returnUrl } : {}),
+        },
+      }
+      if (input.customer) body['customer_id'] = input.customer
+      if (input.metadata) body['metadata'] = input.metadata
+      const res = await this.client.request<XenditEwalletCharge>({
+        method: 'POST',
+        path: '/ewallets/charges',
+        body,
+        ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+      })
+      return toPaymentChargeFromEwallet(res)
+    }
+
+    if (plan.channel === 'qr_code') {
+      const res = await this.client.request<XenditQrCharge>({
+        method: 'POST',
+        path: '/qr_codes',
+        body: {
+          reference_id: reference,
+          type: 'DYNAMIC',
+          currency,
+          amount: input.amount,
+          channel_code: plan.qrChannelCode,
+          ...(input.metadata ? { metadata: input.metadata } : {}),
+        },
+        ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+      })
+      return toPaymentChargeFromQr(res)
+    }
+
+    // Card path.
+    if (spec.kind !== 'card') {
+      throw new ProviderUnsupportedError(PROVIDER, `charges.method.${spec.kind}`)
+    }
+    const body: Record<string, unknown> = {
+      token_id: spec.token,
+      external_id: reference,
+      amount: input.amount,
+      currency,
+      capture: input.capture !== false,
+    }
+    if (input.description) body['description'] = input.description
+    if (input.customer) body['customer_id'] = input.customer
+    if (input.metadata) body['metadata'] = input.metadata
+    const res = await this.client.request<XenditCardCharge>({
+      method: 'POST',
+      path: '/credit_card_charges',
+      body,
+      ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+    })
+    return toPaymentChargeFromCard(res)
+  }
+
+  private async retrieveCharge(id: string): Promise<PaymentCharge> {
+    // Xendit's resource endpoints disagree on charge id format. Tags
+    // disambiguate: `ewc_` / `ewallet_` → /ewallets/charges, `qr_` →
+    // /qr_codes, anything else → /credit_card_charges.
+    if (id.startsWith('ewc_') || id.startsWith('ewallet_')) {
+      const res = await this.client.request<XenditEwalletCharge>({
+        method: 'GET',
+        path: `/ewallets/charges/${id}`,
+      })
+      return toPaymentChargeFromEwallet(res)
+    }
+    if (id.startsWith('qr_')) {
+      const res = await this.client.request<XenditQrCharge>({
+        method: 'GET',
+        path: `/qr_codes/${id}`,
+      })
+      return toPaymentChargeFromQr(res)
+    }
+    const res = await this.client.request<XenditCardCharge>({
+      method: 'GET',
+      path: `/credit_card_charges/${id}`,
+    })
+    return toPaymentChargeFromCard(res)
+  }
+
+  private async refundCharge(input: CreateRefundInput): Promise<PaymentRefund> {
+    const body: Record<string, unknown> = {}
+    // Xendit routes refunds via different fields depending on the source
+    // charge — `payment_id` for e-wallets, `invoice_id` for invoices,
+    // `charge_id` for cards. Heuristic: probe by id prefix; apps that
+    // need explicit control supply the right key via metadata.
+    if (input.charge.startsWith('ewc_') || input.charge.startsWith('ewallet_')) {
+      body['payment_id'] = input.charge
+    } else if (input.charge.startsWith('inv-') || input.charge.startsWith('inv_')) {
+      body['invoice_id'] = input.charge
+    } else {
+      body['charge_id'] = input.charge
+    }
+    if (input.amount !== undefined) body['amount'] = input.amount
+    if (input.reason) body['reason'] = input.reason
+    if (input.metadata) body['metadata'] = input.metadata
+
+    const req: {
+      method: 'POST'
+      path: string
+      body: Record<string, unknown>
+      idempotencyKey?: string
+    } = { method: 'POST', path: '/refunds', body }
+    if (input.idempotencyKey) req.idempotencyKey = input.idempotencyKey
+    const res = await this.client.request<XenditRefund>(req)
+    return toPaymentRefund(res)
+  }
+
+  // ─── invoices / payment links / hosted checkout ─────────────────────────────
+  // All three views share Xendit's /v2/invoices resource.
+
+  readonly links: LinkOps = {
+    create: (input) => this.createLink(input),
+    retrieve: async (id) => toPaymentLink(await this.fetchInvoice(id)),
+    list: (options) => this.listLinks(options),
+    deactivate: async (id) => {
+      const res = await this.client.request<XenditInvoice>({
+        method: 'POST',
+        path: `/invoices/${id}/expire!`,
+      })
+      return toPaymentLink(res)
+    },
+  }
+
+  readonly invoices: InvoiceOps = {
+    retrieve: async (id) => toPaymentInvoice(await this.fetchInvoice(id)),
+    list: (options) => this.listInvoices(options),
+    finalize: () => {
+      throw new ProviderUnsupportedError(PROVIDER, 'invoices.finalize', {
+        reason: 'Xendit invoices are immediately open — no separate finalize step.',
+      })
+    },
+    void: async (id) => {
+      const res = await this.client.request<XenditInvoice>({
+        method: 'POST',
+        path: `/invoices/${id}/expire!`,
+      })
+      return toPaymentInvoice(res)
+    },
+  }
+
+  readonly checkout: CheckoutOps = {
+    // Xendit's hosted-checkout shape is invoice-based (single line, single
+    // amount); Stripe's `items: CheckoutLineItem[]` doesn't map cleanly.
+    // Apps build hosted-payment-page flows on `links.create` instead.
+    create: unsupported(
+      PROVIDER,
+      'checkout.create',
+      'Use links.create — Xendit hosted checkout rides /v2/invoices and does not take a CheckoutLineItem array.',
+    ),
+    retrieve: async (id) => {
+      const inv = await this.fetchInvoice(id)
+      return checkoutFromInvoice(inv)
+    },
+  }
+
+  private async createLink(input: CreatePaymentLinkInput): Promise<PaymentLink> {
+    const body = this.buildInvoiceBody({
+      amount: input.amount,
+      currency: input.currency,
+      ...(input.title ? { title: input.title } : {}),
+      ...(input.description ? { description: input.description } : {}),
+      ...(input.afterCompletionRedirect ? { successRedirect: input.afterCompletionRedirect } : {}),
+      metadata: input.metadata,
+    })
+    const res = await this.client.request<XenditInvoice>({
+      method: 'POST',
+      path: '/v2/invoices',
+      body,
+      ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+    })
+    return toPaymentLink(res)
+  }
+
+  private buildInvoiceBody(opts: {
+    amount?: number
+    currency?: string
+    title?: string
+    description?: string
+    successRedirect?: string
+    cancelRedirect?: string
+    metadata?: Record<string, string>
+    customer?: string
+  }): Record<string, unknown> {
+    if (opts.amount === undefined) {
+      throw new ProviderUnsupportedError(PROVIDER, 'links.create', {
+        reason: 'Xendit links/invoices require an explicit `amount`.',
+      })
+    }
+    const body: Record<string, unknown> = {
+      external_id: `inv_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      amount: opts.amount,
+      currency: opts.currency ?? this.cfg.defaultCurrency ?? 'IDR',
+    }
+    if (opts.title) body['description'] = opts.title
+    if (opts.description) body['description'] = opts.description
+    if (opts.successRedirect) body['success_redirect_url'] = opts.successRedirect
+    if (opts.cancelRedirect) body['failure_redirect_url'] = opts.cancelRedirect
+    if (opts.metadata) body['metadata'] = opts.metadata
+    if (opts.customer) {
+      body['customer'] = { id: opts.customer }
+    }
+    return body
+  }
+
+  private async fetchInvoice(id: string): Promise<XenditInvoice> {
+    return this.client.request<XenditInvoice>({ method: 'GET', path: `/v2/invoices/${id}` })
+  }
+
+  private async listLinks(options?: ListPaymentLinksOptions): Promise<PaginatedPaymentLinks> {
+    const inv = await this.listInvoices({ ...(options ?? {}) })
+    return {
+      data: inv.data.map((i) => toPaymentLink(i.raw as XenditInvoice)),
+      nextCursor: inv.nextCursor,
+    }
+  }
+
+  private async listInvoices(options?: {
+    cursor?: string
+    limit?: number
+    customer?: string
+  }): Promise<PaginatedInvoices> {
+    const query: Record<string, string | number | undefined> = {}
+    if (options?.cursor) query['after_id'] = options.cursor
+    if (options?.limit) query['limit'] = options.limit
+    const list = await this.client.request<XenditInvoice[]>({
+      method: 'GET',
+      path: '/v2/invoices',
+      query,
+    })
+    const data = (Array.isArray(list) ? list : []).map(toPaymentInvoice)
+    const last = data[data.length - 1]
+    return {
+      data,
+      nextCursor: data.length === (options?.limit ?? -1) && last ? last.id : null,
+    }
+  }
+
+  // ─── webhook ────────────────────────────────────────────────────────────────
+
+  readonly webhook: WebhookOps = {
+    verify: async (rawBody, signature) =>
+      xenditVerify(rawBody, signature, this.cfg.webhookToken),
+    normalize: (event): NormalizedWebhookEvent | null =>
+      xenditNormalize(event as XenditEvent),
+  }
+
+  // ─── unsupported placeholders ───────────────────────────────────────────────
+
+  readonly products: ProductOps = {
+    create: unsupported(PROVIDER, 'products.create'),
+    retrieve: unsupported(PROVIDER, 'products.retrieve'),
+    update: unsupported(PROVIDER, 'products.update'),
+    list: unsupported(PROVIDER, 'products.list'),
+  }
+
+  readonly prices: PriceOps = {
+    create: unsupported(PROVIDER, 'prices.create'),
+    retrieve: unsupported(PROVIDER, 'prices.retrieve'),
+    list: unsupported(PROVIDER, 'prices.list'),
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: Ops interfaces have many call sites that
+  // expect typed returns; the `unsupported()` helper returns `never` and we cast through
+  // `unknown` to satisfy the contracts at the type level. Runtime always throws.
+  readonly subscriptions: SubscriptionOps = {
+    create: unsupported(PROVIDER, 'subscriptions.create') as unknown as SubscriptionOps['create'],
+    retrieve: unsupported(PROVIDER, 'subscriptions.retrieve') as unknown as SubscriptionOps['retrieve'],
+    update: unsupported(PROVIDER, 'subscriptions.update') as unknown as SubscriptionOps['update'],
+    cancel: unsupported(PROVIDER, 'subscriptions.cancel') as unknown as SubscriptionOps['cancel'],
+    list: unsupported(PROVIDER, 'subscriptions.list') as unknown as SubscriptionOps['list'],
+  }
+
+  readonly paymentMethods: PaymentMethodOps = {
+    attach: unsupported(PROVIDER, 'paymentMethods.attach') as unknown as PaymentMethodOps['attach'],
+    detach: unsupported(PROVIDER, 'paymentMethods.detach') as unknown as PaymentMethodOps['detach'],
+    list: unsupported(PROVIDER, 'paymentMethods.list') as unknown as PaymentMethodOps['list'],
+  }
+
+  // ─── internals ──────────────────────────────────────────────────────────────
+
+  private resolveMethodSpec(pm: CreateChargeInput['paymentMethod']): PaymentMethodSpec {
+    if (pm === undefined) {
+      throw new ProviderUnsupportedError(PROVIDER, 'charges.create', {
+        reason: 'Xendit charges require an explicit `paymentMethod` spec (qris, gcash, …, or card token).',
+      })
+    }
+    if (typeof pm === 'string') return { kind: 'card', token: pm }
+    return pm
+  }
+}
+
+function checkoutFromInvoice(inv: XenditInvoice): PaymentCheckoutSession {
+  const expiresAt = inv.expiry_date ? new Date(inv.expiry_date) : null
+  return {
+    id: inv.id,
+    provider: PROVIDER,
+    mode: 'payment',
+    url: inv.invoice_url ?? '',
+    status: inv.status === 'PAID' ? 'complete' : inv.status === 'EXPIRED' ? 'expired' : 'open',
+    customerId: null,
+    paymentIntentId: null,
+    subscriptionId: null,
+    expiresAt: expiresAt && !Number.isNaN(expiresAt.getTime()) ? expiresAt : null,
+    metadata: inv.metadata ?? {},
+    createdAt: new Date(inv.created ?? Date.now()),
+    raw: inv,
+  }
+}