@suluk/payments 0.1.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@suluk/payments",
+  "version": "0.1.0",
+  "description": "Provider-agnostic payments — a Workers-native TypeScript reimplementation of the Hyperswitch Prism connector interface. ONE unified request schema (authorize/capture/void/refund/sync + optional customer/tokenize/recurring/webhook); switch processor by config, not code. Prism's native FFI core can't run on the edge, so we adopt its interface + integer-exact status semantics and implement over fetch — zero native deps, light, swappable. The seam that supersedes @suluk/stripe. INTERFACE-first (C048); real connectors + the billing rewire follow. CANDIDATE tooling.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+    "directory": "tooling/ts/packages/payments"
+  },
+  "homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+  "bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p ."
+  }
+}

package/src/connector.ts

@@ -0,0 +1,92 @@
+/**
+ * The agnostic seam (C048) — the `PaymentConnector` interface every processor implements, plus the Prism-style
+ * config-selects-the-connector model: you pass ONE `connectorConfig` naming the processor + its credentials, and
+ * `paymentClient` returns a connector bound to it. Switching Stripe→Adyen is a config change, not a code change — the
+ * whole point. Connectors are FETCH-based (Workers-native); they translate the unified schema to a processor's REST API
+ * and its response back. This file is the INTERFACE; concrete connectors (stripe, adyen, …) are separate modules.
+ */
+import type {
+  AuthorizeRequest, PaymentResponse, CaptureRequest, VoidRequest, RefundRequest, RefundResponse, SyncRequest, Secret,
+  ClientSession, CreatePaymentSessionRequest, CreateSetupSessionRequest,
+} from "./types";
+import { IntegrationError } from "./errors";
+
+/** Per-request HTTP tuning + the mockable transport seam (a Worker passes nothing → global fetch; a test passes a mock). */
+export interface HttpOptions {
+  fetch?: typeof fetch;
+  totalTimeoutMs?: number;
+}
+
+/**
+ * A payment processor behind the unified schema. The CORE flows (authorize/capture/void/refund/sync) are required; the
+ * advanced surfaces (customer, tokenize/vault, recurring, webhook) are OPTIONAL — a connector declares them as it gains
+ * coverage, and the caller feature-detects. A soft decline is returned as `status: FAILURE`, never thrown.
+ */
+export interface PaymentConnector {
+  /** the processor id, e.g. "stripe". */
+  readonly name: string;
+  authorize(req: AuthorizeRequest): Promise<PaymentResponse>;
+  capture(req: CaptureRequest): Promise<PaymentResponse>;
+  void(req: VoidRequest): Promise<PaymentResponse>;
+  refund(req: RefundRequest): Promise<RefundResponse>;
+  sync(req: SyncRequest): Promise<PaymentResponse>;
+
+  // ── optional advanced surfaces (mirroring Prism's extra clients); added per-connector as supported ──
+  /** create a processor customer (returns its id). */
+  createCustomer?(req: { email?: string; metadata?: Record<string, string> }): Promise<{ customerId: string }>;
+  /** vault an instrument → a reusable token (the app/processor vault; the library stores nothing). */
+  tokenize?(req: { customerId?: string; paymentMethod: AuthorizeRequest["paymentMethod"] }): Promise<{ token: Secret }>;
+  /** set up an off-session mandate for recurring charges. */
+  recurringSetup?(req: { customerId: string; paymentMethod: AuthorizeRequest["paymentMethod"] }): Promise<{ mandateId: string }>;
+  /** charge an established recurring mandate off-session. */
+  recurringCharge?(req: { mandateId: string; amount: AuthorizeRequest["amount"]; merchantTransactionId: string }): Promise<PaymentResponse>;
+  /** revoke a recurring mandate. */
+  recurringRevoke?(req: { mandateId: string }): Promise<void>;
+  /** verify + normalize a processor webhook into a unified event. */
+  handleWebhook?(raw: string, headers: Record<string, string>): Promise<WebhookEvent>;
+
+  // ── the client-token surface (Prism's MerchantAuthenticationClient) — browser-confirmable sessions ──
+  /** Create a browser-confirmable PAYMENT session (Stripe PaymentIntent client_secret) — the Payment-Element / one-click
+   *  path. The browser confirms with the processor SDK; crediting happens on the webhook, not here. */
+  createPaymentSession?(req: CreatePaymentSessionRequest): Promise<ClientSession>;
+  /** Create a browser-confirmable SETUP session (Stripe SetupIntent client_secret) — vault a card without charging. */
+  createSetupSession?(req: CreateSetupSessionRequest): Promise<ClientSession>;
+}
+
+/** A normalized webhook event (the unified shape a connector's handleWebhook produces). */
+export interface WebhookEvent {
+  type: string;
+  connectorTransactionId?: string;
+  status?: number;
+  raw: unknown;
+}
+
+/** A connector's typed credentials (per processor). `Secret`-wrapped so keys aren't logged. */
+export type ConnectorAuth = Record<string, Secret | undefined>;
+
+/** The Prism-shaped config: exactly ONE processor named under `connectorConfig`. */
+export interface ConnectorConfig {
+  connectorConfig: Record<string, ConnectorAuth>;
+}
+
+/** Builds a connector from its typed auth + http options — what each processor module exports. */
+export type ConnectorFactory = (auth: ConnectorAuth, http?: HttpOptions) => PaymentConnector;
+
+/** The connector registry: processor id → factory. The app composes it from the connector modules it ships. */
+export type ConnectorRegistry = Record<string, ConnectorFactory>;
+
+/**
+ * The Prism-style entry point: read the single processor named in `config.connectorConfig`, look up its factory in the
+ * registry, and return a bound {@link PaymentConnector}. Throws {@link IntegrationError} on a config that names zero, more
+ * than one, or an unregistered processor — a request-phase bug, surfaced before any money moves.
+ */
+export function paymentClient(config: ConnectorConfig, registry: ConnectorRegistry, http?: HttpOptions): PaymentConnector {
+  const names = Object.keys(config.connectorConfig ?? {});
+  if (names.length !== 1) {
+    throw new IntegrationError("INVALID_CONFIGURATION", `connectorConfig must name exactly one processor (got ${names.length}: [${names.join(", ")}])`);
+  }
+  const name = names[0];
+  const factory = registry[name];
+  if (!factory) throw new IntegrationError("INVALID_CONFIGURATION", `no connector registered for "${name}" (registry has: [${Object.keys(registry).join(", ")}])`);
+  return factory(config.connectorConfig[name], http);
+}

package/src/connectors/stripe.ts

