@suluk/stripe 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,35 @@
+<p align="center">
+  <a href="https://github.com/MahmoodKhalil57/suluk">
+    <img src="https://raw.githubusercontent.com/MahmoodKhalil57/suluk/main/branding/export/wordmark.png" alt="Suluk" width="360" />
+  </a>
+</p>
+
+<h1 align="center">@suluk/stripe</h1>
+
+<p align="center"><b>First-class Stripe via a swappable PaymentProvider: usage-based billing (Billing Meters + meter events), customers, metered prices, subscriptions, webhooks — and a bridge from @suluk/cost to Stripe usage. Other processors follow Stripe.</b></p>
+
+<p align="center">
+  <em>Part of <a href="https://github.com/MahmoodKhalil57/suluk">Suluk</a> — one typed OpenAPI v4 contract projecting into every full-stack layer.</em>
+</p>
+
+---
+
+> **CANDIDATE tooling — not official OpenAPI.** Suluk is a single-contributor candidate for
+> OpenAPI Specification v4.0 ("Moonwalk"), unaffiliated with the OpenAPI Initiative and unable
+> to ratify anything on the SIG's behalf.
+
+## Install
+
+```sh
+bun add @suluk/stripe
+```
+
+## The Suluk cycle
+
+`@suluk/stripe` is one station on the Suluk walk — author one v4 source, then **validate · audit ·
+preview · generate · deploy** the whole stack from it. Explore the full toolchain in the
+[main repository](https://github.com/MahmoodKhalil57/suluk) or drive it from the [VS Code cockpit](https://marketplace.visualstudio.com/items?itemName=MahmoodKhalil.suluk-vscode).
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,14 +1,25 @@
 {
   "name": "@suluk/stripe",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "First-class Stripe via a swappable PaymentProvider: usage-based billing (Billing Meters + meter events), customers, metered prices, subscriptions, webhooks — and a bridge from @suluk/cost to Stripe usage. Other processors follow Stripe. CANDIDATE tooling.",
-  "type": "module",
-  "main": "src/index.ts",
-  "exports": {
-  ".": "./src/index.ts"
+  "publishConfig": {
+  "access": "public"
+},
+"license": "Apache-2.0",
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+  "directory": "tooling/ts/packages/stripe"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"exports": {
+".": "./src/index.ts"
 },
 "dependencies": {
-"@suluk/cost": "0.1.0"
+"@suluk/cost": "^0.1.2"
 },
 "peerDependencies": {
 "stripe": "^17.0.0 || ^18.0.0"

package/src/checkout.ts

@@ -0,0 +1,167 @@
+/**
+ * The checkout money-path (saastarter-parity Phase 1; PARITY §2 trust layer). Distinct from usage billing
+ * (stripe.ts): one-time checkout — payment intents, the saved-card vault, customer find-or-create. The TRUST core
+ * is PURE and lives here (never charge a client-supplied amount; reuse a matching intent so a retry can't
+ * double-charge; re-price on a cart change; thread a deterministic idempotency key) — built on the Phase-0 pricing
+ * primitives. The Stripe API calls are a SWAPPABLE binding (`StripeCheckoutLike`), satisfied by the real SDK or a mock.
+ */
+import {
+  orderTotal, verifyAmount, idempotencyKey,
+  type CartLine, type Discount, type AmountVerdict,
+} from "./pricing";
+
+/** A saved card, surfaced to the account/checkout UI (saastarter CardInfo, services/stripe.ts:13). */
+export interface CardInfo {
+  id: string;
+  brand?: string;
+  last4?: string;
+  expMonth?: number;
+  expYear?: number;
+  isDefault: boolean;
+}
+
+/** A Stripe PaymentMethod (the slice we read). */
+export interface PaymentMethodLike {
+  id: string;
+  customer?: string | null;
+  card?: { brand?: string; last4?: string; exp_month?: number; exp_year?: number } | null;
+}
+
+/** A Stripe PaymentIntent (the slice we read). */
+export interface PaymentIntentLike {
+  id: string;
+  amount: number;
+  currency: string;
+  status?: string;
+  client_secret?: string | null;
+}
+
+/** The minimal Stripe checkout surface this module calls — satisfied by the real `stripe` SDK and by mocks. */
+export interface StripeCheckoutLike {
+  customers: {
+    create(params: Record<string, unknown>): Promise<{ id: string }>;
+    list(params: { email: string; limit?: number }): Promise<{ data: { id: string }[] }>;
+  };
+  paymentIntents: {
+    create(params: Record<string, unknown>, opts?: { idempotencyKey?: string }): Promise<PaymentIntentLike>;
+    retrieve(id: string): Promise<PaymentIntentLike>;
+    update(id: string, params: Record<string, unknown>): Promise<PaymentIntentLike>;
+  };
+  setupIntents: { create(params: Record<string, unknown>): Promise<{ client_secret: string | null }> };
+  paymentMethods: {
+    list(params: { customer: string; type: string }): Promise<{ data: PaymentMethodLike[] }>;
+    retrieve(id: string): Promise<PaymentMethodLike>;
+    detach(id: string): Promise<PaymentMethodLike>;
+  };
+}
+
+// ── the PURE trust core ───────────────────────────────────────────────────────────────────────────────
+
+export interface IntentPlan {
+  /** create a new intent · reuse the matching one (no charge change) · update an existing one to a new total. */
+  action: "create" | "reuse" | "update";
+  /** the AUTHORITATIVE amount, recomputed from line prices — never a client-supplied number. */
+  amountCents: number;
+  currency: string;
+  /** deterministic key (cart × scope) — threaded into create so a retry reuses one intent (no double-charge). */
+  idempotencyKey: string;
+  /** the intent to reuse/update (absent for create). */
+  intentId?: string;
+  /** when a client claimed an amount, the anti-tampering verdict (the caller MUST reject `ok:false`). */
+  amountVerdict?: AmountVerdict;
+}
+
+/**
+ * Decide what to do with a checkout's payment intent — the anti-double-charge / anti-tampering decision, pure and
+ * fully testable. Recomputes the total from authoritative prices; reuses an existing intent iff its amount already
+ * matches (idempotent retry); updates it when the cart changed; creates one otherwise. If `claimedCents` is given,
+ * attaches the verifyAmount verdict so the caller can reject a tampered amount BEFORE touching Stripe.
+ */
+export function planPaymentIntent(input: {
+  lines: CartLine[];
+  discount?: Discount | null;
+  /** principal/session id — namespaces the idempotency key so two users' identical carts don't collide. */
+  scope: string;
+  currency: string;
+  existingIntent?: { id: string; amountCents: number } | null;
+  claimedCents?: number;
+}): IntentPlan {
+  const discount = input.discount ?? null;
+  const amountCents = orderTotal(input.lines, discount).totalCents;
+  const key = idempotencyKey(input.scope, input.lines, discount);
+  const amountVerdict = input.claimedCents != null ? verifyAmount(input.lines, discount, input.claimedCents) : undefined;
+  let action: IntentPlan["action"] = "create";
+  if (input.existingIntent) action = input.existingIntent.amountCents === amountCents ? "reuse" : "update";
+  return {
+    action, amountCents, currency: input.currency, idempotencyKey: key,
+    ...(input.existingIntent ? { intentId: input.existingIntent.id } : {}),
+    ...(amountVerdict ? { amountVerdict } : {}),
+  };
+}
+
+/** Map a Stripe PaymentMethod to a CardInfo (pure). `defaultId` marks the default card. */
+export function cardInfoFrom(pm: PaymentMethodLike, defaultId?: string | null): CardInfo {
+  return {
+    id: pm.id,
+    brand: pm.card?.brand,
+    last4: pm.card?.last4,
+    expMonth: pm.card?.exp_month,
+    expYear: pm.card?.exp_year,
+    isDefault: pm.id === defaultId,
+  };
+}
+
+/** Does a payment method belong to this customer? The ownership guard for detach / set-default (no cross-account ops). */
+export function ownsPaymentMethod(pm: PaymentMethodLike, customerId: string): boolean {
+  return pm.customer === customerId;
+}
+
+// ── the Stripe-backed binding ─────────────────────────────────────────────────────────────────────────
+
+export interface CheckoutProvider {
+  name: string;
+  /** Find a customer by email, else create one (saastarter getOrCreateCustomer, services/stripe.ts:143). */
+  getOrCreateCustomer(input: { email: string; name?: string; metadata?: Record<string, string> }): Promise<{ customerId: string }>;
+  /** The saved-card vault for a customer (default card flagged). */
+  listPaymentMethods(customerId: string, defaultPaymentMethodId?: string | null): Promise<CardInfo[]>;
+  /** A SetupIntent client secret — to vault a new card without charging. */
+  createSetupIntent(customerId: string): Promise<{ clientSecret: string | null }>;
+  /** Detach a saved card — guarded: throws if the card isn't this customer's. */
+  detachPaymentMethod(customerId: string, paymentMethodId: string): Promise<void>;
+  /** Execute an {@link IntentPlan} against Stripe: create (idempotent) / update / reuse. */
+  applyIntentPlan(plan: IntentPlan): Promise<PaymentIntentLike>;
+}
+
+/** The Stripe checkout binding (the swap point; another processor implements the same interface). */
+export function stripeCheckout(client: StripeCheckoutLike): CheckoutProvider {
+  return {
+    name: "stripe",
+    async getOrCreateCustomer({ email, name, metadata }) {
+      const existing = await client.customers.list({ email, limit: 1 });
+      if (existing.data[0]) return { customerId: existing.data[0].id };
+      const created = await client.customers.create({ email, ...(name ? { name } : {}), ...(metadata ? { metadata } : {}) });
+      return { customerId: created.id };
+    },
+    async listPaymentMethods(customerId, defaultPaymentMethodId) {
+      const { data } = await client.paymentMethods.list({ customer: customerId, type: "card" });
+      return data.map((pm) => cardInfoFrom(pm, defaultPaymentMethodId));
+    },
+    async createSetupIntent(customerId) {
+      const si = await client.setupIntents.create({ customer: customerId });
+      return { clientSecret: si.client_secret };
+    },
+    async detachPaymentMethod(customerId, paymentMethodId) {
+      const pm = await client.paymentMethods.retrieve(paymentMethodId);
+      if (!ownsPaymentMethod(pm, customerId)) throw new Error(`forbidden: payment method ${paymentMethodId} does not belong to ${customerId}`);
+      await client.paymentMethods.detach(paymentMethodId);
+    },
+    async applyIntentPlan(plan) {
+      if (plan.action === "reuse" && plan.intentId) return client.paymentIntents.retrieve(plan.intentId);
+      if (plan.action === "update" && plan.intentId) return client.paymentIntents.update(plan.intentId, { amount: plan.amountCents, currency: plan.currency });
+      return client.paymentIntents.create(
+        { amount: plan.amountCents, currency: plan.currency },
+        { idempotencyKey: plan.idempotencyKey },
+      );
+    },
+  };
+}

package/src/index.ts

@@ -7,6 +7,18 @@
 export type { PaymentProvider, StripeLike, Customer, Subscription, WebhookEvent } from "./types";
 export {
   customerParams, productParams, meterParams, meteredPriceParams, subscriptionParams, meterEventParams,
-  setupUsageBilling, stripeProvider, usageEventsFromCost, reportCostUsage,
+  billingPortalSessionParams, setupUsageBilling, stripeProvider, usageEventsFromCost, reportCostUsage,
   type UsageBillingConfig, type CostBillingConfig,
 } from "./stripe";
+export {
+  subtotal, computeDiscountAmount, validateDiscount, prorateDiscount, orderTotal, verifyAmount,
+  cartFingerprint, idempotencyKey,
+  type CartLine, type Discount, type DiscountResult, type DiscountRejection, type OrderTotal, type AmountVerdict,
+} from "./pricing";
+// the checkout money-path (Phase 1): the pure anti-double-charge / anti-tampering core + the Stripe binding.
+export {
+  planPaymentIntent, cardInfoFrom, ownsPaymentMethod, stripeCheckout,
+  type IntentPlan, type CardInfo, type CheckoutProvider,
+  type StripeCheckoutLike, type PaymentMethodLike, type PaymentIntentLike,
+} from "./checkout";
+export { webhookRouter, STRIPE_EVENTS, type WebhookRouter, type WebhookHandler, type HandleResult } from "./webhook";

package/src/pricing.ts

@@ -0,0 +1,150 @@
+/**
+ * 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 };
+}
+
+/**
+ * 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.ts

@@ -41,6 +41,13 @@ export function subscriptionParams(i: { customerId: string; priceId: string }):
   return { customer: i.customerId, items: [{ price: i.priceId }] };
 }
 
+/** A Billing customer-portal session — the hosted page where a customer manages saved cards + invoices. */
+export function billingPortalSessionParams(i: { customerId: string; returnUrl: string; configuration?: string }): Record<string, unknown> {
+  const p: Record<string, unknown> = { customer: i.customerId, return_url: i.returnUrl };
+  if (i.configuration) p.configuration = i.configuration; // an explicit portal configuration id (else Stripe's default)
+  return p;
+}
+
 /** A meter event — reports usage for a customer (the `value` is what you price on). */
 export function meterEventParams(i: { eventName: string; customerId: string; value: number; at?: number }): Record<string, unknown> {
   const payload: Record<string, unknown> = { stripe_customer_id: i.customerId, value: String(i.value) };
@@ -75,6 +82,10 @@ export function stripeProvider(client: StripeLike, cfg: { webhookSecret?: string
     async createCustomer(i) { return { id: (await client.customers.create(customerParams(i))).id }; },
     async subscribeMetered(i) { return { id: (await client.subscriptions.create(subscriptionParams(i))).id }; },
     async reportUsage(i) { await client.billing.meterEvents.create(meterEventParams(i)); },
+    async billingPortalUrl(i) {
+      if (!client.billingPortal) throw new Error("This Stripe client has no billingPortal support (the REST adapter / SDK provides it).");
+      return { url: (await client.billingPortal.sessions.create(billingPortalSessionParams(i))).url };
+    },
     verifyWebhook(body, signature) {
       const e = client.webhooks.constructEvent(body, signature, cfg.webhookSecret ?? "");
       return { type: e.type, data: e.data };

package/src/types.ts

@@ -20,6 +20,8 @@ export interface PaymentProvider {
   subscribeMetered(input: { customerId: string; priceId: string }): Promise<Subscription>;
   /** Report usage for billing — one meter event (the value you price on). `at` is an input (reproducible). */
   reportUsage(input: { customerId: string; eventName: string; value: number; at?: number }): Promise<void>;
+  /** Open the hosted customer billing portal (manage saved cards + invoices). Optional — not every processor has one. */
+  billingPortalUrl?(input: { customerId: string; returnUrl: string }): Promise<{ url: string }>;
   /** Verify + parse a webhook from the raw body + signature. */
   verifyWebhook(rawBody: string, signature: string): WebhookEvent;
 }
@@ -34,5 +36,7 @@ export interface StripeLike {
     meters: { create(params: Record<string, unknown>): Promise<{ id: string }> };
     meterEvents: { create(params: Record<string, unknown>): Promise<{ identifier?: string }> };
   };
+  /** The Billing customer portal. Optional — present on the real SDK + the REST adapter, omitted by minimal mocks. */
+  billingPortal?: { sessions: { create(params: Record<string, unknown>): Promise<{ url: string }> } };
   webhooks: { constructEvent(body: string, sig: string, secret: string): { type: string; data: unknown } };
 }

package/src/webhook.ts

@@ -0,0 +1,51 @@
+/**
+ * A typed webhook event-router (saastarter-parity Phase 1) layered over the existing `verifyWebhook` (stripe.ts).
+ * `verifyWebhook` proves a payload is authentic; this dispatches it to a per-event-type handler — the structured
+ * alternative to one giant `switch (event.type)`. Pure routing: no Stripe calls, no network.
+ */
+import type { WebhookEvent } from "./types";
+
+export type WebhookHandler = (event: WebhookEvent) => 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: WebhookEvent): 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 = {
+  paymentSucceeded: "payment_intent.succeeded",
+  paymentFailed: "payment_intent.payment_failed",
+  chargeRefunded: "charge.refunded",
+  setupSucceeded: "setup_intent.succeeded",
+  subscriptionUpdated: "customer.subscription.updated",
+  subscriptionDeleted: "customer.subscription.deleted",
+  invoicePaid: "invoice.paid",
+} as const;

package/test/checkout.test.ts

@@ -0,0 +1,128 @@
+import { test, expect, describe } from "bun:test";
+import {
+  planPaymentIntent, cardInfoFrom, ownsPaymentMethod, stripeCheckout,
+  webhookRouter, STRIPE_EVENTS,
+  type StripeCheckoutLike, type PaymentMethodLike, type CartLine,
+} from "../src/index";
+
+const lines: CartLine[] = [{ unitCents: 1999, qty: 2, id: "a" }, { unitCents: 500, qty: 1, id: "b" }]; // 4498
+
+describe("planPaymentIntent — the anti-double-charge / anti-tampering core (pure)", () => {
+  test("create when there is no existing intent; amount is authoritative; key is deterministic", () => {
+    const p = planPaymentIntent({ lines, scope: "u1", currency: "usd" });
+    expect(p.action).toBe("create");
+    expect(p.amountCents).toBe(4498);
+    expect(p.idempotencyKey).toBe(planPaymentIntent({ lines, scope: "u1", currency: "usd" }).idempotencyKey); // deterministic
+    expect(p.intentId).toBeUndefined();
+  });
+
+  test("reuse when an existing intent already matches the recomputed total (idempotent retry)", () => {
+    const p = planPaymentIntent({ lines, scope: "u1", currency: "usd", existingIntent: { id: "pi_1", amountCents: 4498 } });
+    expect(p.action).toBe("reuse");
+    expect(p.intentId).toBe("pi_1");
+  });
+
+  test("update when the cart changed (existing intent amount differs)", () => {
+    const p = planPaymentIntent({ lines, scope: "u1", currency: "usd", existingIntent: { id: "pi_1", amountCents: 9999 } });
+    expect(p.action).toBe("update");
+    expect(p.amountCents).toBe(4498); // re-priced to the authoritative total
+  });
+
+  test("NEVER trusts a client amount: the plan uses the recomputed total + flags a tampered claim", () => {
+    const tampered = planPaymentIntent({ lines, scope: "u1", currency: "usd", claimedCents: 1 });
+    expect(tampered.amountCents).toBe(4498);            // ignores the claimed 1¢
+    expect(tampered.amountVerdict?.ok).toBe(false);
+    expect(planPaymentIntent({ lines, scope: "u1", currency: "usd", claimedCents: 4498 }).amountVerdict?.ok).toBe(true);
+  });
+
+  test("the idempotency key namespaces by scope (two users' identical carts don't collide)", () => {
+    expect(planPaymentIntent({ lines, scope: "u1", currency: "usd" }).idempotencyKey)
+      .not.toBe(planPaymentIntent({ lines, scope: "u2", currency: "usd" }).idempotencyKey);
+  });
+});
+
+describe("card vault helpers (pure)", () => {
+  const pm: PaymentMethodLike = { id: "pm_1", customer: "cus_1", card: { brand: "visa", last4: "4242", exp_month: 12, exp_year: 2030 } };
+  test("cardInfoFrom maps a PaymentMethod and flags the default", () => {
+    expect(cardInfoFrom(pm, "pm_1")).toEqual({ id: "pm_1", brand: "visa", last4: "4242", expMonth: 12, expYear: 2030, isDefault: true });
+    expect(cardInfoFrom(pm, "pm_other").isDefault).toBe(false);
+  });
+  test("ownsPaymentMethod guards cross-account ops", () => {
+    expect(ownsPaymentMethod(pm, "cus_1")).toBe(true);
+    expect(ownsPaymentMethod(pm, "cus_2")).toBe(false);
+  });
+});
+
+describe("stripeCheckout — the Stripe-backed binding", () => {
+  function mockClient(overrides: Partial<StripeCheckoutLike> = {}) {
+    const calls: { create: unknown[]; piCreate: [unknown, unknown][]; detached: string[] } = { create: [], piCreate: [], detached: [] };
+    const client: StripeCheckoutLike = {
+      customers: {
+        async create(p) { calls.create.push(p); return { id: "cus_new" }; },
+        async list() { return { data: [] }; },
+      },
+      paymentIntents: {
+        async create(p, opts) { calls.piCreate.push([p, opts]); return { id: "pi_new", amount: (p as { amount: number }).amount, currency: "usd" }; },
+        async retrieve(id) { return { id, amount: 4498, currency: "usd" }; },
+        async update(id, p) { return { id, amount: (p as { amount: number }).amount, currency: "usd" }; },
+      },
+      setupIntents: { async create() { return { client_secret: "seti_secret" }; } },
+      paymentMethods: {
+        async list() { return { data: [{ id: "pm_1", customer: "cus_1", card: { brand: "visa", last4: "4242" } }] }; },
+        async retrieve(id) { return { id, customer: "cus_1" }; },
+        async detach(id) { calls.detached.push(id); return { id }; },
+      },
+      ...overrides,
+    };
+    return { client, calls };
+  }
+
+  test("getOrCreateCustomer reuses an existing customer by email, else creates", async () => {
+    const found = stripeCheckout({ ...mockClient().client, customers: { async create() { return { id: "x" }; }, async list() { return { data: [{ id: "cus_found" }] }; } } });
+    expect(await found.getOrCreateCustomer({ email: "a@b.co" })).toEqual({ customerId: "cus_found" });
+    const { client } = mockClient();
+    expect(await stripeCheckout(client).getOrCreateCustomer({ email: "new@b.co" })).toEqual({ customerId: "cus_new" });
+  });
+
+  test("listPaymentMethods maps cards + flags the default; createSetupIntent returns a secret", async () => {
+    const co = stripeCheckout(mockClient().client);
+    expect(await co.listPaymentMethods("cus_1", "pm_1")).toEqual([{ id: "pm_1", brand: "visa", last4: "4242", expMonth: undefined, expYear: undefined, isDefault: true }]);
+    expect(await co.createSetupIntent("cus_1")).toEqual({ clientSecret: "seti_secret" });
+  });
+
+  test("detachPaymentMethod detaches an owned card and refuses a foreign one", async () => {
+    const { client, calls } = mockClient();
+    const co = stripeCheckout(client);
+    await co.detachPaymentMethod("cus_1", "pm_1");
+    expect(calls.detached).toEqual(["pm_1"]);
+    await expect(co.detachPaymentMethod("cus_2", "pm_1")).rejects.toThrow("forbidden");
+  });
+
+  test("applyIntentPlan: create threads the idempotency key; reuse retrieves; update re-prices", async () => {
+    const { client, calls } = mockClient();
+    const co = stripeCheckout(client);
+    await co.applyIntentPlan(planPaymentIntent({ lines, scope: "u1", currency: "usd" }));
+    expect(calls.piCreate[0][1]).toMatchObject({ idempotencyKey: expect.stringContaining("co_u1_") });
+    expect((await co.applyIntentPlan(planPaymentIntent({ lines, scope: "u1", currency: "usd", existingIntent: { id: "pi_1", amountCents: 4498 } }))).id).toBe("pi_1");
+    expect((await co.applyIntentPlan(planPaymentIntent({ lines, scope: "u1", currency: "usd", existingIntent: { id: "pi_1", amountCents: 1 } }))).amount).toBe(4498);
+  });
+});
+
+describe("webhookRouter — typed event dispatch over verifyWebhook", () => {
+  test("dispatches to the registered handler; falls back for unknown types", async () => {
+    const seen: string[] = [];
+    const router = webhookRouter()
+      .on(STRIPE_EVENTS.paymentSucceeded, (e) => { seen.push("paid:" + (e.data as { id?: string }).id); })
+      .onUnhandled((e) => { seen.push("unhandled:" + e.type); });
+    expect(await router.handle({ type: STRIPE_EVENTS.paymentSucceeded, data: { id: "pi_9" } })).toEqual({ type: "payment_intent.succeeded", handled: true });
+    expect(await router.handle({ type: "charge.refunded", data: {} })).toEqual({ type: "charge.refunded", handled: false });
+    expect(seen).toEqual(["paid:pi_9", "unhandled:charge.refunded"]);
+  });
+
+  test("seeded handler map works too", async () => {
+    let hit = false;
+    const r = webhookRouter({ "invoice.paid": () => { hit = true; } });
+    await r.handle({ type: "invoice.paid", data: {} });
+    expect(hit).toBe(true);
+  });
+});

package/test/pricing.test.ts

@@ -0,0 +1,150 @@
+import { test, expect, describe } from "bun:test";
+import {
+  subtotal, computeDiscountAmount, validateDiscount, prorateDiscount, orderTotal, verifyAmount,
+  cartFingerprint, idempotencyKey, requiresStripe, STRIPE_MIN_CHARGE_CENTS, type CartLine, type Discount,
+} from "../src/index";
+
+const lines = (xs: [number, number][]): CartLine[] => xs.map(([unitCents, qty], i) => ({ unitCents, qty, id: i + 1 }));
+
+describe("@suluk/stripe money — pure pricing primitives (the trust layer)", () => {
+  test("subtotal is integer cents, qty/price clamped non-negative + truncated", () => {
+    expect(subtotal(lines([[1000, 2], [250, 3]]))).toBe(2750);
+    expect(subtotal([{ unitCents: 100.6, qty: 2.9 }])).toBe(101 * 2); // round price, trunc qty → 101*2
+    expect(subtotal([{ unitCents: -5, qty: 3 }, { unitCents: 100, qty: -1 }])).toBe(0); // no negatives
+  });
+
+  describe("computeDiscountAmount — rounded + CLAMPED to the subtotal (no over-discount, no negatives)", () => {
+    test("percent rounds to a whole cent", () => {
+      expect(computeDiscountAmount(999, { type: "percent", value: 10 })).toBe(100); // 99.9 → 100
+      expect(computeDiscountAmount(1000, { type: "percent", value: 15 })).toBe(150);
+    });
+    test("a discount can never exceed the subtotal", () => {
+      expect(computeDiscountAmount(500, { type: "fixed", value: 9999 })).toBe(500); // clamped
+      expect(computeDiscountAmount(500, { type: "percent", value: 200 })).toBe(500); // clamped (even if pct absurd)
+    });
+    test("zero subtotal → zero discount", () => {
+      expect(computeDiscountAmount(0, { type: "percent", value: 50 })).toBe(0);
+    });
+  });
+
+  describe("validateDiscount — specific rejection reasons (shopper is told WHY)", () => {
+    const sub = 5000;
+    test("no discount", () => expect(validateDiscount(sub, null)).toMatchObject({ valid: false, reason: "no-discount", amountCents: 0 }));
+    test("non-positive value", () => expect(validateDiscount(sub, { type: "fixed", value: 0 })).toMatchObject({ valid: false, reason: "non-positive-value" }));
+    test("percent over 100", () => expect(validateDiscount(sub, { type: "percent", value: 150 })).toMatchObject({ valid: false, reason: "percent-out-of-range" }));
+    test("below minimum", () => expect(validateDiscount(1000, { type: "percent", value: 10, minSubtotalCents: 5000 })).toMatchObject({ valid: false, reason: "below-minimum" }));
+    test("valid → the computed amount", () => expect(validateDiscount(sub, { type: "percent", value: 10, minSubtotalCents: 5000 })).toMatchObject({ valid: true, amountCents: 500 }));
+  });
+
+  describe("prorateDiscount — sums EXACTLY to the order discount (cart drawer can't drift from order summary)", () => {
+    test("a discount that doesn't divide evenly still sums exactly, by largest-remainder", () => {
+      const ls = lines([[100, 1], [100, 1], [100, 1]]); // 3 lines × $1.00
+      const shares = prorateDiscount(ls, 10); // 10¢ over 3 lines = 3,3,4 (or perm), sum = 10
+      expect(shares.reduce((a, b) => a + b, 0)).toBe(10);
+      expect(shares.every((s) => s >= 0)).toBe(true);
+    });
+    test("proportional to line totals, exact sum", () => {
+      const ls = lines([[1000, 1], [3000, 1]]); // $10 and $30 → 1:3
+      const shares = prorateDiscount(ls, 401); // 401¢ → ~100.25 / 300.75 → sums to 401
+      expect(shares.reduce((a, b) => a + b, 0)).toBe(401);
+      expect(shares[1]).toBeGreaterThan(shares[0]); // the bigger line absorbs more
+    });
+    test("no line share exceeds its own total", () => {
+      const ls = lines([[100, 1], [10000, 1]]);
+      const shares = prorateDiscount(ls, 150); // small line is only 100¢
+      expect(shares[0]).toBeLessThanOrEqual(100);
+      expect(shares.reduce((a, b) => a + b, 0)).toBe(150);
+    });
+    test("zero/empty cases", () => {
+      expect(prorateDiscount(lines([[100, 1]]), 0)).toEqual([0]);
+      expect(prorateDiscount([], 50)).toEqual([]);
+    });
+    test("randomized invariant: proration always sums to min(want, gross) and is non-negative", () => {
+      for (let seed = 1; seed <= 200; seed++) {
+        const n = (seed % 5) + 1;
+        const ls = Array.from({ length: n }, (_, i) => ({ unitCents: ((seed * (i + 7)) % 900) + 1, qty: ((seed + i) % 3) + 1, id: i }));
+        const gross = subtotal(ls);
+        const want = (seed * 13) % (gross + 50); // sometimes exceeds gross → should clamp
+        const shares = prorateDiscount(ls, want);
+        expect(shares.reduce((a, b) => a + b, 0)).toBe(Math.min(want, gross));
+        expect(shares.every((s, i) => s >= 0 && s <= ls[i].unitCents * ls[i].qty)).toBe(true);
+      }
+    });
+  });
+
+  test("orderTotal composes subtotal − validated discount", () => {
+    const ls = lines([[1000, 2], [500, 1]]); // 2500
+    expect(orderTotal(ls, { type: "percent", value: 10 })).toEqual({ subtotalCents: 2500, discountCents: 250, totalCents: 2250 });
+    expect(orderTotal(ls, { type: "percent", value: 10, minSubtotalCents: 9999 })).toEqual({ subtotalCents: 2500, discountCents: 0, totalCents: 2500 }); // ineligible → no discount
+    expect(orderTotal(ls)).toEqual({ subtotalCents: 2500, discountCents: 0, totalCents: 2500 });
+  });
+
+  describe("verifyAmount — anti-tampering recompute (never trust the client's amount)", () => {
+    const ls = lines([[1999, 2]]); // $39.98
+    test("a matching amount passes", () => {
+      expect(verifyAmount(ls, null, 3998)).toMatchObject({ ok: true, expectedCents: 3998, deltaCents: 0 });
+    });
+    test("a tampered (lowered) amount is rejected with the delta", () => {
+      const v = verifyAmount(ls, null, 100); // attacker claims $1.00
+      expect(v.ok).toBe(false);
+      expect(v.reason).toBe("amount-mismatch");
+      expect(v.expectedCents).toBe(3998);
+      expect(v.deltaCents).toBe(100 - 3998);
+    });
+    test("the discount is part of the authoritative recompute", () => {
+      expect(verifyAmount(ls, { type: "percent", value: 50 }, 1999)).toMatchObject({ ok: true }); // 50% of 3998 = 1999
+      expect(verifyAmount(ls, { type: "percent", value: 50 }, 3998).ok).toBe(false); // client ignored the discount? still must match server
+    });
+    test("tolerance is honored", () => {
+      expect(verifyAmount(ls, null, 3999, { toleranceCents: 1 }).ok).toBe(true);
+      expect(verifyAmount(ls, null, 4000, { toleranceCents: 1 }).ok).toBe(false);
+    });
+  });
+
+  describe("idempotency — a stable key for intent-reuse (no double-charge)", () => {
+    const a = lines([[1000, 1], [500, 2]]);
+    test("the same cart → the same key (a retry reuses one intent)", () => {
+      expect(idempotencyKey("user-1", a)).toBe(idempotencyKey("user-1", a));
+    });
+    test("line order doesn't change the fingerprint", () => {
+      expect(cartFingerprint(a)).toBe(cartFingerprint([...a].reverse()));
+    });
+    test("a changed cart → a different key", () => {
+      expect(idempotencyKey("user-1", a)).not.toBe(idempotencyKey("user-1", lines([[1000, 1], [500, 3]])));
+      expect(idempotencyKey("user-1", a)).not.toBe(idempotencyKey("user-1", a, { type: "percent", value: 10 }));
+    });
+    test("a different principal → a different key (no cross-tenant intent reuse)", () => {
+      expect(idempotencyKey("user-1", a)).not.toBe(idempotencyKey("user-2", a));
+    });
+  });
+
+  describe("maxDiscountCents — capping a percentage discount", () => {
+    test("a percent discount is capped at maxDiscountCents", () => {
+      expect(computeDiscountAmount(30000, { type: "percent", value: 30, maxDiscountCents: 5000 })).toBe(5000); // 9000 → capped 5000
+    });
+    test("under the cap, the full percent applies", () => {
+      expect(computeDiscountAmount(10000, { type: "percent", value: 30, maxDiscountCents: 5000 })).toBe(3000);
+    });
+    test("no cap → uncapped (back-compat)", () => {
+      expect(computeDiscountAmount(30000, { type: "percent", value: 30 })).toBe(9000);
+    });
+    test("the cap still respects the [0, subtotal] clamp", () => {
+      expect(computeDiscountAmount(2000, { type: "fixed", value: 9999, maxDiscountCents: 5000 })).toBe(2000);
+    });
+  });
+
+  describe("requiresStripe — the $0.50 floor / free-order decision", () => {
+    test("a chargeable total requires Stripe", () => {
+      expect(requiresStripe(2900)).toBe(true);
+      expect(requiresStripe(STRIPE_MIN_CHARGE_CENTS)).toBe(true);
+    });
+    test("$0 and sub-floor totals go the free path", () => {
+      expect(requiresStripe(0)).toBe(false);
+      expect(requiresStripe(49)).toBe(false);
+    });
+    test("poison totals never require a charge", () => {
+      expect(requiresStripe(NaN)).toBe(false);
+      expect(requiresStripe(-100)).toBe(false);
+    });
+  });
+});

package/test/stripe.test.ts

@@ -2,7 +2,7 @@ import { test, expect, describe } from "bun:test";
 import type { CostEvent } from "@suluk/cost";
 import {
   customerParams, meterParams, meteredPriceParams, subscriptionParams, meterEventParams,
-  setupUsageBilling, stripeProvider, usageEventsFromCost, reportCostUsage, type StripeLike,
+  billingPortalSessionParams, setupUsageBilling, stripeProvider, usageEventsFromCost, reportCostUsage, type StripeLike,
 } from "../src/index";
 
 /** A recording mock that satisfies StripeLike — records every call + returns fake ids. */
@@ -18,6 +18,7 @@ function mockStripe() {
       meters: { create: rec("billing.meters.create", "mtr_1") },
       meterEvents: { create: rec("billing.meterEvents.create", "evt_1") },
     },
+    billingPortal: { sessions: { create: async (params: Record<string, unknown>) => { calls.push({ method: "billingPortal.sessions.create", params }); return { url: "https://billing.stripe.com/p/session_1" }; } } },
     webhooks: { constructEvent: (b, s, secret) => { calls.push({ method: "webhooks.constructEvent", params: { b, s, secret } }); return { type: "invoice.paid", data: { ok: true } }; } },
   };
   return { client, calls };
@@ -41,6 +42,10 @@ describe("pure param builders → exact Stripe payloads", () => {
     expect(customerParams({ email: "a@b.c" })).toEqual({ email: "a@b.c" });
     expect(subscriptionParams({ customerId: "cus_1", priceId: "price_1" })).toEqual({ customer: "cus_1", items: [{ price: "price_1" }] });
   });
+  test("billing-portal session params (customer + return_url, optional configuration)", () => {
+    expect(billingPortalSessionParams({ customerId: "cus_1", returnUrl: "https://x.dev/account" })).toEqual({ customer: "cus_1", return_url: "https://x.dev/account" });
+    expect(billingPortalSessionParams({ customerId: "cus_1", returnUrl: "https://x.dev/account", configuration: "bpc_1" })).toMatchObject({ configuration: "bpc_1" });
+  });
 });
 
 describe("flows over a StripeLike client", () => {
@@ -59,6 +64,8 @@ describe("flows over a StripeLike client", () => {
     expect((await stripe.createCustomer({ email: "a@b.c" })).id).toBe("cus_1");
     expect((await stripe.subscribeMetered({ customerId: "cus_1", priceId: "price_1" })).id).toBe("sub_1");
     await stripe.reportUsage({ customerId: "cus_1", eventName: "api_cost", value: 4050 });
+    expect((await stripe.billingPortalUrl!({ customerId: "cus_1", returnUrl: "https://x.dev/account" })).url).toBe("https://billing.stripe.com/p/session_1");
+    expect(calls.find((c) => c.method === "billingPortal.sessions.create")!.params).toEqual({ customer: "cus_1", return_url: "https://x.dev/account" });
     const evt = stripe.verifyWebhook("{raw}", "sig_1");
     expect(evt.type).toBe("invoice.paid");
     expect(calls.find((c) => c.method === "billing.meterEvents.create")!.params).toMatchObject({ event_name: "api_cost", payload: { stripe_customer_id: "cus_1", value: "4050" } });