reveclicat 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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
+- Google Play in the generator: `--store play_store` / `subscriber.store: play_store` emit `store: PLAY_STORE`, `GPA.dddd-dddd-dddd-ddddd` order ids with `..N` renewal suffixes (Google's `Purchase.getOrderId` convention), a new order on resubscription, and the `<subscription_id>:<base_plan_id>` default product id. New example `scenarios/play-trial-converts.yaml` (`rcc init` now copies 7 scenarios). (T-071, T-072)
+
+### Changed
+- `product_id` no longer has a default in the scenario schema / `--product`; the per-store default is applied by the generator. Explicit values are unchanged. (T-071)
+
 ## [0.1.1] — 2026-08-29
 
 ### Fixed
@@ -41,6 +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.1.1...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                   # v0.1: app_store only
+  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).
+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).
-- v0.1 models the **App Store** only. Google Play, Stripe, Amazon and Roku stores, a built-in tunnel, a web UI and hosted mode are intentionally out of scope (see the Icebox in `docs/BACKLOG.md`).
+- 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.1.1",
+  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,8 +165,17 @@ var CANCEL_REASONS = [
   "UNKNOWN"
 ];
 var EXPIRATION_REASONS = [...CANCEL_REASONS, "SUBSCRIPTION_PAUSED"];
-var CLI_STORES = ["app_store"];
-var CLI_STORE_TO_STORE = { app_store: "APP_STORE" };
+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";
@@ -421,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";
@@ -449,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: {
@@ -458,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);
 }
 
@@ -609,13 +626,14 @@ var Subscriber = class {
     this.period = asDuration(opts.period);
     this.trial = opts.trial === void 0 ? void 0 : asDuration(opts.trial);
     this.grace = asDuration(opts.gracePeriod ?? "P16D");
-    this.store = CLI_STORE_TO_STORE[opts.store ?? "app_store"];
+    this.cliStore = opts.store ?? "app_store";
+    this.store = CLI_STORE_TO_STORE[this.cliStore];
     this.environment = opts.environment ?? "SANDBOX";
     this.price = opts.price ?? 9.99;
     this.currency = opts.currency ?? "USD";
     this.countryCode = opts.countryCode ?? "US";
     this.entitlementIds = opts.entitlementIds ?? ["premium"];
-    this.productId = opts.productId;
+    this.productId = opts.productId ?? DEFAULT_PRODUCT_ID[this.cliStore];
     this.appUserId = opts.appUserId === void 0 || opts.appUserId === "auto" ? `$RCAnonymousID:${deps.rng.hex(32)}` : opts.appUserId;
     this.appId = opts.appId ?? `app${deps.rng.hex(12)}`;
   }
@@ -627,6 +645,11 @@ var Subscriber = class {
   trial;
   grace;
   store;
+  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;
@@ -651,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);
@@ -673,6 +696,9 @@ var Subscriber = class {
       this.expirationAtMs = draft.expirationAtMs;
       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;
     }
@@ -681,11 +707,31 @@ var Subscriber = class {
     return event;
   }
   /* ----------------------------------------------------------- internals */