@@ -0,0 +1,183 @@
+/**
+ * The built-in Stripe connector (C048) — the first real backend for the agnostic {@link PaymentConnector}. It translates
+ * the unified schema to Stripe's REST API (`fetch` over `x-www-form-urlencoded`, Workers-native — no `stripe` SDK, no
+ * native deps) and maps Stripe's response back to the integer-exact unified {@link PaymentStatus}/{@link RefundStatus}.
+ * The status MAPPING is the load-bearing, parity-critical part (a wrong mapping silently mis-reports a charge), so every
+ * arm is witnessed. Soft declines come back IN-BAND as `FAILURE`/`AUTHENTICATION_PENDING`; only transport/unexpected
+ * errors throw (Prism's contract).
+ */
+import type { ConnectorAuth, ConnectorFactory, HttpOptions, PaymentConnector } from "../connector";
+import { ConnectorError, IntegrationError, NetworkError } from "../errors";
+import { PaymentStatus, RefundStatus, CaptureMethod, type PaymentResponse } from "../types";
+import { stripePost, stripeGet, toForm } from "../stripe-transport";
+
+interface StripePi {
+  id?: string;
+  status?: string;
+  amount?: number;
+  currency?: string;
+  client_secret?: string;
+  next_action?: { redirect_to_url?: { url?: string } };
+  last_payment_error?: { code?: string; message?: string; decline_code?: string };
+}
+interface StripeErr {
+  error?: { type?: string; code?: string; message?: string; decline_code?: string; payment_intent?: StripePi };
+}
+
+/** Stripe PaymentIntent.status → the unified PaymentStatus (the parity table). */
+function mapPiStatus(s: string | undefined): PaymentStatus {
+  switch (s) {
+    case "succeeded": return PaymentStatus.CHARGED;
+    case "requires_capture": return PaymentStatus.AUTHORIZED;
+    case "requires_action":
+    case "requires_confirmation": return PaymentStatus.AUTHENTICATION_PENDING;
+    case "processing": return PaymentStatus.PENDING;
+    case "canceled": return PaymentStatus.VOIDED;
+    case "requires_payment_method": return PaymentStatus.FAILURE; // the (initial) attempt didn't succeed
+    default: return PaymentStatus.UNRESOLVED;
+  }
+}
+
+/** Stripe Refund.status → the unified RefundStatus. */
+function mapRefundStatus(s: string | undefined): RefundStatus {
+  switch (s) {
+    case "succeeded": return RefundStatus.REFUND_SUCCESS;
+    case "pending":
+    case "requires_action": return RefundStatus.REFUND_PENDING;
+    case "failed":
+    case "canceled": return RefundStatus.REFUND_FAILURE;
+    default: return RefundStatus.UNSPECIFIED;
+  }
+}
+
+/** Build the unified PaymentResponse from a Stripe PI (the success/redirect arm). */
+function piToResponse(pi: StripePi): PaymentResponse {
+  const status = mapPiStatus(pi.status);
+  const res: PaymentResponse = { status, connectorTransactionId: pi.id };
+  if (status === PaymentStatus.AUTHENTICATION_PENDING && pi.next_action?.redirect_to_url?.url) {
+    res.redirectionData = { url: pi.next_action.redirect_to_url.url, method: "GET" };
+  }
+  if (pi.amount != null && pi.currency) res.amount = { minorAmount: pi.amount, currency: pi.currency.toUpperCase() };
+  return res;
+}
+
+export const stripeConnector: ConnectorFactory = (auth: ConnectorAuth, http?: HttpOptions): PaymentConnector => {
+  const secret = auth.apiKey?.value;
+  if (!secret) throw new IntegrationError("INVALID_CONFIGURATION", "stripe connector needs { apiKey: { value } }");
+  const doFetch = http?.fetch ?? fetch;
+
+  const cfg = { secretKey: secret, fetch: doFetch };
+  async function call(path: string, form: URLSearchParams | null, idempotencyKey?: string): Promise<{ ok: boolean; status: number; json: StripePi & StripeErr }> {
+    let res: Response;
+    try {
+      res = form ? await stripePost(cfg, path, form, idempotencyKey) : await stripeGet(cfg, path);
+    } catch (e) {
+      throw new NetworkError("CONNECT_TIMEOUT", e instanceof Error ? e.message : String(e));
+    }
+    const json = (await res.json().catch(() => ({}))) as StripePi & StripeErr;
+    return { ok: res.ok, status: res.status, json };
+  }
+
+  return {
+    name: "stripe",
+
+    async authorize(req) {
+      const form: Record<string, unknown> = {
+        amount: req.amount.minorAmount,
+        currency: req.amount.currency.toLowerCase(),
+        capture_method: req.captureMethod === CaptureMethod.MANUAL ? "manual" : "automatic",
+        confirm: true,
+        customer: req.customerId,
+        off_session: req.offSession ? true : undefined,
+        setup_future_usage: req.setupFutureUsage ? "off_session" : undefined,
+        return_url: req.returnUrl,
+        metadata: { merchantTransactionId: req.merchantTransactionId, ...req.metadata },
+      };
+      const token = req.paymentMethod.token?.value; // a saved/vaulted payment method id (Secret)
+      if (token) {
+        form.payment_method = token; // a saved/vaulted payment method id
+      } else if (req.paymentMethod.card) {
+        const c = req.paymentMethod.card;
+        form.payment_method_data = { type: "card", card: { number: c.cardNumber.value, exp_month: c.cardExpMonth.value, exp_year: c.cardExpYear.value, cvc: c.cardCvc.value } };
+      } else {
+        throw new IntegrationError("MISSING_REQUIRED_FIELD", "authorize needs paymentMethod.card or paymentMethod.token");
+      }
+      // the merchant txn id is the idempotency key — a retry of the SAME logical charge never double-charges.
+      const { ok, status, json } = await call("payment_intents", toForm(form), `auth:${req.merchantTransactionId}`);
+      if (ok) return piToResponse(json);
+      // error arm: an off-session 3DS decline carries the PI (→ AUTHENTICATION_PENDING); a card decline is an in-band
+      // FAILURE (Stripe returns HTTP 402 / `type: card_error` for these — an EXPECTED card outcome, not a transport
+      // failure); anything else (4xx config error, 5xx, network) THROWS as a ConnectorError.
+      const err = json.error;
+      if (err?.code === "authentication_required" && err.payment_intent) {
+        return { status: PaymentStatus.AUTHENTICATION_PENDING, connectorTransactionId: err.payment_intent.id, error: { code: err.code, message: err.message } };
+      }
+      if (status === 402 || err?.type === "card_error") {
+        return { status: PaymentStatus.FAILURE, connectorTransactionId: err?.payment_intent?.id, error: { code: err?.decline_code ?? err?.code, message: err?.message } };
+      }
+      throw new ConnectorError(err?.code ?? "stripe_error", err?.message ?? `Stripe authorize failed (HTTP ${status})`);
+    },
+
+    async capture(req) {
+      const { ok, json } = await call(`payment_intents/${req.connectorTransactionId}/capture`, toForm({ amount_to_capture: req.amountToCapture.minorAmount }));
+      if (!ok) return { status: PaymentStatus.CAPTURE_FAILED, connectorTransactionId: req.connectorTransactionId, error: { code: json.error?.code, message: json.error?.message } };
+      return piToResponse(json);
+    },
+
+    async void(req) {
+      const { ok, json } = await call(`payment_intents/${req.connectorTransactionId}/cancel`, toForm({ cancellation_reason: "requested_by_customer" }));
+      if (!ok) return { status: PaymentStatus.VOID_FAILED, connectorTransactionId: req.connectorTransactionId, error: { code: json.error?.code, message: json.error?.message } };
+      return piToResponse(json);
+    },
+
+    async refund(req) {
+      const { ok, json } = await call("refunds", toForm({ payment_intent: req.connectorTransactionId, amount: req.refundAmount.minorAmount }), `refund:${req.merchantRefundId}`);
+      const r = json as { id?: string; status?: string } & StripeErr;
+      if (!ok) return { status: RefundStatus.REFUND_FAILURE, error: { code: r.error?.code, message: r.error?.message } };
+      return { status: mapRefundStatus(r.status), connectorRefundId: r.id };
+    },
+
+    async sync(req) {
+      const { ok, json } = await call(`payment_intents/${req.connectorTransactionId}`, null);
+      if (!ok) return { status: PaymentStatus.UNRESOLVED, connectorTransactionId: req.connectorTransactionId, error: { code: json.error?.code, message: json.error?.message } };
+      return piToResponse(json);
+    },
+
+    async createCustomer(req) {
+      const { ok, json } = await call("customers", toForm({ email: req.email, metadata: req.metadata }));
+      const c = json as { id?: string } & StripeErr;
+      if (!ok || !c.id) throw new ConnectorError(c.error?.code ?? "stripe_error", c.error?.message ?? "Stripe customer create failed");
+      return { customerId: c.id };
+    },
+
+    async createPaymentSession(req) {
+      const form: Record<string, unknown> = {
+        amount: req.amount.minorAmount,
+        currency: req.amount.currency.toLowerCase(),
+        customer: req.customerId,
+        metadata: req.metadata,
+        ...(req.captureMethod === CaptureMethod.MANUAL ? { capture_method: "manual" } : {}),
+        ...(req.setupFutureUsage ? { setup_future_usage: "off_session" } : {}),
+      };
+      const token = req.paymentMethod?.value;
+      // a saved token → a one-click charge pinned to it; otherwise the browser collects the card (Payment Element).
+      if (token) { form.payment_method = token; form.payment_method_types = ["card"]; }
+      else form.automatic_payment_methods = { enabled: true };
+      const { ok, status, json } = await call("payment_intents", toForm(form));
+      if (!ok || json.error || !json.client_secret) throw new ConnectorError(json.error?.code ?? "stripe_error", json.error?.message ?? `Stripe payment session failed (HTTP ${status})`);
+      return { clientSecret: json.client_secret, connectorTransactionId: json.id, customerId: req.customerId };
+    },
+
+    async createSetupSession(req) {
+      const { ok, status, json } = await call("setup_intents", toForm({
+        customer: req.customerId,
+        automatic_payment_methods: { enabled: true },
+        usage: "off_session",
+        metadata: req.metadata,
+      }));
+      if (!ok || json.error || !json.client_secret) throw new ConnectorError(json.error?.code ?? "stripe_error", json.error?.message ?? `Stripe setup session failed (HTTP ${status})`);
+      return { clientSecret: json.client_secret, connectorTransactionId: json.id, customerId: req.customerId };
+    },
+  };
+};
+

package/src/errors.ts

