@wireai/activation 0.11.0 → 0.12.0

package/src/revenuecat/revenueCatBridge.ts

@@ -0,0 +1,221 @@
+/**
+ * revenueCatBridge - the short, first-class path from RevenueCat to Wire activation.
+ *
+ *   const revenuecat = createRevenueCatBridge({ analytics, entitlementId: "pro" });
+ *   revenuecat.paywallShown(offering, { source: variant });
+ *   revenuecat.checkoutStarted(pkg, { source: variant });
+ *   const entitled = revenuecat.purchaseCompleted(customerInfo, pkg, { source: variant });
+ *
+ * WHAT IT REPLACES: every consumer was hand-rolling the same four things around its paywall,
+ * differently: its own event names, its own idea of which RevenueCat fields are safe to send, its
+ * own entitlement check duplicated at the purchase and the restore site, and its own plan-tier
+ * user property. This owns all four, so adopting the purchase funnel is a constructor plus five
+ * call sites.
+ *
+ * ── THE JOIN KEY (read this before you wire it) ───────────────────────────────────────────────
+ * A purchase event is only worth anything if it can be joined to the SAME user's onboarding. The
+ * key that does that is `user_context.device_key`, NOT `session_id`:
+ *
+ *   • Purchase side: this bridge reports through a kit sink (`createAnalytics` or
+ *     `createWireActivation`). Both auto-mint a stable, persisted, per-install `device_key` and
+ *     stamp it on every event (see `context/deviceId.ts`).
+ *   • Onboarding side: `<WireOnboarding userContext={activationJoinContext(deviceKey)} />`. The kit
+ *     forwards `userContext` verbatim into the A2A session-start metadata, and the server records
+ *     it on the session's `session_started` event, where the SAME `device_key` lookup reads it.
+ *
+ * Pass the SAME `deviceKey` to both. `session_id` is NOT a join key across these two families: the
+ * onboarding session id is the A2A `contextId`, the app-event session id is the per-open id, and
+ * they live in disjoint spaces on purpose. Intersecting them yields zero rows, every time.
+ *
+ * PURE + dependency-free: no React, no React Native, no `react-native-purchases`. Fire-and-forget
+ * throughout, so an analytics failure can never take the paywall down with it.
+ */
+import type { Analytics } from "../analytics/analyticsFacade";
+import type { WireActivation } from "../activation/wireActivation";
+import {
+  PLAN_TIER_CONTEXT_KEY,
+  WIRE_PURCHASE_EVENTS,
+  describeEntitlement,
+  describeFailure,
+  describePackage,
+  resolvePlanTier,
+  type PlanTier,
+} from "./purchaseEvents";
+import type {
+  RevenueCatCustomerInfoLike,
+  RevenueCatOfferingLike,
+  RevenueCatPackageLike,
+  RevenueCatSink,
+} from "./types";
+
+/**
+ * COMPILE-TIME PROOF that both kit sinks satisfy {@link RevenueCatSink}, so a host can pass the
+ * analytics instance it already holds with no adapter of its own. Type-only (erased at build), and
+ * `tsc --noEmit` fails here the day either surface drifts. This lives in source, not the test file,
+ * because `tsconfig.json` excludes tests from the typecheck.
+ */
+type AssertIsSink<T extends RevenueCatSink> = T;
+type _AnalyticsIsASink = AssertIsSink<Analytics>;
+type _WireActivationIsASink = AssertIsSink<WireActivation>;
+
+/** Small, non-PII extras a host merges onto a purchase event (paywall variant, entry point, ...). */
+export type PurchaseProps = Record<string, string | number | boolean>;
+
+/** Inputs for {@link createRevenueCatBridge}. */
+export interface RevenueCatBridgeConfig {
+  /**
+   * Where events go: the `createAnalytics(...)` instance (offline-first queue) or the
+   * `createWireActivation(...)` instance (awaitable POST). Both already carry the `device_key` this
+   * funnel joins on, so pass the one the app already holds rather than creating a second.
+   */
+  analytics: RevenueCatSink;
+  /**
+   * The entitlement identifier that means "paid" in THIS app, exactly as configured in the
+   * RevenueCat dashboard (e.g. `"pro"`). The bridge reads `customerInfo.entitlements.active[id]`.
+   */
+  entitlementId: string;
+  /** Non-PII props merged into EVERY event from this bridge. A per-call prop of the same name wins. */
+  commonProps?: PurchaseProps;
+  /**
+   * Whether entitlement changes also update the bound user context with `plan_tier`
+   * (`user_context["custom.plan_tier"]`), so the whole funnel can be sliced paid vs trial vs free.
+   * Default `true`. Requires a sink with `setUserContext` (`createAnalytics`); a no-op otherwise.
+   */
+  writePlanTier?: boolean;
+}
+
+/** The bridge surface. Every method is fire-and-forget and never throws. */
+export interface RevenueCatBridge {
+  /**
+   * The paywall became visible. Pass the RevenueCat offering you just loaded and the bridge derives
+   * `offering_id` + `packages_count`. Fires even with no offering, because a paywall that reached
+   * the user with nothing to sell is exactly the failure you want in the funnel.
+   */
+  paywallShown(offering?: RevenueCatOfferingLike, props?: PurchaseProps): void;
+  /** The user tapped buy and the store sheet is opening. */
+  checkoutStarted(pkg: RevenueCatPackageLike, props?: PurchaseProps): void;
+  /**
+   * The store returned from a purchase. Fires `wire_purchase_completed` when the configured
+   * entitlement is now active, and `wire_purchase_failed` with `reason: "not_entitled"` when the
+   * store confirmed but nothing was granted (the case hosts usually drop on the floor). Syncs
+   * `plan_tier` either way. Returns whether the user is entitled now, so the caller can navigate.
+   */
+  purchaseCompleted(
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    pkg?: RevenueCatPackageLike,
+    props?: PurchaseProps,
+  ): boolean;
+  /** The purchase call rejected. Separates a user cancel from a real store error via `reason`. */
+  purchaseFailed(error: unknown, pkg?: RevenueCatPackageLike, props?: PurchaseProps): void;
+  /** A restore finished. Reports the resulting tier and returns whether the user is entitled now. */
+  purchasesRestored(
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    props?: PurchaseProps,
+  ): boolean;
+  /**
+   * Write the current tier to the bound user context WITHOUT emitting an event. Call it once at
+   * launch with a `getCustomerInfo()` snapshot so returning subscribers are segmented correctly
+   * from their first event of the session. Returns the tier it resolved.
+   */
+  syncPlanTier(customerInfo: RevenueCatCustomerInfoLike | undefined): PlanTier;
+}
+
+/**
+ * Create a bridge bound to one sink and one entitlement. Pure, React-free, and safe to create at
+ * module scope next to the paywall.
+ */
+export const createRevenueCatBridge = (config: RevenueCatBridgeConfig): RevenueCatBridge => {
+  const { analytics, entitlementId } = config;
+  const writeTier = config.writePlanTier !== false;
+
+  /**
+   * Send one event. Swallows a throwing sink AND a rejected promise from an awaitable one, so an
+   * analytics failure is never visible at the paywall and never becomes an unhandled rejection.
+   */
+  const emit = (event: string, props: Record<string, unknown>): void => {
+    try {
+      const result = analytics.track(event, { ...config.commonProps, ...props });
+      if (result && typeof (result as Promise<boolean>).catch === "function") {
+        void (result as Promise<boolean>).catch(() => {});
+      }
+    } catch {
+      /* analytics must never break a purchase */
+    }
+  };
+
+  const syncPlanTier = (customerInfo: RevenueCatCustomerInfoLike | undefined): PlanTier => {
+    const tier = resolvePlanTier(customerInfo, entitlementId);
+    if (!writeTier) return tier;
+    try {
+      analytics.setUserContext?.({ extra: { [PLAN_TIER_CONTEXT_KEY]: tier } });
+    } catch {
+      /* a sink without a usable context writer is not a purchase failure */
+    }
+    return tier;
+  };
+
+  const paywallShown = (offering?: RevenueCatOfferingLike, props?: PurchaseProps): void => {
+    const shown: Record<string, unknown> = {
+      packages_count: offering?.availablePackages?.length ?? 0,
+    };
+    if (typeof offering?.identifier === "string") shown.offering_id = offering.identifier;
+    emit(WIRE_PURCHASE_EVENTS.paywallShown, { ...shown, ...props });
+  };
+
+  const checkoutStarted = (pkg: RevenueCatPackageLike, props?: PurchaseProps): void => {
+    emit(WIRE_PURCHASE_EVENTS.checkoutStarted, { ...describePackage(pkg), ...props });
+  };
+
+  const purchaseCompleted = (
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    pkg?: RevenueCatPackageLike,
+    props?: PurchaseProps,
+  ): boolean => {
+    const tier = syncPlanTier(customerInfo);
+    const entitled = tier !== "free";
+    if (entitled) {
+      emit(WIRE_PURCHASE_EVENTS.purchased, {
+        ...describePackage(pkg),
+        ...describeEntitlement(customerInfo, entitlementId),
+        ...props,
+      });
+      return true;
+    }
+    // The store said yes but the entitlement is not active: a product/entitlement mapping problem,
+    // the single most common silent paywall defect. Report it rather than returning quietly.
+    emit(WIRE_PURCHASE_EVENTS.purchaseFailed, {
+      ...describePackage(pkg),
+      reason: "not_entitled",
+      code: "unknown",
+      entitlement: entitlementId,
+      ...props,
+    });
+    return false;
+  };
+
+  const purchaseFailed = (
+    error: unknown,
+    pkg?: RevenueCatPackageLike,
+    props?: PurchaseProps,
+  ): void => {
+    emit(WIRE_PURCHASE_EVENTS.purchaseFailed, {
+      ...describePackage(pkg),
+      ...describeFailure(error),
+      ...props,
+    });
+  };
+
+  const purchasesRestored = (
+    customerInfo: RevenueCatCustomerInfoLike | undefined,
+    props?: PurchaseProps,
+  ): boolean => {
+    const tier = syncPlanTier(customerInfo);
+    emit(WIRE_PURCHASE_EVENTS.restored, {
+      ...describeEntitlement(customerInfo, entitlementId),
+      ...props,
+    });
+    return tier !== "free";
+  };
+
+  return { paywallShown, checkoutStarted, purchaseCompleted, purchaseFailed, purchasesRestored, syncPlanTier };
+};

