@wireai/activation 0.10.0 → 0.12.0

package/src/analytics/eventQueue.ts

@@ -24,7 +24,12 @@
  * `notifyOnline()`; persistence is the host-injected AsyncStorage-compatible subset.
  */
 import type { ContextEnvelope } from "./contextEnvelope";
-import type { ClientEvent, ClientEventTarget } from "./reportClientEvent";
+import {
+  buildEventsRequest,
+  warnOnSkippedEvents,
+  type ClientEvent,
+  type ClientEventTarget,
+} from "./reportClientEvent";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 
 /** Envelope source: a fixed envelope or a provider evaluated at enqueue time (fresh network type). */
@@ -161,6 +166,11 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   const stamp = (event: ClientEvent): ClientEvent => {
     const env = resolveEnvelope();
     const stamped: ClientEvent = { ...event };
+    // Client enqueue timestamp: distinguishes a GENUINE repeat (same event fired seconds apart)
+    // from a REDUNDANT re-enqueue of the same instant. The de-dup signature below includes it, so
+    // two identical events enqueued in the same millisecond still collapse (a re-render), while the
+    // same action repeated later carries a fresh `ts` and survives. A caller-set `ts` is preserved.
+    if (stamped.ts === undefined) stamped.ts = Date.now();
     if (!env) return stamped;
     if (!stamped.device && env.device) stamped.device = env.device;
     if (!stamped.session_id && env.sessionId) stamped.session_id = env.sessionId;
@@ -227,19 +237,18 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   // The queue's OWN awaited POST. Reads `res.ok` to drive retry/dequeue. NEVER throws — a missing
   // fetch, a rejecting network, or a JSON error resolves to `false` (batch stays, retry schedules).
   const postBatch = async (events: ClientEvent[]): Promise<boolean> => {
-    if (!target?.serverUrl || events.length === 0) return false;
+    // Build the /v1/events request through the ONE canonical builder (url + headers + body) so this
+    // queue never re-describes the endpoint. The abort-timeout stays: the queue owns retry/dequeue,
+    // so a hung request must be cut loose to schedule a backoff rather than block the drain forever.
+    const req = buildEventsRequest(target, events);
+    if (!req) return false;
     const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
     const timer = setTimeout(() => controller?.abort(), 15_000);
     try {
-      const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
-      const headers: Record<string, string> = { "Content-Type": "application/json" };
-      if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-      const res = await fetch(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({ events }),
-        signal: controller?.signal,
-      });
+      const res = await fetch(req.url, { ...req.init, signal: controller?.signal });
+      // A 200 can still carry `skipped:N` — events the server threw away. Log-only: the ack below
+      // stays `res.ok`, so retry/dequeue behaviour is unchanged.
+      warnOnSkippedEvents(res);
       return !!(res && (res as { ok?: boolean }).ok);
     } catch {
       return false;

package/src/analytics/index.ts

@@ -64,5 +64,33 @@ export type {
 // ─── The thin optional React hook over the façade ─────────────────────────────
 export { useAnalytics } from "./useAnalytics";
 
+// ─── Logout / reset helpers + the email-shape guard (analytics-focused surface) ─
+export {
+  clearUserContext,
+  clearPiiFromContext,
+  analyticsUserIdStorageKey,
+} from "../context/userContext";
+export type { ClearUserContextOptions } from "../context/userContext";
+export { looksLikeEmail } from "../identity/userIdentity";
+
+// ─── The ONE auto-minted, persisted per-install `device_key` (the join key) ────
+// Public so an analytics-only consumer can read the SAME id the façade stamps and forward it to the
+// onboarding side via `activationJoinContext(deviceKey)`. Without it the join has no reachable key.
+export {
+  resolveAutoDeviceKey,
+  resetAutoDeviceKeys,
+  deviceIdStorageKey,
+  AUTO_DEVICE_ID_PREFIX,
+} from "../context/deviceId";
+export type { DeviceKeyStorage, ResolveAutoDeviceKeyOptions } from "../context/deviceId";
+
 // ─── Current per-open session registry (identify/app-events reuse the live session) ───
-export { getCurrentSessionId, setCurrentSessionId, resetCurrentSessionId } from "./currentSession";
+export {
+  getCurrentSessionId,
+  // The write-through read every wire path uses: returns the registered per-open id, minting +
+  // registering one when no app-open has been registered (the server drops an event with no
+  // `session_id` and still answers 200).
+  ensureCurrentSessionId,
+  setCurrentSessionId,
+  resetCurrentSessionId,
+} from "./currentSession";

package/src/analytics/reportClientEvent.ts

@@ -76,6 +76,16 @@ export type ClientEvent = {
    * Lets the backend reconcile onboarding sessions to real users. Old servers ignore it.
    */
   user_id?: string;
+  /**
+   * Client-stamped epoch-ms timestamp of when the event was ENQUEUED on the device. Optional and
+   * ADDITIVE: the offline queue stamps it at enqueue time (see `createEventQueue`) so two otherwise
+   * byte-identical events fired seconds apart (a genuine repeat, e.g. the user taps "share" twice)
+   * are NOT collapsed by the queue's identical-JSON de-dup — while two truly simultaneous
+   * re-enqueues of the same instant (a redundant re-render) still share a `ts` and collapse. A raw
+   * `Date.now()`, never a wall-clock the server trusts (the server derives its own receive time);
+   * an old/strict server that does not model it simply ignores the unknown field.
+   */
+  ts?: number;
 };
 
 /** Where to POST. Derived from `WireOnboardingConfig` (`serverUrl` + `apiKey`). */
@@ -102,8 +112,8 @@ export const makeSessionId = (): string =>
  * copy of the endpoint path, headers, or envelope shape to drift. Returns `null` when there is
  * nothing to send (no target / no events) or serialization throws, so callers just bail.
  */
-const buildEventsRequest = (
-  target: ClientEventTarget | undefined,
+export const buildEventsRequest = (
+  target: { serverUrl: string; apiKey?: string } | undefined,
   events: ClientEvent[],
 ): { url: string; init: RequestInit } | null => {
   if (!target?.serverUrl || events.length === 0) return null;
@@ -118,6 +128,44 @@ const buildEventsRequest = (
   }
 };
 
+/** RN sets this global; absent under node/SSR. Read defensively inside {@link warnOnSkippedEvents}. */
+declare const __DEV__: boolean | undefined;
+
+/**
+ * Read the `/v1/events` ACK body and warn (dev builds only) when the server DISCARDED events.
+ *
+ * The endpoint answers HTTP **200** with `{ ok, written, skipped }` — an event it refuses (a missing
+ * `session_id`, a malformed payload) is counted in `skipped`, never surfaced in the status code. Every
+ * send path here reads `res.ok` alone, so a whole batch can evaporate behind a green response. This
+ * consumes the body of the PERSISTENT paths (the offline queue + session-start) and names the count.
+ *
+ * LOG ONLY: returns immediately, never throws, and never influences retry / dequeue / return values.
+ * A response with no usable `.json` (an old server, a test mock) is silently ignored.
+ */
+export const warnOnSkippedEvents = (res: unknown): void => {
+  try {
+    const json = (res as { json?: () => Promise<unknown> } | null | undefined)?.json;
+    if (typeof json !== "function") return;
+    void Promise.resolve(json.call(res))
+      .then((body) => {
+        const skipped = (body as { skipped?: unknown } | null | undefined)?.skipped;
+        if (typeof skipped !== "number" || skipped <= 0) return;
+        if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+          console.warn(
+            `[wireai] the server ACCEPTED the /v1/events POST but DISCARDED ${skipped} event(s) ` +
+              "(skipped in the response body) — they are gone, not retried. The usual cause is an " +
+              "event with a missing or empty session_id.",
+          );
+        }
+      })
+      .catch(() => {
+        // Unreadable / already-consumed body — best-effort logging, swallow.
+      });
+  } catch {
+    // A hostile response object — swallow.
+  }
+};
+
 /**
  * POST one or more client events, fire-and-forget. A missing/invalid target, a build error,
  * a missing `fetch`, or a network failure is swallowed — the call returns immediately and the

package/src/analytics/screenTracking.ts

@@ -42,7 +42,12 @@ export interface ScreenTrackerOptions {
    * exposes. When omitted, the tracker still de-dups and fires `onScreen`, but sends nothing.
    */
   target?: { serverUrl: string; apiKey: string };
-  /** The onboarding/session id to correlate screen views with, when known. */
+  /**
+   * The onboarding/session id to correlate screen views with, when known. Omitting it no longer
+   * means the view goes out WITHOUT a `session_id` (the server requires one and drops the event
+   * behind an HTTP 200 — that is why screen tracking silently produced nothing for a host that
+   * never mounted the lifecycle hook). `reportAppEvent` falls back to the current per-open id.
+   */
   sessionId?: string;
   /** A stable, non-PII device id — groups a device's sessions server-side. */
   deviceKey?: string;

package/src/analytics/useAnalytics.ts

@@ -11,7 +11,7 @@
  *   analytics.track("content_share", { source: "feed" });
  *   // ...on reconnect: analytics.notifyOnline();
  */
-import { useRef } from "react";
+import { useEffect, useRef } from "react";
 
 import {
   createAnalytics,
@@ -38,5 +38,26 @@ export const useAnalytics = (
     prevKeys.current = currentKeys;
     ref.current = createAnalytics(config, options);
   }
+
+  // A LATE-ARRIVING host device key must still reach the instance.
+  //
+  // `createAnalytics` copies `config.userContext` into a closure at construction and never re-reads
+  // the prop, and `config.userContext.deviceKey` is deliberately NOT part of `currentKeys` (rebuilding
+  // the instance would throw away the event queue's pending buffer). So a host that hydrates its
+  // device id asynchronously — an AsyncStorage read that resolves after first render — used to be
+  // stamped with the kit's auto-minted `wdev_*` id FOREVER, while a sibling `useWireActivation`
+  // (which does key on it) rebuilt and used the real one. One install, two `device_key` values, in
+  // the same app, on the key every gating rule and the purchase↔onboarding join reads.
+  //
+  // `setUserContext` is the non-destructive seam for exactly this: it updates the bound context in
+  // place, so subsequent events carry the host key with no queue rebuild.
+  const hostDeviceKey =
+    typeof config.userContext?.deviceKey === "string" && config.userContext.deviceKey.trim()
+      ? config.userContext.deviceKey.trim()
+      : undefined;
+  useEffect(() => {
+    if (hostDeviceKey) ref.current?.setUserContext({ deviceKey: hostDeviceKey });
+  }, [hostDeviceKey]);
+
   return ref.current;
 };

package/src/context/deviceId.ts

@@ -41,3 +41,112 @@ export const mintDeviceId = (): string => {
   const time = Date.now().toString(36);
   return `${AUTO_DEVICE_ID_PREFIX}${time}_${randomChunk()}${randomChunk()}`;
 };
+
+// ── The ONE auto device key per install ──────────────────────────────────────────────────────
+//
+// WHY A REGISTRY AND NOT A `let` PER FACTORY: `createAnalytics` and `createWireActivation` each
+// used to mint their OWN id synchronously and then race a storage read to overwrite it. A host that
+// creates BOTH (the documented wiring: a façade for `track`/`screen`, an activation instance for the
+// gate-firing `wire.track`) therefore had TWO auto ids for ONE install. Every event carried whichever
+// id its own surface minted, so the `device_key` the server groups a device's sessions under — the
+// key `min_sessions`, A/B arm stickiness, and the purchase↔onboarding join all read — SPLIT in two.
+// On a first run both also wrote their own id to the same storage slot, so which one survived was a
+// coin flip. Same failure class as joining two event families on disjoint id spaces: no error, just
+// halved counts and a join that misses.
+//
+// The fix is the pattern this repo already uses for `currentSession` and `activation revalidation`:
+// ONE value in a `globalThis` slot keyed by `Symbol.for(...)`, so every inlined copy of this module
+// (tsup duplicates modules across the `.` / `./analytics` bundles) addresses the SAME registry.
+// Keyed by `appId` so two tenants in one process never share an id.
+//
+// RESIDUAL WINDOW (documented, not fixed here): the storage read is async, so events emitted in the
+// milliseconds before hydration completes still carry the freshly minted id rather than the persisted
+// one. The registry makes every surface agree on WHICH id that is; it does not make the read sync.
+
+/** Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle. */
+const AUTO_DEVICE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:autoDeviceKeys");
+
+/** The shared registry: the live id per `appId`, plus the set of appIds whose hydration already ran. */
+type AutoDeviceKeyRegistry = { keys: Map<string, string>; hydrating: Set<string> };
+
+type GlobalWithDeviceKeys = typeof globalThis & {
+  [AUTO_DEVICE_KEY_SLOT]?: AutoDeviceKeyRegistry;
+};
+
+const deviceKeyGlobal = globalThis as GlobalWithDeviceKeys;
+
+const autoDeviceKeyRegistry = (): AutoDeviceKeyRegistry => {
+  const existing = deviceKeyGlobal[AUTO_DEVICE_KEY_SLOT];
+  if (existing) return existing;
+  const created: AutoDeviceKeyRegistry = { keys: new Map(), hydrating: new Set() };
+  deviceKeyGlobal[AUTO_DEVICE_KEY_SLOT] = created;
+  return created;
+};
+
+/** The persistence subset {@link resolveAutoDeviceKey} needs (a strict subset of `WireOnboardingStorage`). */
+export type DeviceKeyStorage = {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+};
+
+/** Options for {@link resolveAutoDeviceKey}. Omitting `storage` gives a PROCESS-scoped id, not a
+ *  per-install one — see the caller notes: a caller with no persistence must decide whether a
+ *  per-launch id is better or worse than no id for its metric. */
+export interface ResolveAutoDeviceKeyOptions {
+  /** Tenant/app id — namespaces both the registry entry and the storage slot. */
+  appId?: string;
+  /** Host persistence. Present → the id survives launches. Absent → process-scoped only. */
+  storage?: DeviceKeyStorage;
+}
+
+/**
+ * The ONE auto-minted `device_key` for an install, shared by every kit surface.
+ *
+ * SYNCHRONOUS by contract (a fire-and-forget event path cannot await): returns the current live id
+ * immediately, minting one on first call. When `storage` is supplied it also kicks off a SINGLE
+ * hydration per `appId` that adopts the persisted id (or persists the freshly minted one). Callers
+ * should call this per EVENT rather than caching the return value, so an event built after hydration
+ * carries the persisted id.
+ *
+ * A host-supplied `deviceKey` always wins — callers must short-circuit before reaching this.
+ * Never throws: a missing, hung, or rejecting storage adapter degrades to the in-memory id.
+ */
+export const resolveAutoDeviceKey = (opts: ResolveAutoDeviceKeyOptions = {}): string => {
+  const registry = autoDeviceKeyRegistry();
+  const appId = opts.appId ?? "default";
+
+  let id = registry.keys.get(appId);
+  if (!id) {
+    id = mintDeviceId();
+    registry.keys.set(appId, id);
+  }
+
+  const storage = opts.storage;
+  // Single-flight: the FIRST caller with storage owns hydration for this appId; later callers just
+  // read whatever the registry currently holds.
+  if (storage && !registry.hydrating.has(appId)) {
+    registry.hydrating.add(appId);
+    const slot = deviceIdStorageKey(appId);
+    const minted = id;
+    try {
+      void Promise.resolve(storage.getItem(slot))
+        .then((saved) => {
+          const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : undefined;
+          if (persisted) registry.keys.set(appId, persisted);
+          else void Promise.resolve(storage.setItem(slot, minted)).catch(() => {});
+        })
+        .catch(() => {});
+    } catch {
+      // A storage adapter that throws synchronously — degrade to the in-memory id.
+    }
+  }
+
+  return registry.keys.get(appId) ?? id;
+};
+
+/** Test-only: forget every auto id + hydration flag so a unit test starts from a clean registry. */
+export const resetAutoDeviceKeys = (): void => {
+  const registry = autoDeviceKeyRegistry();
+  registry.keys.clear();
+  registry.hydrating.clear();
+};

package/src/context/userContext.ts

@@ -23,6 +23,7 @@
  * dependency-free FNV-1a fold (see {@link hashEmailFnv1a}) — no crypto library, no async.
  */
 import { sanitizeUserId } from "../identity/userIdentity";
+import type { WireOnboardingStorage } from "../session/persistedSession";
 
 /**
  * The single, extensible user-context object. A host passes it ONCE (at analytics init) and may
@@ -152,6 +153,78 @@ export const namespaceExtra = (
   return out;
 };
 
+/**
+ * The storage key the analytics façade persists the bound opaque `user_id` under (namespaced per
+ * `appId`, mirroring {@link deviceIdStorageKey}). Exported so a logout path can target it directly.
+ */
+export const analyticsUserIdStorageKey = (appId?: string): string =>
+  `wireai:analytics:userId:${appId ?? "default"}`;
+
+/**
+ * Return a COPY of a {@link WireUserContext} with every USER-scoped (PII / pseudonymous) field
+ * removed — `userId`, `userEmail`, `hashEmail`, and `extra` — while KEEPING the non-PII device-scope
+ * fields (`appVersion`, `deviceKey`). This is the in-memory half of logout: after it, the same
+ * analytics instance keeps its stable `device_key` (which groups a DEVICE, not a user) but no longer
+ * stamps the previous user's id/email onto events. Pure; never mutates the input.
+ */
+export const clearPiiFromContext = (ctx: WireUserContext = {}): WireUserContext => {
+  const rest: WireUserContext = {};
+  if (typeof ctx.appVersion === "string") rest.appVersion = ctx.appVersion;
+  if (typeof ctx.deviceKey === "string") rest.deviceKey = ctx.deviceKey;
+  return rest;
+};
+
+/** Options for {@link clearUserContext}. */
+export interface ClearUserContextOptions {
+  /** Host persistence (AsyncStorage subset) — the persisted bound `user_id` is removed from here. */
+  storage?: WireOnboardingStorage;
+  /** Tenant/app id — namespaces the persisted key (`wireai:analytics:userId:<appId>`). */
+  appId?: string;
+}
+
+/**
+ * LOGOUT primitive: purge the persisted, bound opaque `user_id` for an app so the NEXT user on a
+ * shared device is not silently attributed to the previous one. Removes the
+ * `wireai:analytics:userId:<appId>` key that the analytics façade persists and reuses across
+ * launches. Fire-and-forget: a missing storage or a failing adapter resolves quietly.
+ *
+ * COVERAGE. The stateful `createAnalytics(...)` instance also exposes {@link Analytics.reset}, which
+ * does this AND clears the in-memory binding + PII in one call — prefer it when you hold the
+ * instance. This standalone helper covers the `createWireActivation` / `wire` path (whose config is
+ * captured immutably, so it has no `reset`): call `clearUserContext({ storage, appId })` on logout,
+ * and RECREATE the `wire` / analytics instance without the user's `userContext` (userId/userEmail)
+ * so no further events carry the previous user's identity. The non-PII per-install `device_key`
+ * (`wireai:analytics:deviceKey:<appId>`) is intentionally left in place — it groups a device, not a
+ * person, and stays stable across users of the same install.
+ */
+export const clearUserContext = async (opts: ClearUserContextOptions = {}): Promise<void> => {
+  const storage = opts.storage;
+  if (!storage) return;
+  try {
+    await storage.removeItem(analyticsUserIdStorageKey(opts.appId));
+  } catch {
+    /* best-effort, swallow — logout must never throw into the UI */
+  }
+};
+
+/**
+ * The `userContext` value to hand `<WireOnboarding userContext={...} />` so an onboarding session
+ * and the app's later events (purchases, actions, screens) share ONE join key.
+ *
+ * WHY it exists as a named function instead of an inline object literal: the wire key is
+ * `device_key`, the prop-facing name is `deviceKey`, and the analytics surfaces auto-mint the value
+ * for you. A host that hand-writes `userContext={{ deviceKey }}` produces a bucket the server's
+ * device lookup does not read, and the resulting funnel is silently EMPTY rather than wrong. This is
+ * the one place that spelling is decided.
+ *
+ * Pass the SAME `deviceKey` you gave `createAnalytics` / `createWireActivation`. `session_id` is not
+ * a join key across those two families: an onboarding session id is the A2A `contextId` and an
+ * app-event session id is the per-open id, so intersecting them returns nothing.
+ */
+export const activationJoinContext = (
+  deviceKey: string,
+): Record<string, string | number | boolean> => resolveUserContext({ deviceKey }).userContext ?? {};
+
 /** Options for {@link resolveUserContext}. */
 export interface ResolveUserContextOptions {
   /**

package/src/identity/userIdentity.ts

@@ -44,6 +44,16 @@ export const sanitizeUserId = (raw: unknown): string | undefined => {
   return trimmed.length > USER_ID_MAX_LENGTH ? trimmed.slice(0, USER_ID_MAX_LENGTH) : trimmed;
 };
 
+/**
+ * A permissive email-SHAPE test (`local@domain.tld`) — NOT an RFC validator. Its ONE job is to
+ * catch the common integration mistake of binding a RAW EMAIL as the opaque `user_id`: that leaks
+ * PII into the top-level id (which the server treats as an opaque key and may surface), when the
+ * email belongs in the opt-in `user_context.user_email` field instead. `identify()` uses this to
+ * refuse an email-shaped id (with a dev warning) unless the host opts in explicitly. Trims first.
+ */
+export const looksLikeEmail = (value: unknown): boolean =>
+  typeof value === "string" && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim());
+
 /** Options for {@link identifyOnboarding}. */
 export type IdentifyOnboardingOptions = {
   /** Tenant transport, same shape as `WireOnboardingConfig` (only these two fields are used). */

package/src/index.ts

@@ -141,7 +141,7 @@ export { detectAppVersion } from "./device/appVersion";
 export { detectNativeModel } from "./device/deviceModel";
 
 // ─── User identity (opaque pseudonymous id; late binding, dependency-free) ────
-export { identifyOnboarding, sanitizeUserId, USER_ID_MAX_LENGTH } from "./identity/userIdentity";
+export { identifyOnboarding, sanitizeUserId, looksLikeEmail, USER_ID_MAX_LENGTH } from "./identity/userIdentity";
 export type { IdentifyOnboardingOptions } from "./identity/userIdentity";
 
 // ─── Rich user context (one object → every event's user_context; opt-in email PII) ────
@@ -150,6 +150,10 @@ export {
   namespaceExtra,
   hashEmailFnv1a,
   isWireScalar,
+  clearUserContext,
+  clearPiiFromContext,
+  analyticsUserIdStorageKey,
+  activationJoinContext,
   RESERVED_USER_CONTEXT_KEYS,
   EXTRA_KEY_PREFIX,
 } from "./context/userContext";
@@ -157,12 +161,29 @@ export type {
   WireUserContext,
   ResolvedUserContext,
   ResolveUserContextOptions,
+  ClearUserContextOptions,
 } from "./context/userContext";
-export { mintDeviceId, deviceIdStorageKey, AUTO_DEVICE_ID_PREFIX } from "./context/deviceId";
+export {
+  mintDeviceId,
+  deviceIdStorageKey,
+  AUTO_DEVICE_ID_PREFIX,
+  // `resolveAutoDeviceKey` is the id `createAnalytics` / `createWireActivation` auto-mint and persist.
+  // It MUST be public: the documented purchase↔onboarding join is
+  // `<WireOnboarding userContext={activationJoinContext(deviceKey)} />`, and a host that owns NO device
+  // id of its own had no way to obtain the key the analytics side was already stamping — so its
+  // purchase events carried `wdev_*` while its onboarding session carried no `device_key` at all, and
+  // the join returned the silent zero the README warns about.
+  resolveAutoDeviceKey,
+  resetAutoDeviceKeys,
+} from "./context/deviceId";
+export type { DeviceKeyStorage, ResolveAutoDeviceKeyOptions } from "./context/deviceId";
 
 // ─── Current per-open session registry (identify/app-events reuse the live session) ───
 export {
   getCurrentSessionId,
+  // Returns the registered per-open id, minting + registering one when no app-open has been
+  // registered yet — so no wire path can emit the empty `session_id` the server drops behind a 200.
+  ensureCurrentSessionId,
   setCurrentSessionId,
   resetCurrentSessionId,
 } from "./analytics/currentSession";
@@ -185,6 +206,33 @@ export {
   resetActivationRevalidation,
 } from "./activation";
 
+// ─── RevenueCat (purchase funnel → the same events stream, joined on device_key) ──
+export {
+  createRevenueCatBridge,
+  WIRE_PURCHASE_EVENTS,
+  PLAN_TIER_CONTEXT_KEY,
+  activeEntitlement,
+  describeEntitlement,
+  describeFailure,
+  describePackage,
+  isUserCancelled,
+  resolvePlanTier,
+} from "./revenuecat";
+export type {
+  RevenueCatBridge,
+  RevenueCatBridgeConfig,
+  PurchaseProps,
+  WirePurchaseEventName,
+  PlanTier,
+  RevenueCatCustomerInfoLike,
+  RevenueCatEntitlementLike,
+  RevenueCatErrorLike,
+  RevenueCatOfferingLike,
+  RevenueCatPackageLike,
+  RevenueCatProductLike,
+  RevenueCatSink,
+} from "./revenuecat";
+
 // ─── Session mapping (one `app.session_started` per app-open → /v1/events) ─────
 export {
   reportSessionStart,

package/src/questionnaire/runtime.ts

@@ -5,7 +5,13 @@
  * host that mounted CoachmarkProvider gets questionnaire gating for free - no second storage
  * to wire. Once-per-user is keyed on the questionnaire `id`.
  */
-export { resolveStorage, readInt, writeInt } from "../reviews/runtime";
+export {
+  resolveStorage,
+  readInt,
+  writeInt,
+  bumpSessionCount,
+  currentOpenId,
+} from "../reviews/runtime";
 
 /** Once-gate key. Keyed by app version when `oncePerVersion` is on, so a new release re-enables. */
 export const questionnaireSeenKey = (id: string, version?: string): string =>
@@ -15,6 +21,10 @@ export const questionnaireSeenKey = (id: string, version?: string): string =>
 export const questionnaireLastShownKey = (id: string): string =>
   `wire_questionnaire_${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 questionnaireSessionsKey = (id: string): string =>
   `wire_questionnaire_${id}_sessions`;
+
+/** Companion key holding the open id the counter was LAST incremented for (see `bumpSessionCount`). */
+export const questionnaireSessionOpenKey = (id: string): string =>
+  `wire_questionnaire_${id}_open`;

package/src/questionnaire/transport.ts

@@ -75,7 +75,11 @@ export const fetchQuestionnaireDecision = async (
     const res = await fetch(url, { headers });
     if (!res || !res.ok) return null;
     const json = (await res.json()) as QuestionnaireDecisionResponse | null;
-    return json ?? null;
+    // A body without a boolean `fire` is not a decision. Guard it explicitly (mirrors
+    // `fetchReviewDecision`) rather than letting `{}` through as a truthy object a gate would treat
+    // as a verdict (`{}.fire === undefined` is falsy, so it would silently read as "never fire").
+    if (!json || typeof json.fire !== "boolean") return null;
+    return json;
   } catch {
     /* unreachable / non-2xx / bad JSON / missing-fetch - never show */
     return null;

package/src/questionnaire/useQuestionnaireGate.ts

@@ -20,8 +20,10 @@ import { useResolvedFeatures } from "../features/WireFeaturesProvider";
 import { sameDecision, shallowEqual } from "../reviews/equality";
 import { decideQuestionnaire, evaluateGate, resolveRules } from "./decision";
 import {
+  bumpSessionCount,
   questionnaireLastShownKey,
   questionnaireSeenKey,
+  questionnaireSessionOpenKey,
   questionnaireSessionsKey,
   readInt,
   resolveStorage,
@@ -71,14 +73,14 @@ export const useQuestionnaireGate = ({
   );
   const lastKey = questionnaireLastShownKey(config.id);
   const sessionsKey = questionnaireSessionsKey(config.id);
+  const sessionOpenKey = questionnaireSessionOpenKey(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 — see the same note
+  // in `useReviewGate`; `bumpSessionCount` keys off the live per-open session id, so a remount or a
+  // StrictMode double-invoke of this initializer reads the same number back instead of inflating it.
+  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/revenuecat/index.ts

@@ -0,0 +1,55 @@
+/**
+ * revenuecat - the drop-in RevenueCat to Wire activation path.
+ *
+ * Re-exported from the main `@wireai/activation` barrel (no separate subpath): it is a pure,
+ * dependency-free mapping layer with no UI, so it costs an analytics-only consumer nothing.
+ *
+ * Adopting it is a constructor plus your existing paywall call sites:
+ *
+ *   import { createAnalytics, createRevenueCatBridge, activationJoinContext } from "@wireai/activation";
+ *
+ *   const analytics = createAnalytics({ serverUrl, apiKey, storage, userContext: { deviceKey } });
+ *   const revenuecat = createRevenueCatBridge({ analytics, entitlementId: "pro" });
+ *
+ *   revenuecat.paywallShown(offering, { source: variant });
+ *   revenuecat.checkoutStarted(pkg, { source: variant });
+ *   const entitled = revenuecat.purchaseCompleted(customerInfo, pkg, { source: variant });
+ *
+ * And the join that makes the numbers real, on the onboarding side:
+ *
+ *   <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
+ *
+ * See `revenueCatBridge.ts` for why that key is `device_key` and never `session_id`.
+ */
+
+// ─── The bridge (the thing you wire) ──────────────────────────────────────────
+export { createRevenueCatBridge } from "./revenueCatBridge";
+export type {
+  RevenueCatBridge,
+  RevenueCatBridgeConfig,
+  PurchaseProps,
+} from "./revenueCatBridge";
+
+// ─── Canonical purchase-funnel names + the pure mappers behind the bridge ─────
+export {
+  WIRE_PURCHASE_EVENTS,
+  PLAN_TIER_CONTEXT_KEY,
+  activeEntitlement,
+  describeEntitlement,
+  describeFailure,
+  describePackage,
+  isUserCancelled,
+  resolvePlanTier,
+} from "./purchaseEvents";
+export type { WirePurchaseEventName, PlanTier } from "./purchaseEvents";
+
+// ─── Structural mirrors of the react-native-purchases shapes (no native dep) ──
+export type {
+  RevenueCatCustomerInfoLike,
+  RevenueCatEntitlementLike,
+  RevenueCatErrorLike,
+  RevenueCatOfferingLike,
+  RevenueCatPackageLike,
+  RevenueCatProductLike,
+  RevenueCatSink,
+} from "./types";