@suluk/billing 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@suluk/billing",
+  "version": "0.1.0",
+  "description": "Stripe PLUMBING over an injected config (secret key + a mockable fetch): the HTTP transport (with the refund idempotency-key), customer/SetupIntent/PaymentIntent creation, the saved-card surface, the money-moving paths (hosted Checkout + portal + on-default-card top-up + off-session charge), Stripe Tax, the subscription mechanics over a generic SubPlan catalog, and the package-owned billing-account store. Pure Stripe wrappers — the webhook dispatch, credit grants, branded email, the pricing matrix, and refund/pooling stay in the app. Extracted from a real app (C046). CANDIDATE tooling.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+    "directory": "tooling/ts/packages/billing"
+  },
+  "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/payments": "^0.1.0",
+    "@suluk/drizzle": "^0.1.6",
+    "drizzle-orm": "^0.45.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p ."
+  }
+}

package/src/account.ts

@@ -0,0 +1,59 @@
+/**
+ * The billing-account store (C046, v2) — the app's user ↔ Stripe link: the customer id + the active subscription id,
+ * owned by @suluk/billing and applied by the app's migrations. `userId` is the PK as a PLAIN column (the app owns the
+ * `user` table; add the FK + cascade in your migration), exactly like @suluk/credits owns its ledger with a plain
+ * `userId`. The app injects a Drizzle handle (`DrizzleD1Database` in prod; bun:sqlite bridged to it in tests). Extracted
+ * verbatim from the source.
+ */
+import { eq } from "drizzle-orm";
+import type { DrizzleD1Database } from "drizzle-orm/d1";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+
+/** The injected DB handle. Prod is drizzle/d1; tests bridge drizzle/bun-sqlite to this type (a runtime-identity narrow). */
+export type BillingDB = DrizzleD1Database;
+
+export const billingAccount = sqliteTable("billing_account", {
+  /** the user id — PK; a plain column (the app owns the user table; add the FK + onDelete cascade in your migration). */
+  userId: text("userId").primaryKey(),
+  /** the Stripe customer id (set on the first top-up/subscribe; reused so a saved card is never orphaned). */
+  stripeCustomerId: text("stripeCustomerId"),
+  /** the ACTIVE subscription id, or null when the user has none (cleared by customer.subscription.deleted). */
+  subscriptionId: text("subscriptionId"),
+  updatedAt: integer("updatedAt", { mode: "timestamp" }).notNull(),
+});
+
+/** The user's Stripe customer id, or null when they have no billing account yet. */
+export async function billingCustomerId(db: BillingDB, userId: string): Promise<string | null> {
+  const rows = await db.select().from(billingAccount).where(eq(billingAccount.userId, userId)).limit(1);
+  return rows[0]?.stripeCustomerId ?? null;
+}
+
+/** The user's recorded Stripe subscription id, or null when they have no subscription. */
+export async function billingSubscriptionId(db: BillingDB, userId: string): Promise<string | null> {
+  const rows = await db.select().from(billingAccount).where(eq(billingAccount.userId, userId)).limit(1);
+  return rows[0]?.subscriptionId ?? null;
+}
+
+/** Persist the user's Stripe customer id WITHOUT touching subscriptionId — so a one-time top-up never clears a
+ *  subscriber's `subscriptionId` (unlike {@link upsertBillingAccount}, which sets it). Idempotent on the userId PK. */
+export async function linkBillingCustomer(db: BillingDB, userId: string, customerId: string): Promise<void> {
+  await db
+    .insert(billingAccount)
+    .values({ userId, stripeCustomerId: customerId, subscriptionId: null, updatedAt: new Date() })
+    .onConflictDoUpdate({ target: billingAccount.userId, set: { stripeCustomerId: customerId, updatedAt: new Date() } })
+    .run();
+}
+
+/** Persist customer + subscription together (the subscribe path sets both). Idempotent on the userId PK. */
+export async function upsertBillingAccount(db: BillingDB, userId: string, customerId: string, subscriptionId: string | null): Promise<void> {
+  await db
+    .insert(billingAccount)
+    .values({ userId, stripeCustomerId: customerId, subscriptionId, updatedAt: new Date() })
+    .onConflictDoUpdate({ target: billingAccount.userId, set: { stripeCustomerId: customerId, subscriptionId, updatedAt: new Date() } })
+    .run();
+}
+
+/** Clear the recorded subscription (on customer.subscription.deleted) — leaves the customer id (+ its saved card) intact. */
+export async function clearSubscription(db: BillingDB, userId: string): Promise<void> {
+  await db.update(billingAccount).set({ subscriptionId: null, updatedAt: new Date() }).where(eq(billingAccount.userId, userId)).run();
+}

package/src/agnostic.ts

@@ -0,0 +1,26 @@
+/**
+ * The agnostic payment bridge (C048) — billing's server-side charge + customer paths now run through @suluk/payments
+ * (Stripe today, swappable by construction) instead of hand-rolled Stripe calls. This is the first step of deprecating
+ * the direct @suluk/stripe coupling: `createCustomer` + `chargeOffSession` are re-expressed over the unified
+ * {@link PaymentConnector}; the browser/Element/hosted-Checkout + subscription flows stay direct for now (they need the
+ * client-token surface — the follow-on migration). Parity-tested: the agnostic path emits the same Stripe request and
+ * preserves the off-session decline taxonomy.
+ */
+import { stripeConnector, PaymentStatus, type PaymentConnector } from "@suluk/payments";
+import type { StripeConfig } from "./transport";
+
+/** The payment connector bound to this billing config. Stripe now; changing the backend is a one-line swap here. */
+export function paymentConnector(cfg: StripeConfig): PaymentConnector {
+  return stripeConnector({ apiKey: { value: cfg.secretKey } }, { fetch: cfg.fetch });
+}
+
+/** Map a unified PaymentStatus back to the Stripe-ish status STRING billing's callers already branch on ("succeeded" /
+ *  "requires_action" / "processing" / "failed"), so the rewire is drop-in for the existing auto-top-up flow. */
+const STATUS_STRING: Partial<Record<PaymentStatus, string>> = {
+  [PaymentStatus.CHARGED]: "succeeded",
+  [PaymentStatus.AUTHORIZED]: "requires_capture",
+  [PaymentStatus.AUTHENTICATION_PENDING]: "requires_action",
+  [PaymentStatus.PENDING]: "processing",
+  [PaymentStatus.FAILURE]: "failed",
+};
+export const statusString = (s: PaymentStatus): string => STATUS_STRING[s] ?? "failed";

package/src/billing.ts

