@wireai/activation 0.11.0 → 0.12.1

package/src/analytics/reportClientEvent.ts

@@ -128,6 +128,48 @@ export 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.
+ *
+ * DEV-GATED FIRST: the `__DEV__` check is the FIRST statement, before the body is even looked at.
+ * The check used to sit inside the `.then`, so a release build parsed the JSON of every
+ * persistent-path POST to build a warning no one would ever read. Nothing here runs in production.
+ */
+export const warnOnSkippedEvents = (res: unknown): void => {
+  if (typeof __DEV__ === "undefined" || !__DEV__) return;
+  if (typeof console === "undefined" || !console.warn) return;
+  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;
+        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/coachmarks/runtime.ts

@@ -8,35 +8,71 @@
  * the root by `CoachmarkProvider`. Singletons let a hook read the gate without
  * every call site threading the storage through props. The provider is still the
  * single writer — it calls `setCoachmarkStorage` / `setCoachmarkTesting` on mount.
+ *
+ * ── WHY A globalThis SLOT, NOT PLAIN MODULE VARIABLES ─────────────────────────────────────────
+ * These three values used to be plain module `let`s, and this module is inlined by tsup into FOUR
+ * dist bundles (`./coachmarks`, `./reviews`, `./questionnaire`, `./showcase`). Under `dist`
+ * resolution — node `import`/`require`, SSR, jest, RN-web, anything that is not Metro — a host that
+ * mounts `CoachmarkProvider` from `@wireai/activation/coachmarks` wrote the COACHMARKS copy, while
+ * `useReviewGate` from `@wireai/activation/reviews` read the REVIEWS copy, which was still `null`.
+ * Everything downstream then failed silently: `readInt(null, …)` returns 0, so `bumpSessionCount`
+ * returns 1 forever and the fail-closed `minSessions: 2` default is unsatisfiable (the gate NEVER
+ * fires); the `seen` once-gate never persists; and a tenant's coachmarks kill switch never reaches
+ * the reviews bundle. Metro masked it by collapsing every subpath back to one `src/` file through
+ * the `react-native` export condition, which is a bundler accident, not a guarantee.
+ *
+ * Same remedy this repo already applies to `currentSession`, the auto device-key registry and the
+ * activation revalidation counter: ONE record in a `globalThis` slot keyed by `Symbol.for(...)`, so
+ * every inlined copy of this module addresses the SAME state.
  */
 import type { CoachmarkStorage } from "./types";
 
-let storageSingleton: CoachmarkStorage | null = null;
-let testing = false;
-// The coachmarks feature kill switch (from GET /v1/features). Default true = fail-open: with no
-// flags fetched, coachmarks behave exactly as before. CoachmarkProvider writes it from the
-// resolved flags. Disabled → the tour never ARMS and the overlay `show()` is a no-op, so nothing
-// paints and — critically — no once-gate is written, so re-enabling replays the tour correctly.
-let coachmarksEnabled = true;
+/** Well-known key into the runtime-global symbol registry — one coachmark runtime across bundles. */
+const COACHMARK_RUNTIME_SLOT: unique symbol = Symbol.for("@wireai/activation:coachmarkRuntime");
+
+/** The shared runtime: the provider-injected storage, the QA replay flag, and the kill switch. */
+type CoachmarkRuntime = {
+  storage: CoachmarkStorage | null;
+  testing: boolean;
+  // The coachmarks feature kill switch (from GET /v1/features). Default true = fail-open: with no
+  // flags fetched, coachmarks behave exactly as before. CoachmarkProvider writes it from the
+  // resolved flags. Disabled → the tour never ARMS and the overlay `show()` is a no-op, so nothing
+  // paints and — critically — no once-gate is written, so re-enabling replays the tour correctly.
+  coachmarksEnabled: boolean;
+};
+
+type GlobalWithCoachmarkRuntime = typeof globalThis & {
+  [COACHMARK_RUNTIME_SLOT]?: CoachmarkRuntime;
+};
+
+const runtimeGlobal = globalThis as GlobalWithCoachmarkRuntime;
+
+const coachmarkRuntime = (): CoachmarkRuntime => {
+  const existing = runtimeGlobal[COACHMARK_RUNTIME_SLOT];
+  if (existing) return existing;
+  const created: CoachmarkRuntime = { storage: null, testing: false, coachmarksEnabled: true };
+  runtimeGlobal[COACHMARK_RUNTIME_SLOT] = created;
+  return created;
+};
 
 /**
  * Set the coachmarks master switch (from the resolved feature flags). Default true (fail-open).
  * Written by CoachmarkProvider; read imperatively by the tour arm + the overlay store.
  */
 export const setCoachmarksEnabled = (value: boolean): void => {
-  coachmarksEnabled = value;
+  coachmarkRuntime().coachmarksEnabled = value;
 };
 
 /** Whether the coachmarks module is enabled. False → tours/overlays are silently skipped. */
-export const areCoachmarksEnabled = (): boolean => coachmarksEnabled;
+export const areCoachmarksEnabled = (): boolean => coachmarkRuntime().coachmarksEnabled;
 
 /** Set (or clear) the injected sync gate storage. Called by CoachmarkProvider. */
 export const setCoachmarkStorage = (storage: CoachmarkStorage | null): void => {
-  storageSingleton = storage;
+  coachmarkRuntime().storage = storage;
 };
 
 /** The currently-injected gate storage, or null if no provider is mounted. */
-export const getCoachmarkStorage = (): CoachmarkStorage | null => storageSingleton;
+export const getCoachmarkStorage = (): CoachmarkStorage | null => coachmarkRuntime().storage;
 
 /**
  * Toggle the global QA replay flag. When true, EVERY seen-gate reads as unseen
@@ -44,11 +80,11 @@ export const getCoachmarkStorage = (): CoachmarkStorage | null => storageSinglet
  * mount. The app flips ONE boolean to QA the whole coachmark surface.
  */
 export const setCoachmarkTesting = (value: boolean): void => {
-  testing = value;
+  coachmarkRuntime().testing = value;
 };
 
 /** Whether replay-everything QA mode is on. */
-export const isCoachmarkTesting = (): boolean => testing;
+export const isCoachmarkTesting = (): boolean => coachmarkRuntime().testing;
 
 /** Gate key for a tour: `wire_coachmark_<tourId>_seen`. */
 export const coachmarkGateKey = (tourId: string): string =>
@@ -73,8 +109,8 @@ export const hasSeenGate = (
   storageOverride?: CoachmarkStorage | null,
   testingOverride?: boolean,
 ): boolean => {
-  if (testingOverride ?? testing) return false;
-  const storage = storageOverride ?? storageSingleton;
+  if (testingOverride ?? isCoachmarkTesting()) return false;
+  const storage = storageOverride ?? getCoachmarkStorage();
   if (!storage) return false;
   try {
     return storage.getItem(key) === SEEN_VALUE;
@@ -92,8 +128,8 @@ export const markSeenGate = (
   storageOverride?: CoachmarkStorage | null,
   testingOverride?: boolean,
 ): void => {
-  if (testingOverride ?? testing) return;
-  const storage = storageOverride ?? storageSingleton;
+  if (testingOverride ?? isCoachmarkTesting()) return;
+  const storage = storageOverride ?? getCoachmarkStorage();
   if (!storage) return;
   try {
     storage.setItem(key, SEEN_VALUE);

package/src/config/wireConfigFromEnv.ts

@@ -12,12 +12,31 @@
  *   return <WireOnboarding config={config} ... />;
  *
  * `appId` defaults to `EXPO_PUBLIC_WIREAI_APP_ID` (or "default"); pass overrides to
- * set `appId`/`metadata` or to substitute the key/URL programmatically.
+ * set `appId`/`metadata` or to substitute the key/URL programmatically. `appVersion`
+ * defaults to `detectAppVersion()` so every surface built from this config carries it.
  */
+import { detectAppVersion } from "../device/appVersion";
 import type { WireOnboardingConfig } from "../types";
 
 export type WireConfigOverrides = Partial<WireOnboardingConfig>;
 
+/** The env vars this helper reads. Exported so a host preflight can assert them itself. */
+export const WIRE_ENV_VARS = [
+  "EXPO_PUBLIC_WIREAI_API_KEY",
+  "EXPO_PUBLIC_WIREAI_SERVER_URL",
+  "EXPO_PUBLIC_WIREAI_APP_ID",
+] as const;
+
+/** RN sets this global; absent under node/SSR. Read defensively via {@link warnInDev}. */
+declare const __DEV__: boolean | undefined;
+
+/** Emit a one-line developer warning, but ONLY in a dev build (RN `__DEV__`). No-op in prod/tests. */
+const warnInDev = (message: string): void => {
+  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+    console.warn(message);
+  }
+};
+
 /**
  * Minimal `process.env` declaration so the kit stays RN-pure (no `@types/node`).
  * In RN/Expo, `process.env.EXPO_PUBLIC_*` is provided/inlined by Metro at build
@@ -41,12 +60,37 @@ export const wireConfigFromEnv = (
     overrides?.appId ?? process.env.EXPO_PUBLIC_WIREAI_APP_ID ?? "default";
 
   // Missing transport → null, so the host gates on one falsy check.
-  if (!apiKey || !serverUrl) return null;
+  //
+  // The `null` return is the CORRECT contract and hosts rely on it — but it is also the quietest
+  // failure the kit has: a missing EAS env var makes this return null, and then the facade never
+  // constructs, `useLifecycleEvents` no-ops on `!cfg?.serverUrl`, and every gate returns null. Wire
+  // is 100% off, with no error anywhere. Name it once in dev, and name WHICH var is missing.
+  if (!apiKey || !serverUrl) {
+    const missing = [
+      apiKey ? undefined : "EXPO_PUBLIC_WIREAI_API_KEY",
+      serverUrl ? undefined : "EXPO_PUBLIC_WIREAI_SERVER_URL",
+    ].filter(Boolean);
+    warnInDev(
+      `[wireai] wireConfigFromEnv() returned null: ${missing.join(" and ")} ${
+        missing.length > 1 ? "are" : "is"
+      } missing. The kit is now FULLY DISABLED (no onboarding, no analytics, no gates) and nothing ` +
+        "else will report an error. Set the var(s) in your env / EAS secrets.",
+    );
+    return null;
+  }
+
+  // `appVersion` is part of `WireOnboardingConfig`, but this helper could not carry it — so a host
+  // that built its config here forwarded `config.appVersion === undefined` to every surface. The
+  // facade and the lifecycle path each auto-detect their own fallback; `createWireActivation` does
+  // not, so every `wire.track` event shipped with no `app_version` at all. Detect once here (an
+  // explicit override still wins) and the whole config carries it.
+  const appVersion = overrides?.appVersion ?? detectAppVersion();
 
   return {
     apiKey,
     serverUrl,
     appId,
+    ...(appVersion ? { appVersion } : {}),
     ...(overrides?.metadata ? { metadata: overrides.metadata } : {}),
   };
 };

package/src/context/deviceId.ts

@@ -41,3 +41,176 @@ 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: the storage read is async, so an event emitted in the milliseconds before
+// hydration completes carries 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. A caller that can afford to
+// wait (the lifecycle hook's mount effect — see `hydrateAutoDeviceKey`) should await instead: its two
+// events are the ONLY ones the server counts `min_sessions` from, so a per-launch id there is not a
+// millisecond of noise, it is a counter that can never exceed 1.
+
+/** 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`, the set of appIds whose hydration already started,
+ *  and the in-flight (or settled) hydration promise per `appId` so a waiter can join it. */
+type AutoDeviceKeyRegistry = {
+  keys: Map<string, string>;
+  hydrating: Set<string>;
+  pending?: Map<string, Promise<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;
+}
+
+/**
+ * Start (or join) the SINGLE-FLIGHT storage read for `appId` and resolve to the id it settles on.
+ * The promise is parked on the registry so a later `hydrateAutoDeviceKey` awaits the SAME read
+ * instead of starting a second one. Never rejects: any storage failure resolves to the live id.
+ */
+const startHydration = (
+  registry: AutoDeviceKeyRegistry,
+  appId: string,
+  storage: DeviceKeyStorage,
+  minted: string,
+): Promise<string> => {
+  if (!registry.pending) registry.pending = new Map();
+  const existing = registry.pending.get(appId);
+  if (existing) return existing;
+
+  const slot = deviceIdStorageKey(appId);
+  const settled = (): string => registry.keys.get(appId) ?? minted;
+  let run: Promise<string>;
+  try {
+    run = Promise.resolve(storage.getItem(slot))
+      .then((saved) => {
+        const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : undefined;
+        if (persisted) {
+          registry.keys.set(appId, persisted);
+          return persisted;
+        }
+        // First run on this install: persist the id we just minted so the next launch adopts it.
+        return Promise.resolve(storage.setItem(slot, minted)).then(settled, settled);
+      })
+      .catch(settled);
+  } catch {
+    // A storage adapter that throws synchronously — degrade to the in-memory id.
+    run = Promise.resolve(settled());
+  }
+  registry.pending.set(appId, run);
+  return run;
+};
+
+/**
+ * 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);
+    void startHydration(registry, appId, storage, id);
+  }
+
+  return registry.keys.get(appId) ?? id;
+};
+
+/**
+ * The AWAITABLE sibling of {@link resolveAutoDeviceKey}: resolve to the auto `device_key` AFTER the
+ * persisted id has been read back (or written, on a first run), so the caller stamps the id this
+ * install will keep rather than the one that was minted a millisecond ago.
+ *
+ * WHY IT EXISTS: `resolveAutoDeviceKey` is synchronous by contract, so a caller firing at mount got
+ * the freshly minted id and the persisted one landed milliseconds later. For most events that is
+ * noise. For `app.session_started` it is the whole metric: the server computes `min_sessions` by
+ * counting distinct opens grouped by `device_key`, so a per-launch key there makes the counter
+ * structurally incapable of exceeding 1, and it splits `first_open` off from every event that
+ * follows it. Only a caller that can afford one storage read should use this; the fire-and-forget
+ * event paths must stay on the sync function.
+ *
+ * Never throws or rejects: a missing, hung, or rejecting adapter resolves to the in-memory id, and
+ * with no `storage` it resolves immediately (there is nothing to hydrate from).
+ */
+export const hydrateAutoDeviceKey = async (
+  opts: ResolveAutoDeviceKeyOptions = {},
+): Promise<string> => {
+  // Mint + register synchronously first, so a waiter and a concurrent sync caller share ONE id.
+  const id = resolveAutoDeviceKey(opts);
+  if (!opts.storage) return id;
+  const registry = autoDeviceKeyRegistry();
+  const appId = opts.appId ?? "default";
+  const pending = registry.pending?.get(appId);
+  if (pending) await pending;
+  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();
+  registry.pending?.clear();
+};

package/src/context/userContext.ts

@@ -207,6 +207,24 @@ export const clearUserContext = async (opts: ClearUserContextOptions = {}): Prom
   }
 };
 
+/**
+ * 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/index.ts

@@ -109,7 +109,12 @@ export type {
 } from "./features";
 
 // ─── Config + env helpers ─────────────────────────────────────────────────────
-export { wireConfigFromEnv } from "./config/wireConfigFromEnv";
+export {
+  wireConfigFromEnv,
+  // The three `EXPO_PUBLIC_WIREAI_*` names, so a host preflight can assert its own env instead of
+  // discovering a missing var as a silently disabled kit (`wireConfigFromEnv` returns null).
+  WIRE_ENV_VARS,
+} from "./config/wireConfigFromEnv";
 export type { WireConfigOverrides } from "./config/wireConfigFromEnv";
 export { isOnboardingEnabled } from "./config/onboardingFlag";
 export type { OnboardingFlagOptions } from "./config/onboardingFlag";
@@ -153,6 +158,7 @@ export {
   clearUserContext,
   clearPiiFromContext,
   analyticsUserIdStorageKey,
+  activationJoinContext,
   RESERVED_USER_CONTEXT_KEYS,
   EXTRA_KEY_PREFIX,
 } from "./context/userContext";
@@ -162,11 +168,30 @@ export type {
   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,
+  // The awaitable sibling: resolves AFTER the persisted id has been read back, for a caller that can
+  // afford one storage read and must not stamp a key minted a millisecond ago (the lifecycle mount).
+  hydrateAutoDeviceKey,
+  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";
@@ -189,6 +214,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,14 @@
  * 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,
+  warnMissingGateStorage,
+} 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 +22,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/useQuestionnaireGate.ts

@@ -20,11 +20,14 @@ 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,
+  warnMissingGateStorage,
   writeInt,
 } from "./runtime";
 import type {
@@ -71,13 +74,17 @@ 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.
+  // 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(() => {
     const store = resolveStorage(storage);
-    const next = readInt(store, sessionsKey) + 1;
-    writeInt(store, sessionsKey, next);
-    return next;
+    // Same as `useReviewGate`: no storage means the counter never leaves 1, so the fail-closed
+    // minSessions rule is unsatisfiable and the gate silently never fires. Dev-only, once per process.
+    warnMissingGateStorage(store, "questionnaire");
+    return bumpSessionCount(store, sessionsKey, sessionOpenKey);
   })[0];
 
   // Gate the local rules behind an optional client-side timeout, so a reachable server gets a