@bhooai/nexus-payments 0.1.0

package/src/providers/PayoneerProvider.ts

@@ -0,0 +1,122 @@
+import type {
+  PaymentProvider,
+  CreateOrderInput,
+  Order,
+  CaptureInput,
+  RefundInput,
+  RefundResult,
+  WebhookVerifyInput,
+  WebhookEvent,
+  HttpTransport,
+  OrderStatus,
+} from '../types.js';
+import { hmacSha256Hex, safeEqual } from '../signature.js';
+import { PaymentError } from '../errors.js';
+
+/**
+ * Payoneer (happy-path). Payoneer's API requires a registered partner program
+ * and has no public sandbox without provisioned credentials, so this adapter is
+ * structurally complete but verified by signature tests rather than live calls.
+ *
+ * The flow modeled here: the merchant builds a signed payment request (HMAC over
+ * the canonical params) and redirects to a Payoneer checkout URL; Payoneer posts
+ * a webhook signed with the same shared secret (HMAC-SHA256 over the raw body).
+ */
+interface PayoneerConfig {
+  enabled: boolean;
+  sandbox: boolean;
+  programId: string;
+  apiKey: string;
+  /** Shared secret for webhook HMAC verification. */
+  webhookSecret?: string;
+}
+
+function checkoutUrl(sandbox: boolean, programId: string): string {
+  return sandbox
+    ? `https://api.sandbox.payoneer.com/checkout/${programId}`
+    : `https://api.payoneer.com/checkout/${programId}`;
+}
+
+function mapStatus(status: string): OrderStatus {
+  switch (status) {
+    case 'initiated': return 'created';
+    case 'pending': return 'pending';
+    case 'authorized': return 'authorized';
+    case 'completed': case 'paid': return 'captured';
+    case 'failed': return 'failed';
+    case 'cancelled': return 'cancelled';
+    case 'refunded': return 'refunded';
+    default: return 'pending';
+  }
+}
+
+export class PayoneerProvider implements PaymentProvider {
+  readonly name = 'payoneer';
+  private readonly cfg: PayoneerConfig;
+  private readonly transport: HttpTransport;
+
+  constructor(cfg: PayoneerConfig, transport: HttpTransport) {
+    this.cfg = cfg;
+    this.transport = transport;
+    if (!cfg.programId || !cfg.apiKey) throw new PaymentError('payoneer programId/apiKey required', { code: 'CONFIG', provider: 'payoneer' });
+  }
+
+  async createOrder(input: CreateOrderInput): Promise<Order> {
+    const params = new URLSearchParams();
+    params.set('program_id', this.cfg.programId);
+    params.set('reference', input.reference);
+    params.set('amount', input.amount.toFixed(2));
+    params.set('currency', input.currency);
+    if (input.customer?.email) params.set('payee_email', input.customer.email);
+    if (input.returnUrl) params.set('return_url', input.returnUrl);
+    // Canonical signature: HMAC-SHA256(apiKey, sorted query string).
+    const canonical = canonicalQuery(params);
+    const signature = hmacSha256Hex(this.cfg.apiKey, canonical);
+    params.set('signature', signature);
+    return {
+      id: input.reference,
+      reference: input.reference,
+      status: 'created',
+      amount: input.amount,
+      currency: input.currency,
+      paymentUrl: `${checkoutUrl(this.cfg.sandbox, this.cfg.programId)}?${params.toString()}`,
+      raw: Object.fromEntries(params),
+    };
+  }
+
+  async capture(input: CaptureInput): Promise<Order> {
+    return this.getOrderStatus(input.orderId);
+  }
+
+  async refund(_input: RefundInput): Promise<RefundResult> {
+    return { id: `payoneer-refund`, status: 'pending', amount: 0, raw: { note: 'Payoneer refund via partner API (v1)' } };
+  }
+
+  async getOrderStatus(orderId: string): Promise<Order> {
+    return { id: orderId, reference: orderId, status: 'pending', amount: 0, currency: '', raw: { note: 'Payoneer status via webhook (v1)' } };
+  }
+
+  async verifyWebhook(input: WebhookVerifyInput): Promise<WebhookEvent> {
+    const secret = this.cfg.webhookSecret;
+    if (!secret) return { verified: false, provider: this.name, data: 'no webhookSecret configured' };
+    const sig = input.headers['x-payoneer-signature'] ?? input.headers['X-Payoneer-Signature'];
+    const raw = typeof input.rawBody === 'string' ? input.rawBody : input.rawBody.toString();
+    const expected = hmacSha256Hex(secret, raw);
+    const verified = typeof sig === 'string' && safeEqual(sig, expected);
+    let event: string | undefined;
+    let data: unknown;
+    try {
+      const parsed = JSON.parse(raw);
+      event = parsed.event ?? parsed.status;
+      data = parsed;
+    } catch {
+      data = raw;
+    }
+    return { verified, event, data, provider: this.name };
+  }
+}
+
+/** Sort params by key and encode as `k=v&k=v` (deterministic for signing). */
+function canonicalQuery(params: URLSearchParams): string {
+  return [...params.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([k, v]) => `${k}=${v}`).join('&');
+}