@@ -0,0 +1,24 @@
+/**
+ * The error taxonomy (C048) — mirrors Prism's three hard-failure classes. A SOFT decline is NOT one of these: it comes
+ * back in-band as `status: FAILURE` on the response. These are thrown only for request-phase config/validation problems
+ * (`IntegrationError`), unexpected processor responses (`ConnectorError`), and transport failures (`NetworkError`) — so a
+ * caller can distinguish "the card was declined" (in-band, expected) from "the integration is broken" (thrown).
+ */
+export class PaymentLibError extends Error {
+  constructor(
+    public readonly errorCode: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+/** Request-phase: bad/missing config, a missing required field, a serialization failure. The caller's bug to fix. */
+export class IntegrationError extends PaymentLibError {}
+
+/** Response-phase: the processor returned an unexpected shape the connector couldn't transform. */
+export class ConnectorError extends PaymentLibError {}
+
+/** Transport: timeout, connection refused, DNS failure — may recover on retry. */
+export class NetworkError extends PaymentLibError {}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @suluk/payments — provider-agnostic payments for a Suluk app (C048). A Workers-native TypeScript reimplementation of the
+ * Hyperswitch Prism connector interface: ONE unified request schema (authorize / capture / void / refund / sync + the
+ * optional customer / tokenize / recurring / webhook surfaces), and you switch processor by CONFIG, not code. Prism itself
+ * is a native FFI addon that can't run on the edge, so we adopt its interface + status semantics (integer-exact) and
+ * implement over `fetch` — zero native deps, light, swappable. This barrel is the INTERFACE + a mock connector; the real
+ * connectors (stripe, adyen, …) and the @suluk/billing rewire that deprecates @suluk/stripe are the follow-on builds.
+ */
+export * from "./types";
+export { IntegrationError, ConnectorError, NetworkError, PaymentLibError } from "./errors";
+export {
+  paymentClient,
+  type PaymentConnector, type ConnectorConfig, type ConnectorAuth, type ConnectorFactory, type ConnectorRegistry,
+  type HttpOptions, type WebhookEvent,
+} from "./connector";
+export { mockConnector, MOCK_DECLINE_CARD, MOCK_3DS_CARD } from "./mock";
+// the built-in Stripe connector (the first real backend; fetch → Stripe REST, Workers-native).
+export { stripeConnector } from "./connectors/stripe";
+// the low-level Stripe transport (one Stripe client) — for the Stripe-PLATFORM ops the agnostic seam doesn't model.
+export { type StripeConfig, stripePost, stripeGet, toForm } from "./stripe-transport";
+// pricing primitives — processor-agnostic checkout money math (moved from @suluk/stripe; anti-tampering, proration, …).
+export {
+  subtotal, computeDiscountAmount, validateDiscount, prorateDiscount, orderTotal, composeTotal, verifyAmount,
+  cartFingerprint, idempotencyKey, requiresStripe, STRIPE_MIN_CHARGE_CENTS,
+  type CartLine, type Discount, type DiscountResult, type DiscountRejection, type OrderTotal, type OrderTotalFull, type AmountVerdict,
+} from "./pricing";
+// the Stripe webhook surface (SDK-free signature verification + a typed event router; moved from @suluk/stripe).
+export {
+  verifyStripeSignature, timingSafeHexEqual, webhookRouter, STRIPE_EVENTS,
+  type VerifyOptions, type StripeWebhookEvent, type WebhookHandler, type WebhookRouter, type HandleResult,
+} from "./stripe-webhook";

package/src/mock.ts

@@ -0,0 +1,60 @@
+/**
+ * A mock connector (C048) — proves the {@link PaymentConnector} seam end-to-end without a real processor, and doubles as a
+ * deterministic local/test stand-in (like a processor's test mode). It keeps a tiny in-memory ledger so capture/void/
+ * refund/sync are coherent across a flow. Behaviour keys off the PAN: a decline test card → in-band `FAILURE`; a 3DS
+ * card (or `THREE_DS` auth) → `AUTHENTICATION_PENDING` + redirection; otherwise `CHARGED` (auto) / `AUTHORIZED` (manual).
+ * This is NOT a payment processor — the real connectors (stripe, adyen, …) are the follow-on build.
+ */
+import type { ConnectorFactory, PaymentConnector } from "./connector";
+import { IntegrationError } from "./errors";
+import { AuthenticationType, CaptureMethod, PaymentStatus, RefundStatus, type MinorAmount } from "./types";
+
+/** Well-known test PANs (Stripe-compatible values, for familiarity). */
+export const MOCK_DECLINE_CARD = "4000000000000002";
+export const MOCK_3DS_CARD = "4000000000003220";
+
+export const mockConnector: ConnectorFactory = (auth) => {
+  if (!auth.apiKey?.value) throw new IntegrationError("INVALID_CONFIGURATION", "mock connector needs an apiKey");
+  const ledger = new Map<string, { amount: MinorAmount; status: PaymentStatus }>();
+  let seq = 0;
+  const id = () => `mock_${++seq}`;
+
+  const connector: PaymentConnector = {
+    name: "mock",
+    async authorize(req) {
+      const pan = req.paymentMethod.card?.cardNumber.value ?? req.paymentMethod.token?.value ?? "";
+      if (pan === MOCK_DECLINE_CARD) return { status: PaymentStatus.FAILURE, error: { code: "card_declined", message: "Your card was declined." } };
+      if (req.authType === AuthenticationType.THREE_DS || pan === MOCK_3DS_CARD) {
+        const txn = id();
+        ledger.set(txn, { amount: req.amount, status: PaymentStatus.AUTHENTICATION_PENDING });
+        return { status: PaymentStatus.AUTHENTICATION_PENDING, connectorTransactionId: txn, redirectionData: { url: req.returnUrl ?? "https://mock.test/3ds", method: "GET" } };
+      }
+      const txn = id();
+      const status = req.captureMethod === CaptureMethod.MANUAL ? PaymentStatus.AUTHORIZED : PaymentStatus.CHARGED;
+      ledger.set(txn, { amount: req.amount, status });
+      return { status, connectorTransactionId: txn, amount: req.amount };
+    },
+    async capture(req) {
+      const t = ledger.get(req.connectorTransactionId);
+      if (!t) return { status: PaymentStatus.CAPTURE_FAILED, error: { code: "not_found", message: "unknown transaction" } };
+      t.status = PaymentStatus.CHARGED;
+      return { status: PaymentStatus.CHARGED, connectorTransactionId: req.connectorTransactionId, amount: req.amountToCapture };
+    },
+    async void(req) {
+      const t = ledger.get(req.connectorTransactionId);
+      if (!t) return { status: PaymentStatus.VOID_FAILED, error: { code: "not_found", message: "unknown transaction" } };
+      t.status = PaymentStatus.VOIDED;
+      return { status: PaymentStatus.VOIDED, connectorTransactionId: req.connectorTransactionId };
+    },
+    async refund(req) {
+      const t = ledger.get(req.connectorTransactionId);
+      if (!t) return { status: RefundStatus.REFUND_FAILURE, error: { code: "not_found", message: "unknown transaction" } };
+      return { status: RefundStatus.REFUND_SUCCESS, connectorRefundId: `mock_re_${++seq}` };
+    },
+    async sync(req) {
+      const t = ledger.get(req.connectorTransactionId);
+      return t ? { status: t.status, connectorTransactionId: req.connectorTransactionId, amount: t.amount } : { status: PaymentStatus.UNSPECIFIED };
+    },
+  };
+  return connector;
+};

package/src/pricing.ts

@@ -0,0 +1,167 @@
+/**
+ * MONEY — pure, side-effect-free pricing primitives (saastarter-parity roadmap, Phase 0; PARITY §2 trust layer).
+ *
+ * The checkout-resilience cluster is "invisible until the edge case hits; exactly what separates a toy cart from
+ * one you'd trust with money." Its core is arithmetic that MUST be authored once and conformance-tested, never
+ * re-derived per app where the cart-drawer total and the order-summary total silently drift:
+ *
+ *   • all money is INTEGER minor units (cents) — never a float (0.1 + 0.2 has no place near money);
+ *   • a discount NEVER exceeds the subtotal (no negative totals, no free-money over-discount);
+ *   • per-line proration sums EXACTLY to the order discount (largest-remainder), so every surface agrees;
+ *   • verifyAmount RECOMPUTES the total from authoritative prices and rejects a client-supplied amount that
+ *     doesn't match (anti-tampering — never trust the amount the browser sends);
+ *   • a deterministic idempotency key from the cart lets a retry REUSE one payment intent (no double-charge).
+ *
+ * The BUSINESS rules around a discount (is it active? in its date window? under its usage cap? category-limited?)
+ * stay the app's concern — this module is the MATH + the structural validation, the part every store shares.
+ */
+
+/** One cart line. `unitCents` is the authoritative price (from the server, not the client). */
+export interface CartLine { unitCents: number; qty: number; id?: string | number }
+
+/** A discount's MATH shape (the structural part; app-side eligibility rules are separate). */
+export interface Discount {
+  type: "percent" | "fixed";
+  /** percent: 0–100; fixed: cents off the subtotal. */
+  value: number;
+  /** the discount only applies at/above this subtotal (cents). */
+  minSubtotalCents?: number;
+  /** cap the amount removed (cents) — e.g. "30% off, up to $50". Applied before the [0, subtotal] clamp. */
+  maxDiscountCents?: number;
+}
+
+/** Stripe's minimum chargeable amount (USD). Below it, a charge is impossible — the order must go the free path. */
+export const STRIPE_MIN_CHARGE_CENTS = 50;
+
+/** Does this total require a real Stripe charge, or can it complete as a free order? Centralizes the $0.50 floor
+ *  decision so the free-checkout branch and the Stripe branch can never disagree about where $0–$0.49 goes. */
+export function requiresStripe(totalCents: number): boolean {
+  return Math.max(0, Math.round(fin(totalCents))) >= STRIPE_MIN_CHARGE_CENTS;
+}
+
+export interface DiscountResult { valid: boolean; amountCents: number; reason?: DiscountRejection }
+export type DiscountRejection = "no-discount" | "non-positive-value" | "percent-out-of-range" | "below-minimum";
+
+export interface OrderTotal { subtotalCents: number; discountCents: number; totalCents: number }
+export interface AmountVerdict { ok: boolean; expectedCents: number; claimedCents: number; deltaCents: number; reason?: "amount-mismatch" }
+
+const sum = (ns: number[]) => ns.reduce((a, b) => a + b, 0);
+/** Coerce a non-finite number (NaN/±Infinity) to 0 — money math must never propagate poison. */
+const fin = (n: number) => (Number.isFinite(n) ? n : 0);
+const lineTotal = (l: CartLine) => Math.max(0, Math.round(fin(l.unitCents))) * Math.max(0, Math.trunc(fin(l.qty)));
+
+/** Subtotal in cents — integer, non-negative. */
+export function subtotal(lines: CartLine[]): number {
+  return sum(lines.map(lineTotal));
+}
+
+/**
+ * The cents a discount removes from `subtotalCents` — ROUNDED to a whole cent and CLAMPED to [0, subtotal] so a
+ * discount can never exceed the order or go negative. Validation (eligibility) is `validateDiscount`; this is the
+ * raw amount assuming the discount applies.
+ */
+export function computeDiscountAmount(subtotalCents: number, d: Discount): number {
+  const base = Math.max(0, Math.round(fin(subtotalCents)));
+  if (base === 0 || !Number.isFinite(d.value) || d.value <= 0) return 0; // a non-finite/non-positive value buys nothing
+  const raw = d.type === "percent" ? (base * d.value) / 100 : d.value;
+  // cap a percentage (or fixed) discount at maxDiscountCents if set ("30% off, up to $50"), then clamp to [0, subtotal].
+  const capped = d.maxDiscountCents != null && Number.isFinite(d.maxDiscountCents) ? Math.min(raw, Math.max(0, d.maxDiscountCents)) : raw;
+  return Math.min(base, Math.max(0, Math.round(capped)));
+}
+
+/**
+ * Validate a discount against a subtotal, with a SPECIFIC rejection reason (PARITY: "specific discount-rejection
+ * reasons" — a shopper is told *why*, not just "invalid"). Structural only; the app layers active/window/usage.
+ */
+export function validateDiscount(subtotalCents: number, d: Discount | undefined | null): DiscountResult {
+  if (!d) return { valid: false, amountCents: 0, reason: "no-discount" };
+  if (d.value <= 0) return { valid: false, amountCents: 0, reason: "non-positive-value" };
+  if (d.type === "percent" && d.value > 100) return { valid: false, amountCents: 0, reason: "percent-out-of-range" };
+  if (d.minSubtotalCents != null && subtotalCents < d.minSubtotalCents) return { valid: false, amountCents: 0, reason: "below-minimum" };
+  return { valid: true, amountCents: computeDiscountAmount(subtotalCents, d) };
+}
+
+/**
+ * Split `discountCents` across `lines` proportionally to each line's total, as whole cents that sum EXACTLY to
+ * `discountCents` (largest-remainder apportionment). This is what keeps the cart drawer and the order summary
+ * from disagreeing by a cent. Each line's share is clamped to its own total.
+ */
+export function prorateDiscount(lines: CartLine[], discountCents: number): number[] {
+  const totals = lines.map(lineTotal);
+  const gross = sum(totals);
+  const want = Math.min(Math.max(0, Math.round(discountCents)), gross);
+  if (gross <= 0 || want <= 0) return lines.map(() => 0);
+  const exact = totals.map((t) => (want * t) / gross);
+  const shares = exact.map((e, i) => Math.min(totals[i], Math.floor(e)));
+  let remainder = want - sum(shares);
+  // hand the leftover cents to the lines with the largest fractional part that still have headroom
+  const order = exact
+    .map((e, i) => ({ i, frac: e - Math.floor(e) }))
+    .sort((a, b) => b.frac - a.frac || a.i - b.i);
+  for (let k = 0; remainder > 0 && k < order.length * 2; k++) {
+    const { i } = order[k % order.length];
+    if (shares[i] < totals[i]) { shares[i] += 1; remainder -= 1; }
+  }
+  return shares;
+}
+
+/** Compose the authoritative order total from lines + an optional (already-validated) discount. */
+export function orderTotal(lines: CartLine[], discount?: Discount | null): OrderTotal {
+  const subtotalCents = subtotal(lines);
+  const discountCents = discount ? validateDiscount(subtotalCents, discount).amountCents : 0;
+  return { subtotalCents, discountCents, totalCents: subtotalCents - discountCents };
+}
+
+/** The full order total once shipping + tax (from the ./shipping + ./tax adapters) are known. */
+export interface OrderTotalFull { subtotalCents: number; discountCents: number; shippingCents: number; taxCents: number; totalCents: number }
+
+/**
+ * Fold every component into ONE authoritative total: subtotal − discount + shipping + tax, each a non-negative whole
+ * cent and the discount never exceeding the subtotal. The single place the order total is composed once shipping (a
+ * ShippingOption) and tax (a TaxResult) are resolved — so the cart drawer, checkout summary, order record, and the
+ * Stripe charge can never disagree.
+ */
+export function composeTotal(parts: { subtotalCents: number; discountCents?: number; shippingCents?: number; taxCents?: number }): OrderTotalFull {
+  const subtotalCents = Math.max(0, Math.round(fin(parts.subtotalCents)));
+  const discountCents = Math.min(subtotalCents, Math.max(0, Math.round(fin(parts.discountCents ?? 0))));
+  const shippingCents = Math.max(0, Math.round(fin(parts.shippingCents ?? 0)));
+  const taxCents = Math.max(0, Math.round(fin(parts.taxCents ?? 0)));
+  return { subtotalCents, discountCents, shippingCents, taxCents, totalCents: subtotalCents - discountCents + shippingCents + taxCents };
+}
+
+/**
+ * ANTI-TAMPERING: recompute the total from authoritative line prices + the discount and compare it to the amount
+ * the client claims (e.g. a PaymentIntent amount the browser posted). Reject any mismatch beyond `toleranceCents`
+ * (default 0 — money is exact). The server must call this before honoring any client-supplied amount.
+ */
+export function verifyAmount(lines: CartLine[], discount: Discount | null | undefined, claimedCents: number, opts: { toleranceCents?: number } = {}): AmountVerdict {
+  const expectedCents = orderTotal(lines, discount).totalCents;
+  const deltaCents = Math.round(claimedCents) - expectedCents;
+  const ok = Math.abs(deltaCents) <= (opts.toleranceCents ?? 0);
+  return { ok, expectedCents, claimedCents: Math.round(claimedCents), deltaCents, ...(ok ? {} : { reason: "amount-mismatch" as const }) };
+}
+
+/**
+ * A stable fingerprint of the priced cart (+ discount) — order-independent over lines. Two carts that should be
+ * charged identically produce the same fingerprint; any price/qty/discount change produces a different one.
+ */
+export function cartFingerprint(lines: CartLine[], discount?: Discount | null): string {
+  const norm = lines
+    .map((l) => `${l.id ?? "?"}:${Math.round(l.unitCents)}x${Math.trunc(l.qty)}`)
+    .sort()
+    .join("|");
+  const d = discount ? `${discount.type}:${discount.value}:${discount.minSubtotalCents ?? ""}` : "";
+  const s = `${norm}#${d}`;
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 16777619) >>> 0; }
+  return h.toString(16).padStart(8, "0");
+}
+
+/**
+ * A deterministic idempotency key for a checkout attempt. The SAME cart under the same scope (principal) yields
+ * the SAME key, so a retried "create payment intent" REUSES the existing intent instead of charging twice; a
+ * changed cart yields a new key. Thread this into the processor's idempotency-key header.
+ */
+export function idempotencyKey(scope: string, lines: CartLine[], discount?: Discount | null): string {
+  return `co_${scope}_${cartFingerprint(lines, discount)}`;
+}