package/src/revenuecat/types.ts

@@ -0,0 +1,95 @@
+/**
+ * types - STRUCTURAL mirrors of the `react-native-purchases` shapes this adapter READS.
+ *
+ * WHY structural and not an import: `react-native-purchases` is a NATIVE module. Importing it
+ * (even as an optional peer) would put a native rebuild in the kit's dependency story, which the
+ * kit's hard rule forbids. Every field below is a subset of the real 9.6.x typings
+ * (`@revenuecat/purchases-typescript-internal`: `CustomerInfo`, `PurchasesEntitlementInfo`,
+ * `PurchasesPackage`, `PurchasesStoreProduct`, `PurchasesError`), declared as plain `string` /
+ * `number` / `boolean` so a host can pass its REAL RevenueCat objects straight in: RevenueCat's
+ * `Store`, `PACKAGE_TYPE`, `PERIOD_TYPE` and `PURCHASES_ERROR_CODE` are all STRING enums, and a
+ * string enum member is assignable to `string`.
+ *
+ * The adapter only ever reads. It never constructs a RevenueCat object and never calls the SDK.
+ */
+
+/** One entitlement as RevenueCat reports it (subset of `PurchasesEntitlementInfo`). */
+export interface RevenueCatEntitlementLike {
+  /** The entitlement identifier configured in the RevenueCat dashboard, e.g. `"pro"`. */
+  readonly identifier: string;
+  /** True while the customer has access. */
+  readonly isActive: boolean;
+  /** `"NORMAL" | "INTRO" | "TRIAL" | "PREPAID"` on the real type; compared case-insensitively. */
+  readonly periodType?: string;
+  /** True when the underlying subscription renews at the end of the period. */
+  readonly willRenew?: boolean;
+  /** The store the entitlement was unlocked from, e.g. `"APP_STORE"`. */
+  readonly store?: string;
+  /** The product id that unlocked the entitlement. */
+  readonly productIdentifier?: string;
+  /** False when the purchase is a production one. */
+  readonly isSandbox?: boolean;
+}
+
+/** The customer snapshot RevenueCat returns from a purchase, a restore, or `getCustomerInfo`. */
+export interface RevenueCatCustomerInfoLike {
+  readonly entitlements: {
+    /** Active entitlements keyed by identifier. Missing key means "not entitled". */
+    readonly active: { readonly [key: string]: RevenueCatEntitlementLike | undefined };
+  };
+  /** Product ids of the customer's active subscriptions. */
+  readonly activeSubscriptions?: readonly string[];
+}
+
+/** The purchasable product on a package (subset of `PurchasesStoreProduct`). */
+export interface RevenueCatProductLike {
+  readonly identifier: string;
+  /** Price in the local currency, as a number. */
+  readonly price?: number;
+  /** ISO currency code of `price`, e.g. `"EUR"`. */
+  readonly currencyCode?: string;
+}
+
+/** One offering package (subset of `PurchasesPackage`). */
+export interface RevenueCatPackageLike {
+  readonly identifier: string;
+  /** `"ANNUAL" | "MONTHLY" | ...` on the real type. */
+  readonly packageType?: string;
+  readonly product: RevenueCatProductLike;
+  /** The offering this package belongs to. */
+  readonly offeringIdentifier?: string;
+}
+
+/** The current offering a paywall renders (subset of `PurchasesOffering`). */
+export interface RevenueCatOfferingLike {
+  readonly identifier?: string;
+  readonly availablePackages?: readonly RevenueCatPackageLike[];
+}
+
+/** The rejected value of a RevenueCat purchase call (subset of `PurchasesError`). */
+export interface RevenueCatErrorLike {
+  /** `PURCHASES_ERROR_CODE`, a STRING enum; `"1"` is `PURCHASE_CANCELLED_ERROR`. */
+  readonly code?: string;
+  readonly message?: string;
+  /** Deprecated on the real type but still populated by 9.6.x. */
+  readonly userCancelled?: boolean | null;
+}
+
+/**
+ * The Wire sink the bridge reports through. Deliberately STRUCTURAL so BOTH kit surfaces satisfy
+ * it with no adapter of their own:
+ *   - `createAnalytics(...)` (offline-first queue) matches `track` + `setUserContext`;
+ *   - `createWireActivation(...)` (awaitable `wire.track`) matches `track`.
+ *
+ * Both auto-mint and stamp `user_context.device_key` on every event, which is the join key this
+ * adapter's whole design rests on (see `joinKey.md` in the module docs / the README section).
+ */
+export interface RevenueCatSink {
+  /** Report an in-app event. Returns `void` (queued) or `Promise<boolean>` (awaited POST). */
+  track(event: string, props?: Record<string, unknown>): void | Promise<boolean>;
+  /**
+   * Optional: update the bound user context. Present on `createAnalytics`, absent on
+   * `createWireActivation` (its config is captured immutably), so entitlement sync is a no-op there.
+   */
+  setUserContext?(partial: { extra?: Record<string, string | number | boolean> }): void;
+}