package/src/providers/RazorpayProvider.ts

@@ -0,0 +1,184 @@
+import type {
+  PaymentProvider,
+  CreateOrderInput,
+  Order,
+  CaptureInput,
+  RefundInput,
+  RefundResult,
+  WebhookVerifyInput,
+  WebhookEvent,
+  HttpTransport,
+  OrderStatus,
+  ConnectionTest,
+} from '../types.js';
+import { jsonRequest, basicAuth } from '../http.js';
+import { hmacSha256Hex, safeEqual } from '../signature.js';
+import { PaymentError } from '../errors.js';
+
+interface RazorpayConfig {
+  enabled: boolean;
+  sandbox: boolean;
+  keyId: string;
+  keySecret: string;
+  /** Webhook secret configured in the Razorpay dashboard. */
+  webhookSecret?: string;
+}
+
+const BASE = 'https://api.razorpay.com/v1';
+
+/** Razorpay status → unified status. */
+function mapStatus(s: string): OrderStatus {
+  switch (s) {
+    case 'created': return 'created';
+    case 'attempted': return 'pending';
+    case 'paid': return 'paid';
+    case 'captured': return 'captured';
+    case 'failed': return 'failed';
+    case 'refunded': return 'refunded';
+    default: return 'pending';
+  }
+}
+
+/** Razorpay uses minor units (paise) for INR; for non-INR it's the smallest unit too. */
+function toMinor(amount: number, currency: string): number {
+  // Razorpay expects amounts in the smallest currency unit. For currencies with
+  // 3 decimal places (KWD/BHD/JOD) the factor is 1000; otherwise 100. v1 handles
+  // the common 2-decimal case plus the 0-decimal case (JPY).
+  const threeDp = ['KWD', 'BHD', 'JOD', 'OMR', 'TND'];
+  const zeroDp = ['JPY', 'KRW', 'VND', 'ISK'];
+  if (threeDp.includes(currency)) return Math.round(amount * 1000);
+  if (zeroDp.includes(currency)) return Math.round(amount);
+  return Math.round(amount * 100);
+}
+function fromMinor(amount: number, currency: string): number {
+  const threeDp = ['KWD', 'BHD', 'JOD', 'OMR', 'TND'];
+  const zeroDp = ['JPY', 'KRW', 'VND', 'ISK'];
+  if (threeDp.includes(currency)) return amount / 1000;
+  if (zeroDp.includes(currency)) return amount;
+  return amount / 100;
+}
+
+export class RazorpayProvider implements PaymentProvider {
+  readonly name = 'razorpay';
+  private readonly cfg: RazorpayConfig;
+  private readonly transport: HttpTransport;
+
+  constructor(cfg: RazorpayConfig, transport: HttpTransport) {
+    this.cfg = cfg;
+    this.transport = transport;
+    if (!cfg.keyId || !cfg.keySecret) throw new PaymentError('razorpay keyId/keySecret required', { code: 'CONFIG', provider: 'razorpay' });
+  }
+
+  private auth(): string {
+    return basicAuth(this.cfg.keyId, this.cfg.keySecret);
+  }
+
+  async createOrder(input: CreateOrderInput): Promise<Order> {
+    const body = JSON.stringify({
+      amount: toMinor(input.amount, input.currency),
+      currency: input.currency,
+      receipt: input.reference,
+      notes: input.description ? { description: input.description } : undefined,
+    });
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${BASE}/orders`,
+      headers: { 'content-type': 'application/json', authorization: this.auth() },
+      body,
+    });
+    return {
+      id: res.id,
+      reference: res.receipt ?? input.reference,
+      status: mapStatus(res.status),
+      amount: fromMinor(res.amount, res.currency),
+      currency: res.currency,
+      raw: res,
+    };
+  }
+
+  async capture(input: CaptureInput): Promise<Order> {
+    const paymentId = input.paymentId;
+    if (!paymentId) throw new PaymentError('razorpay capture requires paymentId', { code: 'CONFIG', provider: 'razorpay' });
+    // Resolve the order currency once so we can convert a partial-capture amount.
+    const order = await this.getOrderStatus(input.orderId);
+    const body = JSON.stringify({
+      amount: input.amount != null ? toMinor(input.amount, order.currency) : undefined,
+      currency: order.currency,
+    });
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${BASE}/payments/${paymentId}/capture`,
+      headers: { 'content-type': 'application/json', authorization: this.auth() },
+      body,
+    });
+    return {
+      id: res.order_id ?? input.orderId,
+      reference: order.reference,
+      status: mapStatus(res.status),
+      amount: fromMinor(res.amount, res.currency ?? order.currency),
+      currency: res.currency ?? order.currency,
+      paymentId: res.id,
+      raw: res,
+    };
+  }
+
+  async refund(input: RefundInput): Promise<RefundResult> {
+    const body = JSON.stringify({
+      amount: input.amount != null ? toMinor(input.amount, 'INR') : undefined,
+      notes: input.reason ? { reason: input.reason } : undefined,
+    });
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'POST',
+      url: `${BASE}/payments/${input.paymentId}/refund`,
+      headers: { 'content-type': 'application/json', authorization: this.auth() },
+      body,
+    });
+    return { id: res.id, status: res.status, amount: fromMinor(res.amount, res.currency || 'INR'), raw: res };
+  }
+
+  async getOrderStatus(orderId: string): Promise<Order> {
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'GET',
+      url: `${BASE}/orders/${orderId}`,
+      headers: { authorization: this.auth() },
+    });
+    return {
+      id: res.id,
+      reference: res.receipt ?? '',
+      status: mapStatus(res.status),
+      amount: fromMinor(res.amount, res.currency),
+      currency: res.currency,
+      raw: res,
+    };
+  }
+
+  /** Live probe: list orders. Authenticates the key pair without moving money. */
+  async testConnection(): Promise<ConnectionTest> {
+    const res = await jsonRequest(this.transport, this.name, {
+      method: 'GET',
+      url: `${BASE}/orders?count=1`,
+      headers: { authorization: this.auth() },
+    });
+    const count = Array.isArray(res.items) ? res.items.length : 0;
+    return { ok: true, detail: `authenticated; ${count} order(s) in the first page` };
+  }
+
+  async verifyWebhook(input: WebhookVerifyInput): Promise<WebhookEvent> {
+    const secret = this.cfg.webhookSecret;
+    if (!secret) return { verified: false, provider: this.name, data: 'no webhook secret configured' };
+    const sig = input.headers['x-razorpay-signature'] ?? input.headers['X-Razorpay-Signature'];
+    const raw = typeof input.rawBody === 'string' ? input.rawBody : input.rawBody.toString();
+    const expected = hmacSha256Hex(secret, raw);
+    const verified = typeof sig === 'string' && safeEqual(sig, expected);
+    let event: string | undefined;
+    let data: unknown;
+    try {
+      const parsed = JSON.parse(raw);
+      event = parsed.event;
+      data = parsed.payload;
+    } catch {
+      data = raw;
+    }
+    return { verified, event, data, provider: this.name };
+  }
+}

