reveclicat 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -41,11 +41,14 @@ type CancelReason = (typeof CANCEL_REASONS)[number];
 declare const EXPIRATION_REASONS: readonly ["UNSUBSCRIBE", "BILLING_ERROR", "DEVELOPER_INITIATED", "PRICE_INCREASE", "CUSTOMER_SUPPORT", "UNKNOWN", "SUBSCRIPTION_PAUSED"];
 type ExpirationReason = (typeof EXPIRATION_REASONS)[number];
 /** CLI-facing store names (lowercase) → RevenueCat `store` values. Generator supports these; receivers accept every store. */
-declare const CLI_STORES: readonly ["app_store", "play_store"];
+declare const CLI_STORES: readonly ["app_store", "play_store", "stripe"];
 type CliStore = (typeof CLI_STORES)[number];
 declare const CLI_STORE_TO_STORE: Record<CliStore, Store>;
 /** Default product id per store (Play uses RevenueCat's `<subscription_id>:<base_plan_id>` format). */
 declare const DEFAULT_PRODUCT_ID: Record<CliStore, string>;
+/** Events a store never emits (official store-compatibility table, docs/payload-sources.md). */
+declare const UNSUPPORTED_EVENTS_BY_STORE: Partial<Record<CliStore, readonly EventType[]>>;
+declare const STORE_LABEL: Record<CliStore, string>;
 
 /**
  * Zod schemas for RevenueCat webhook events (v0.1: 7 event types).
@@ -2040,6 +2043,7 @@ declare const ScenarioSchema: z.ZodObject<{
         store: z.ZodDefault<z.ZodEnum<{
             app_store: "app_store";
             play_store: "play_store";
+            stripe: "stripe";
         }>>;
         environment: z.ZodDefault<z.ZodEnum<{
             SANDBOX: "SANDBOX";
@@ -2108,15 +2112,17 @@ interface TransitionContext {
     hasTrial: boolean;
     /** State to return to on UNCANCELLATION (the state before the CANCELLATION). */
     resumeState: "trial" | "active";
+    /** Store being simulated; some stores never emit some events. */
+    store?: CliStore | undefined;
 }
 declare class IllegalTransitionError extends RccError {
     readonly state: SubscriptionState;
     readonly event: EventType;
     readonly legal: readonly EventType[];
-    constructor(state: SubscriptionState, event: EventType);
+    constructor(state: SubscriptionState, event: EventType, store?: CliStore);
 }
-/** Events that may legally follow `state`, in display order. */
-declare function legalEvents(state: SubscriptionState): EventType[];
+/** Events that may legally follow `state`, in display order; `store` removes events that store never emits. */
+declare function legalEvents(state: SubscriptionState, store?: CliStore): EventType[];
 /** Pure transition. Throws IllegalTransitionError; never returns an incoherent state. */
 declare function transition(state: SubscriptionState, event: EventType, ctx: TransitionContext): SubscriptionState;
 
