@crvouga/mockingbird-service-stripe 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog — @crvouga/mockingbird-service-stripe
 
+## 1.4.0 (2026-09-29)
+
+### Features
+
+- retry failed subscription renewals and apply the configured outcome ([c737a68](https://github.com/crvouga/mockingbird/commit/c737a6873a5e9b984b382b9f00c0b01f1712116c))
+
+### Fixes and improvements
+
+- validate list elements ahead of a schema issue in order ([5a09c88](https://github.com/crvouga/mockingbird/commit/5a09c880a432b4e13e2ef5b519a8a76962d372da))
+- answer a missing SetupIntent with Stripe's 404 resource_missing ([9e8368f](https://github.com/crvouga/mockingbird/commit/9e8368ff2d01303cf5ff5410afc3387c75163ca6))
+- leave the portal configuration list out of live parity walks ([9adfc89](https://github.com/crvouga/mockingbird/commit/9adfc89ed7dbe88d798724deaf9d9ccddea60800))
+- use --all-snapshot with Stripe CLI 1.52 in the webhook oracle ([d95804c](https://github.com/crvouga/mockingbird/commit/d95804cbdf98bcbd2199865dcdd13157d44b1d12))
+- pass --events to stripe listen so Stripe CLI 1.52 starts ([b31d3da](https://github.com/crvouga/mockingbird/commit/b31d3da44396f79630f21f732fd4fb2cc1d3fcc9))
+- report why stripe listen exited in the webhook oracle ([19461e4](https://github.com/crvouga/mockingbird/commit/19461e478a3d0489aac646820ecaad12b2d6ce2a))
+
+## 1.3.1 (2026-09-29)
+
+### Fixes and improvements
+
+- say 'No such configuration' for a missing portal configuration ([6fad72a](https://github.com/crvouga/mockingbird/commit/6fad72a676b359672653508d9dd654e656ac6aa1))
+- upper-case only two-letter country codes like the live API ([4ee5121](https://github.com/crvouga/mockingbird/commit/4ee5121cf2254fd75eef34bbeefee496cd16964a))
+- leave portal configuration listing out of live parity walks ([20d715a](https://github.com/crvouga/mockingbird/commit/20d715a548e60dd933fab52e7ba661870607049e))
+- keep the shipping address country verbatim like the live API ([052e285](https://github.com/crvouga/mockingbird/commit/052e285a0ae9bcc26050f1c50ed635085438c3d1))
+- use --all-snapshot so the Stripe CLI webhook oracle starts ([09809bf](https://github.com/crvouga/mockingbird/commit/09809bfcd106cc4570d74e781ab0619efb191e05))
+- listen for all events so newer Stripe CLIs start the webhook oracle ([278e364](https://github.com/crvouga/mockingbird/commit/278e364c77263d8cff65fb6d03fde9e89a1010ca))
+- surface redacted stripe listen output when the webhook oracle fails to start ([dd179bb](https://github.com/crvouga/mockingbird/commit/dd179bbdf7a0d38ba097f79041ec818eaf69dfc5))
+- sign and retry webhooks on the injected clock ([1091bde](https://github.com/crvouga/mockingbird/commit/1091bde0df69d9cc3eba2062d8523755e6caca14))
+
 ## 1.3.0 (2026-09-29)
 
 ### Features

package/README.md

@@ -86,7 +86,7 @@ the mock's hosted page.
 
 State is partitioned by **account**, and the account is chosen by API key:
 
-- `PUT /__admin/accounts {"accounts": [{id, keys, apiVersion?, webhookSecrets?, corpus?, displayName?}]}`
+- `PUT /__admin/accounts {"accounts": [{id, keys, apiVersion?, webhookSecrets?, corpus?, displayName?, billing?}]}`
   (also `createRuntime({accounts})` / `serve --accounts <json|file>`). Every key listed on an
   account acts as it. Any other test key is an account of its own (`accountOfKey(key)`), so an MSO
   key reading a PC object gets Stripe's exact `404 resource_missing` (`No such payment_intent: 'pi_…'`).
@@ -94,6 +94,8 @@ State is partitioned by **account**, and the account is chosen by API key:
   its webhook payloads render at (default `2024-06-20`, what every backend receiver of ours pins).
 - `webhookSecrets: {"<receiver url>": "whsec_…"}` delivers every event of the account there.
 - `corpus: true` seeds the recorded catalog (below).
+- `billing: {retries: {scheduleDays?, afterAllFail?}}` sets the account's failed-renewal retries
+  (see Lifecycles and the clock); unset fields use `createRuntime({lifecycle: {paymentRetries}})`.
 
 **Namespaces** isolate parallel workers; each namespace has its own copy of every account. Carriers:
 the `x-mockingbird-namespace` header, the `/ns/<namespace>/…` path prefix, or **by API key**:
@@ -118,7 +120,7 @@ holds, ancestors included); Stripe's own rules are enforced: a non-expandable fi
 
 Every state change records an event in the account's log (`GET /v1/events`, filterable by
 `types[]` and `created`) and publishes it through the shared webhook hub, signed
-`Stripe-Signature: t=<wall-clock unix>,v1=<hex HMAC-SHA256(secret, "t.body")>` over the exact bytes —
+`Stripe-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "t.body")>` over the exact bytes —
 `stripe.webhooks.constructEvent` verifies them.
 
 - Endpoints: `PUT /__admin/webhook-endpoints [{account, url, secret, enabledEvents: ["*"|…]}]`
@@ -126,6 +128,11 @@ Every state change records an event in the account's log (`GET /v1/events`, filt
   `serve --webhook-url/--webhook-secret`, accounts' `webhookSecrets`, and endpoints created through
   `POST /v1/webhook_endpoints` (signed with the `whsec_` returned at creation). One event fans out to
   every matching endpoint, as on Stripe. Retries follow the hub's schedule.
+- `t` is the wall clock, unless the runtime's `clock` is injected (`createRuntime({ clock })`):
+  then `t`, retries and the attempt timeout run on that clock, so a virtual-time suite verifies with
+  `constructEventAsync(body, sig, secret, tolerance, undefined, clock.now())` and sees a retry when it
+  advances the clock (`runtime.clock.advance`, or `runtime.tick()` after moving its own clock).
+  `webhooks: { now, schedule, cancel, id }` override the hub's sources directly.
 - `GET /__admin/webhooks`, `/webhooks/events`, `POST /__admin/webhooks/:id/replay`, `/webhooks/flush`.
 - Delivery faults: presets `webhook_duplicate` (same event id twice — our receiver's in-flight
   dedupe answers 500), `webhook_reorder` (the next two swapped), `webhook_drop` (never delivered,
@@ -166,6 +173,18 @@ clock-driven lifecycle, so their webhooks fire at once; the served mock also tic
   voided (`void`), marked `uncollectible` (`mark_uncollectible`, `invoice.marked_uncollectible`) or
   left as drafts (`keep_as_draft`), never charged; the status holds. `pause_collection[resumes_at]`
   lifts the pause on its own before the renewal it precedes; `pause_collection=""` lifts it now.
+- **Payment retries**: a declined renewal (`charge_automatically`) leaves the invoice `open` with
+  `attempt_count: 1` and `next_payment_attempt`, and the subscription `past_due`. Each retry
+  `scheduleDays` after the first failure (default `[3, 5, 7]`, Stripe's classic "3 retries over
+  1 week") charges again when the clock reaches it: a decline bumps `attempt_count`, emits
+  `invoice.payment_failed` and moves `next_payment_attempt`; a working default payment method pays
+  the invoice (`invoice.paid`) and the subscription is `active` again
+  (`customer.subscription.updated`). After the last retry `next_payment_attempt` is `null` and
+  `afterAllFail` applies: `cancel` (the default: `canceled`, `cancellation_details.reason:
+  payment_failed`, `customer.subscription.deleted`), `unpaid` (`customer.subscription.updated`) or
+  `past_due` (nothing changes). An empty schedule applies it at the first failure. The schedule is
+  fixed, not Stripe's ML-timed Smart Retries; set it per account (`billing.retries`, also
+  `PUT /__admin/accounts`) or for the runtime (`lifecycle.paymentRetries`). Dunning emails are not sent.
 - `incomplete` subscriptions become `incomplete_expired` after 23 h (their invoice is voided).
 - Checkout Sessions expire at `expires_at` (`checkout.session.expired`).
 - Schedule phases advance; the last one releases or cancels per `end_behavior`.
@@ -362,8 +381,6 @@ plus `port`, `host`; resolves `{url, port, runtime, close}`), `serveTarget` (the
   PaymentSheet cannot be redirected (member-app native keeps its fake provider).
 - **Connect** (`Stripe-Account`, application fees, transfers), tax, shipping, Radar, mandates,
   meters, quotes, credit notes, payouts, and non-card payment methods (bank debits, wallets).
-- **Smart retries / dunning**: a failed renewal goes `past_due` once; later automatic retries,
-  `unpaid` and dunning emails are not run.
 - **Proration arithmetic** is day-fraction approximate (Stripe prorates to the second);
   `auto_advance` drafts are not finalized an hour later.
 - **Customer portal extras**: the login page (`login_page.url` is not served), `schedule_at_period_end`

package/dist/{chunk-2WP3EV2W.js → chunk-P77GCNSW.js}

@@ -1559,7 +1559,7 @@ var restoreNamespace = (sqlite, namespace, snapshot) => {
 };
 
 // ../core/dist/version.js
-var PACKAGE_VERSION = true ? "1.3.0" : UNRELEASED_VERSION;
+var PACKAGE_VERSION = true ? "1.4.0" : UNRELEASED_VERSION;
 
 // ../core/dist/signing.js
 var encoder = new TextEncoder();
@@ -2583,6 +2583,27 @@ var eraOf = (version) => {
 };
 
 // src/accounts.ts
+var DEFAULT_PAYMENT_RETRIES = {
+  scheduleDays: [3, 5, 7],
+  afterAllFail: "cancel"
+};
+var RETRY_OUTCOMES = ["cancel", "unpaid", "past_due"];
+var validateRetries = (id, value) => {
+  const raw = value?.retries;
+  if (typeof value !== "object" || value === null || typeof raw !== "object" || raw === null)
+    return `${id}: billing must be {"retries": {"scheduleDays": [3, 5, 7], "afterAllFail": "cancel"}}`;
+  const { scheduleDays, afterAllFail } = raw;
+  if (scheduleDays !== void 0 && (!Array.isArray(scheduleDays) || scheduleDays.some(
+    (day, index) => typeof day !== "number" || !Number.isFinite(day) || day <= 0 || index > 0 && day <= scheduleDays[index - 1]
+  )))
+    return `${id}: billing.retries.scheduleDays must be increasing positive numbers of days`;
+  if (afterAllFail !== void 0 && !RETRY_OUTCOMES.includes(afterAllFail))
+    return `${id}: billing.retries.afterAllFail must be one of ${RETRY_OUTCOMES.join(", ")}`;
+  return {
+    ...scheduleDays !== void 0 ? { scheduleDays } : {},
+    ...afterAllFail !== void 0 ? { afterAllFail } : {}
+  };
+};
 var DEFAULT_WEBHOOK_API_VERSION = "2024-06-20";
 var KEY = /^(?:sk|rk|pk)_(?:test|live)_[A-Za-z0-9_]+$/;
 var validateAccounts = (value) => {
@@ -2607,8 +2628,11 @@ var validateAccounts = (value) => {
     const secrets = raw.webhookSecrets;
     if (secrets !== void 0 && (typeof secrets !== "object" || secrets === null || Object.values(secrets).some((secret) => typeof secret !== "string")))
       return `${raw.id}: webhookSecrets must map receiver URLs to whsec_ secrets`;
+    const retries = raw.billing === void 0 ? void 0 : validateRetries(raw.id, raw.billing);
+    if (typeof retries === "string") return retries;
     accounts.push({
       id: raw.id,
+      ...retries ? { billing: { retries } } : {},
       keys: raw.keys,
       ...typeof raw.apiVersion === "string" ? { apiVersion: raw.apiVersion } : {},
       ...secrets ? { webhookSecrets: secrets } : {},
@@ -4875,11 +4899,19 @@ var activateAfterPayment = (scope, subscriptionId, intent) => {
 };
 var markPaymentFailed = (scope, invoice) => {
   const now = customerNow(scope, invoice.customer);
+  const attempts = invoice.attempt_count + 1;
+  let next = now + 3 * DAY;
+  if (invoice.subscription !== null) {
+    const days = scope.services.paymentRetries(scope.account.account).scheduleDays;
+    const first = attempts === 1 || invoice.next_payment_attempt === null ? now : invoice.next_payment_attempt - (days[attempts - 2] ?? 0) * DAY;
+    const day = days[attempts - 1];
+    next = day === void 0 ? null : first + day * DAY;
+  }
   const failed = {
     ...invoice,
-    attempt_count: invoice.attempt_count + 1,
+    attempt_count: attempts,
     attempted: true,
-    next_payment_attempt: now + 3 * DAY
+    next_payment_attempt: next
   };
   scope.account.invoices.update(failed.id, failed);
   scope.emit("invoice.payment_failed", renderInvoice(failed, scope.account));
@@ -5315,12 +5347,15 @@ var cycleSubscription = (scope, current) => {
   });
   claimInvoiceItems(scope, invoice);
   let status = moved.status;
+  let exhausted = false;
   if (!keepDraft) {
     const finalized = finalizeInvoice(scope, invoice);
     const collected = collectCycleInvoice(scope, current, finalized);
     invoice = collected.invoice;
-    if (finalized.status === "open" && current.pause_collection === null && finalized.collection_method === "charge_automatically")
+    if (finalized.status === "open" && current.pause_collection === null && finalized.collection_method === "charge_automatically") {
       status = collected.failed ? "past_due" : "active";
+      exhausted = collected.failed && invoice.attempt_count > 0 && invoice.next_payment_attempt === null;
+    }
   }
   const latest = scope.account.subscriptions.get(current.id) ?? moved;
   const next = {
@@ -5334,6 +5369,33 @@ var cycleSubscription = (scope, current) => {
   const after = renderSubscription(next, scope.account);
   const changed = changedFields(before, after);
   scope.emit("customer.subscription.updated", after, changed);
+  if (exhausted) applyFailedPaymentOutcome(scope, next);
+};
+var applyFailedPaymentOutcome = (scope, current) => {
+  const outcome = scope.services.paymentRetries(scope.account.account).afterAllFail;
+  if (outcome === "cancel") cancelSubscription(scope, current, "payment_failed");
+  else if (outcome === "unpaid") saveSubscription(scope, current, { ...current, status: "unpaid" });
+};
+var retryDueInvoices = (scope, subscription, now) => {
+  for (let guard2 = 0; guard2 < 50; guard2 += 1) {
+    const due = scope.account.invoices.list({
+      order: "oldest",
+      where: (invoice) => invoice.subscription === subscription.id && invoice.status === "open" && invoice.collection_method === "charge_automatically" && invoice.next_payment_attempt !== null && invoice.next_payment_attempt <= now
+    })[0]?.value;
+    if (due === void 0) return;
+    let settled;
+    try {
+      settled = payInvoice(scope, due, { offSession: true });
+    } catch (error) {
+      if (!(error instanceof StripeError)) throw error;
+      settled = scope.account.invoices.get(due.id) ?? due;
+    }
+    const current = scope.account.subscriptions.get(subscription.id);
+    if (settled.status !== "open" || current === void 0) return;
+    if (settled.next_payment_attempt === due.next_payment_attempt) return;
+    if (settled.next_payment_attempt === null) applyFailedPaymentOutcome(scope, current);
+    if (settled.next_payment_attempt === null || current.status !== "past_due") return;
+  }
 };
 var periodAmount = (scope, subscription, at) => {
   const lines = subscriptionItems(scope, subscription).map((item) => {
@@ -5744,7 +5806,8 @@ var releaseSchedule = (scope, schedule, now) => {
 var DEFAULT_LIFECYCLE = {
   upcomingInvoiceDays: 3,
   trialWillEndDays: 3,
-  incompleteExpiryHours: 23
+  incompleteExpiryHours: 23,
+  paymentRetries: DEFAULT_PAYMENT_RETRIES
 };
 var runLifecycle = (scope, settings, onlyCustomers) => {
   const inScope = (customer) => onlyCustomers === void 0 ? customer === null || !findCustomer(scope, customer)?.test_clock : customer !== null && onlyCustomers.has(customer);
@@ -5778,6 +5841,10 @@ var runLifecycle = (scope, settings, onlyCustomers) => {
       );
     }
     for (let guard2 = 0; guard2 < 120; guard2 += 1) {
+      if (subscription.status === "past_due") {
+        retryDueInvoices(scope, subscription, now2);
+        subscription = scope.account.subscriptions.get(subscription.id) ?? subscription;
+      }
       if (!["active", "trialing", "past_due"].includes(subscription.status)) break;
       const cancelAt = subscription.cancel_at;
       if (cancelAt !== null && cancelAt <= now2) {
@@ -6461,7 +6528,13 @@ var parseParams = (schema, raw, options = {}) => {
       if (error) throw error;
     }
     const issue = issues[0];
-    if (issue) throw issueToError(issue);
+    if (issue) {
+      const failing = /^[^[]+\[(\d+)\]/.exec(issue.path)?.[1];
+      const list = params[key];
+      if (failing !== void 0 && Number(failing) > 0 && Array.isArray(list))
+        options.validate?.[key]?.({ ...params, [key]: list.slice(0, Number(failing)) });
+      throw issueToError(issue);
+    }
     options.validate?.[key]?.(params);
   }
   const stray = parsed.issues[0];
@@ -7184,7 +7257,7 @@ var loginPageOf = (scope, raw, base2, id) => {
 var requireConfiguration = (scope, id, param = "configuration") => {
   if (!scope.account.portalConfigurations.get(id)) ensureDefaultConfiguration(scope);
   const config = scope.account.portalConfigurations.get(id);
-  if (!config) throw resourceMissing("billing portal configuration", id, param);
+  if (!config) throw resourceMissing("configuration", id, param);
   return config;
 };
 var flowSubscription = (scope, customer, id, param) => {
@@ -7314,14 +7387,13 @@ var billingPortalHandlers = (services) => ({
   GetBillingPortalConfigurations: async (context) => {
     const scope = requestScope(services, context);
     const params = queryParams(context);
-    ensureDefaultConfiguration(scope);
     const active = booleanOf(params.active);
     const isDefault = booleanOf(params.is_default);
     return jsonRes(
       200,
       await paginate(scope.account.portalConfigurations, params, {
         url: "/v1/billing_portal/configurations",
-        kind: "billing portal configuration",
+        kind: "configuration",
         where: (config) => (active === void 0 || config.active === active) && (isDefault === void 0 || config.is_default === isDefault),
         render: (config) => renderConfiguration(scope, config)
       })
@@ -9852,7 +9924,7 @@ var paymentIntentHandlers = (services) => {
 // src/setup-intents.ts
 var requireSetupIntent = (scope, id) => {
   const intent = scope.account.setupIntents.get(id);
-  if (!intent) throw invalidRequest(`No such setup_intent: '${id}'`, "intent", "resource_missing");
+  if (!intent) throw resourceMissing("setupintent", id, "intent");
   return intent;
 };
 var confirmSetup = (scope, intent, method, autoAuthenticate = false) => {
@@ -10891,7 +10963,7 @@ var toAddress = (raw) => {
   const out = {};
   for (const key of ADDRESS_KEYS) {
     const value = input[key];
-    out[key] = value === void 0 ? null : key === "country" ? value.replace(/[a-z]/g, (letter) => letter.toUpperCase()) : value;
+    out[key] = value === void 0 ? null : key === "country" && /^[A-Za-z]{2}$/.test(value) ? value.toUpperCase() : value;
   }
   return out;
 };
@@ -16428,6 +16500,29 @@ var reshapeQaCommand = (command, _state, rng) => {
   return withBody(command, next);
 };
 
+// src/webhook-timers.ts
+var createClockTimers = (clock) => {
+  const timers = /* @__PURE__ */ new Set();
+  return {
+    schedule(callback, delayMs) {
+      const timer = { due: clock.now() + delayMs, callback };
+      timers.add(timer);
+      return timer;
+    },
+    cancel(handle) {
+      timers.delete(handle);
+    },
+    run() {
+      const now = clock.now();
+      const due = [...timers].filter((timer) => timer.due <= now).sort((a, b) => a.due - b.due);
+      for (const timer of due) {
+        if (!timers.delete(timer)) continue;
+        timer.callback();
+      }
+    }
+  };
+};
+
 // src/runtime.ts
 var RATE_LIMITED = {
   error: {
@@ -16542,10 +16637,18 @@ var guard = (run) => {
 };
 var createRuntime2 = (options = {}) => {
   const accounts = new AccountDirectory(options.accounts ?? []);
+  const baseClock = options.clock ?? createClock();
+  const timers = options.clock ? createClockTimers(options.clock) : void 0;
   const hub = createWebhookHub({
     signer: signers.timestamped("Stripe-Signature"),
     ...options.webhooks?.retryDelaysMs ? { retryDelaysMs: options.webhooks.retryDelaysMs } : {},
     ...options.webhooks?.fetch ? { fetch: options.webhooks.fetch } : {},
+    ...options.clock ? { now: () => baseClock.now() } : {},
+    ...options.webhooks?.now ? { now: options.webhooks.now } : {},
+    ...timers ? { schedule: timers.schedule, cancel: timers.cancel } : {},
+    ...options.webhooks?.schedule ? { schedule: options.webhooks.schedule } : {},
+    ...options.webhooks?.cancel ? { cancel: options.webhooks.cancel } : {},
+    ...options.webhooks?.id ? { id: options.webhooks.id } : {},
     endpoints: options.webhooks?.endpoints ?? []
   });
   let runtimeRef;
@@ -16607,8 +16710,8 @@ var createRuntime2 = (options = {}) => {
       else syncEndpoints(namespace);
     }
   };
-  const baseClock = options.clock ?? createClock();
   const tickAll = () => {
+    timers?.run();
     if (!runtimeRef) return;
     for (const name of runtimeRef.namespaces()) runtimeRef.instance(name).tick(true);
   };
@@ -16912,6 +17015,10 @@ var StripeAPI = class {
       publish: options.onWebhook,
       accounts,
       deliveryVersion: (account) => accounts.config(account)?.apiVersion ?? webhookVersion,
+      paymentRetries: (account) => ({
+        ...this.settings.paymentRetries,
+        ...accounts.config(account)?.billing?.retries
+      }),
       pendingWebhooks: options.pendingWebhooks ?? (() => 0),
       namespacePrefix: options.publicNamespace === void 0 || options.publicNamespace === "default" ? "" : `/ns/${encodeURIComponent(options.publicNamespace)}`,
       publicUrl: options.publicUrl,
@@ -17214,4 +17321,4 @@ export {
   createRuntime2 as createRuntime,
   StripeAPI
 };
-//# sourceMappingURL=chunk-2WP3EV2W.js.map
+//# sourceMappingURL=chunk-P77GCNSW.js.map