package/src/providers/SkrillProvider.ts

@@ -0,0 +1,117 @@
+import type {
+  PaymentProvider,
+  CreateOrderInput,
+  Order,
+  CaptureInput,
+  RefundInput,
+  RefundResult,
+  WebhookVerifyInput,
+  WebhookEvent,
+  HttpTransport,
+  OrderStatus,
+} from '../types.js';
+import { md5Hex, safeEqual } from '../signature.js';
+import { PaymentError } from '../errors.js';
+
+/**
+ * Skrill Quick Checkout (happy-path). The merchant redirects the buyer to
+ * https://pay.skrill.com/ with payment params; Skrill posts a status report
+ * (IPN) to `status_url` whose `md5sig` we verify.
+ *
+ * md5sig (status report) = MD5(merchant_email + secret_word + mb_transaction_id
+ *                           + amount + currency), sent uppercase by Skrill.
+ */
+interface SkrillConfig {
+  enabled: boolean;
+  sandbox: boolean;
+  /** Skrill merchant email (the pay_to_email). */
+  merchantEmail: string;
+  /** Secret word set in the Skrill merchant account. */
+  secretWord: string;
+}
+
+const CHECKOUT_URL = 'https://pay.skrill.com/';
+
+function mapStatus(status: string): OrderStatus {
+  switch (status) {
+    case '0': case 'pending': return 'pending';
+    case '2': case 'processed': return 'captured';
+    case '1': case 'cancelled': return 'cancelled';
+    case '-1': case 'failed': return 'failed';
+    default: return 'pending';
+  }
+}
+
+export class SkrillProvider implements PaymentProvider {
+  readonly name = 'skrill';
+  private readonly cfg: SkrillConfig;
+  private readonly transport: HttpTransport;
+
+  constructor(cfg: SkrillConfig, transport: HttpTransport) {
+    this.cfg = cfg;
+    this.transport = transport;
+    if (!cfg.merchantEmail) throw new PaymentError('skrill merchantEmail required', { code: 'CONFIG', provider: 'skrill' });
+  }
+
+  async createOrder(input: CreateOrderInput): Promise<Order> {
+    const params = new URLSearchParams();
+    params.set('pay_to_email', this.cfg.merchantEmail);
+    params.set('transaction_id', input.reference);
+    params.set('amount', input.amount.toFixed(2));
+    params.set('currency', input.currency);
+    params.set('detail1_description', input.description ?? 'Order');
+    params.set('detail1_text', input.reference);
+    if (input.returnUrl) params.set('return_url', input.returnUrl);
+    if (input.cancelUrl) params.set('cancel_url', input.cancelUrl);
+    if (input.returnUrl) params.set('status_url', input.returnUrl);
+    return {
+      id: input.reference,
+      reference: input.reference,
+      status: 'created',
+      amount: input.amount,
+      currency: input.currency,
+      paymentUrl: `${CHECKOUT_URL}?${params.toString()}`,
+      raw: Object.fromEntries(params),
+    };
+  }
+
+  /** Skrill captures on the hosted page; no server-side capture. */
+  async capture(input: CaptureInput): Promise<Order> {
+    return this.getOrderStatus(input.orderId);
+  }
+
+  async refund(_input: RefundInput): Promise<RefundResult> {
+    return { id: `skrill-refund`, status: 'pending', amount: 0, raw: { note: 'Skrill refund via merchant panel (v1)' } };
+  }
+
+  async getOrderStatus(orderId: string): Promise<Order> {
+    return { id: orderId, reference: orderId, status: 'pending', amount: 0, currency: '', raw: { note: 'Skrill status via webhook (v1)' } };
+  }
+
+  async verifyWebhook(input: WebhookVerifyInput): Promise<WebhookEvent> {
+    const raw = typeof input.rawBody === 'string' ? input.rawBody : input.rawBody.toString();
+    const fields = parseForm(raw);
+    const provided = fields.md5sig;
+    if (!provided) return { verified: false, provider: this.name, data: 'no md5sig in payload' };
+    if (!this.cfg.secretWord) return { verified: false, provider: this.name, data: 'no secretWord configured' };
+    const message = `${this.cfg.merchantEmail}${this.cfg.secretWord}${fields.mb_transaction_id ?? ''}${fields.amount ?? ''}${fields.currency ?? ''}`;
+    const expected = md5Hex(message).toUpperCase();
+    const verified = safeEqual(provided.toUpperCase(), expected);
+    return {
+      verified,
+      event: fields.status ? `payment.${fields.status}` : undefined,
+      data: fields,
+      provider: this.name,
+    };
+  }
+}
+
+function parseForm(body: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const pair of body.split('&')) {
+    if (!pair) continue;
+    const [k, ...rest] = pair.split('=');
+    out[decodeURIComponent(k!)] = decodeURIComponent(rest.join('='));
+  }
+  return out;
+}