package/src/stripe-transport.ts

@@ -0,0 +1,44 @@
+/**
+ * The low-level Stripe HTTP transport (C048) — the fetch-based Stripe client the {@link stripeConnector} rides, exported
+ * so an app's Stripe-PLATFORM operations (hosted Checkout, subscriptions, saved-card management, Tax — the things the
+ * agnostic PaymentConnector deliberately doesn't model) ride the SAME client instead of a separate legacy one. This is
+ * intentionally Stripe-specific: agnostic payment FLOWS go through the connector, these platform ops through this
+ * transport — one Stripe roof, no accidental second path. Workers-native (fetch + x-www-form-urlencoded), zero deps.
+ */
+export interface StripeConfig {
+  secretKey: string;
+  /** the HTTP transport — a mock in tests; defaults to the global `fetch` in prod. */
+  fetch?: typeof fetch;
+}
+
+const BASE = "https://api.stripe.com/v1";
+
+export const stripePost = (cfg: StripeConfig, path: string, form: URLSearchParams, idempotencyKey?: string): Promise<Response> =>
+  (cfg.fetch ?? fetch)(`${BASE}/${path}`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${cfg.secretKey}`,
+      "content-type": "application/x-www-form-urlencoded",
+      // refunds/charges pass one so a retry of the SAME logical operation never moves money twice (Stripe replays it).
+      ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
+    },
+    body: form.toString(),
+  });
+
+export const stripeGet = (cfg: StripeConfig, path: string): Promise<Response> =>
+  (cfg.fetch ?? fetch)(`${BASE}/${path}`, { headers: { authorization: `Bearer ${cfg.secretKey}` } });
+
+/** Stripe's bracket-nested `x-www-form-urlencoded` encoder: objects → `key[k]`, arrays → `key[i]`, scalars appended;
+ *  undefined/null are skipped. Handles the nested arrays checkout/subscription payloads need (`line_items[0][price]`). */
+export function toForm(obj: Record<string, unknown>): URLSearchParams {
+  const out = new URLSearchParams();
+  for (const [k, v] of Object.entries(obj)) encode(k, v, out);
+  return out;
+}
+
+function encode(key: string, v: unknown, out: URLSearchParams): void {
+  if (v === undefined || v === null) return;
+  if (Array.isArray(v)) v.forEach((item, i) => encode(`${key}[${i}]`, item, out));
+  else if (typeof v === "object") for (const [k, val] of Object.entries(v as Record<string, unknown>)) encode(`${key}[${k}]`, val, out);
+  else out.append(key, String(v));
+}

package/src/stripe-webhook.ts

@@ -0,0 +1,98 @@
+/**
+ * The Stripe webhook surface (C048) — moved here from @suluk/stripe so the whole payment story (flows + transport +
+ * pricing + webhooks) lives under @suluk/payments. Two pieces: SDK-free signature VERIFICATION (Web Crypto HMAC-SHA256 —
+ * Workers/Bun/Node 18+, no `stripe` SDK) and a typed event ROUTER (dispatch a verified event to a per-type handler
+ * instead of one giant switch). Pure of any SDK + network. @suluk/stripe re-exports these as a deprecated shim.
+ */
+
+// ── signature verification ────────────────────────────────────────────────────────────────────────────────────────
+
+/** Constant-time hex-string compare (no early-out) — guards the signature check against timing oracles. */
+export function timingSafeHexEqual(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;
+}
+
+export interface VerifyOptions {
+  /** current unix seconds (default `Date.now()/1000`) — injectable for tests + replay-window tuning. */
+  now?: () => number;
+  /** reject events whose timestamp is older than this many seconds (default 300 — Stripe's window). */
+  toleranceSec?: number;
+}
+
+/**
+ * Verify a Stripe `stripe-signature` header against the raw request body + the endpoint signing secret. Returns true iff
+ * a v1 signature matches the HMAC of `${t}.${rawBody}` AND the timestamp is within tolerance. Pass the RAW (unparsed)
+ * body — re-serializing JSON changes the bytes and breaks the HMAC.
+ */
+export async function verifyStripeSignature(rawBody: string, sigHeader: string, secret: string, opts: VerifyOptions = {}): Promise<boolean> {
+  if (!rawBody || !sigHeader || !secret) return false;
+  const parts: Record<string, string> = {};
+  for (const p of sigHeader.split(",")) { const i = p.indexOf("="); if (i > 0 && !(p.slice(0, i) in parts)) parts[p.slice(0, i)] = p.slice(i + 1); } // split on the FIRST '=' only
+  const ts = Number(parts.t);
+  if (!parts.t || !parts.v1 || !Number.isFinite(ts)) return false;
+  const now = (opts.now ?? (() => Date.now() / 1000))();
+  if (Math.abs(now - ts) > (opts.toleranceSec ?? 300)) return false; // reject stale/replayed events (Stripe's 5-min window)
+  const keyData = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = await crypto.subtle.sign("HMAC", keyData, new TextEncoder().encode(`${ts}.${rawBody}`));
+  const expected = [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return timingSafeHexEqual(expected, parts.v1);
+}
+
+// ── the typed event router ────────────────────────────────────────────────────────────────────────────────────────
+
+/** A verified webhook event — only `type` is required (the router dispatches on it); `data` carries the payload. */
+export interface StripeWebhookEvent {
+  type: string;
+  data?: unknown;
+}
+
+export type WebhookHandler = (event: StripeWebhookEvent) => void | Promise<void>;
+
+export interface HandleResult {
+  type: string;
+  /** a registered handler ran (false ⇒ the unhandled fallback ran, or nothing matched). */
+  handled: boolean;
+}
+
+export interface WebhookRouter {
+  /** register (or replace) the handler for an event type; chainable. */
+  on(type: string, handler: WebhookHandler): WebhookRouter;
+  /** register a fallback for types with no specific handler; chainable. */
+  onUnhandled(handler: WebhookHandler): WebhookRouter;
+  /** dispatch one verified event to its handler. */
+  handle(event: StripeWebhookEvent): Promise<HandleResult>;
+}
+
+/** Build a router, optionally seeded with a `{ type → handler }` map. */
+export function webhookRouter(handlers: Record<string, WebhookHandler> = {}): WebhookRouter {
+  const map = new Map<string, WebhookHandler>(Object.entries(handlers));
+  let fallback: WebhookHandler | undefined;
+  const router: WebhookRouter = {
+    on(type, handler) { map.set(type, handler); return router; },
+    onUnhandled(handler) { fallback = handler; return router; },
+    async handle(event) {
+      const handler = map.get(event.type);
+      if (handler) { await handler(event); return { type: event.type, handled: true }; }
+      if (fallback) await fallback(event);
+      return { type: event.type, handled: false };
+    },
+  };
+  return router;
+}
+
+/** The common Stripe checkout/billing event types (for discoverability + typo-safe registration). */
+export const STRIPE_EVENTS = {
+  checkoutCompleted: "checkout.session.completed",
+  checkoutExpired: "checkout.session.expired",
+  paymentSucceeded: "payment_intent.succeeded",
+  paymentFailed: "payment_intent.payment_failed",
+  chargeRefunded: "charge.refunded",
+  disputeClosed: "charge.dispute.closed",
+  setupSucceeded: "setup_intent.succeeded",
+  subscriptionUpdated: "customer.subscription.updated",
+  subscriptionDeleted: "customer.subscription.deleted",
+  invoicePaid: "invoice.paid",
+} as const;

package/src/types.ts

@@ -0,0 +1,216 @@
+/**
+ * The unified payment schema (C048) — a Workers-native TypeScript reimplementation of the Hyperswitch Prism interface.
+ * Prism ships as a native FFI addon (Rust core) that can't run in a Cloudflare Worker, so we adopt its INTERFACE — one
+ * request schema for every processor — and implement it ourselves over `fetch` (zero native deps, edge-safe). The status
+ * enums mirror Prism's INTEGER values exactly, so a real Prism backend stays a drop-in later and connector semantics
+ * match. Sensitive values are wrapped in {@link Secret} (a PCI-scope signal — the library never logs them).
+ */
+
+/** A processor-side secret / PII value — wrapped so it's explicit at every call site and never accidentally logged. */
+export type Secret<T = string> = { value: T };
+
+/** ISO-4217 currency. A curated set for `Currency.USD`-style access; open to any code a connector accepts. */
+export const Currency = { USD: "USD", EUR: "EUR", GBP: "GBP", AED: "AED", SAR: "SAR", INR: "INR", CAD: "CAD", AUD: "AUD" } as const;
+export type Currency = (typeof Currency)[keyof typeof Currency] | (string & {});
+
+/** Auto-capture on authorize, or authorize-then-capture-later. */
+export enum CaptureMethod {
+  AUTOMATIC = "AUTOMATIC",
+  MANUAL = "MANUAL",
+}
+
+/** 3-D Secure preference. */
+export enum AuthenticationType {
+  NO_THREE_DS = "NO_THREE_DS",
+  THREE_DS = "THREE_DS",
+}
+
+/**
+ * Payment status — INTEGER values mirroring Prism exactly (do NOT renumber; a real Prism backend + connector code depend
+ * on these). A soft decline is `FAILURE` returned IN-BAND on the response (never thrown). Use with authorize/capture/void.
+ */
+export enum PaymentStatus {
+  UNSPECIFIED = 0,
+  STARTED = 1,
+  AUTHENTICATION_FAILED = 2,
+  ROUTER_DECLINED = 3,
+  AUTHENTICATION_PENDING = 4,
+  AUTHENTICATION_SUCCESSFUL = 5,
+  AUTHORIZED = 6,
+  AUTHORIZATION_FAILED = 7,
+  CHARGED = 8,
+  VOIDED = 11,
+  VOID_INITIATED = 12,
+  CAPTURE_INITIATED = 13,
+  CAPTURE_FAILED = 14,
+  VOID_FAILED = 15,
+  PARTIAL_CHARGED = 17,
+  UNRESOLVED = 19,
+  PENDING = 20,
+  FAILURE = 21,
+  PARTIALLY_AUTHORIZED = 25,
+  EXPIRED = 26,
+}
+
+/** Refund status — a SEPARATE enum from {@link PaymentStatus} with overlapping integers (mirrors Prism). `REFUND_PENDING`
+ *  is a normal success state for many processors — treat PENDING + SUCCESS both as success. */
+export enum RefundStatus {
+  UNSPECIFIED = 0,
+  REFUND_FAILURE = 1,
+  REFUND_MANUAL_REVIEW = 2,
+  REFUND_PENDING = 3,
+  REFUND_SUCCESS = 4,
+  REFUND_TRANSACTION_FAILURE = 5,
+}
+
+/** An amount in the currency's minor unit (cents), the Prism convention (no floats in the money path). */
+export interface MinorAmount {
+  minorAmount: number;
+  currency: Currency;
+}
+
+export interface CardDetails {
+  cardNumber: Secret;
+  cardExpMonth: Secret;
+  cardExpYear: Secret;
+  cardCvc: Secret;
+  cardHolderName?: Secret;
+}
+
+/** The payment instrument. Extend with wallet / bank-transfer as connectors gain coverage; card + token are the core.
+ *  `token` is a saved/vaulted instrument id (the app's or the processor's vault — the library stores nothing). */
+export interface PaymentMethod {
+  card?: CardDetails;
+  token?: Secret;
+}
+
+export interface Address {
+  line1?: string;
+  line2?: string;
+  city?: string;
+  state?: string;
+  postalCode?: string;
+  country?: string;
+}
+
+export interface OrderDetail {
+  description: string;
+  quantity?: number;
+  amount?: number;
+}
+
+/** A structured error the library surfaces (in-band on FAILURE, or on a thrown IntegrationError/ConnectorError). Only
+ *  primitive fields — never a processor's raw object (which may not be serializable). */
+export interface PaymentError {
+  message?: string;
+  code?: string;
+  reason?: string;
+}
+
+/** Where to send the customer for 3DS / redirect flows (present when status is AUTHENTICATION_PENDING). */
+export interface RedirectionData {
+  url?: string;
+  method?: "GET" | "POST";
+  fields?: Record<string, string>;
+}
+
+// ── Requests / responses (mirroring Prism's PaymentService* shapes) ───────────────────────────────────────────────────
+
+export interface AuthorizeRequest {
+  merchantTransactionId: string;
+  amount: MinorAmount;
+  captureMethod: CaptureMethod;
+  paymentMethod: PaymentMethod;
+  authType: AuthenticationType;
+  address?: Address;
+  returnUrl?: string;
+  orderDetails?: OrderDetail[];
+  /** an existing processor customer to attach the charge to (optional). */
+  customerId?: string;
+  /** save the instrument for later off-session use (recurring / one-click). */
+  setupFutureUsage?: boolean;
+  /** the charge is happening WITHOUT the cardholder present (auto top-up / recurring) — the processor may decline for
+   *  3DS (`AUTHENTICATION_PENDING`) rather than charge. Maps to Stripe `off_session`, Adyen `ContAuth`, etc. */
+  offSession?: boolean;
+  /** free-form key/value the processor stores + echoes on its webhook (e.g. `{ userId, credits }` the crediting path
+   *  reads). Most processors support it (Stripe metadata, Adyen additionalData). */
+  metadata?: Record<string, string>;
+  testMode?: boolean;
+}
+
+export interface PaymentResponse {
+  status: PaymentStatus;
+  connectorTransactionId?: string;
+  redirectionData?: RedirectionData;
+  error?: PaymentError;
+  /** the amount actually captured/authorized, when the processor reports it. */
+  amount?: MinorAmount;
+}
+
+export interface CaptureRequest {
+  merchantCaptureId: string;
+  connectorTransactionId: string;
+  amountToCapture: MinorAmount;
+  testMode?: boolean;
+}
+
+export interface VoidRequest {
+  merchantVoidId: string;
+  connectorTransactionId: string;
+  cancellationReason?: string;
+  testMode?: boolean;
+}
+
+export interface RefundRequest {
+  merchantRefundId: string;
+  connectorTransactionId: string;
+  refundAmount: MinorAmount;
+  /** the ORIGINAL payment amount (minor units) — some processors require it to compute a partial refund. */
+  paymentAmount: number;
+  reason?: string;
+  testMode?: boolean;
+}
+
+export interface RefundResponse {
+  status: RefundStatus;
+  connectorRefundId?: string;
+  error?: PaymentError;
+}
+
+export interface SyncRequest {
+  connectorTransactionId: string;
+  testMode?: boolean;
+}
+
+// ── the client-token surface (Prism's MerchantAuthenticationClient) — browser-confirmable sessions ────────────────────
+
+/**
+ * A browser-confirmable session: the server creates the intent, the browser SDK confirms it with `clientSecret`, so raw
+ * card data never touches the server (PCI-scope reduction). Crediting lands on the processor webhook, not the create
+ * call. This is the piece a pure server-side `authorize` can't express — the Payment-Element / one-click / add-card flows.
+ */
+export interface ClientSession {
+  /** the token the browser SDK confirms with — Stripe's `client_secret`; another processor's equivalent. */
+  clientSecret: string;
+  connectorTransactionId?: string;
+  customerId?: string;
+}
+
+/** Create a PAYMENT session to confirm in-browser. Omit `paymentMethod` for a Payment-Element flow (the browser collects
+ *  the card); pass a saved `paymentMethod` token for a one-click charge on a saved card. */
+export interface CreatePaymentSessionRequest {
+  amount: MinorAmount;
+  customerId?: string;
+  /** pin the charge to a saved instrument (one-click); omit to let the browser collect one (Payment Element). */
+  paymentMethod?: Secret;
+  captureMethod?: CaptureMethod;
+  /** save the collected card for later off-session use. */
+  setupFutureUsage?: boolean;
+  metadata?: Record<string, string>;
+}
+
+/** Create a SETUP session to vault a card without charging ("add card"). */
+export interface CreateSetupSessionRequest {
+  customerId: string;
+  metadata?: Record<string, string>;
+}

package/test/payments.test.ts

@@ -0,0 +1,87 @@
+import { test, expect, describe } from "bun:test";
+import {
+  paymentClient, mockConnector, MOCK_DECLINE_CARD, MOCK_3DS_CARD, IntegrationError,
+  PaymentStatus, RefundStatus, CaptureMethod, AuthenticationType, Currency,
+  type ConnectorConfig, type ConnectorRegistry, type AuthorizeRequest,
+} from "../src/index";
+
+/**
+ * C048 — the agnostic payment interface (a TS reimplementation of the Prism schema), witnessed via the mock connector.
+ * The load-bearing properties: the status enums are Prism-integer-EXACT (a real Prism backend stays swappable), the
+ * config SELECTS the connector (switch processor without code), a decline is in-band (not thrown), and a full flow is
+ * coherent through the seam.
+ */
+const registry: ConnectorRegistry = { mock: mockConnector, stripe: mockConnector }; // "stripe" is the mock here (interface-first)
+const cfg = (name: string): ConnectorConfig => ({ connectorConfig: { [name]: { apiKey: { value: "sk_test_1" } } } });
+const card = (pan: string): AuthorizeRequest["paymentMethod"] => ({
+  card: { cardNumber: { value: pan }, cardExpMonth: { value: "12" }, cardExpYear: { value: "2030" }, cardCvc: { value: "123" } },
+});
+const authReq = (pan: string, over: Partial<AuthorizeRequest> = {}): AuthorizeRequest => ({
+  merchantTransactionId: "txn_1",
+  amount: { minorAmount: 1000, currency: Currency.USD },
+  captureMethod: CaptureMethod.AUTOMATIC,
+  paymentMethod: card(pan),
+  authType: AuthenticationType.NO_THREE_DS,
+  ...over,
+});
+
+describe("Prism-integer-exact status semantics", () => {
+  test("PaymentStatus + RefundStatus carry Prism's exact integer values", () => {
+    expect([PaymentStatus.AUTHORIZED, PaymentStatus.CHARGED, PaymentStatus.VOIDED, PaymentStatus.FAILURE, PaymentStatus.AUTHENTICATION_PENDING]).toEqual([6, 8, 11, 21, 4]);
+    expect([RefundStatus.REFUND_PENDING, RefundStatus.REFUND_SUCCESS]).toEqual([3, 4]);
+  });
+});
+
+describe("config selects the connector (switch processor by config)", () => {
+  test("paymentClient binds the single named processor", () => {
+    expect(paymentClient(cfg("mock"), registry).name).toBe("mock");
+    expect(paymentClient(cfg("stripe"), registry).name).toBe("mock"); // same mock, chosen by a different config
+  });
+
+  test("a config naming zero, many, or an unregistered processor throws IntegrationError", () => {
+    expect(() => paymentClient({ connectorConfig: {} }, registry)).toThrow(IntegrationError);
+    expect(() => paymentClient({ connectorConfig: { mock: { apiKey: { value: "x" } }, stripe: { apiKey: { value: "y" } } } }, registry)).toThrow(/exactly one/);
+    expect(() => paymentClient(cfg("adyen"), registry)).toThrow(/no connector registered for "adyen"/);
+  });
+});
+
+describe("the unified flow through the seam", () => {
+  test("auto-capture authorize → CHARGED; manual → AUTHORIZED then capture → CHARGED", async () => {
+    const c = paymentClient(cfg("mock"), registry);
+    const auto = await c.authorize(authReq("4111111111111111"));
+    expect(auto.status).toBe(PaymentStatus.CHARGED);
+    expect(auto.connectorTransactionId).toBeString();
+
+    const manual = await c.authorize(authReq("4111111111111111", { captureMethod: CaptureMethod.MANUAL }));
+    expect(manual.status).toBe(PaymentStatus.AUTHORIZED);
+    const cap = await c.capture({ merchantCaptureId: "cap_1", connectorTransactionId: manual.connectorTransactionId!, amountToCapture: { minorAmount: 1000, currency: Currency.USD } });
+    expect(cap.status).toBe(PaymentStatus.CHARGED);
+  });
+
+  test("a decline card is IN-BAND FAILURE (not a throw); 3DS → AUTHENTICATION_PENDING + redirection", async () => {
+    const c = paymentClient(cfg("mock"), registry);
+    const declined = await c.authorize(authReq(MOCK_DECLINE_CARD));
+    expect(declined.status).toBe(PaymentStatus.FAILURE);
+    expect(declined.error?.code).toBe("card_declined");
+
+    const tds = await c.authorize(authReq(MOCK_3DS_CARD, { returnUrl: "https://app/return" }));
+    expect(tds.status).toBe(PaymentStatus.AUTHENTICATION_PENDING);
+    expect(tds.redirectionData?.url).toBe("https://app/return");
+  });
+
+  test("void + refund + sync are coherent across the flow", async () => {
+    const c = paymentClient(cfg("mock"), registry);
+    const auth = await c.authorize(authReq("4111111111111111", { captureMethod: CaptureMethod.MANUAL }));
+    const voided = await c.void({ merchantVoidId: "v_1", connectorTransactionId: auth.connectorTransactionId! });
+    expect(voided.status).toBe(PaymentStatus.VOIDED);
+    expect((await c.sync({ connectorTransactionId: auth.connectorTransactionId! })).status).toBe(PaymentStatus.VOIDED);
+
+    const charged = await c.authorize(authReq("4111111111111111"));
+    const refund = await c.refund({ merchantRefundId: "r_1", connectorTransactionId: charged.connectorTransactionId!, refundAmount: { minorAmount: 500, currency: Currency.USD }, paymentAmount: 1000 });
+    expect(refund.status).toBe(RefundStatus.REFUND_SUCCESS);
+  });
+
+  test("a connector with a bad config throws IntegrationError at bind time", () => {
+    expect(() => paymentClient({ connectorConfig: { mock: {} } }, registry)).toThrow(/needs an apiKey/);
+  });
+});

package/test/pricing-webhook.test.ts

@@ -0,0 +1,59 @@
+import { test, expect, describe } from "bun:test";
+import {
+  subtotal, orderTotal, verifyAmount, prorateDiscount, computeDiscountAmount, idempotencyKey,
+  verifyStripeSignature, webhookRouter, STRIPE_EVENTS, type CartLine, type Discount,
+} from "../src/index";
+
+/** C048 — the pricing + Stripe-webhook surfaces moved here from @suluk/stripe; direct coverage in their new home. */
+
+describe("pricing primitives (moved from @suluk/stripe)", () => {
+  const lines: CartLine[] = [{ unitCents: 1999, qty: 2, id: "a" }, { unitCents: 500, qty: 1, id: "b" }];
+
+  test("verifyAmount is anti-tampering (recomputes; rejects a mismatch)", () => {
+    const total = orderTotal(lines, null).totalCents; // 4498
+    expect(verifyAmount(lines, null, total).ok).toBe(true);
+    expect(verifyAmount(lines, null, total - 1).reason).toBe("amount-mismatch");
+  });
+
+  test("a discount never exceeds the subtotal; proration sums EXACTLY", () => {
+    expect(computeDiscountAmount(subtotal(lines), { type: "fixed", value: 9_999_999 } as Discount)).toBe(subtotal(lines));
+    const shares = prorateDiscount(lines, 777);
+    expect(shares.reduce((a, b) => a + b, 0)).toBe(777);
+  });
+
+  test("idempotencyKey is order-independent + scope-sensitive", () => {
+    const k = idempotencyKey("u1", lines);
+    expect(idempotencyKey("u1", [...lines].reverse())).toBe(k);
+    expect(idempotencyKey("u2", lines)).not.toBe(k);
+  });
+});
+
+describe("Stripe webhook surface (moved from @suluk/stripe)", () => {
+  async function sign(secret: string, ts: number, body: string): Promise<string> {
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${ts}.${body}`));
+    return [...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+
+  test("verifyStripeSignature: accepts a correctly-signed fresh event; rejects tampered/stale/missing", async () => {
+    const secret = "whsec_test";
+    const body = '{"type":"payment_intent.succeeded"}';
+    const ts = 1_700_000_000;
+    const sig = await sign(secret, ts, body);
+    const now = () => ts;
+    expect(await verifyStripeSignature(body, `t=${ts},v1=${sig}`, secret, { now })).toBe(true);
+    expect(await verifyStripeSignature(`${body} `, `t=${ts},v1=${sig}`, secret, { now })).toBe(false); // body tampered
+    expect(await verifyStripeSignature(body, `t=${ts - 999},v1=${sig}`, secret, { now })).toBe(false); // stale (outside tolerance)
+    expect(await verifyStripeSignature("", "", "")).toBe(false); // missing
+  });
+
+  test("webhookRouter dispatches by type + falls back to onUnhandled", async () => {
+    const seen: string[] = [];
+    const router = webhookRouter()
+      .on(STRIPE_EVENTS.invoicePaid, () => void seen.push("paid"))
+      .onUnhandled((e) => void seen.push(`unhandled:${e.type}`));
+    expect((await router.handle({ type: STRIPE_EVENTS.invoicePaid })).handled).toBe(true);
+    expect((await router.handle({ type: "some.other" })).handled).toBe(false);
+    expect(seen).toEqual(["paid", "unhandled:some.other"]);
+  });
+});