package/src/reviews/runtime.ts

@@ -6,6 +6,8 @@
  */
 import type { CoachmarkStorage } from "../coachmarks/types";
 import { getCoachmarkStorage } from "../coachmarks/runtime";
+import { getCurrentSessionId } from "../analytics/currentSession";
+import { makeSessionId } from "../analytics/reportClientEvent";
 
 /** Once-gate key. Keyed by app version when `oncePerVersion` is on, so a new release re-enables. */
 export const reviewSeenKey = (id: string, version?: string): string =>
@@ -14,9 +16,12 @@ export const reviewSeenKey = (id: string, version?: string): string =>
 /** Last-shown timestamp key (epoch ms), for the cooldown rule. */
 export const reviewLastShownKey = (id: string): string => `wire_review_${id}_last`;
 
-/** Session-count key, incremented once per gate mount, for the min-sessions rule. */
+/** Session-count key, incremented once per APP-OPEN (not per mount), for the min-sessions rule. */
 export const reviewSessionsKey = (id: string): string => `wire_review_${id}_sessions`;
 
+/** Companion key holding the open id the counter was LAST incremented for (see {@link bumpSessionCount}). */
+export const reviewSessionOpenKey = (id: string): string => `wire_review_${id}_open`;
+
 /** Resolve the storage to use: an explicit override, else the provider-injected singleton. */
 export const resolveStorage = (
   override?: CoachmarkStorage | null,
@@ -43,3 +48,89 @@ export const writeInt = (storage: CoachmarkStorage | null, key: string, value: n
     // Best-effort.
   }
 };
