@volter/twin-stripe 2.0.22 → 2.0.23

package/dist/src/semantics/renewals.d.ts

@@ -1,4 +1,4 @@
-import type { SemanticsContext } from '@volter/world-core';
+import { type SemanticsContext } from '@volter/world-core';
 import { type Row } from './shared.js';
 /** A customer's now: its test clock's frozen time when it is on one (docs.stripe.com/billing/testing/test-clocks), the
  *  World's otherwise. */

package/dist/src/semantics/renewals.js

@@ -1,3 +1,29 @@
+// A subscription's invoices over time: the first one Checkout pays, and each renewal. Time's moves are made
+// as the twin's trial end already made them: caught up to the customer's clock (the World's, or its test
+// clock) whenever the twin is asked anything (../stripe-server.ts), each checked against the machines in
+// ../manifest.ts.
+//
+// - Checkout's subscription session pays the first invoice with the card the customer entered, which becomes the
+//   subscription's default payment method (docs.stripe.com/payments/checkout/how-checkout-works); nothing is due
+//   on a trial's.
+// - At each period's end Stripe drafts a `subscription_cycle` invoice for the next period and advances the
+//   period; a trial's end is the first such renewal, and the subscription is active from then
+//   (docs.stripe.com/billing/subscriptions/overview#how-payments-work-subscriptions,
+//   docs.stripe.com/billing/subscriptions/trials).
+// - About an hour after, Stripe finalizes the draft and charges the subscription's default payment method,
+//   else the customer's (docs.stripe.com/invoicing/integration/workflow-transitions#finalized,
+//   docs.stripe.com/api/subscriptions/object#subscription_object-default_payment_method).
+// - A declined renewal leaves the invoice open with its attempt counted and the subscription past_due
+//   (docs.stripe.com/billing/subscriptions/overview#payment-status); paying the invoice later, through the API
+//   (docs.stripe.com/api/invoices/pay) or on the customer portal (docs.stripe.com/customer-management), makes it
+//   active again.
+//
+// Where the documentation stops and the twin decides: Stripe retries a failed renewal on its Smart Retries
+// schedule and may then cancel or mark the subscription unpaid; the twin makes no retry (next_payment_attempt
+// is null) and leaves it past_due until the invoice is paid. A paused subscription (pause_collection) is not renewed.
+// - One set to cancel at its period's end is canceled when the period ends, with no renewal
+//   (docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle).
+import { runAsVendorMove } from '@volter/world-core';
 import { addBillingInterval, applyCouponDiscount, declineFor, mintClientSecret, priceAmount, resolveSubscriptionBillingInterval } from "../stripe-twin.js";
 import { finalizedFields } from "./invoices.js";
 import { mintCharge } from "./payment-intents.js";
@@ -195,6 +221,10 @@ export async function payOpenInvoice(ctx, invoiceId, paymentMethod) {
  *  moment it was due: a period that ended renews (a trial's end among them) or, set to cancel, cancels; a renewal
  *  drafted an hour or more ago is finalized and charged. */
 export async function advanceBilling(ctx, only) {
+    // the billing clock is the vendor's own move, wherever a handler reaches it: never the request's caller's
+    return runAsVendorMove(() => advanceBillingDue(ctx, only));
+}
+async function advanceBillingDue(ctx, only) {
     const at = at_(ctx);
     for (let guard = 0; guard < 10_000 && (await billingStep(ctx, at, only)); guard++)
         ;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-stripe",
-  "version": "2.0.22",
+  "version": "2.0.23",
   "description": "Local Stripe twin — a faithful, stateful local Stripe API your real `stripe` SDK talks to unmodified. Mirror, simulate, and fork. Built on @volter/world-core.",
   "keywords": [
     "twin",
@@ -56,15 +56,15 @@
     "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
   },
   "dependencies": {
-    "@volter/world-ui": "0.1.21",
+    "@volter/world-ui": "0.1.22",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.21"
+    "@volter/world-core": "2.0.22"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.21",
+    "@volter/world-core": "2.0.22",
     "@volter/world-tooling": "0.1.0",
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",

package/src/semantics/renewals.ts

@@ -23,7 +23,7 @@
 // is null) and leaves it past_due until the invoice is paid. A paused subscription (pause_collection) is not renewed.
 // - One set to cancel at its period's end is canceled when the period ends, with no renewal
 //   (docs.stripe.com/billing/subscriptions/cancel#cancel-at-end-of-cycle).
-import type { SemanticsContext } from '@volter/world-core';
+import { runAsVendorMove, type SemanticsContext } from '@volter/world-core';
 import { addBillingInterval, applyCouponDiscount, declineFor, mintClientSecret, priceAmount, resolveSubscriptionBillingInterval } from '../stripe-twin.ts';
 import { finalizedFields } from './invoices.ts';
 import { mintCharge } from './payment-intents.ts';
@@ -227,6 +227,11 @@ export async function payOpenInvoice(ctx: SemanticsContext, invoiceId: string, p
  *  moment it was due: a period that ended renews (a trial's end among them) or, set to cancel, cancels; a renewal
  *  drafted an hour or more ago is finalized and charged. */
 export async function advanceBilling(ctx: SemanticsContext, only?: (sub: Row) => boolean): Promise<void> {
+  // the billing clock is the vendor's own move, wherever a handler reaches it: never the request's caller's
+  return runAsVendorMove(() => advanceBillingDue(ctx, only));
+}
+
+async function advanceBillingDue(ctx: SemanticsContext, only?: (sub: Row) => boolean): Promise<void> {
   const at = at_(ctx);
   for (let guard = 0; guard < 10_000 && (await billingStep(ctx, at, only)); guard++);
 }