-  newTransactionId() {
-    let s = String(1 + this.deps.rng.int(9));
-    for (let i = 0; i < 15; i++) s += String(this.deps.rng.int(10));
+  digits(n) {
+    let s = "";
+    for (let i = 0; i < n; i++) s += String(this.deps.rng.int(10));
+    return s;
+  }
+  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`; 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();
+  }
   draftFor(type, from, now) {
     const d = {
       originalTransactionId: this.originalTransactionId,
@@ -693,13 +739,16 @@ var Subscriber = class {
       purchasedAtMs: this.purchasedAtMs,
       expirationAtMs: this.expirationAtMs,
       periodType: this.periodType,
-      gracePeriodExpirationAtMs: this.gracePeriodExpirationAtMs
+      gracePeriodExpirationAtMs: this.gracePeriodExpirationAtMs,
+      renewalIndex: this.renewalIndex
     };
     switch (type) {
       case "INITIAL_PURCHASE": {
         const startsTrial = from === "none" && this.trial !== void 0;
         d.transactionId = this.newTransactionId();
-        d.originalTransactionId ??= d.transactionId;
+        if (this.cliStore !== "app_store") d.originalTransactionId = d.transactionId;
+        else d.originalTransactionId ??= d.transactionId;
+        d.renewalIndex = 0;
         d.purchasedAtMs = now;
         d.expirationAtMs = addDuration(now, startsTrial ? this.trial : this.period);
         d.periodType = startsTrial ? "TRIAL" : "NORMAL";
@@ -707,8 +756,14 @@ var Subscriber = class {
         break;
       }
       case "RENEWAL": {
+        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.transactionId = this.newTransactionId();
+        d.renewalIndex += 1;
         d.purchasedAtMs = start;
         d.expirationAtMs = addDuration(start, this.period);
         d.periodType = "NORMAL";
@@ -716,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") {
@@ -734,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(),
@@ -754,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";
@@ -974,8 +1037,8 @@ function parseEnvironment(input) {
 }
 function parseStore(input) {
   if (CLI_STORES.includes(input)) return input;
-  throw new RccError(`Unsupported --store "${input}". v0.1 supports: ${CLI_STORES.join(", ")}.`, {
-    hint: "Other stores are on the roadmap (see docs/BACKLOG.md \u2192 Icebox)."
+  throw new RccError(`Unsupported --store "${input}". The generator supports: ${CLI_STORES.join(", ")}.`, {
+    hint: "Receivers (listen/tail/inbox) accept events from every store; only generation is limited. Others are in the Icebox."
   });
 }
 function parseSeed(input) {
@@ -999,7 +1062,7 @@ function buildSingleEvent(type, opts) {
   return { api_version: "1.0", event };
 }
 function registerSend(program, io) {
-  program.command("send").argument("<EVENT_TYPE>", `event to send: ${EVENT_TYPES.join(" | ")}`).description("Send a single, schema-valid RevenueCat webhook event to your endpoint.").option("--to <url>", `target URL (default: ${DEFAULT_TARGET}, or "to" in ${CONFIG_FILE})`).option("--store <store>", `store: ${CLI_STORES.join(" | ")} (default: app_store, or "store" in ${CONFIG_FILE})`).option("--user <app_user_id>", "app_user_id (default: generated $RCAnonymousID)").option("--product <product_id>", "product_id", "com.example.premium.monthly").option("--auth-header <value>", `value sent as the Authorization header (default: "authHeader" in ${CONFIG_FILE})`).option("--environment <env>", `${ENVIRONMENTS.join(" | ")} (default: SANDBOX, or "environment" in ${CONFIG_FILE})`).option("--set <key=value>", "override a payload field (repeatable, dot paths allowed)", (v, acc) => [...acc ?? [], v]).option("--seed <seed>", "deterministic ids and timestamps").option("--dry-run", "print the payload instead of sending it").addHelpText("after", `
+  program.command("send").argument("<EVENT_TYPE>", `event to send: ${EVENT_TYPES.join(" | ")}`).description("Send a single, schema-valid RevenueCat webhook event to your endpoint.").option("--to <url>", `target URL (default: ${DEFAULT_TARGET}, or "to" in ${CONFIG_FILE})`).option("--store <store>", `store to simulate: ${CLI_STORES.join(" | ")} (default: app_store, or "store" in ${CONFIG_FILE})`).option("--user <app_user_id>", "app_user_id (default: generated $RCAnonymousID)").option("--product <product_id>", "product_id (default: com.example.premium.monthly, or com.example.premium:monthly for play_store)").option("--auth-header <value>", `value sent as the Authorization header (default: "authHeader" in ${CONFIG_FILE})`).option("--environment <env>", `${ENVIRONMENTS.join(" | ")} (default: SANDBOX, or "environment" in ${CONFIG_FILE})`).option("--set <key=value>", "override a payload field (repeatable, dot paths allowed)", (v, acc) => [...acc ?? [], v]).option("--seed <seed>", "deterministic ids and timestamps").option("--dry-run", "print the payload instead of sending it").addHelpText("after", `
 Examples:
   $ rcc send INITIAL_PURCHASE
   $ rcc send RENEWAL --to http://localhost:8787/webhook --auth-header "Bearer dev"
@@ -1211,12 +1274,13 @@ var eventType = z3.enum(EVENT_TYPES, {
 var httpStatus = z3.int({ error: "response_status must be an integer HTTP status (e.g. 200)." }).min(100).max(599);
 var SubscriberConfigSchema = z3.strictObject({
   app_user_id: z3.string().min(1).default("auto"),
-  product_id: z3.string().min(1).default("com.example.premium.monthly"),
+  /** No default here: the Subscriber picks a per-store default (see specs/F7-google-play.md). */
+  product_id: z3.string().min(1).optional(),
   period: duration.default("P1M"),
   trial: duration.optional(),
   grace_period: duration.default("P16D"),
   store: z3.enum(CLI_STORES, {
-    error: (iss) => `Unsupported store "${String(iss.input)}". v0.1 supports: ${list(CLI_STORES)}.`
+    error: (iss) => `Unsupported store "${String(iss.input)}". Supported: ${list(CLI_STORES)}.`
   }).default("app_store"),
   environment: z3.enum(ENVIRONMENTS, {
     error: (iss) => `Invalid environment "${String(iss.input)}". Use one of: ${list(ENVIRONMENTS)}.`
@@ -1253,7 +1317,6 @@ var ScenarioSchema = z3.strictObject({
   description: z3.string().optional(),
   subscriber: SubscriberConfigSchema.default({
     app_user_id: "auto",
-    product_id: "com.example.premium.monthly",
     period: "P1M",
     grace_period: "P16D",
     store: "app_store",