+
+/** Read a string from sync storage (undefined on a missing/blank/throwing read). */
+const readStr = (storage: CoachmarkStorage | null, key: string): string | undefined => {
+  if (!storage) return undefined;
+  try {
+    const raw = storage.getItem(key);
+    return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+// ── The "which app-open is this" id ──────────────────────────────────────────────────────────
+//
+// The gates' `minSessions` rule needs a SESSION, and the counter behind it used to increment once
+// per gate MOUNT. A mount is not a session: navigating away from the home feed and back, a tab that
+// unmounts its screen, or React StrictMode's dev double-invoke of the `useState` initializer all
+// bumped it. So `minSessions: 2` — the fail-closed default added after the 2026-07-16 one-star
+// incident — was satisfiable inside the user's FIRST app open, which is the exact thing it exists
+// to prevent. `sessions` was a count of mounts wearing the name of a session.
+//
+// The correct unit already exists: `getCurrentSessionId()`, the per-open id the server sees on
+// `app.session_started`. When a host wires the lifecycle events, the counter keys off THAT and is
+// exactly "distinct app-opens", the same unit the server's own `min_sessions` uses.
+//
+// When no host wired lifecycle events there is no registered open, so we fall back to a PROCESS-
+// scoped id: one JS process is one app launch, which is still a genuine app-open and is strictly
+// closer to a session than a mount is. It lives in a `globalThis` slot keyed by `Symbol.for(...)`
+// for the same reason `currentSession` does: tsup inlines this module into several bundles and a
+// plain module-local `let` would give each bundle its own "process".
+const PROCESS_OPEN_ID_SLOT: unique symbol = Symbol.for("@wireai/activation:processOpenId");
+
+type GlobalWithOpenId = typeof globalThis & { [PROCESS_OPEN_ID_SLOT]?: string };
+
+const openIdGlobal = globalThis as GlobalWithOpenId;
+
+/**
+ * The id identifying THIS app-open for gate counting: the live per-open `session_id` when a host
+ * wired the lifecycle events, else a stable per-process id. Never empty.
+ */
+export const currentOpenId = (): string => {
+  const live = getCurrentSessionId();
+  if (live) return live;
+  const existing = openIdGlobal[PROCESS_OPEN_ID_SLOT];
+  if (existing) return existing;
+  const created = makeSessionId();
+  openIdGlobal[PROCESS_OPEN_ID_SLOT] = created;
+  return created;
+};
+
+/** Test-only: forget the process open id so a unit test starts from a clean launch. */
+export const resetProcessOpenId = (): void => {
+  openIdGlobal[PROCESS_OPEN_ID_SLOT] = undefined;
+};
+
+/**
+ * Return the app-open count for the gate, incrementing it AT MOST ONCE per app-open.
+ *
+ * IDEMPOTENT by construction: the open id that last incremented the counter is stored alongside it,
+ * so a second call within the same open (a remount, a StrictMode double-invoke, a second gate render)
+ * reads the stored count back instead of bumping it. A new open id bumps exactly once.
+ *
+ * Storage-less hosts get `1` for the first call and `1` for every later call within the open —
+ * degraded but never inflating, which is the safe direction for a fail-closed gate.
+ */
+export const bumpSessionCount = (
+  storage: CoachmarkStorage | null,
+  sessionsKey: string,
+  openKey: string,
+  openId: string = currentOpenId(),
+): number => {
+  const lastOpen = readStr(storage, openKey);
+  const stored = readInt(storage, sessionsKey);
+  // Already counted this open → return what we counted, do not bump again.
+  if (lastOpen === openId) return stored > 0 ? stored : 1;
+  const next = stored + 1;
+  writeInt(storage, sessionsKey, next);
+  if (storage) {
+    try {
+      storage.setItem(openKey, openId);
+    } catch {
+      // Best-effort: a failed write only means this open may be counted twice.
+    }
+  }
+  return next;
+};

package/src/reviews/transport.ts

@@ -12,6 +12,7 @@
  * question_key=<name>), which is what the backend review-firing rules evaluate on — and
  * it seeds the broader app-analytics stream. Keep payloads minimal + non-PII.
  */
+import { ensureCurrentSessionId } from "../analytics/currentSession";
 import { buildEventsRequest, type ClientEvent } from "../analytics/reportClientEvent";
 import type { ReviewDecisionResponse, ReviewSubmission, ReviewTarget } from "./types";
 
@@ -157,7 +158,11 @@ export const fetchReviewDecision = async (
 
 /** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */
 export interface ReportAppEventOptions {
-  /** The onboarding/session id to correlate with, when known. */
+  /**
+   * The onboarding/session id to correlate with, when known. Optional: when omitted the event
+   * still carries the CURRENT per-open session id (`ensureCurrentSessionId()`), because an event
+   * with no `session_id` is dropped server-side behind a 200. Pass one only to override.
+   */
   sessionId?: string;
   /** A stable, non-PII device id — the review-decision endpoint reads it for min-sessions. */
   deviceKey?: string;
@@ -171,6 +176,16 @@ export interface ReportAppEventOptions {
  * stable identifier and `meta` small + non-PII.
  *
  *   reportAppEvent(target, "content_share", { sessionId, deviceKey });
+ *
+ * ── `session_id` IS NON-NEGOTIABLE ON THE WIRE ───────────────────────────────────────────
+ * The server's event model declares `session_id` required + non-empty, and `POST /v1/events`
+ * validates per event inside a try/except that counts the failure as `skipped` and STILL returns
+ * HTTP 200. An event sent without a `session_id` is therefore accepted and discarded, and a
+ * fire-and-forget caller never finds out. This used to be reachable through the ordinary API:
+ * `options.sessionId` was optional, so a host calling `reportAppEvent(target, "screen", { deviceKey })`
+ * posted every screen view into that hole. So the id is no longer conditional — an explicit
+ * `sessionId` wins, otherwise the CURRENT per-open id is used (minted + registered if no app-open
+ * has been registered yet).
  */
 export const reportAppEvent = (
   target: ReviewTarget | undefined,
@@ -179,11 +194,15 @@ export const reportAppEvent = (
 ): void => {
   if (!target?.serverUrl || !name) return;
   try {
+    // An explicit id wins; a missing OR BLANK one falls back to the current per-open id. A bare
+    // `??` would let `sessionId: ""` through, and the server rejects an empty string exactly like
+    // a missing key (`min_length=1`), so the blank case has to fall back too.
+    const supplied = options.sessionId ?? "";
     const event: Record<string, unknown> = {
       event_type: "app_event",
       question_key: name,
+      session_id: supplied.trim().length > 0 ? supplied : ensureCurrentSessionId(),
     };
-    if (options.sessionId) event.session_id = options.sessionId;
     // device_key rides in the non-PII user_context bucket the server sanitizes; the
     // review-decision endpoint reads it to group a device's sessions.
     if (options.deviceKey) event.user_context = { device_key: options.deviceKey };

package/src/reviews/useReviewGate.ts

@@ -19,10 +19,12 @@ import { useResolvedFeatures } from "../features/WireFeaturesProvider";
 import { decideReview, evaluateGate, resolveRules } from "./decision";
 import { sameDecision, shallowEqual } from "./equality";
 import {
+  bumpSessionCount,
   readInt,
   resolveStorage,
   reviewLastShownKey,
   reviewSeenKey,
+  reviewSessionOpenKey,
   reviewSessionsKey,
   writeInt,
 } from "./runtime";
@@ -70,14 +72,17 @@ export const useReviewGate = ({
   const seenKey = reviewSeenKey(config.id, config.oncePerVersion === false ? undefined : config.appVersion);
   const lastKey = reviewLastShownKey(config.id);
   const sessionsKey = reviewSessionsKey(config.id);
+  const sessionOpenKey = reviewSessionOpenKey(config.id);
 
-  // Read (and bump) the session counter ONCE per mount: this mount is a new session.
-  const sessions = useState(() => {
-    const store = resolveStorage(storage);
-    const next = readInt(store, sessionsKey) + 1;
-    writeInt(store, sessionsKey, next);
-    return next;
-  })[0];
+  // Read (and bump) the app-open counter. IDEMPOTENT per app-open, NOT per mount: `bumpSessionCount`
+  // keys off the live per-open session id (or a per-process id when no host wired the lifecycle
+  // events), so a remount, a navigation return, or React StrictMode's dev double-invoke of this
+  // initializer all read the same number back instead of inflating it. Before this, `sessions`
+  // counted mounts, so the fail-closed `minSessions: 2` default could be satisfied inside the user's
+  // very first app open — the exact scenario it was added to prevent.
+  const sessions = useState(() =>
+    bumpSessionCount(resolveStorage(storage), sessionsKey, sessionOpenKey),
+  )[0];
 
   // Gate the local rules behind an optional client-side timeout, so a reachable server
   // gets a window to answer first. A present `decision` bypasses the wait entirely.

package/src/session-analytics/lifecycle.ts

@@ -212,11 +212,18 @@ export interface WireLifecycleOptions extends ReportFirstOpenOptions {}
  * Route both through the same `sink` (the offline queue) to buffer them. Fire-and-forget.
  */
 export const wireLifecycleEvents = (opts: WireLifecycleOptions): void => {
-  reportFirstOpen(opts);
+  // ONE per-open id for BOTH events when the caller supplies none. Without this, `reportFirstOpen`
+  // fell through to `buildLifecycleEvent`'s own `makeSessionId()` while `reportSessionStart` minted a
+  // DIFFERENT one — so `app.first_open` carried a session id the server never saw a `session_started`
+  // for and back-filled into a phantom session, inflating session counts. `useLifecycleEvents` already
+  // pinned this (it mints `mountOpenSessionId`); the React-free entry point did not, so the identical
+  // bug was still reachable from the documented non-hook path.
+  const sessionId = opts.sessionId ?? makeSessionId();
+  reportFirstOpen({ ...opts, sessionId });
   reportSessionStart({
     target: opts.target,
     sink: opts.sink,
-    sessionId: opts.sessionId,
+    sessionId,
     userId: opts.userId,
     deviceKey: opts.deviceKey,
     sessionCount: opts.sessionCount,

package/src/session-analytics/reportSessionStart.ts

@@ -32,7 +32,12 @@
  * never be able to break the app.
  */
 import { setCurrentSessionId } from "../analytics/currentSession";
-import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
+import {
+  makeSessionId,
+  warnOnSkippedEvents,
+  type ClientEvent,
+  type ClientEventTarget,
+} from "../analytics/reportClientEvent";
 import type { DeviceContext } from "../device/deviceContext";
 import { sanitizeUserId } from "../identity/userIdentity";
 
@@ -162,9 +167,15 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
       method: "POST",
       headers,
       body: JSON.stringify({ events: [event] }),
-    }).catch(() => {
-      // Network/transport error — analytics is best-effort, swallow.
-    });
+    })
+      .then((res) => {
+        // A 200 can still carry `skipped:N` — the server took the request and threw the event away.
+        // Log-only; this path has nothing to retry either way.
+        warnOnSkippedEvents(res);
+      })
+      .catch(() => {
+        // Network/transport error — analytics is best-effort, swallow.
+      });
   } catch {
     // URL construction, JSON serialization, a throwing sink, or a missing fetch — swallow.
   }

package/src/session-analytics/useLifecycleEvents.ts

@@ -29,6 +29,7 @@ import { AppState, Platform, type AppStateStatus } from "react-native";
 
 import { createEventQueue, type EnvelopeSource, type EventQueue } from "../analytics/eventQueue";
 import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
+import { resolveAutoDeviceKey } from "../context/deviceId";
 import { collectDeviceContext } from "../device/deviceContext";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import { reportFirstOpen } from "./lifecycle";
@@ -114,6 +115,31 @@ export const useLifecycleEvents = (
     const targetOf = (cfg: LifecycleConfig | undefined): ClientEventTarget | undefined =>
       cfg?.serverUrl ? { serverUrl: cfg.serverUrl, apiKey: cfg.apiKey ?? "" } : undefined;
 
+    /**
+     * The `device_key` these lifecycle events ride under. A host-supplied id always wins.
+     *
+     * WHY THE FALLBACK EXISTS: `min_sessions` (the review / questionnaire firing rule, and the
+     * "fire on the user's Nth session" recipe in the README) is computed SERVER-SIDE by counting
+     * distinct `app.session_started` events grouped by `user_context.device_key`. A host that took
+     * the batteries-included path and passed no `deviceKey` emitted those events with NO device key
+     * at all — while its `createAnalytics` / `createWireActivation` events carried an auto-minted
+     * one. Two disjoint identity spaces again: the counter the rule reads could never increase, so
+     * `min_sessions` was structurally unsatisfiable and the gate never fired from the server side.
+     *
+     * ONLY WITH `storage`: the auto id is per-INSTALL only when it can be persisted. With no
+     * storage it would be per-LAUNCH, which would make every open look like a brand-new device and
+     * corrupt `min_sessions` in the other direction. So no storage → no fallback, same as before.
+     */
+    const resolveDeviceKey = (
+      cfg: LifecycleConfig | undefined,
+      opts: UseLifecycleEventsOptions,
+    ): string | undefined => {
+      const host = typeof opts.deviceKey === "string" && opts.deviceKey.trim() ? opts.deviceKey : undefined;
+      if (host) return host;
+      if (!cfg?.storage) return undefined;
+      return resolveAutoDeviceKey({ appId: cfg.appId, storage: cfg.storage });
+    };
+
     // ONE per-open session id for the MOUNT open, shared by first_open AND session_started below.
     // WHY: `first_open` used to default to its OWN fresh `makeSessionId()` (via `buildLifecycleEvent`)
     // while `session_started` minted a different one — so every install's `first_open` carried a
@@ -138,7 +164,7 @@ export const useLifecycleEvents = (
         sink: resolveSink(),
         sessionId,
         userId: opts.userId,
-        deviceKey: opts.deviceKey,
+        deviceKey: resolveDeviceKey(cfg, opts),
         sessionCount: opts.sessionCount,
         appVersion: cfg?.appVersion ?? device.appVersion,
         platform: Platform.OS,
@@ -166,7 +192,7 @@ export const useLifecycleEvents = (
           storage: cfg?.storage,
           appId: cfg?.appId,
           userId: opts.userId,
-          deviceKey: opts.deviceKey,
+          deviceKey: resolveDeviceKey(cfg, opts),
           sessionCount: opts.sessionCount,
           appVersion: cfg?.appVersion ?? device.appVersion,
           platform: Platform.OS,