package/src/signature.ts

@@ -0,0 +1,24 @@
+import { createHmac, createHash } from 'node:crypto';
+
+/** HMAC-SHA256 hex digest (Razorpay webhooks + PayU v2). */
+export function hmacSha256Hex(key: string | Buffer, message: string): string {
+  return createHmac('sha256', key).update(message).digest('hex');
+}
+
+/** SHA-512 hex digest (PayU payment hash). */
+export function sha512Hex(message: string): string {
+  return createHash('sha512').update(message).digest('hex');
+}
+
+/** MD5 hex digest (Skrill Quick Checkout signature). */
+export function md5Hex(message: string): string {
+  return createHash('md5').update(message).digest('hex');
+}
+
+/** Constant-time string compare (webhook signature verification). */
+export function safeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}

package/src/types.ts

@@ -0,0 +1,150 @@
+/**
+ * Unified payment provider interface. All gateway adapters implement this so the
+ * app code is gateway-agnostic. Amounts are expressed in MAJOR units (e.g. 10.50
+ * = $10.50); each provider converts to its native representation (Razorpay paise,
+ * PayPal decimal string, PayU string, etc.).
+ *
+ * Tiering (documented in README):
+ *   - Razorpay: full (REST + signature verify)
+ *   - PayPal:   full (Orders v2 + OAuth2)
+ *   - PayU:     happy-path (hash-based create + webhook verify)
+ *   - Skrill:   happy-path (Quick Checkout URL + MD5 signature)
+ *   - Payoneer: happy-path (signed redirect; Payoneer has no public sandbox
+ *               without a registered program — verified structurally, not live)
+ */
+
+export type OrderStatus =
+  | 'created'
+  | 'pending'
+  | 'authorized'
+  | 'paid'
+  | 'captured'
+  | 'failed'
+  | 'refunded'
+  | 'cancelled';
+
+export interface Money {
+  /** Amount in major units (e.g. 10.50). */
+  amount: number;
+  /** ISO 4217 currency code. */
+  currency: string;
+}
+
+export interface CustomerInfo {
+  email?: string;
+  name?: string;
+  phone?: string;
+  userId?: string;
+}
+
+export interface CreateOrderInput {
+  amount: number;
+  currency: string;
+  /** Merchant order id / receipt reference. */
+  reference: string;
+  description?: string;
+  customer?: CustomerInfo;
+  /** Hosted-checkout return URL (PayPal/Skrill/PayU). */
+  returnUrl?: string;
+  cancelUrl?: string;
+}
+
+export interface Order {
+  /** Provider order id. */
+  id: string;
+  /** Merchant reference echoed back. */
+  reference: string;
+  status: OrderStatus;
+  amount: number;
+  currency: string;
+  /** Hosted checkout / redirect URL, when the provider offers one. */
+  paymentUrl?: string;
+  /** Provider payment id once a payment exists. */
+  paymentId?: string;
+  /** Raw provider response for debugging / extra fields. */
+  raw: unknown;
+}
+
+export interface CaptureInput {
+  orderId: string;
+  paymentId?: string;
+  /** Partial capture amount (major units); omitted = full. */
+  amount?: number;
+}
+
+export interface RefundInput {
+  paymentId: string;
+  amount?: number;
+  reason?: string;
+}
+
+export interface RefundResult {
+  id: string;
+  status: string;
+  amount: number;
+  raw: unknown;
+}
+
+export interface WebhookVerifyInput {
+  rawBody: string | Buffer;
+  headers: Record<string, string>;
+  /** Route params (e.g. provider name) if mounted on a param route. */
+  params?: Record<string, string>;
+}
+
+export interface WebhookEvent {
+  verified: boolean;
+  /** Event type (e.g. "payment.captured", "refund.created"). */
+  event?: string;
+  /** Normalized payload — provider-specific. */
+  data?: unknown;
+  /** Provider name that produced the event. */
+  provider?: string;
+}
+
+/** Result of a live connectivity probe (admin test console). */
+export interface ConnectionTest {
+  ok: boolean;
+  /** Human note on success (e.g. "authenticated as sandbox merchant"). */
+  detail?: string;
+  /** Error message when ok is false. */
+  error?: string;
+}
+
+export interface PaymentProvider {
+  readonly name: string;
+  createOrder(input: CreateOrderInput): Promise<Order>;
+  capture(input: CaptureInput): Promise<Order>;
+  refund(input: RefundInput): Promise<RefundResult>;
+  getOrderStatus(orderId: string): Promise<Order>;
+  verifyWebhook(input: WebhookVerifyInput): Promise<WebhookEvent>;
+  /**
+   * Optional live check that exercises the provider's API (e.g. listing orders /
+   * exchanging an OAuth token) WITHOUT creating money movement. Implemented by
+   * providers that can be probed anonymously; the admin test console calls it to
+   * show a green/red signal. Providers without a safe probe omit it and are
+   * reported as "configured — no public probe".
+   */
+  testConnection?(): Promise<ConnectionTest>;
+}
+
+/** Injectable HTTP transport so providers are testable without live gateways. */
+export interface HttpRequest {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  url: string;
+  headers?: Record<string, string>;
+  body?: string;
+}
+export interface HttpResponse {
+  status: number;
+  body: string;
+  headers?: Record<string, string>;
+}
+export type HttpTransport = (req: HttpRequest) => Promise<HttpResponse>;
+
+/** Provider configuration as it appears in nexus.config.ts `payments.<provider>`. */
+export interface ProviderConfig {
+  enabled: boolean;
+  sandbox: boolean;
+  [key: string]: unknown;
+}