@@ -0,0 +1,167 @@
+/**
+ * Stripe wrappers (C046, v1) — customer + intent creation and the saved-card surface, over the injected {@link
+ * StripeConfig}. Extracted from the source with the `res.ok` + field-presence + throw semantics PRESERVED VERBATIM; the
+ * only deliberate change is dropping the Effect-`Schema` defensive response-decode (a robustness layer the app can
+ * re-add) in favour of plain JSON access — so this package carries no `effect` dependency. The money-MOVING paths
+ * (checkout, charge-off-session), the pricing-woven subscription logic (status/change), the webhook dispatch, the credit
+ * grant, email, and the billing-account DB linking are NOT here — they stay in the app (the careful follow-on).
+ */
+import { type StripeConfig, stripePost, stripeGet, toForm } from "./transport";
+import { paymentConnector } from "./agnostic";
+import { Currency } from "@suluk/payments";
+
+type StripeErr = { error?: { message?: string } };
+
+/** Create a Stripe customer for the user (the caller persists the id). Routed through @suluk/payments (C048) — the
+ *  processor is swappable; the Stripe request (POST /customers with email + metadata[userId]) is unchanged. */
+export async function createCustomer(cfg: StripeConfig, email: string | null, userId: string): Promise<string> {
+  const { customerId } = await paymentConnector(cfg).createCustomer!({ email: email ?? undefined, metadata: { userId } });
+  return customerId;
+}
+
+/** Create a $0 SetupIntent to vault a card without charging ("Add card"). Returns the client secret. */
+export async function createSetupIntent(cfg: StripeConfig, customerId: string, userId: string): Promise<string> {
+  // C048 — vault a card ("add card") via @suluk/payments' client-token surface; returns the client secret the browser confirms.
+  const session = await paymentConnector(cfg).createSetupSession!({ customerId, metadata: { userId } });
+  return session.clientSecret;
+}
+
+/** Create a PaymentIntent for an on-site one-time top-up (saves the card; the webhook credits it). Returns the client secret. */
+export async function createPaymentIntent(cfg: StripeConfig, customerId: string, amountCents: number, meta: { userId: string; credits: number; taxCalculation?: string | null }): Promise<string> {
+  // C048 — the Payment-Element flow via @suluk/payments' client-token surface: creates the PaymentIntent (no
+  // paymentMethod → automatic_payment_methods; saves the card) and returns the client secret the browser confirms.
+  const session = await paymentConnector(cfg).createPaymentSession!({
+    amount: { minorAmount: amountCents, currency: Currency.USD },
+    customerId,
+    setupFutureUsage: true,
+    metadata: { userId: meta.userId, credits: String(meta.credits), source: "onsite_topup", ...(meta.taxCalculation ? { tax_calculation: meta.taxCalculation } : {}) },
+  });
+  return session.clientSecret;
+}
+
+/** A buyer's tax location (from a saved card's billing address). */
+export interface TaxAddress {
+  country: string;
+  state: string | null;
+  postalCode: string | null;
+  city: string | null;
+  line1: string | null;
+}
+
+/** A payment method as the billing panel shows it — card + its billing address + whether it's the customer's default. */
+export interface PaymentMethodWire {
+  id: string;
+  brand: string;
+  last4: string;
+  expMonth: number;
+  expYear: number;
+  name: string | null;
+  line1: string | null;
+  line2: string | null;
+  city: string | null;
+  region: string | null;
+  postalCode: string | null;
+  country: string | null;
+  isDefault: boolean;
+}
+
+interface StripePmRaw {
+  id: string;
+  card?: { brand?: string; last4?: string; exp_month?: number; exp_year?: number };
+  billing_details?: { name?: string | null; address?: { line1?: string | null; line2?: string | null; city?: string | null; state?: string | null; postal_code?: string | null; country?: string | null } | null };
+}
+
+/** List a customer's saved cards (each with its billing address), marking the invoice default. */
+export async function listPaymentMethods(cfg: StripeConfig, customerId: string): Promise<PaymentMethodWire[]> {
+  const [pmRes, custRes] = await Promise.all([
+    stripeGet(cfg, `payment_methods?customer=${customerId}&type=card&limit=20`),
+    stripeGet(cfg, `customers/${customerId}`),
+  ]);
+  const list = (await pmRes.json()) as { data?: StripePmRaw[] };
+  const cust = (await custRes.json()) as { invoice_settings?: { default_payment_method?: string | null } };
+  const defaultId = cust?.invoice_settings?.default_payment_method ?? null;
+  return (list.data ?? []).map((pm) => {
+    const addr = pm.billing_details?.address ?? null;
+    return {
+      id: pm.id,
+      brand: pm.card?.brand ?? "card",
+      last4: pm.card?.last4 ?? "",
+      expMonth: pm.card?.exp_month ?? 0,
+      expYear: pm.card?.exp_year ?? 0,
+      name: pm.billing_details?.name ?? null,
+      line1: addr?.line1 ?? null,
+      line2: addr?.line2 ?? null,
+      city: addr?.city ?? null,
+      region: addr?.state ?? null,
+      postalCode: addr?.postal_code ?? null,
+      country: addr?.country ?? null,
+      isDefault: pm.id === defaultId,
+    };
+  });
+}
+
+/** The customer's DEFAULT saved card — its id (to charge) + its billing address (to locate tax). Graceful: a transient
+ *  Stripe error returns null rather than blocking a top-up (this is only tax LOCATION / an off-session skip). */
+export async function defaultCard(cfg: StripeConfig, customerId: string): Promise<{ pmId: string; address: TaxAddress | null } | null> {
+  try {
+    const cards = await listPaymentMethods(cfg, customerId);
+    const d = cards.find((c) => c.isDefault);
+    if (!d) return null;
+    const address: TaxAddress | null = d.country ? { country: d.country, state: d.region, postalCode: d.postalCode, city: d.city, line1: d.line1 } : null;
+    return { pmId: d.id, address };
+  } catch {
+    return null;
+  }
+}
+
+/** The customer's default payment-method id (to charge off-session), or null. */
+export async function defaultPaymentMethodId(cfg: StripeConfig, customerId: string): Promise<string | null> {
+  return (await defaultCard(cfg, customerId))?.pmId ?? null;
+}
+
+/** Whether `pmId` belongs to `customerId` — guards set-default / detach against another customer's card. */
+export async function ownsPaymentMethod(cfg: StripeConfig, customerId: string, pmId: string): Promise<boolean> {
+  return (await listPaymentMethods(cfg, customerId)).some((m) => m.id === pmId);
+}
+
+/** Make `pmId` the customer's default payment method for invoices. */
+export async function setDefaultPaymentMethod(cfg: StripeConfig, customerId: string, pmId: string): Promise<void> {
+  const res = await stripePost(cfg, `customers/${customerId}`, toForm({ invoice_settings: { default_payment_method: pmId } }));
+  if (!res.ok) throw new Error(`Stripe set-default failed (${res.status})`);
+}
+
+/** Point an ACTIVE subscription at `pmId` too, so changing the default card moves the recurring charge to it. */
+export async function setSubscriptionDefaultCard(cfg: StripeConfig, subscriptionId: string, pmId: string): Promise<void> {
+  const res = await stripePost(cfg, `subscriptions/${subscriptionId}`, toForm({ default_payment_method: pmId }));
+  if (!res.ok) throw new Error(`Stripe subscription set-default-card failed (${res.status})`);
+}
+
+/** Detach (remove) a saved card from the customer. */
+export async function detachPaymentMethod(cfg: StripeConfig, pmId: string): Promise<void> {
+  const res = await stripePost(cfg, `payment_methods/${pmId}/detach`, toForm({}));
+  if (!res.ok) throw new Error(`Stripe detach failed (${res.status})`);
+}
+
+/** Schedule the subscription to cancel at the period end (`cancel=true`) or resume it (`cancel=false`). */
+export async function setSubscriptionCancel(cfg: StripeConfig, subscriptionId: string, cancel: boolean): Promise<void> {
+  const res = await stripePost(cfg, `subscriptions/${subscriptionId}`, toForm({ cancel_at_period_end: cancel }));
+  if (!res.ok) {
+    const body = (await res.json()) as StripeErr;
+    throw new Error(body?.error?.message ?? `Stripe subscription update failed (${res.status})`);
+  }
+}
+
+/** Best-effort: if the subscription's latest invoice is still OPEN (a failed renewal), retry it NOW. No-op when there's
+ *  nothing open to pay; never throws (a fix-billing flow must not 500 on the retry). */
+export async function payOpenInvoice(cfg: StripeConfig, subscriptionId: string): Promise<void> {
+  try {
+    const res = await stripeGet(cfg, `subscriptions/${subscriptionId}?expand[]=latest_invoice`);
+    if (!res.ok) return;
+    const sub = (await res.json()) as { latest_invoice?: { id?: string; status?: string } };
+    const inv = sub?.latest_invoice;
+    if (!inv?.id || inv.status !== "open") return;
+    await stripePost(cfg, `invoices/${inv.id}/pay`, toForm({}));
+  } catch (e) {
+    console.warn(`[billing] payOpenInvoice ${subscriptionId} failed:`, e instanceof Error ? e.message : String(e));
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @suluk/billing — Stripe plumbing over an injected config (C046). The transport + customer/intent creation + the
+ * saved-card surface (v1), plus the money-MOVING paths (hosted Checkout, portal, on-default-card top-up, off-session
+ * charge), the pricing-woven subscription logic made generic over a SubPlan catalog, the Stripe Tax mechanics, and the
+ * package-owned billing-account store (v2). Ported with the source's `res.ok`/field semantics verbatim; the Effect-Schema
+ * defensive decode is dropped (plain typed JSON access → no `effect` dep). STAYS APP (policy, not library): the Stripe
+ * WEBHOOK dispatch (composes @suluk/stripe webhookRouter + these primitives + @suluk/credits.grantOnce), the branded
+ * email templates, payment-alert kinds, and refund/subscription-pooling (operator-excluded from the start).
+ */
+export { type StripeConfig, stripePost, stripeGet, toForm } from "./transport";
+export {
+  createCustomer, createSetupIntent, createPaymentIntent,
+  listPaymentMethods, defaultCard, defaultPaymentMethodId, ownsPaymentMethod,
+  setDefaultPaymentMethod, setSubscriptionDefaultCard, detachPaymentMethod,
+  setSubscriptionCancel, payOpenInvoice,
+  type PaymentMethodWire, type TaxAddress,
+} from "./billing";
+// v2 — money-moving Stripe primitives (app supplies product name + success/cancel/return URLs).
+export {
+  createCheckout, createSubscriptionCheckout, createPortalSessionForCustomer,
+  createPaymentIntentOnDefaultCard, chargeOffSession,
+  type CheckoutOpts, type SubscriptionCheckoutOpts, type TopupMeta,
+} from "./payments";
+// v2 — Stripe Tax mechanics (graceful: any failure → taxCents 0, the top-up always proceeds).
+export { calculateTax, recordTaxTransaction, type TaxResult, type TaxLocation } from "./tax";
+// v2 — subscription mechanics over a generic SubPlan catalog (the pricing matrix stays in the app).
+export {
+  type SubPlan, planById, planByPrice, ceilingFor, ensurePlanPrice, createSubscriptionOnDefaultCard,
+  getSubscriptionStatus, changeSubscriptionPlan,
+  type SubscriptionBranding, type SubscriptionStatus, type ChangePlanResult,
+} from "./subscriptions";
+// v2 — the package-owned billing-account store (the user ↔ Stripe link; the app injects a Drizzle handle).
+export {
+  billingAccount, type BillingDB,
+  billingCustomerId, billingSubscriptionId, linkBillingCustomer, upsertBillingAccount, clearSubscription,
+} from "./account";

package/src/payments.ts

@@ -0,0 +1,147 @@
+/**
+ * The money-MOVING Stripe primitives (C046, v2) — hosted Checkout (one-time + subscription), the billing portal, the
+ * on-saved-card top-up PaymentIntent, and the OFF-SESSION auto-top-up charge with its decline/3DS handling. Pure Stripe
+ * mechanics over the injected {@link StripeConfig}; the app supplies its product NAME + success/cancel/return URLs (no app
+ * routes or branding baked in) and reads the returned secrets. Extracted verbatim with the source's res.ok / field /
+ * throw semantics; plain typed JSON access (no Effect-Schema decode). The credit GRANT for these charges happens on the
+ * Stripe webhook via @suluk/credits.grantOnce — app POLICY, not here.
+ */
+import { type StripeConfig, stripePost, toForm } from "./transport";
+import { defaultPaymentMethodId } from "./billing";
+import { paymentConnector, statusString } from "./agnostic";
+import { PaymentStatus, CaptureMethod, AuthenticationType, Currency } from "@suluk/payments";
+import type { SubPlan } from "./subscriptions";
+
+type StripeErr = { error?: { message?: string; code?: string; payment_intent?: { id?: string; status?: string } } };
+
+/** The metadata tag the webhook reads to decide whether (and how) to credit a PaymentIntent. */
+export type TopupMeta = { userId: string; credits: number; taxCalculation?: string | null };
+
+export interface CheckoutOpts {
+  userId: string;
+  /** the user's existing customer (reused so a saved card isn't orphaned), or null to let Checkout create one. */
+  customerId: string | null;
+  amountCents: number;
+  credits: number;
+  /** the URL Stripe returns to on success (the app composes it from its origin + route). */
+  successUrl: string;
+  cancelUrl: string;
+  /** the line-item product name shown on the hosted page, e.g. "acme — 600 credits". */
+  productName: string;
+}
+
+/** Create a Stripe Checkout Session (one-time top-up) — the hosted FALLBACK to the on-site Payment Element. Reuses the
+ *  user's existing customer or has Checkout create one, captures the billing address, and saves the card for future
+ *  off-session use. Returns the hosted checkout URL. */
+export async function createCheckout(cfg: StripeConfig, o: CheckoutOpts): Promise<string> {
+  const form = toForm({
+    mode: "payment",
+    success_url: o.successUrl,
+    cancel_url: o.cancelUrl,
+    client_reference_id: o.userId,
+    customer: o.customerId ?? undefined,
+    customer_creation: o.customerId ? undefined : "always",
+    // Capture the billing address WITH the card → Stripe stores it on the PaymentMethod (no separate table; no shipping).
+    billing_address_collection: "required",
+    // Stripe Tax on the charge; customer_update.address:auto saves the collected address to an EXISTING customer so the tax
+    // location resolves. $0 until registered, then auto-collects.
+    automatic_tax: { enabled: true },
+    customer_update: o.customerId ? { address: "auto" } : undefined,
+    line_items: [{ quantity: 1, price_data: { currency: "usd", unit_amount: o.amountCents, product_data: { name: o.productName } } }],
+    metadata: { userId: o.userId, credits: o.credits },
+    // setup_future_usage saves the card. NO `source` here, so payment_intent.succeeded skips this PI — a Checkout charge
+    // is credited via checkout.session.completed, never twice.
+    payment_intent_data: { metadata: { userId: o.userId, credits: o.credits }, setup_future_usage: "off_session" },
+  });
+  const res = await stripePost(cfg, "checkout/sessions", form);
+  const session = (await res.json()) as StripeErr & { url?: string };
+  if (!res.ok || !session.url) throw new Error(session.error?.message ?? `Stripe checkout failed (${res.status})`);
+  return session.url;
+}
+
+export interface SubscriptionCheckoutOpts {
+  userId: string;
+  plan: SubPlan;
+  successUrl: string;
+  cancelUrl: string;
+  /** the line-item product name shown on the hosted page, e.g. "acme — Pro". */
+  productName: string;
+}
+
+/** Stripe Checkout in SUBSCRIPTION mode (recurring). subscription_data.metadata carries who + how many credits/cycle. */
+export async function createSubscriptionCheckout(cfg: StripeConfig, o: SubscriptionCheckoutOpts): Promise<string> {
+  const form = toForm({
+    mode: "subscription",
+    success_url: o.successUrl,
+    cancel_url: o.cancelUrl,
+    client_reference_id: o.userId,
+    billing_address_collection: "required",
+    line_items: [
+      { quantity: 1, price_data: { currency: "usd", unit_amount: o.plan.priceCents, recurring: { interval: "month" }, product_data: { name: o.productName } } },
+    ],
+    subscription_data: { metadata: { userId: o.userId, credits: o.plan.credits, planId: o.plan.id } },
+    automatic_tax: { enabled: true },
+    metadata: { userId: o.userId },
+  });
+  const res = await stripePost(cfg, "checkout/sessions", form);
+  const session = (await res.json()) as StripeErr & { url?: string };
+  if (!res.ok || !session.url) throw new Error(session.error?.message ?? `Stripe subscription checkout failed (${res.status})`);
+  return session.url;
+}
+
+/** Open the Stripe billing portal (manage/cancel) for an existing customer. Returns the URL; throws on a Stripe error. */
+export async function createPortalSessionForCustomer(cfg: StripeConfig, customerId: string, returnUrl: string): Promise<string> {
+  const res = await stripePost(cfg, "billing_portal/sessions", toForm({ customer: customerId, return_url: returnUrl }));
+  const session = (await res.json()) as StripeErr & { url?: string };
+  if (!res.ok || !session.url) throw new Error(`Stripe billing portal failed (${res.status})`);
+  return session.url;
+}
+
+/** Create a PaymentIntent on the customer's SAVED DEFAULT card — the one-click top-up path. The server resolves the
+ *  default payment method (client can't inject one), pins the PI to it, and returns the client secret; the browser
+ *  confirms (3DS in-page if needed). Returns null when there's no default card to charge. No setup_future_usage — the
+ *  card is already saved. */
+export async function createPaymentIntentOnDefaultCard(cfg: StripeConfig, customerId: string, amountCents: number, meta: TopupMeta): Promise<string | null> {
+  // C048 — the one-click flow via @suluk/payments' client-token surface: resolve the default card (client can't inject
+  // one), pin the session to it, return the client secret the browser confirms. Null when there's no default card.
+  const pmId = await defaultPaymentMethodId(cfg, customerId);
+  if (!pmId) return null;
+  const session = await paymentConnector(cfg).createPaymentSession!({
+    amount: { minorAmount: amountCents, currency: Currency.USD },
+    customerId,
+    paymentMethod: { value: pmId },
+    metadata: { userId: meta.userId, credits: String(meta.credits), source: "onsite_topup", ...(meta.taxCalculation ? { tax_calculation: meta.taxCalculation } : {}) },
+  });
+  return session.clientSecret;
+}
+
+/** An OFF-SESSION charge on a saved card (auto-top-up). Confirms immediately; metadata carries who + credits + `source`
+ *  so the payment_intent.succeeded webhook credits idempotently on the SAME `pi:<id>` key. Returns the PaymentIntent id +
+ *  status, plus `authRequired` when the card needs 3DS (a decline to NOTIFY, not throw on). A hard 402 card decline is
+ *  also returned (not thrown) so the caller can alert; a transient/transport failure throws (it may recover). */
+export async function chargeOffSession(
+  cfg: StripeConfig,
+  customerId: string,
+  pmId: string,
+  amountCents: number,
+  meta: TopupMeta,
+): Promise<{ id: string | null; status: string | null; authRequired: boolean }> {
+  // C048 — routed through @suluk/payments (Stripe today, swappable). The connector emits the SAME off-session PI request
+  // (amount/currency/customer/payment_method/off_session/confirm + the app metadata) and returns the unified status; we
+  // map it back to billing's `{ id, status, authRequired }` shape, preserving the decline taxonomy: a 3DS decline
+  // (AUTHENTICATION_PENDING) sets `authRequired` (email the user), a hard card decline (FAILURE) is RETURNED not thrown
+  // (raise the alert), and a transport/unexpected error still THROWS (from the connector). A fresh idempotency key per
+  // call (unique merchantTransactionId) preserves the original's "every call is a new charge" behaviour.
+  const res = await paymentConnector(cfg).authorize({
+    merchantTransactionId: crypto.randomUUID(),
+    amount: { minorAmount: amountCents, currency: Currency.USD },
+    captureMethod: CaptureMethod.AUTOMATIC,
+    paymentMethod: { token: { value: pmId } },
+    authType: AuthenticationType.NO_THREE_DS,
+    customerId,
+    offSession: true,
+    metadata: { userId: meta.userId, credits: String(meta.credits), source: "auto_topup", ...(meta.taxCalculation ? { tax_calculation: meta.taxCalculation } : {}) },
+  });
+  const authRequired = res.status === PaymentStatus.AUTHENTICATION_PENDING;
+  return { id: res.connectorTransactionId ?? null, status: statusString(res.status), authRequired };
+}

package/src/subscriptions.ts

@@ -0,0 +1,233 @@
+/**
+ * Subscription mechanics (C046, v2) — the recurring-billing logic, made generic over a {@link SubPlan} shape so the
+ * pricing MATRIX stays in the app (it owns COGS/markup/tier discounts) while the Stripe wiring lives here. The app passes
+ * its plan catalog (`SubPlan[]`) + a branding seam; the package owns find-or-create pricing, the create-on-default-card
+ * one-click path, live status, and the in-place plan CHANGE with its paid-CEILING semantics. Extracted verbatim with the
+ * source's res.ok / field semantics; plain typed JSON access (no Effect-Schema decode). The webhook DISPATCH that grants
+ * the cycle's credits on `invoice.paid` is app POLICY (it composes @suluk/credits.grantOnce + these primitives).
+ */
+import { type StripeConfig, stripePost, stripeGet, toForm } from "./transport";
+import { defaultPaymentMethodId } from "./billing";
+
+/** A subscription plan as the app prices it — generic shape; the app derives `priceCents`/`credits` from its COGS model. */
+export interface SubPlan {
+  id: string;
+  name: string;
+  credits: number;
+  priceCents: number;
+  label: string;
+}
+
+/** The app's plan whose id is `id`, or undefined — the generic lookup the orchestrators use against the injected catalog. */
+export const planById = (plans: SubPlan[], id: string): SubPlan | undefined => plans.find((p) => p.id === id);
+
+/** The plan whose monthly price is exactly `priceCents` (each tier has a distinct price), or undefined — maps a live
+ *  Stripe item price back to a plan (e.g. resolving the paid-ceiling plan). */
+export const planByPrice = (plans: SubPlan[], priceCents: number): SubPlan | undefined => plans.find((p) => p.priceCents === priceCents);
+
+/** Branding seam for the Stripe Product/Price a plan creates — app-controlled so find-or-create stays stable + on-brand. */
+export interface SubscriptionBranding {
+  /** the recurring Price's product name; default `${plan.name} (monthly)`. */
+  productName?: (plan: SubPlan) => string;
+  /** the lookup_key PREFIX that makes find-or-create idempotent across repricing; default "sub". KEEP STABLE per app. */
+  lookupKeyPrefix?: string;
+}
+
+type StripeErr = { error?: { message?: string } };
+interface SubItem {
+  id?: string;
+  current_period_end?: number;
+  price?: { unit_amount?: number };
+}
+interface SubObject {
+  id?: string;
+  status?: string;
+  items?: { data?: SubItem[] };
+  current_period_end?: number;
+  cancel_at_period_end?: boolean;
+  metadata?: Record<string, string>;
+  latest_invoice?: { status?: string; confirmation_secret?: { client_secret?: string }; payment_intent?: { client_secret?: string } };
+  error?: { message?: string };
+}
+
+/** Find (by lookup_key) or create the recurring Stripe Price for a plan. The lookup_key embeds the price + credits, so a
+ *  repricing mints a FRESH price rather than reusing a stale one. Returns the price id. */
+export async function ensurePlanPrice(cfg: StripeConfig, plan: SubPlan, branding?: SubscriptionBranding): Promise<string> {
+  const prefix = branding?.lookupKeyPrefix ?? "sub";
+  const productName = branding?.productName ?? ((p: SubPlan) => `${p.name} (monthly)`);
+  const lookupKey = `${prefix}_${plan.id}_${plan.priceCents}_${plan.credits}_m`;
+  const found = (await (await stripeGet(cfg, `prices?lookup_keys[0]=${lookupKey}&active=true&limit=1`)).json()) as { data?: { id?: string }[] };
+  if (found?.data?.[0]?.id) return found.data[0].id;
+  const prodRes = await stripePost(cfg, "products", toForm({ name: productName(plan) }));
+  const product = (await prodRes.json()) as StripeErr & { id?: string };
+  if (!prodRes.ok || !product.id) throw new Error(product.error?.message ?? `Stripe product create failed (${prodRes.status})`);
+  const priceRes = await stripePost(
+    cfg,
+    "prices",
+    toForm({ product: product.id, currency: "usd", unit_amount: plan.priceCents, recurring: { interval: "month" }, lookup_key: lookupKey }),
+  );
+  const price = (await priceRes.json()) as StripeErr & { id?: string };
+  if (!priceRes.ok || !price.id) throw new Error(price.error?.message ?? `Stripe price create failed (${priceRes.status})`);
+  return price.id;
+}
+
+/** Create a subscription ON the saved default card (one-click). payment_behavior=default_incomplete leaves the first
+ *  invoice unpaid with a PaymentIntent the browser confirms (confirmCardPayment → 3DS in-page) → the subscription
+ *  activates → invoice.paid grants the cycle's credits. Returns the first invoice's client secret + the subscription id,
+ *  or null when there's no default card. */
+export async function createSubscriptionOnDefaultCard(
+  cfg: StripeConfig,
+  customerId: string,
+  plan: SubPlan,
+  userId: string,
+  branding?: SubscriptionBranding,
+): Promise<{ clientSecret: string; subscriptionId: string } | null> {
+  const pmId = await defaultPaymentMethodId(cfg, customerId);
+  if (!pmId) return null;
+  const price = await ensurePlanPrice(cfg, plan, branding);
+  const res = await stripePost(
+    cfg,
+    "subscriptions",
+    toForm({
+      customer: customerId,
+      items: [{ price }],
+      default_payment_method: pmId,
+      payment_behavior: "default_incomplete",
+      // Stripe Tax computes + adds tax to each invoice automatically (from the saved card's billing address). $0 until the
+      // account has a head-office address + active tax registrations, then starts collecting with no code change.
+      automatic_tax: { enabled: true },
+      // `confirmation_secret` is the current field (Stripe ≥ 2025-03-31 removed `invoice.payment_intent`); `payment_intent`
+      // is still read below as a fallback for accounts pinned to an older API version.
+      expand: ["latest_invoice.confirmation_secret"],
+      metadata: { userId, credits: plan.credits, planId: plan.id },
+    }),
+  );
+  const sub = (await res.json()) as SubObject;
+  if (!res.ok || sub.error || !sub.id) throw new Error(sub.error?.message ?? `Stripe subscription create failed (${res.status})`);
+  const clientSecret = sub.latest_invoice?.confirmation_secret?.client_secret ?? sub.latest_invoice?.payment_intent?.client_secret;
+  if (!clientSecret) throw new Error("Stripe subscription created without a first-invoice client secret");
+  return { clientSecret, subscriptionId: sub.id };
+}
+
+/** The "paid ceiling" for the CURRENT cycle = the highest plan price already CHARGED this cycle. Persisted in subscription
+ *  metadata (raised on each above-ceiling upgrade), guarded by the period end so it auto-resets at the next renewal. Falls
+ *  back to the current item price — a defer-change lowers the item price (for next cycle's billing) but NOT the ceiling, so
+ *  a later change to ANY plan ≤ the ceiling stays free (you already paid for that level); only EXCEEDING it charges. PURE. */
+export const ceilingFor = (metadata: Record<string, string> | undefined, periodEndSec: number, currentPriceCents: number): number => {
+  const stored = Number(metadata?.cycleCeilingCents ?? 0);
+  const storedEnd = Number(metadata?.cycleCeilingEnd ?? 0);
+  return stored > 0 && storedEnd === periodEndSec ? Math.max(stored, currentPriceCents) : currentPriceCents;
+};
+
+/** The user's CURRENT subscription as the UI needs it (plan + status + period end + pending-cancel + the cycle's paid
+ *  ceiling), or null when there's no live subscription. Live state from Stripe; `plans` is the app catalog for the
+ *  price fallback when the live item lacks one. */
+export interface SubscriptionStatus {
+  planId: string | null;
+  status: string;
+  currentPeriodEnd: number; // ms epoch
+  cancelAtPeriodEnd: boolean;
+  paidCeilingCents: number; // highest plan price charged this cycle — a change ≤ this defers to next cycle (no charge)
+}
+export async function getSubscriptionStatus(cfg: StripeConfig, subscriptionId: string, plans: SubPlan[]): Promise<SubscriptionStatus | null> {
+  const res = await stripeGet(cfg, `subscriptions/${subscriptionId}`);
+  if (!res.ok) return null;
+  const sub = (await res.json()) as SubObject;
+  if (!sub?.status || !["active", "trialing", "past_due"].includes(sub.status)) return null; // not a live plan
+  const item = sub.items?.data?.[0];
+  const periodEnd = sub.current_period_end ?? item?.current_period_end ?? 0;
+  const currentPriceCents = item?.price?.unit_amount ?? planById(plans, sub.metadata?.planId ?? "")?.priceCents ?? 0;
+  return {
+    planId: sub.metadata?.planId ?? null,
+    status: sub.status,
+    currentPeriodEnd: periodEnd * 1000,
+    cancelAtPeriodEnd: sub.cancel_at_period_end ?? false,
+    paidCeilingCents: ceilingFor(sub.metadata, periodEnd, currentPriceCents),
+  };
+}
+
+/** Change the subscriber's plan IN PLACE against the cycle's PAID CEILING (see {@link ceilingFor}). ABOVE the ceiling = an
+ *  upgrade: immediate + prorated for the difference ABOVE THE CEILING, charged off-session; the matching prorated credits
+ *  land on that invoice.paid (3DS-safe). AT OR BELOW the ceiling = a deferred change: no charge + no new credits now — it
+ *  re-prices for the NEXT renewal (so up→down→up within a cycle never re-charges). Returns the kind, the period end, and a
+ *  clientSecret ONLY when the upgrade's prorated charge needs in-page 3DS. `plans` is the app catalog. */
+export interface ChangePlanResult {
+  kind: "upgrade" | "downgrade";
+  clientSecret: string | null;
+  currentPeriodEnd: number; // ms epoch
+}
+export async function changeSubscriptionPlan(
+  cfg: StripeConfig,
+  subscriptionId: string,
+  newPlan: SubPlan,
+  userId: string,
+  plans: SubPlan[],
+  branding?: SubscriptionBranding,
+): Promise<ChangePlanResult> {
+  const getRes = await stripeGet(cfg, `subscriptions/${subscriptionId}`);
+  const current = (await getRes.json()) as SubObject;
+  const item = current?.items?.data?.[0];
+  if (!getRes.ok || !item?.id) throw new Error(current?.error?.message ?? `Stripe subscription retrieve failed (${getRes.status})`);
+  const currentPriceCents = item.price?.unit_amount ?? planById(plans, current?.metadata?.planId ?? "")?.priceCents ?? 0;
+  if (currentPriceCents <= 0) throw new Error("Could not determine the current plan price"); // don't guess "upgrade" + charge
+  const periodEndSec = current?.current_period_end ?? item.current_period_end ?? 0;
+  const periodEnd = periodEndSec * 1000;
+  const wasScheduledToCancel = current?.cancel_at_period_end === true; // switching plans on a canceling sub means "keep it"
+
+  // Decide against the PAID CEILING, not the current price: a prior defer-downgrade lowers the item price but not the
+  // ceiling, so going back UP to a plan you already paid for this cycle must NOT re-charge.
+  const ceilingCents = ceilingFor(current?.metadata, periodEndSec, currentPriceCents);
+  const isUpgrade = newPlan.priceCents > ceilingCents;
+  const newCeiling = Math.max(ceilingCents, newPlan.priceCents); // an upgrade raises it; a deferred change preserves it
+  const newPriceId = await ensurePlanPrice(cfg, newPlan, branding);
+
+  // EXCEEDING the ceiling after a prior defer-downgrade left the item BELOW it: first bump the item up to the ceiling price
+  // with NO proration, so Stripe measures the upgrade proration from the CEILING (newPlan − ceiling), not from the lower
+  // current price. No-op when current == ceiling.
+  if (isUpgrade && currentPriceCents < ceilingCents) {
+    const ceilingPlan = planByPrice(plans, ceilingCents);
+    if (ceilingPlan) {
+      const ceilingPriceId = await ensurePlanPrice(cfg, ceilingPlan, branding);
+      const bump = await stripePost(
+        cfg,
+        `subscriptions/${subscriptionId}`,
+        toForm({ items: [{ id: item.id, price: ceilingPriceId }], proration_behavior: "none" }),
+      );
+      if (!bump.ok) console.warn(`[billing] couldn't bump sub ${subscriptionId} to the ceiling before upgrade (http ${bump.status})`);
+    }
+  }
+
+  const res = await stripePost(
+    cfg,
+    `subscriptions/${subscriptionId}`,
+    toForm({
+      items: [{ id: item.id, price: newPriceId }], // re-price the SAME item (don't add a second line)
+      proration_behavior: isUpgrade ? "always_invoice" : "none", // above ceiling bills the diff now; ≤ ceiling waits for renewal
+      // pending_if_incomplete holds the UPGRADE as a pending change until its prorated charge is actually paid — so an
+      // abandoned/declined 3DS never moves the user to the higher plan without collecting. (Deferred changes don't charge.)
+      payment_behavior: isUpgrade ? "pending_if_incomplete" : undefined,
+      // (re)assert Stripe Tax only on a DEFERRED change. NOT on an upgrade: pending_if_incomplete REJECTS automatic_tax as
+      // an unsupported param (a hard 400); a sub created after the Tax wiring already has it enabled from subscribe.
+      automatic_tax: isUpgrade ? undefined : { enabled: true },
+      // cycleCeiling{Cents,End}: the paid ceiling for this cycle — an upgrade raises it to newPlan, a deferred change keeps
+      // it (so a later re-change ≤ it stays free); the End stamp lets it auto-reset at the next renewal.
+      metadata: { userId, planId: newPlan.id, credits: newPlan.credits, cycleCeilingCents: newCeiling, cycleCeilingEnd: periodEndSec },
+      expand: ["latest_invoice.confirmation_secret"],
+    }),
+  );
+  const sub = (await res.json()) as SubObject;
+  if (!res.ok || sub.error || !sub.id) throw new Error(sub.error?.message ?? `Stripe plan change failed (${res.status})`);
+
+  // A plan change on a subscription that was scheduled to cancel means the user wants to KEEP it → un-schedule the
+  // cancellation. A SEPARATE update because cancel_at_period_end is NOT a supported pending-update param (it would 400 the
+  // upgrade re-price). Best-effort: the plan change already succeeded, so a resume failure is logged, never thrown.
+  if (wasScheduledToCancel) {
+    const resumeRes = await stripePost(cfg, `subscriptions/${subscriptionId}`, toForm({ cancel_at_period_end: false }));
+    if (!resumeRes.ok) console.warn(`[billing] plan change couldn't resume cancel-scheduled sub ${subscriptionId} (http ${resumeRes.status})`);
+  }
+
+  const inv = sub.latest_invoice;
+  const needsAction = isUpgrade && inv?.status !== "paid"; // off-session success → status "paid" → no in-page step
+  const clientSecret = needsAction ? (inv?.confirmation_secret?.client_secret ?? inv?.payment_intent?.client_secret ?? null) : null;
+  return { kind: isUpgrade ? "upgrade" : "downgrade", clientSecret, currentPeriodEnd: periodEnd };
+}

package/src/tax.ts

@@ -0,0 +1,80 @@
+/**
+ * Stripe Tax mechanics (C046, v2) — sales-tax / VAT for an on-site or auto top-up via the Tax Calculation API (raw
+ * PaymentIntents don't support `automatic_tax`, unlike subscriptions/checkout), plus recording the finished calculation
+ * as a Tax Transaction for compliance. GRACEFUL by design: no location or ANY failure yields `{ taxCents: 0 }` so a
+ * top-up ALWAYS proceeds (covering the period before Stripe Tax is set up + any unregistered jurisdiction at $0).
+ * Extracted verbatim with the source's res.ok / field semantics; plain typed JSON access (no Effect-Schema decode).
+ */
+import { type StripeConfig, stripePost, toForm } from "./transport";
+import type { TaxAddress } from "./billing";
+
+export interface TaxResult {
+  taxCents: number;
+  calculationId: string | null;
+}
+
+/** A buyer's tax location. The saved card's BILLING ADDRESS is preferred (precise + works off-session); the request IP is
+ *  the fallback for a first on-session purchase where no card is saved yet. */
+export interface TaxLocation {
+  address?: TaxAddress | null;
+  ip?: string | null;
+}
+
+/** Build Stripe `customer_details` for the Calculation API from the best available location, or null when none. */
+const taxCustomerDetails = (loc: TaxLocation): Record<string, unknown> | null => {
+  if (loc.address?.country)
+    return {
+      address: {
+        country: loc.address.country,
+        state: loc.address.state ?? undefined,
+        postal_code: loc.address.postalCode ?? undefined,
+        city: loc.address.city ?? undefined,
+        line1: loc.address.line1 ?? undefined,
+      },
+      address_source: "billing",
+    };
+  if (loc.ip) return { ip_address: loc.ip };
+  return null;
+};
+
+/**
+ * Sales-tax / VAT for an on-site or auto top-up. The taxable base is the credits `subtotalCents` (tax_behavior=exclusive →
+ * tax added on top); the processing service fee is a pass-through, not part of the taxable sale. Located by the saved
+ * card's billing address (preferred — works off-session) or the request IP. GRACEFUL — no location or any failure yields
+ * `{ taxCents: 0 }` so a top-up always proceeds. When active, the returned `calculationId` is recorded via
+ * {@link recordTaxTransaction}.
+ */
+export async function calculateTax(cfg: StripeConfig, customerId: string, subtotalCents: number, loc: TaxLocation): Promise<TaxResult> {
+  const customer_details = taxCustomerDetails(loc);
+  if (!customer_details) return { taxCents: 0, calculationId: null }; // no location → can't compute; skip
+  try {
+    const res = await stripePost(
+      cfg,
+      "tax/calculations",
+      toForm({
+        currency: "usd",
+        customer: customerId,
+        line_items: [{ amount: subtotalCents, reference: "credits", tax_behavior: "exclusive" }],
+        customer_details,
+      }),
+    );
+    if (!res.ok) return { taxCents: 0, calculationId: null }; // inactive / unlocatable → no tax, top-up still proceeds
+    const calc = (await res.json()) as { tax_amount_exclusive?: number; id?: string };
+    return { taxCents: calc?.tax_amount_exclusive ?? 0, calculationId: calc?.id ?? null };
+  } catch {
+    return { taxCents: 0, calculationId: null };
+  }
+}
+
+/** Record a finished tax calculation as a Tax Transaction (the compliance/reporting step), keyed to a `reference`
+ *  (e.g. `pi:<id>`) which is Stripe's idempotency anchor — a replay of the same reference returns the existing
+ *  transaction rather than creating a second, so re-delivery can't double-record. Best-effort — never throws into the
+ *  caller (the charge already succeeded; a missed record is reconciled manually). */
+export async function recordTaxTransaction(cfg: StripeConfig, calculationId: string, reference: string): Promise<void> {
+  try {
+    const res = await stripePost(cfg, "tax/transactions/create_from_calculation", toForm({ calculation: calculationId, reference }));
+    if (!res.ok) console.warn(`[stripe-tax] tax transaction NOT recorded for ${reference} (calc ${calculationId}, http ${res.status}) — reconcile manually`);
+  } catch (e) {
+    console.warn(`[stripe-tax] tax transaction record threw for ${reference} (calc ${calculationId})`, e);
+  }
+}

package/src/transport.ts

@@ -0,0 +1,7 @@
+/**
+ * The Stripe HTTP transport (C046 → C048) — the seam every billing wrapper rides. Now re-exported from @suluk/payments so
+ * ALL of billing's Stripe HTTP (the agnostic payment flows AND the Stripe-platform ops: checkout, subscriptions, saved
+ * cards, tax) rides ONE Stripe client. The legacy @suluk/stripe coupling is gone — there's no separate path to reach for
+ * by accident. Config-injected: the secret key + a mockable `fetch`.
+ */
+export { type StripeConfig, stripePost, stripeGet, toForm } from "@suluk/payments";

package/test/agnostic.test.ts

@@ -0,0 +1,47 @@
+import { test, expect, describe } from "bun:test";
+import { paymentConnector, statusString } from "../src/agnostic";
+import { createCustomer } from "../src/index";
+import { PaymentStatus } from "@suluk/payments";
+import type { StripeConfig } from "../src/transport";
+
+/**
+ * C048 — billing's server-side charge + customer paths now run through @suluk/payments. The existing billing-v2 suite is
+ * the behavioural parity net (same tests, new innards, still green); this pins the new bridge directly: the connector is
+ * a real Stripe connector, and the unified→billing status mapping is exact.
+ */
+interface Call { path: string; body: string }
+function mockStripe(routes: Record<string, unknown>): { cfg: StripeConfig; calls: Call[] } {
+  const calls: Call[] = [];
+  const fetchMock = (async (url: string | URL, init?: RequestInit) => {
+    const path = String(url).replace("https://api.stripe.com/v1/", "");
+    calls.push({ path, body: (init?.body as string) ?? "" });
+    const key = Object.keys(routes).find((k) => path.startsWith(k));
+    return new Response(JSON.stringify(key ? routes[key] : {}), { status: 200 });
+  }) as unknown as typeof fetch;
+  return { cfg: { secretKey: "sk_test", fetch: fetchMock }, calls };
+}
+
+describe("the agnostic bridge", () => {
+  test("paymentConnector(cfg) is a Stripe-backed connector bound to the billing config", async () => {
+    const { cfg, calls } = mockStripe({ customers: { id: "cus_9" } });
+    const c = paymentConnector(cfg);
+    expect(c.name).toBe("stripe");
+    expect(await c.createCustomer!({ email: "x@y.com" })).toEqual({ customerId: "cus_9" });
+    expect(calls[0].path).toBe("customers");
+  });
+
+  test("createCustomer routes through @suluk/payments (same POST /customers request)", async () => {
+    const { cfg, calls } = mockStripe({ customers: { id: "cus_1" } });
+    expect(await createCustomer(cfg, "a@b.com", "user_1")).toBe("cus_1");
+    expect(calls[0].body).toContain("email=a%40b.com");
+    expect(calls[0].body).toContain("metadata%5BuserId%5D=user_1");
+  });
+
+  test("statusString maps the unified status back to billing's Stripe-ish strings", () => {
+    expect(statusString(PaymentStatus.CHARGED)).toBe("succeeded");
+    expect(statusString(PaymentStatus.AUTHENTICATION_PENDING)).toBe("requires_action");
+    expect(statusString(PaymentStatus.PENDING)).toBe("processing");
+    expect(statusString(PaymentStatus.FAILURE)).toBe("failed");
+    expect(statusString(PaymentStatus.AUTHORIZATION_FAILED)).toBe("failed"); // any other → failed
+  });
+});

package/test/billing-account.test.ts

@@ -0,0 +1,49 @@
+import { test, expect, describe, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import {
+  billingCustomerId, billingSubscriptionId, linkBillingCustomer, upsertBillingAccount, clearSubscription, type BillingDB,
+} from "../src/index";
+
+/** C046 v2 — the billing-account store, witnessed against a REAL bun:sqlite. The package owns the schema; we apply it
+ *  here and bridge bun:sqlite → BillingDB (a runtime-identity narrow, as the source app does in tests). */
+function freshDb(): BillingDB {
+  const sqlite = new Database(":memory:");
+  sqlite.run(`CREATE TABLE billing_account (userId TEXT PRIMARY KEY, stripeCustomerId TEXT, subscriptionId TEXT, updatedAt INTEGER NOT NULL)`);
+  return drizzle(sqlite) as unknown as BillingDB;
+}
+
+let db: BillingDB;
+const U = "user_1";
+beforeEach(() => {
+  db = freshDb();
+});
+
+describe("the billing-account store", () => {
+  test("empty by default", async () => {
+    expect(await billingCustomerId(db, U)).toBeNull();
+    expect(await billingSubscriptionId(db, U)).toBeNull();
+  });
+
+  test("linkBillingCustomer sets the customer id (idempotent on userId)", async () => {
+    await linkBillingCustomer(db, U, "cus_1");
+    expect(await billingCustomerId(db, U)).toBe("cus_1");
+    await linkBillingCustomer(db, U, "cus_2"); // re-link → updates, doesn't duplicate
+    expect(await billingCustomerId(db, U)).toBe("cus_2");
+  });
+
+  test("a top-up link NEVER clears a subscriber's subscriptionId", async () => {
+    await upsertBillingAccount(db, U, "cus_1", "sub_1"); // subscribe sets both
+    expect(await billingSubscriptionId(db, U)).toBe("sub_1");
+    await linkBillingCustomer(db, U, "cus_1"); // a later one-time top-up
+    expect(await billingSubscriptionId(db, U)).toBe("sub_1"); // still subscribed — the load-bearing guard
+    expect(await billingCustomerId(db, U)).toBe("cus_1");
+  });
+
+  test("upsertBillingAccount sets both; clearSubscription drops only the subscription", async () => {
+    await upsertBillingAccount(db, U, "cus_1", "sub_1");
+    await clearSubscription(db, U); // customer.subscription.deleted
+    expect(await billingSubscriptionId(db, U)).toBeNull();
+    expect(await billingCustomerId(db, U)).toBe("cus_1"); // the saved card stays reachable
+  });
+});

package/test/billing-v2.test.ts

@@ -0,0 +1,193 @@
+import { test, expect, describe } from "bun:test";
+import {
+  createCheckout, createSubscriptionCheckout, createPortalSessionForCustomer,
+  createPaymentIntentOnDefaultCard, chargeOffSession,
+  ceilingFor, planById, planByPrice, ensurePlanPrice, getSubscriptionStatus, changeSubscriptionPlan,
+  createSubscriptionOnDefaultCard, type StripeConfig, type SubPlan,
+} from "../src/index";
+
+/** C046 v2 — the money-moving + subscription wrappers, witnessed with a MOCK fetch (the injected transport seam): we
+ *  assert the right Stripe request (path + method + form body) and the response handling. No live Stripe, no effect dep. */
+interface Call { path: string; method: string; body: string; headers: Record<string, string> }
+type Route = { status?: number; body: unknown };
+function mockStripe(routes: Record<string, Route>): { cfg: StripeConfig; 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 { cfg: { secretKey: "sk_test", fetch: fetchMock }, calls };
+}
+
+const STARTER: SubPlan = { id: "starter", name: "Starter", credits: 200, priceCents: 1000, label: "200 credits / month" };
+const PRO: SubPlan = { id: "pro", name: "Pro", credits: 700, priceCents: 3000, label: "700 credits / month" };
+const PLANS = [STARTER, PRO];
+const TF = { lookupKeyPrefix: "tf", productName: (p: SubPlan) => `acme — ${p.name} (monthly)` };
+
+/** A customer whose default card is `pm_1`, so the default-card paths resolve a PM. */
+const withDefaultCard = (routes: Record<string, Route>) =>
+  mockStripe({
+    "GET payment_methods": { body: { data: [{ id: "pm_1", card: { brand: "visa", last4: "4242" }, billing_details: { address: { country: "US" } } }] } },
+    "GET customers/cus_1": { body: { invoice_settings: { default_payment_method: "pm_1" } } },
+    ...routes,
+  });
+
+describe("money-moving: checkout + portal", () => {
+  test("createCheckout posts mode=payment with the product name, metadata, saved card; returns the hosted url", async () => {
+    const { cfg, calls } = mockStripe({ "POST checkout/sessions": { body: { url: "https://checkout.stripe.com/c/x" } } });
+    const url = await createCheckout(cfg, { userId: "u1", customerId: "cus_1", amountCents: 2000, credits: 600, successUrl: "https://app/ok", cancelUrl: "https://app/no", productName: "acme — 600 credits" });
+    expect(url).toBe("https://checkout.stripe.com/c/x");
+    const body = calls[0].body;
+    expect(body).toContain("mode=payment");
+    expect(body).toContain("product_data%5D%5Bname%5D=acme"); // ...[product_data][name]=acme...
+    expect(body).toContain("setup_future_usage%5D=off_session");
+    expect(body).toContain("metadata%5Bcredits%5D=600");
+  });
+
+  test("createSubscriptionCheckout posts mode=subscription with the recurring price + plan metadata", async () => {
+    const { cfg, calls } = mockStripe({ "POST checkout/sessions": { body: { url: "https://checkout.stripe.com/c/sub" } } });
+    const url = await createSubscriptionCheckout(cfg, { userId: "u1", plan: PRO, successUrl: "https://app/ok", cancelUrl: "https://app/no", productName: "acme — Pro" });
+    expect(url).toBe("https://checkout.stripe.com/c/sub");
+    expect(calls[0].body).toContain("mode=subscription");
+    expect(calls[0].body).toContain("recurring%5D%5Binterval%5D=month");
+    expect(calls[0].body).toContain("subscription_data%5Bmetadata%5D%5BplanId%5D=pro");
+  });
+
+  test("createCheckout throws the Stripe error message on failure", async () => {
+    const { cfg } = mockStripe({ "POST checkout/sessions": { status: 400, body: { error: { message: "amount too small" } } } });
+    await expect(createCheckout(cfg, { userId: "u1", customerId: null, amountCents: 1, credits: 0, successUrl: "s", cancelUrl: "c", productName: "x" })).rejects.toThrow("amount too small");
+  });
+
+  test("createPortalSessionForCustomer returns the portal url with the return_url", async () => {
+    const { cfg, calls } = mockStripe({ "POST billing_portal/sessions": { body: { url: "https://billing.stripe.com/p/x" } } });
+    expect(await createPortalSessionForCustomer(cfg, "cus_1", "https://app/account")).toBe("https://billing.stripe.com/p/x");
+    expect(calls[0].body).toContain("return_url=https%3A%2F%2Fapp%2Faccount");
+  });
+});
+
+describe("money-moving: on-default-card top-up", () => {
+  test("createPaymentIntentOnDefaultCard pins the resolved default PM and returns the client secret", async () => {
+    const { cfg, calls } = withDefaultCard({ "POST payment_intents": { body: { client_secret: "pi_secret_1" } } });
+    const secret = await createPaymentIntentOnDefaultCard(cfg, "cus_1", 2000, { userId: "u1", credits: 600 });
+    expect(secret).toBe("pi_secret_1");
+    const pi = calls.find((c) => c.path === "payment_intents")!;
+    expect(pi.body).toContain("payment_method=pm_1");
+    expect(pi.body).toContain("metadata%5Bsource%5D=onsite_topup");
+  });
+
+  test("returns null when the customer has no default card (no charge attempted)", async () => {
+    const { cfg, calls } = mockStripe({
+      "GET payment_methods": { body: { data: [] } },
+      "GET customers/cus_1": { body: { invoice_settings: { default_payment_method: null } } },
+    });
+    expect(await createPaymentIntentOnDefaultCard(cfg, "cus_1", 2000, { userId: "u1", credits: 600 })).toBeNull();
+    expect(calls.some((c) => c.path === "payment_intents" && c.method === "POST")).toBe(false);
+  });
+});
+
+describe("money-moving: off-session charge (auto-top-up)", () => {
+  test("a succeeded charge returns id + status, authRequired false", async () => {
+    const { cfg, calls } = mockStripe({ "POST payment_intents": { body: { id: "pi_1", status: "succeeded" } } });
+    expect(await chargeOffSession(cfg, "cus_1", "pm_1", 2000, { userId: "u1", credits: 600 })).toEqual({ id: "pi_1", status: "succeeded", authRequired: false });
+    expect(calls[0].body).toContain("off_session=true");
+    expect(calls[0].body).toContain("metadata%5Bsource%5D=auto_topup");
+  });
+
+  test("a 3DS decline (authentication_required) returns authRequired:true — NOT a throw", async () => {
+    const { cfg } = mockStripe({ "POST payment_intents": { status: 402, body: { error: { code: "authentication_required", payment_intent: { id: "pi_2", status: "requires_action" } } } } });
+    expect(await chargeOffSession(cfg, "cus_1", "pm_1", 2000, { userId: "u1", credits: 600 })).toEqual({ id: "pi_2", status: "requires_action", authRequired: true });
+  });
+
+  test("a hard 402 card decline is RETURNED (status failed), not thrown", async () => {
+    const { cfg } = mockStripe({ "POST payment_intents": { status: 402, body: { error: { code: "card_declined", payment_intent: { id: "pi_3", status: "failed" } } } } });
+    expect(await chargeOffSession(cfg, "cus_1", "pm_1", 2000, { userId: "u1", credits: 600 })).toEqual({ id: "pi_3", status: "failed", authRequired: false });
+  });
+
+  test("a transient/transport failure THROWS (it may recover)", async () => {
+    const { cfg } = mockStripe({ "POST payment_intents": { status: 500, body: { error: { message: "stripe down" } } } });
+    await expect(chargeOffSession(cfg, "cus_1", "pm_1", 2000, { userId: "u1", credits: 600 })).rejects.toThrow("stripe down");
+  });
+});
+
+describe("subscriptions: ceilingFor (pure paid-ceiling math)", () => {
+  test("honours a stored ceiling only when its End matches this cycle; else falls back to the current price", () => {
+    const meta = { cycleCeilingCents: "3000", cycleCeilingEnd: "100" };
+    expect(ceilingFor(meta, 100, 1000)).toBe(3000); // same cycle → the higher paid ceiling stands
+    expect(ceilingFor(meta, 200, 1000)).toBe(1000); // different cycle → reset to current price
+    expect(ceilingFor(undefined, 100, 1000)).toBe(1000); // no metadata → current price
+    expect(ceilingFor({ cycleCeilingCents: "500", cycleCeilingEnd: "100" }, 100, 1000)).toBe(1000); // max(500,1000)
+  });
+
+  test("planById / planByPrice resolve against the injected catalog", () => {
+    expect(planById(PLANS, "pro")).toBe(PRO);
+    expect(planById(PLANS, "nope")).toBeUndefined();
+    expect(planByPrice(PLANS, 1000)).toBe(STARTER);
+    expect(planByPrice(PLANS, 999)).toBeUndefined();
+  });
+});
+
+describe("subscriptions: pricing + status + change", () => {
+  test("ensurePlanPrice REUSES an existing lookup_key price (no product/price create)", async () => {
+    const { cfg, calls } = mockStripe({ "GET prices": { body: { data: [{ id: "price_existing" }] } } });
+    expect(await ensurePlanPrice(cfg, PRO, TF)).toBe("price_existing");
+    expect(calls.length).toBe(1); // only the GET — no product/price POST
+    expect(calls[0].path).toContain("lookup_keys[0]=tf_pro_3000_700_m"); // literal brackets in the GET path
+  });
+
+  test("ensurePlanPrice CREATES product + price when none is found", async () => {
+    const { cfg, calls } = mockStripe({
+      "GET prices": { body: { data: [] } },
+      "POST products": { body: { id: "prod_1" } },
+      "POST prices": { body: { id: "price_new" } },
+    });
+    expect(await ensurePlanPrice(cfg, PRO, TF)).toBe("price_new");
+    expect(calls.map((c) => `${c.method} ${c.path.split("?")[0]}`)).toEqual(["GET prices", "POST products", "POST prices"]);
+  });
+
+  test("getSubscriptionStatus maps a live sub; returns null for a non-live one", async () => {
+    const live = mockStripe({ "GET subscriptions/sub_1": { body: { status: "active", cancel_at_period_end: false, current_period_end: 1000, items: { data: [{ price: { unit_amount: 3000 } }] }, metadata: { planId: "pro" } } } });
+    expect(await getSubscriptionStatus(live.cfg, "sub_1", PLANS)).toEqual({ planId: "pro", status: "active", currentPeriodEnd: 1_000_000, cancelAtPeriodEnd: false, paidCeilingCents: 3000 });
+    const dead = mockStripe({ "GET subscriptions/sub_1": { body: { status: "canceled" } } });
+    expect(await getSubscriptionStatus(dead.cfg, "sub_1", PLANS)).toBeNull();
+  });
+
+  test("changeSubscriptionPlan: ABOVE the ceiling = an upgrade (always_invoice + a 3DS clientSecret)", async () => {
+    const { cfg, calls } = mockStripe({
+      "GET subscriptions/sub_1": { body: { status: "active", cancel_at_period_end: false, current_period_end: 1000, items: { data: [{ id: "si_1", price: { unit_amount: 1000 } }] }, metadata: { planId: "starter" } } },
+      "GET prices": { body: { data: [{ id: "price_pro" }] } },
+      "POST subscriptions/sub_1": { body: { id: "sub_1", latest_invoice: { status: "open", confirmation_secret: { client_secret: "pi_up_secret" } } } },
+    });
+    const r = await changeSubscriptionPlan(cfg, "sub_1", PRO, "u1", PLANS, TF);
+    expect(r).toEqual({ kind: "upgrade", clientSecret: "pi_up_secret", currentPeriodEnd: 1_000_000 });
+    const post = calls.find((c) => c.method === "POST" && c.path === "subscriptions/sub_1")!;
+    expect(post.body).toContain("proration_behavior=always_invoice");
+    expect(post.body).toContain("payment_behavior=pending_if_incomplete");
+  });
+
+  test("changeSubscriptionPlan: AT/BELOW the ceiling = a deferred downgrade (proration none, no charge, no secret)", async () => {
+    const { cfg, calls } = mockStripe({
+      "GET subscriptions/sub_1": { body: { status: "active", cancel_at_period_end: false, current_period_end: 1000, items: { data: [{ id: "si_1", price: { unit_amount: 3000 } }] }, metadata: { planId: "pro" } } },
+      "GET prices": { body: { data: [{ id: "price_starter" }] } },
+      "POST subscriptions/sub_1": { body: { id: "sub_1", latest_invoice: { status: "paid" } } },
+    });
+    const r = await changeSubscriptionPlan(cfg, "sub_1", STARTER, "u1", PLANS, TF);
+    expect(r).toEqual({ kind: "downgrade", clientSecret: null, currentPeriodEnd: 1_000_000 });
+    const post = calls.find((c) => c.method === "POST" && c.path === "subscriptions/sub_1")!;
+    expect(post.body).toContain("proration_behavior=none");
+  });
+
+  test("createSubscriptionOnDefaultCard charges the saved card; null when there's none", async () => {
+    const ok = withDefaultCard({
+      "GET prices": { body: { data: [{ id: "price_pro" }] } },
+      "POST subscriptions": { body: { id: "sub_new", latest_invoice: { confirmation_secret: { client_secret: "sub_secret" } } } },
+    });
+    expect(await createSubscriptionOnDefaultCard(ok.cfg, "cus_1", PRO, "u1", TF)).toEqual({ clientSecret: "sub_secret", subscriptionId: "sub_new" });
+
+    const noCard = mockStripe({ "GET payment_methods": { body: { data: [] } }, "GET customers/cus_1": { body: { invoice_settings: {} } } });
+    expect(await createSubscriptionOnDefaultCard(noCard.cfg, "cus_1", PRO, "u1", TF)).toBeNull();
+  });
+});

package/test/billing.test.ts

@@ -0,0 +1,87 @@
+import { test, expect, describe } from "bun:test";
+import {
+  createCustomer, createSetupIntent, listPaymentMethods, setDefaultPaymentMethod, detachPaymentMethod,
+  stripePost, toForm, type StripeConfig,
+} from "../src/index";
+
+/**
+ * C046 — @suluk/billing v1, witnessed with a MOCK fetch (the injected transport seam). We assert the right Stripe request
+ * (path + method + auth header + form body) and the response handling — no live Stripe, no effect dep.
+ */
+interface Call {
+  path: string;
+  method: string;
+  body: string;
+  headers: Record<string, string>;
+}
+type Route = { status?: number; body: unknown };
+function mockStripe(routes: Record<string, Route>): { cfg: StripeConfig; 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 { cfg: { secretKey: "sk_test", fetch: fetchMock }, calls };
+}
+
+describe("the transport seam", () => {
+  test("POSTs to Stripe with the bearer auth + form body; passes the idempotency-key when given", async () => {
+    const { cfg, calls } = mockStripe({ "POST refunds": { body: { id: "re_1" } } });
+    await stripePost(cfg, "refunds", toForm({ charge: "ch_1", amount: 500 }), "scope:ch_1");
+    expect(calls[0].method).toBe("POST");
+    expect(calls[0].path).toBe("refunds");
+    expect(calls[0].headers.authorization).toBe("Bearer sk_test");
+    expect(calls[0].headers["idempotency-key"]).toBe("scope:ch_1");
+    expect(calls[0].body).toContain("charge=ch_1");
+    expect(calls[0].body).toContain("amount=500");
+  });
+});
+
+describe("customer + intent creation", () => {
+  test("createCustomer returns the id and sends email + metadata", async () => {
+    const { cfg, calls } = mockStripe({ "POST customers": { body: { id: "cus_1" } } });
+    expect(await createCustomer(cfg, "a@b.com", "user_1")).toBe("cus_1");
+    expect(calls[0].body).toContain("email=a%40b.com");
+    expect(calls[0].body).toContain("metadata%5BuserId%5D=user_1"); // metadata[userId]=user_1
+  });
+
+  test("createSetupIntent returns the client secret", async () => {
+    const { cfg } = mockStripe({ "POST setup_intents": { body: { client_secret: "si_secret_1" } } });
+    expect(await createSetupIntent(cfg, "cus_1", "user_1")).toBe("si_secret_1");
+  });
+
+  test("a Stripe error throws with the error message", async () => {
+    const { cfg } = mockStripe({ "POST customers": { status: 402, body: { error: { message: "card declined" } } } });
+    await expect(createCustomer(cfg, "a@b.com", "user_1")).rejects.toThrow("card declined");
+  });
+});
+
+describe("the saved-card surface", () => {
+  test("listPaymentMethods maps the wire shape + marks the invoice default", async () => {
+    const { cfg } = mockStripe({
+      "GET payment_methods": { body: { data: [{ id: "pm_1", card: { brand: "visa", last4: "4242", exp_month: 12, exp_year: 2030 }, billing_details: { name: "A B", address: { line1: "1 St", city: "SF", state: "CA", postal_code: "94000", country: "US" } } }] } },
+      "GET customers/cus_1": { body: { invoice_settings: { default_payment_method: "pm_1" } } },
+    });
+    const cards = await listPaymentMethods(cfg, "cus_1");
+    expect(cards).toEqual([{ id: "pm_1", brand: "visa", last4: "4242", expMonth: 12, expYear: 2030, name: "A B", line1: "1 St", line2: null, city: "SF", region: "CA", postalCode: "94000", country: "US", isDefault: true }]);
+  });
+
+  test("setDefaultPaymentMethod posts the nested invoice_settings; detach hits the detach path", async () => {
+    const setMock = mockStripe({ "POST customers/cus_1": { body: { id: "cus_1" } } });
+    await setDefaultPaymentMethod(setMock.cfg, "cus_1", "pm_9");
+    expect(setMock.calls[0].body).toContain("invoice_settings%5Bdefault_payment_method%5D=pm_9");
+
+    const detachMock = mockStripe({ "POST payment_methods/pm_9/detach": { body: { id: "pm_9" } } });
+    await detachPaymentMethod(detachMock.cfg, "pm_9");
+    expect(detachMock.calls[0].path).toBe("payment_methods/pm_9/detach");
+  });
+
+  test("a failed set-default throws", async () => {
+    const { cfg } = mockStripe({ "POST customers/cus_1": { status: 400, body: {} } });
+    await expect(setDefaultPaymentMethod(cfg, "cus_1", "pm_9")).rejects.toThrow(/set-default failed/);
+  });
+});

package/tsconfig.json

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