package/test/stripe-connector.test.ts

@@ -0,0 +1,157 @@
+import { test, expect, describe } from "bun:test";
+import {
+  stripeConnector, paymentClient, ConnectorError,
+  PaymentStatus, RefundStatus, CaptureMethod, AuthenticationType, Currency,
+  type ConnectorConfig, type AuthorizeRequest, type HttpOptions,
+} from "../src/index";
+
+/**
+ * C048 — the built-in Stripe connector, witnessed with a MOCK fetch. The load-bearing thing is the STATUS MAPPING
+ * (Stripe PI status → the unified integer enum) + the right Stripe request; a wrong mapping mis-reports money. No live
+ * Stripe.
+ */
+interface Call { path: string; method: string; body: string; headers: Record<string, string> }
+function mock(routes: Record<string, { status?: number; body: unknown }>): { http: HttpOptions; calls: Call[] } {
+  const calls: Call[] = [];
+  const fetchMock = (async (url: string | URL, init?: RequestInit) => {
+    const path = String(url).replace("https://api.stripe.com/v1/", "");
+    const method = (init?.method ?? "GET").toUpperCase();
+    calls.push({ path, method, body: (init?.body as string) ?? "", headers: (init?.headers as Record<string, string>) ?? {} });
+    const key = Object.keys(routes).find((k) => `${method} ${path}`.startsWith(k));
+    const r = key ? routes[key] : { body: {} };
+    return new Response(JSON.stringify(r.body), { status: r.status ?? 200 });
+  }) as unknown as typeof fetch;
+  return { http: { fetch: fetchMock }, calls };
+}
+const cfg: ConnectorConfig = { connectorConfig: { stripe: { apiKey: { value: "sk_test_1" } } } };
+const rawCard = (over: Partial<AuthorizeRequest> = {}): AuthorizeRequest => ({
+  merchantTransactionId: "txn_1",
+  amount: { minorAmount: 2000, currency: Currency.USD },
+  captureMethod: CaptureMethod.AUTOMATIC,
+  paymentMethod: { card: { cardNumber: { value: "4242424242424242" }, cardExpMonth: { value: "12" }, cardExpYear: { value: "2030" }, cardCvc: { value: "123" } } },
+  authType: AuthenticationType.NO_THREE_DS,
+  ...over,
+});
+
+describe("authorize — request shape + status mapping", () => {
+  test("auto-capture success → CHARGED, with the right PI request + idempotency key", async () => {
+    const m = mock({ "POST payment_intents": { body: { id: "pi_1", status: "succeeded", amount: 2000, currency: "usd" } } });
+    const c = paymentClient(cfg, { stripe: stripeConnector }, m.http);
+    const res = await c.authorize(rawCard());
+    expect(res.status).toBe(PaymentStatus.CHARGED);
+    expect(res.connectorTransactionId).toBe("pi_1");
+    expect(res.amount).toEqual({ minorAmount: 2000, currency: "USD" });
+    const call = m.calls[0];
+    expect(call.body).toContain("amount=2000");
+    expect(call.body).toContain("currency=usd");
+    expect(call.body).toContain("confirm=true");
+    expect(call.body).toContain("payment_method_data%5Btype%5D=card");
+    expect(call.body).toContain("payment_method_data%5Bcard%5D%5Bnumber%5D=4242424242424242");
+    expect(call.headers["idempotency-key"]).toBe("auth:txn_1");
+  });
+
+  test("manual capture → AUTHORIZED (requires_capture)", async () => {
+    const m = mock({ "POST payment_intents": { body: { id: "pi_2", status: "requires_capture" } } });
+    const res = await stripeConnector(cfg.connectorConfig.stripe, m.http).authorize(rawCard({ captureMethod: CaptureMethod.MANUAL }));
+    expect(res.status).toBe(PaymentStatus.AUTHORIZED);
+    expect(m.calls[0].body).toContain("capture_method=manual");
+  });
+
+  test("requires_action → AUTHENTICATION_PENDING + redirection url", async () => {
+    const m = mock({ "POST payment_intents": { body: { id: "pi_3", status: "requires_action", next_action: { redirect_to_url: { url: "https://hooks.stripe.com/3ds" } } } } });
+    const res = await stripeConnector(cfg.connectorConfig.stripe, m.http).authorize(rawCard({ authType: AuthenticationType.THREE_DS, returnUrl: "https://app/return" }));
+    expect(res.status).toBe(PaymentStatus.AUTHENTICATION_PENDING);
+    expect(res.redirectionData?.url).toBe("https://hooks.stripe.com/3ds");
+  });
+
+  test("a card_error (402) is IN-BAND FAILURE with the decline code — not thrown", async () => {
+    const m = mock({ "POST payment_intents": { status: 402, body: { error: { type: "card_error", code: "card_declined", decline_code: "insufficient_funds", message: "Your card has insufficient funds.", payment_intent: { id: "pi_4" } } } } });
+    const res = await stripeConnector(cfg.connectorConfig.stripe, m.http).authorize(rawCard());
+    expect(res.status).toBe(PaymentStatus.FAILURE);
+    expect(res.error?.code).toBe("insufficient_funds");
+    expect(res.connectorTransactionId).toBe("pi_4");
+  });
+
+  test("an off-session authentication_required (402) → AUTHENTICATION_PENDING (not thrown)", async () => {
+    const m = mock({ "POST payment_intents": { status: 402, body: { error: { type: "invalid_request_error", code: "authentication_required", payment_intent: { id: "pi_5", status: "requires_action" } } } } });
+    const res = await stripeConnector(cfg.connectorConfig.stripe, m.http).authorize(rawCard({ offSession: true, paymentMethod: { token: { value: "pm_saved" } } }));
+    expect(res.status).toBe(PaymentStatus.AUTHENTICATION_PENDING);
+    expect(res.connectorTransactionId).toBe("pi_5");
+    expect(m.calls[0].body).toContain("off_session=true");
+    expect(m.calls[0].body).toContain("payment_method=pm_saved");
+  });
+
+  test("a non-card hard error THROWS ConnectorError", async () => {
+    const m = mock({ "POST payment_intents": { status: 500, body: { error: { type: "api_error", message: "Stripe is down" } } } });
+    await expect(stripeConnector(cfg.connectorConfig.stripe, m.http).authorize(rawCard())).rejects.toThrow(ConnectorError);
+  });
+});
+
+describe("capture / void / refund / sync / customer", () => {
+  test("capture → CHARGED; void → VOIDED", async () => {
+    const cap = mock({ "POST payment_intents/pi_1/capture": { body: { id: "pi_1", status: "succeeded" } } });
+    expect((await stripeConnector(cfg.connectorConfig.stripe, cap.http).capture({ merchantCaptureId: "c1", connectorTransactionId: "pi_1", amountToCapture: { minorAmount: 2000, currency: Currency.USD } })).status).toBe(PaymentStatus.CHARGED);
+    const vd = mock({ "POST payment_intents/pi_1/cancel": { body: { id: "pi_1", status: "canceled" } } });
+    expect((await stripeConnector(cfg.connectorConfig.stripe, vd.http).void({ merchantVoidId: "v1", connectorTransactionId: "pi_1" })).status).toBe(PaymentStatus.VOIDED);
+  });
+
+  test("refund maps succeeded→SUCCESS and pending→PENDING; passes payment_intent + amount + idempotency", async () => {
+    const ok = mock({ "POST refunds": { body: { id: "re_1", status: "succeeded" } } });
+    const r = await stripeConnector(cfg.connectorConfig.stripe, ok.http).refund({ merchantRefundId: "r1", connectorTransactionId: "pi_1", refundAmount: { minorAmount: 500, currency: Currency.USD }, paymentAmount: 2000 });
+    expect(r.status).toBe(RefundStatus.REFUND_SUCCESS);
+    expect(r.connectorRefundId).toBe("re_1");
+    expect(ok.calls[0].body).toContain("payment_intent=pi_1");
+    expect(ok.calls[0].body).toContain("amount=500");
+    expect(ok.calls[0].headers["idempotency-key"]).toBe("refund:r1");
+
+    const pend = mock({ "POST refunds": { body: { id: "re_2", status: "pending" } } });
+    expect((await stripeConnector(cfg.connectorConfig.stripe, pend.http).refund({ merchantRefundId: "r2", connectorTransactionId: "pi_1", refundAmount: { minorAmount: 500, currency: Currency.USD }, paymentAmount: 2000 })).status).toBe(RefundStatus.REFUND_PENDING);
+  });
+
+  test("sync maps the live PI status; createCustomer returns the id", async () => {
+    const s = mock({ "GET payment_intents/pi_1": { body: { id: "pi_1", status: "succeeded" } } });
+    expect((await stripeConnector(cfg.connectorConfig.stripe, s.http).sync({ connectorTransactionId: "pi_1" })).status).toBe(PaymentStatus.CHARGED);
+    const cu = mock({ "POST customers": { body: { id: "cus_1" } } });
+    expect(await stripeConnector(cfg.connectorConfig.stripe, cu.http).createCustomer!({ email: "a@b.com", metadata: { userId: "u1" } })).toEqual({ customerId: "cus_1" });
+    expect(cu.calls[0].body).toContain("email=a%40b.com");
+    expect(cu.calls[0].body).toContain("metadata%5BuserId%5D=u1");
+  });
+});
+
+describe("the client-token surface (browser-confirmable sessions)", () => {
+  test("createPaymentSession (Payment Element): automatic_payment_methods + optional save; returns the client secret", async () => {
+    const m = mock({ "POST payment_intents": { body: { id: "pi_9", client_secret: "pi_9_secret" } } });
+    const s = await stripeConnector(cfg.connectorConfig.stripe, m.http).createPaymentSession!({
+      amount: { minorAmount: 2000, currency: Currency.USD }, customerId: "cus_1", setupFutureUsage: true, metadata: { userId: "u1", source: "onsite_topup" },
+    });
+    expect(s).toEqual({ clientSecret: "pi_9_secret", connectorTransactionId: "pi_9", customerId: "cus_1" });
+    const b = m.calls[0].body;
+    expect(b).toContain("automatic_payment_methods%5Benabled%5D=true");
+    expect(b).toContain("setup_future_usage=off_session");
+    expect(b).toContain("metadata%5Bsource%5D=onsite_topup");
+    expect(b).not.toContain("confirm=true"); // the BROWSER confirms — the server only creates the intent
+  });
+
+  test("createPaymentSession (one-click): pins the saved card, no automatic_payment_methods", async () => {
+    const m = mock({ "POST payment_intents": { body: { id: "pi_10", client_secret: "pi_10_secret" } } });
+    const s = await stripeConnector(cfg.connectorConfig.stripe, m.http).createPaymentSession!({
+      amount: { minorAmount: 2000, currency: Currency.USD }, customerId: "cus_1", paymentMethod: { value: "pm_1" },
+    });
+    expect(s.clientSecret).toBe("pi_10_secret");
+    expect(m.calls[0].body).toContain("payment_method=pm_1");
+    expect(m.calls[0].body).not.toContain("automatic_payment_methods");
+  });
+
+  test("createSetupSession: vaults a card (usage=off_session); returns the client secret", async () => {
+    const m = mock({ "POST setup_intents": { body: { id: "seti_1", client_secret: "seti_secret" } } });
+    const s = await stripeConnector(cfg.connectorConfig.stripe, m.http).createSetupSession!({ customerId: "cus_1", metadata: { userId: "u1" } });
+    expect(s.clientSecret).toBe("seti_secret");
+    expect(m.calls[0].path).toBe("setup_intents");
+    expect(m.calls[0].body).toContain("usage=off_session");
+  });
+
+  test("a session that returns no client_secret throws ConnectorError", async () => {
+    const m = mock({ "POST payment_intents": { status: 400, body: { error: { code: "amount_too_small", message: "Amount too small" } } } });
+    await expect(stripeConnector(cfg.connectorConfig.stripe, m.http).createPaymentSession!({ amount: { minorAmount: 1, currency: Currency.USD } })).rejects.toThrow(ConnectorError);
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test"] }