@@ -2161,6 +2167,8 @@ declare class Subscriber {
     private readonly cliStore;
     /** Play: number of renewals on the current order (drives the `..N` suffix). */
     private renewalIndex;
+    /** A BILLING_ISSUE is open (until a RENEWAL recovers it or the subscription expires). */
+    private billingRetry;
     private readonly environment;
     private readonly price;
     private readonly currency;
@@ -2182,9 +2190,10 @@ declare class Subscriber {
     /** Emit an event: check legality, time guards, build + validate payload, commit state. */
     emit(type: EventType, overrides?: Record<string, unknown>): Event;
     private digits;
-    /** A brand-new order/transaction id in the store's format (see specs/F7-google-play.md). */
+    private alnum;
+    /** A brand-new order/transaction id in the store's format (specs/F7-google-play.md, specs/F8-stripe.md). */
     private newTransactionId;
-    /** 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. */
     private renewalTransactionId;
     private draftFor;
     private buildPayload;
@@ -2254,6 +2263,7 @@ declare const ConfigSchema: z.ZodObject<{
     store: z.ZodOptional<z.ZodEnum<{
         app_store: "app_store";
         play_store: "play_store";
+        stripe: "stripe";
     }>>;
     environment: z.ZodOptional<z.ZodEnum<{
         SANDBOX: "SANDBOX";
@@ -2264,4 +2274,4 @@ type Config = z.infer<typeof ConfigSchema>;
 /** Read `reveclicat.config.json` from `dir` (default cwd). Missing file → {}. Invalid → RccError. */
 declare function loadConfig(dir?: string): Config;
 
-export { type BillingIssueEvent, BillingIssueEventSchema, CANCEL_REASONS, CLI_STORES, CLI_STORE_TO_STORE, type CancelReason, type CancellationEvent, CancellationEventSchema, type CliStore, type Config, ConfigSchema, DEFAULT_PRODUCT_ID, type Duration, ENVIRONMENTS, EVENT_SCHEMAS, EVENT_TYPES, EXPIRATION_REASONS, type EnvelopeClassification, type Environment, type Event, type EventResult, EventSchema, type EventType, ExperimentSchema, type ExpirationEvent, ExpirationEventSchema, type ExpirationReason, IllegalTransitionError, type InitialPurchaseEvent, InitialPurchaseEventSchema, type LifecycleEvent, type LoadedScenario, PERIOD_TYPES, type PeriodType, PrematureEventError, RccError, type RenewalEvent, RenewalEventSchema, type Rng, type RunOptions, type RunResult, STORES, type Scenario, ScenarioSchema, ScenarioValidationError, type Step, type Store, Subscriber, SubscriberAttributeSchema, type SubscriberOptions, type SubscriptionState, type TestEvent, TestEventSchema, type UncancellationEvent, UncancellationEventSchema, type UnknownEvent, UnknownEventSchema, UnknownWebhookEnvelopeSchema, VirtualClock, type WebhookEnvelope, WebhookEnvelopeSchema, addDuration, buildProgram, classifyEnvelope, createRng, createSimulation, formatDuration, legalEvents, loadConfig, loadScenario, loadScenarioWithSource, parseDuration, parseScenario, postEvent, runScenario, transition };
+export { type BillingIssueEvent, BillingIssueEventSchema, CANCEL_REASONS, CLI_STORES, CLI_STORE_TO_STORE, type CancelReason, type CancellationEvent, CancellationEventSchema, type CliStore, type Config, ConfigSchema, DEFAULT_PRODUCT_ID, type Duration, ENVIRONMENTS, EVENT_SCHEMAS, EVENT_TYPES, EXPIRATION_REASONS, type EnvelopeClassification, type Environment, type Event, type EventResult, EventSchema, type EventType, ExperimentSchema, type ExpirationEvent, ExpirationEventSchema, type ExpirationReason, IllegalTransitionError, type InitialPurchaseEvent, InitialPurchaseEventSchema, type LifecycleEvent, type LoadedScenario, PERIOD_TYPES, type PeriodType, PrematureEventError, RccError, type RenewalEvent, RenewalEventSchema, type Rng, type RunOptions, type RunResult, STORES, STORE_LABEL, type Scenario, ScenarioSchema, ScenarioValidationError, type Step, type Store, Subscriber, SubscriberAttributeSchema, type SubscriberOptions, type SubscriptionState, type TestEvent, TestEventSchema, UNSUPPORTED_EVENTS_BY_STORE, type UncancellationEvent, UncancellationEventSchema, type UnknownEvent, UnknownEventSchema, UnknownWebhookEnvelopeSchema, VirtualClock, type WebhookEnvelope, WebhookEnvelopeSchema, addDuration, buildProgram, classifyEnvelope, createRng, createSimulation, formatDuration, legalEvents, loadConfig, loadScenario, loadScenarioWithSource, parseDuration, parseScenario, postEvent, runScenario, transition };

package/dist/index.js

@@ -4,7 +4,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",
@@ -157,9 +157,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";
@@ -414,10 +422,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";
@@ -442,6 +451,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: {
@@ -451,13 +463,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);
 }
 
@@ -624,6 +640,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;
@@ -648,7 +666,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);
@@ -671,6 +689,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;
     }
@@ -684,15 +704,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();
   }
@@ -710,7 +738,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;
@@ -720,8 +748,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);
@@ -730,7 +763,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") {
@@ -748,6 +787,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(),
@@ -768,16 +808,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";
@@ -1934,11 +1975,13 @@ export {
   RccError,
   RenewalEventSchema,
   STORES,
+  STORE_LABEL,
   ScenarioSchema,
   ScenarioValidationError,
   Subscriber,
   SubscriberAttributeSchema,
   TestEventSchema,
+  UNSUPPORTED_EVENTS_BY_STORE,
   UncancellationEventSchema,
   UnknownEventSchema,
   UnknownWebhookEnvelopeSchema,