package/src/webhooks.ts

@@ -0,0 +1,58 @@
+import type { RequestContext, Handler } from '@bhooai/nexus-core/http';
+import type { PaymentProvider, WebhookEvent } from './types.js';
+
+/**
+ * Webhook router: mounts on a route like `/payments/webhook/:provider` and
+ * dispatches the raw body to the named provider's `verifyWebhook`. Verified
+ * events are handed to `onEvent` (the app's business logic); unverified events
+ * are rejected with 401. The handler always responds 200 to the gateway once the
+ * event is accepted (so it isn't retried), or 401 on bad signatures.
+ */
+export class WebhookRouter {
+  private readonly providers: Map<string, PaymentProvider>;
+  private readonly onEvent: (event: WebhookEvent) => Promise<void> | void;
+
+  constructor(providers: Map<string, PaymentProvider>, onEvent: (event: WebhookEvent) => Promise<void> | void) {
+    this.providers = providers;
+    this.onEvent = onEvent;
+  }
+
+  /** nexus-core Handler for `POST /payments/webhook/:provider`. */
+  handler: Handler = async (ctx) => {
+    const providerName = ctx.params.provider;
+    const provider = providerName ? this.providers.get(providerName) : undefined;
+    if (!provider) {
+      ctx.json({ error: `unknown provider: ${providerName}` }, 404);
+      return;
+    }
+    // The body parser may have parsed JSON/form; webhooks need the RAW body for
+    // signature verification. The bodyParser stores the original string under
+    // state.__rawBody when available; fall back to re-serializing the parsed body.
+    const rawBody = (ctx.state.__rawBody as string | Buffer | undefined) ?? serializeBody(ctx.body);
+    const headers: Record<string, string> = {};
+    for (const [k, v] of Object.entries(ctx.headers)) {
+      if (typeof v === 'string') headers[k] = v;
+      else if (Array.isArray(v) && v.length) headers[k] = v[0]!;
+    }
+    const event = await provider.verifyWebhook({ rawBody, headers, params: ctx.params });
+    if (!event.verified) {
+      ctx.json({ error: 'signature verification failed' }, 401);
+      return;
+    }
+    try {
+      await this.onEvent(event);
+    } catch (err) {
+      // Log but still ACK so the gateway doesn't retry; the app should persist + retry internally.
+      ctx.json({ ok: false, error: (err as Error).message }, 200);
+      return;
+    }
+    ctx.json({ ok: true }, 200);
+  };
+}
+
+function serializeBody(body: unknown): string {
+  if (typeof body === 'string') return body;
+  if (Buffer.isBuffer(body)) return body.toString();
+  if (body == null) return '';
+  try { return JSON.stringify(body); } catch { return String(body); }
+}