reveclicat 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project are documented here. Format based on [Keep a
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-08-29
+
+### Added
+- Stripe in the generator: `--store stripe` / `subscriber.store: stripe` — constant `si_…` transaction id, `prod_…` product id default, `renewal_number` on every event, `BILLING_ISSUE` with the period pre-extended and `grace_period_expiration_at_ms: null`, recovery `RENEWAL` that does not re-extend, Stripe money fields (commission 0, takehome 1), `country_code: null`. `UNCANCELLATION` and `TEST` are rejected for Stripe with a store-specific message (official compatibility table). All rules derived from a real captured lifecycle (`test/fixtures/events/real/*.stripe.json`). New example `scenarios/stripe-billing-issue-recovers.yaml`. (T-080–T-083)
+- State machine: `legalEvents(state, store)` / `transition(..., { store })` — legality now has a store dimension. (T-082)
+
+### Changed
+- `RENEWAL` is now legal from `cancelled_pending_expiration` (recovery after a `BILLING_ERROR` cancellation, as observed in real Stripe traffic and described for App Store in the official flows). (T-082)
+
 ## [0.2.0] — 2026-08-29
 
 ### Added
@@ -49,7 +58,8 @@ First release. Unofficial project — not affiliated with RevenueCat, Inc.
 - Consistent error output: every error prints `✖ message` + `→ hint`; usage errors (unknown command/option, missing argument) exit with code 2, other failures with 1; `RCC_DEBUG=1` shows stack traces; `NO_COLOR` honoured. (T-052)
 - Programmatic API (`reveclicat` package): schemas, `Subscriber`, `runScenario`, `loadScenario`, `VirtualClock`, `createRng`.
 
-[Unreleased]: https://github.com/RadW2020/ReveCliCat/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/RadW2020/ReveCliCat/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/RadW2020/ReveCliCat/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/RadW2020/ReveCliCat/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/RadW2020/ReveCliCat/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/RadW2020/ReveCliCat/releases/tag/v0.1.0

package/README.md

@@ -94,7 +94,7 @@ subscriber:                          # all optional
   period: P1M                        # ISO-8601 duration
   trial: P1W                         # omit → no trial
   grace_period: P16D                 # billing-retry window after BILLING_ISSUE
-  store: app_store                   # app_store | play_store (Google-shaped ids and product_id format)
+  store: app_store                   # app_store | play_store | stripe (store-shaped ids, defaults and legal events)
   environment: SANDBOX               # SANDBOX | PRODUCTION
 steps:
   - event: INITIAL_PURCHASE          # starts the trial (period_type: TRIAL, price 0)
@@ -115,7 +115,7 @@ expect:
 
 Rules: a step is exactly one of `event` or `advance`; unknown keys are errors; validation errors point at `file:line:column`. Illegal transitions stop the run with the step number and the list of legal events. `EXPIRATION` is only allowed once the virtual clock has reached `expiration_at_ms` (or the end of the grace period) — the error tells you exactly how much to `advance`.
 
-Shipped examples (`rcc init` copies them): `trial-converts`, `trial-churns`, `billing-issue-recovers`, `billing-issue-churns`, `cancel-then-uncancel`, `happy-year` (12 renewals), `play-trial-converts` (Google Play ids).
+Shipped examples (`rcc init` copies them): `trial-converts`, `trial-churns`, `billing-issue-recovers`, `billing-issue-churns`, `cancel-then-uncancel`, `happy-year` (12 renewals), `play-trial-converts` (Google Play ids), `stripe-billing-issue-recovers` (Stripe dunning flow).
 
 ## CI
 
@@ -174,7 +174,7 @@ none ──INITIAL_PURCHASE──▶ trial ──RENEWAL (conversion)──▶ a
 ## Fidelity & scope
 
 - Schemas, enums and inclusion rules come from the official docs (fetched 2026-08-29) and the official sample payloads are used as test fixtures. The `TEST` event has no published sample, so its schema is marked *provisional* — a captured real one is very welcome (see `docs/BACKLOG.md`, T-004).
-- The generator models **App Store** (`--store app_store`, 16-digit transaction ids, original kept across resubscriptions) and **Google Play** (`--store play_store`, `GPA.…` order ids with `..N` renewal suffixes, `<subscription_id>:<base_plan_id>` product ids, new order on resubscription). Stripe, Amazon and Roku, a built-in tunnel, a web UI and hosted mode are intentionally out of scope (see the Icebox in `docs/BACKLOG.md`). Receivers accept events from every store.
+- The generator models **App Store** (`--store app_store`, 16-digit transaction ids, original kept across resubscriptions), **Google Play** (`--store play_store`, `GPA.…` order ids with `..N` renewal suffixes, `<subscription_id>:<base_plan_id>` product ids, new order on resubscription) and **Stripe** (`--store stripe`, one `si_…` id for the whole subscription, `prod_…` product ids, `renewal_number`, billing issues with the period pre-extended and no grace field, no `UNCANCELLATION`/`TEST` — all taken from real captured events). Amazon, Roku and RevenueCat Billing, a built-in tunnel, a web UI and hosted mode are intentionally out of scope (see the Icebox in `docs/BACKLOG.md`). Receivers accept events from every store.
 - Programmatic use: `import { runScenario, Subscriber, WebhookEnvelopeSchema } from "reveclicat"`.
 
 ## How this was built

package/dist/cli.js

@@ -9,7 +9,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "reveclicat",
-  version: "0.2.0",
+  version: "0.3.0",
   description: "Unofficial CLI to simulate RevenueCat subscription lifecycles and test webhooks locally and in CI. Not affiliated with RevenueCat, Inc.",
   type: "module",
   license: "MIT",
@@ -165,9 +165,17 @@ var CANCEL_REASONS = [
   "UNKNOWN"
 ];
 var EXPIRATION_REASONS = [...CANCEL_REASONS, "SUBSCRIPTION_PAUSED"];
-var CLI_STORES = ["app_store", "play_store"];
-var CLI_STORE_TO_STORE = { app_store: "APP_STORE", play_store: "PLAY_STORE" };
-var DEFAULT_PRODUCT_ID = { app_store: "com.example.premium.monthly", play_store: "com.example.premium:monthly" };
+var CLI_STORES = ["app_store", "play_store", "stripe"];
+var CLI_STORE_TO_STORE = { app_store: "APP_STORE", play_store: "PLAY_STORE", stripe: "STRIPE" };
+var DEFAULT_PRODUCT_ID = {
+  app_store: "com.example.premium.monthly",
+  play_store: "com.example.premium:monthly",
+  stripe: "prod_RccPremiumMonthly"
+};
+var UNSUPPORTED_EVENTS_BY_STORE = {
+  stripe: ["UNCANCELLATION", "TEST"]
+};
+var STORE_LABEL = { app_store: "App Store", play_store: "Google Play", stripe: "Stripe" };
 
 // src/core/config.ts
 var CONFIG_FILE = "reveclicat.config.json";
@@ -422,10 +430,11 @@ var IllegalTransitionError = class extends RccError {
   state;
   event;
   legal;
-  constructor(state, event) {
-    const legal = legalEvents(state);
+  constructor(state, event, store) {
+    const legal = legalEvents(state, store);
+    const unsupported = store !== void 0 && (UNSUPPORTED_EVENTS_BY_STORE[store] ?? []).includes(event);
     super(
-      `Illegal transition: cannot apply ${event} while the subscription is "${state}". Legal events from "${state}": ${legal.join(", ")}.`,
+      unsupported ? `${STORE_LABEL[store]} does not emit ${event} (RevenueCat store compatibility table). Legal events from "${state}" for ${STORE_LABEL[store]}: ${legal.join(", ")}.` : `Illegal transition: cannot apply ${event} while the subscription is "${state}". Legal events from "${state}": ${legal.join(", ")}.`,
       { hint: "Check the order of the steps in your scenario (e.g. a RENEWAL needs an INITIAL_PURCHASE first)." }
     );
     this.name = "IllegalTransitionError";
@@ -450,6 +459,9 @@ var TABLE = {
   },
   cancelled_pending_expiration: {
     UNCANCELLATION: (ctx) => ctx.resumeState,
+    // Real flows: recovery after a BILLING_ERROR cancellation (Stripe capture 2026-08-29); App Store "CANCELLATION
+    // followed by a RENEWAL" when cancelling <24 h before a trial ends (docs S4).
+    RENEWAL: () => "active",
     EXPIRATION: () => "expired"
   },
   billing_issue: {
@@ -459,13 +471,17 @@ var TABLE = {
   },
   expired: { INITIAL_PURCHASE: () => "active" }
 };
-function legalEvents(state) {
-  return [...Object.keys(TABLE[state]), "TEST"];
+function legalEvents(state, store) {
+  const excluded = store === void 0 ? [] : UNSUPPORTED_EVENTS_BY_STORE[store] ?? [];
+  return [...Object.keys(TABLE[state]), "TEST"].filter((e) => !excluded.includes(e));
 }
 function transition(state, event, ctx) {
+  if (ctx.store !== void 0 && (UNSUPPORTED_EVENTS_BY_STORE[ctx.store] ?? []).includes(event)) {
+    throw new IllegalTransitionError(state, event, ctx.store);
+  }
   if (event === "TEST") return state;
   const rule = TABLE[state][event];
-  if (!rule) throw new IllegalTransitionError(state, event);
+  if (!rule) throw new IllegalTransitionError(state, event, ctx.store);
   return rule(ctx);
 }
 
@@ -632,6 +648,8 @@ var Subscriber = class {
   cliStore;
   /** Play: number of renewals on the current order (drives the `..N` suffix). */
   renewalIndex = 0;
+  /** A BILLING_ISSUE is open (until a RENEWAL recovers it or the subscription expires). */
+  billingRetry = false;
   environment;
   price;
   currency;
@@ -656,7 +674,7 @@ var Subscriber = class {
   /** Emit an event: check legality, time guards, build + validate payload, commit state. */
   emit(type, overrides = {}) {
     const from = this._state;
-    const next = transition(from, type, { hasTrial: this.trial !== void 0, resumeState: this.resumeState });
+    const next = transition(from, type, { hasTrial: this.trial !== void 0, resumeState: this.resumeState, store: this.cliStore });
     const now = this.deps.clock.now();
     if (type === "EXPIRATION") {
       const due = Math.max(this.expirationAtMs ?? 0, from === "billing_issue" ? this.gracePeriodExpirationAtMs ?? 0 : 0);
@@ -679,6 +697,8 @@ var Subscriber = class {
       this.periodType = draft.periodType;
       this.gracePeriodExpirationAtMs = draft.gracePeriodExpirationAtMs;
       this.renewalIndex = draft.renewalIndex;
+      if (type === "BILLING_ISSUE") this.billingRetry = true;
+      if (type === "RENEWAL" || type === "EXPIRATION" || type === "INITIAL_PURCHASE") this.billingRetry = false;
       if (type === "CANCELLATION") this.resumeState = from === "trial" ? "trial" : "active";
       this._state = next;
     }
@@ -692,15 +712,23 @@ var Subscriber = class {
     for (let i = 0; i < n; i++) s += String(this.deps.rng.int(10));
     return s;
   }
-  /** A brand-new order/transaction id in the store's format (see specs/F7-google-play.md). */
+  alnum(n) {
+    const A = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+    let s = "";
+    for (let i = 0; i < n; i++) s += A[this.deps.rng.int(A.length)];
+    return s;
+  }
+  /** A brand-new order/transaction id in the store's format (specs/F7-google-play.md, specs/F8-stripe.md). */
   newTransactionId() {
+    if (this.cliStore === "stripe") return `si_${this.alnum(14)}`;
     if (this.cliStore === "play_store") {
       return `GPA.${this.digits(4)}-${this.digits(4)}-${this.digits(4)}-${this.digits(5)}`;
     }
     return String(1 + this.deps.rng.int(9)) + this.digits(15);
   }
-  /** Renewal id: Play appends `..N` to the original order id; App Store issues a fresh transaction id. */
+  /** Renewal id: Play appends `..N`; Stripe keeps the subscription item id; App Store issues a fresh transaction id. */
   renewalTransactionId(originalId, index) {
+    if (this.cliStore === "stripe" && originalId !== void 0) return originalId;
     if (this.cliStore === "play_store" && originalId !== void 0) return `${originalId}..${index}`;
     return this.newTransactionId();
   }
@@ -718,7 +746,7 @@ var Subscriber = class {
       case "INITIAL_PURCHASE": {
         const startsTrial = from === "none" && this.trial !== void 0;
         d.transactionId = this.newTransactionId();
-        if (this.cliStore === "play_store") d.originalTransactionId = d.transactionId;
+        if (this.cliStore !== "app_store") d.originalTransactionId = d.transactionId;
         else d.originalTransactionId ??= d.transactionId;
         d.renewalIndex = 0;
         d.purchasedAtMs = now;
@@ -728,8 +756,13 @@ var Subscriber = class {
         break;
       }
       case "RENEWAL": {
-        const start = d.expirationAtMs ?? now;
         d.transactionId = this.renewalTransactionId(d.originalTransactionId, d.renewalIndex);
+        if (this.cliStore === "stripe" && this.billingRetry) {
+          d.periodType = "NORMAL";
+          d.gracePeriodExpirationAtMs = null;
+          break;
+        }
+        const start = d.expirationAtMs ?? now;
         d.renewalIndex += 1;
         d.purchasedAtMs = start;
         d.expirationAtMs = addDuration(start, this.period);
@@ -738,7 +771,13 @@ var Subscriber = class {
         break;
       }
       case "BILLING_ISSUE":
-        d.gracePeriodExpirationAtMs = addDuration(now, this.grace);
+        if (this.cliStore === "stripe") {
+          d.expirationAtMs = addDuration(d.expirationAtMs ?? now, this.period);
+          d.renewalIndex += 1;
+          d.gracePeriodExpirationAtMs = null;
+        } else {
+          d.gracePeriodExpirationAtMs = addDuration(now, this.grace);
+        }
         break;
       case "TEST":
         if (from === "none") {
@@ -756,6 +795,7 @@ var Subscriber = class {
   buildPayload(type, from, now, d) {
     const isPurchase = type === "INITIAL_PURCHASE" || type === "RENEWAL" || type === "TEST";
     const price = isPurchase && d.periodType !== "TRIAL" ? this.price : 0;
+    const stripe = this.cliStore === "stripe";
     const payload = {
       type,
       id: this.deps.rng.uuid(),
@@ -776,16 +816,17 @@ var Subscriber = class {
       transaction_id: d.transactionId,
       original_transaction_id: d.originalTransactionId,
       is_family_share: false,
-      country_code: this.countryCode,
+      country_code: stripe ? null : this.countryCode,
       store: this.store,
       currency: this.currency,
       price,
       price_in_purchased_currency: price,
       tax_percentage: 0,
-      commission_percentage: 0.3,
-      takehome_percentage: 0.7,
+      commission_percentage: stripe ? 0 : 0.3,
+      takehome_percentage: stripe ? 1 : 0.7,
       offer_code: null
     };
+    if (stripe) payload["renewal_number"] = d.renewalIndex + 1;
     switch (type) {
       case "RENEWAL":
         payload["is_trial_conversion"] = from === "trial";