@wireai/activation 0.11.0 → 0.12.0

package/dist/{transport-BGW9uXZJ.d.mts → transport-CF_eHwzC.d.mts}

@@ -94,7 +94,11 @@ interface FetchReviewDecisionOptions {
 declare const fetchReviewDecision: (target: ReviewTarget | undefined, options?: FetchReviewDecisionOptions) => Promise<ReviewDecisionResponse | null>;
 /** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */
 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;
@@ -107,6 +111,16 @@ 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).
  */
 declare const reportAppEvent: (target: ReviewTarget | undefined, name: string, options?: ReportAppEventOptions) => void;
 

package/dist/{transport-jUJd5kxu.d.ts → transport-DsRe4epC.d.ts}

@@ -94,7 +94,11 @@ interface FetchReviewDecisionOptions {
 declare const fetchReviewDecision: (target: ReviewTarget | undefined, options?: FetchReviewDecisionOptions) => Promise<ReviewDecisionResponse | null>;
 /** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */
 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;
@@ -107,6 +111,16 @@ 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).
  */
 declare const reportAppEvent: (target: ReviewTarget | undefined, name: string, options?: ReportAppEventOptions) => void;
 

package/llms.txt

@@ -31,6 +31,7 @@ The package is more than `<WireOnboarding>`. Tree-shakeable subpath exports (eac
 - `@wireai/activation/analytics`: `createAnalytics({ serverUrl, apiKey, storage })` (Segment/PostHog-shaped `track` / `screen` / `identify` / `setUserContext` / `reset` over an offline-first queue), `createScreenTracker` / `screenTrackingHandler` (auto screen views), `reportAppEvent`, `createEventQueue`, `clearUserContext` (logout). Rich `WireUserContext` supports an opt-in `userEmail` (raw by default, `hashEmail` to fold) and auto-mints a persisted per-install `device_key`. `identify` refuses email-shaped ids unless `allowEmailAsUserId`. See the README "Rich user context & PII" section.
 - `@wireai/activation/reviews`: the in-app review gate. `useReviewGate`, `fetchReviewDecision` (server AI seam; a `{fire:false}` survives intact), `ReviewGate` UI. `minSessions` defaults to 2 (never prompts on the first session; a server decision still overrides).
 - `@wireai/activation/questionnaire`: the pre-onboarding questionnaire gate. `useQuestionnaireGate`, `fetchQuestionnaireDecision` (same server seam; a body without a boolean `fire` resolves to null, never shows).
+- `createRevenueCatBridge({ analytics, entitlementId })` (ROOT-exported) → the RevenueCat purchase funnel: `paywallShown` / `checkoutStarted` / `purchaseCompleted` / `purchaseFailed` / `purchasesRestored` / `syncPlanTier`, emitting the canonical `wire_paywall_shown` / `wire_checkout_started` / `wire_purchase_completed` / `wire_purchase_failed` / `wire_purchase_restored` names. The kit does NOT depend on `react-native-purchases` (a native module); the RevenueCat objects are typed structurally, so a host passes the real ones. THE JOIN KEY between a purchase and an onboarding is `user_context.device_key`, never `session_id` (an onboarding session id is the A2A contextId, an app-event session id is the per-open id, and they are separate spaces): pass the same device key to `createAnalytics`/`createWireActivation` AND to `<WireOnboarding userContext={activationJoinContext(deviceKey)} />`.
 - `useWireActivation({ serverUrl, apiKey, deviceKey? })` → `{ track, sessionId, revalidation }` (ROOT-exported; React-free factory `createWireActivation(config)`). `await track(name, meta?)` POSTs an `app_event` (`question_key=name`) under the current session, resolves `true` on 2xx, and bumps `revalidation`; list `revalidation` in a `fetchReviewDecision` / `fetchQuestionnaireDecision` effect's deps so a review/questionnaire gate re-fetches and fires off an in-app action instead of the host hand-rolling session-id + await-POST + revalidate.
 
 ## Files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",

package/src/activation/useWireActivation.ts

@@ -59,7 +59,18 @@ export const useWireActivation = (config: WireActivationConfig): UseWireActivati
   const ref = useRef<WireActivation | undefined>(undefined);
   const prevKeys = useRef<string>("");
 
-  const currentKeys = `${config.serverUrl}|${config.apiKey}|${config.appId}|${config.deviceKey}`;
+  // The identity of the built instance. `userContext.deviceKey` MUST be in here: `createWireActivation`
+  // honors it as an explicit device key (`config.deviceKey ?? config.userContext?.deviceKey`), so a host
+  // that hydrates its device id asynchronously and passes it only inside `userContext` would otherwise
+  // keep an instance frozen on the first render's `undefined` — the stale-static-ref failure this repo
+  // has already been bitten by (see .memory/70-knowledge.md, "Stale Option Closures in Static Refs").
+  const currentKeys = [
+    config.serverUrl,
+    config.apiKey,
+    config.appId,
+    config.deviceKey,
+    config.userContext?.deviceKey,
+  ].join("|");
   if (!ref.current || prevKeys.current !== currentKeys) {
     prevKeys.current = currentKeys;
     ref.current = createWireActivation(config);

package/src/activation/wireActivation.ts

@@ -12,7 +12,7 @@
  *   await wire.track("journal_done");                            // awaitable POST + auto-revalidate
  *
  * `track` POSTs `event_type='app_event'`, `question_key=<name>` (the EXACT string a review /
- * questionnaire firing TRIGGER matches on) under the CURRENT `getCurrentSessionId()` — the same id
+ * questionnaire firing TRIGGER matches on) under the CURRENT `ensureCurrentSessionId()` — the same id
  * the gates pass to their `/decision` fetch, so the server's session-scoped trigger rule agrees —
  * with `user_context.device_key` for the min-sessions / arm-assignment lookups. On a successful POST
  * it bumps decision revalidation so a subscribed gate re-fetches and can fire.
@@ -22,13 +22,13 @@
  * and `getCurrentSessionId` — it introduces NO second session concept and duplicates no POST path.
  * React-free (the optional React glue is the thin `useWireActivation` hook).
  */
-import { getCurrentSessionId } from "../analytics/currentSession";
+import { ensureCurrentSessionId, getCurrentSessionId } from "../analytics/currentSession";
 import {
   reportClientEventAwait,
   type ClientEvent,
   type ClientEventTarget,
 } from "../analytics/reportClientEvent";
-import { deviceIdStorageKey, mintDeviceId } from "../context/deviceId";
+import { resolveAutoDeviceKey, type ResolveAutoDeviceKeyOptions } from "../context/deviceId";
 import { resolveUserContext, type WireUserContext } from "../context/userContext";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import {
@@ -78,8 +78,14 @@ export type WireActivation = {
   /**
    * Awaitable action report: POST `event_type='app_event'`, `question_key=<name>`, optional `meta`,
    * under the CURRENT session id + `user_context.device_key`. Resolves `true` once the server has
-   * stored it (2xx) and THEN bumps decision revalidation; resolves `false` (no bump) when there is no
-   * current session, a blank name, or the POST fails. Never throws.
+   * stored it (2xx) and THEN bumps decision revalidation; resolves `false` (no bump) for a blank
+   * name or a failed POST. Never throws.
+   *
+   * It no longer refuses when no app-open has been registered: the session id is resolved through
+   * `ensureCurrentSessionId()`, which mints and registers one in that case (the server requires a
+   * non-empty `session_id` and silently drops an event without one, so bailing lost the action
+   * entirely). A host that fires `reportSessionStart` / `useLifecycleEvents` first is unaffected —
+   * the real per-open id is already registered and gets used exactly as before.
    */
   track(name: string, meta?: Record<string, unknown>): Promise<boolean>;
   /** The CURRENT per-open session id (the kit's canonical `getCurrentSessionId()`), or `undefined`. */
@@ -98,27 +104,28 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
   const target: ClientEventTarget = { serverUrl: config.serverUrl, apiKey: config.apiKey };
 
   // Device key: an explicit id (top-level or in userContext) wins and is never overwritten; otherwise
-  // auto-mint ONE and persist via storage (reused every open) so `device_key` is always present.
+  // read the ONE process-wide auto id (`resolveAutoDeviceKey`) so this instance and a sibling
+  // `createAnalytics` instance carry the SAME `device_key` for the same install. Minting locally here
+  // gave one install two auto ids — see the registry note in context/deviceId.ts.
   const explicitDeviceKey = clean(config.deviceKey) ?? clean(config.userContext?.deviceKey);
-  let autoDeviceKey = explicitDeviceKey ?? mintDeviceId();
-  if (config.storage && !explicitDeviceKey) {
-    const storage = config.storage;
-    const key = deviceIdStorageKey(config.appId);
-    void storage
-      .getItem(key)
-      .then((saved) => {
-        const persisted = clean(saved ?? undefined);
-        if (persisted) autoDeviceKey = persisted;
-        else void storage.setItem(key, autoDeviceKey).catch(() => {});
-      })
-      .catch(() => {});
-  }
+  const autoDeviceKeyOptions: ResolveAutoDeviceKeyOptions = {
+    appId: config.appId,
+    // An explicit key opts out of minting AND persisting (unchanged contract).
+    storage: explicitDeviceKey ? undefined : config.storage,
+  };
+  // Start hydration AT CONSTRUCTION (not at the first `track`) so the persisted id is adopted as early
+  // as it used to be. The return value is deliberately discarded — every event re-resolves.
+  if (!explicitDeviceKey) resolveAutoDeviceKey(autoDeviceKeyOptions);
 
   // Stamp the resolved rich context onto the event: `user_context` bucket (device_key always, plus any
   // app_version / opt-in user_email / namespaced extra) and the top-level opaque `user_id`.
   const applyContext = (event: ClientEvent): void => {
     const resolved = resolveUserContext(
-      { ...(config.userContext ?? {}), deviceKey: explicitDeviceKey ?? autoDeviceKey },
+      // `??` is lazy on purpose: an explicit key must never even touch the auto registry.
+      {
+        ...(config.userContext ?? {}),
+        deviceKey: explicitDeviceKey ?? resolveAutoDeviceKey(autoDeviceKeyOptions),
+      },
       { autoAppVersion: config.appVersion },
     );
     if (resolved.userContext) {
@@ -128,10 +135,15 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
   };
 
   const track = async (name: string, meta?: Record<string, unknown>): Promise<boolean> => {
-    const sessionId = getCurrentSessionId();
-    // No current session (no app-open registered yet) or a blank name → nothing to correlate; bail
-    // WITHOUT bumping (a bump with no posted event would only make the gate re-fetch for nothing).
-    if (!clean(name) || !sessionId) return false;
+    // A blank name is the only thing left to refuse on: there is no `question_key` to match a
+    // firing trigger against, so bail WITHOUT bumping (a bump with no posted event would only make
+    // the gate re-fetch for nothing).
+    if (!clean(name)) return false;
+    // No app-open registered is NOT a reason to drop the action. `ensureCurrentSessionId` returns
+    // the registered per-open id when there is one (the unchanged path) and otherwise mints +
+    // registers one, so the POST always carries the non-empty `session_id` the server requires
+    // instead of being accepted with a 200 and discarded.
+    const sessionId = ensureCurrentSessionId();
     const event: ClientEvent = {
       event_type: "app_event",
       session_id: sessionId,

package/src/analytics/analyticsFacade.ts

@@ -36,7 +36,8 @@ import {
   resolveUserContext,
   type WireUserContext,
 } from "../context/userContext";
-import { mintDeviceId, deviceIdStorageKey } from "../context/deviceId";
+import { resolveAutoDeviceKey, type ResolveAutoDeviceKeyOptions } from "../context/deviceId";
+import { detectAppVersion } from "../device/appVersion";
 import { looksLikeEmail, sanitizeUserId } from "../identity/userIdentity";
 
 /** RN sets this global; absent under node/SSR. Read defensively via {@link warnInDev}. */
@@ -63,8 +64,14 @@ export type CreateAnalyticsConfig = {
   /** Tenant API key; sent as `Authorization: Bearer`. */
   apiKey: string;
   /**
-   * Correlation id shared by every event from this instance (and the `identify` event). Defaults
-   * to a fresh `makeSessionId()` at creation so all events agree on one id per analytics instance.
+   * ⚠️ OPT-OUT KNOB, not a default. Supplying a `sessionId` FREEZES the correlation id: every event
+   * this instance ever sends (including `identify`) is pinned to that one id, and the instance stops
+   * following the LIVE per-open session the server registered via `app.session_started`. Lifecycle
+   * analytics then collapse onto a single device-scoped session — one "first open", forever.
+   *
+   * OMIT IT — that is the correct default. Without it the kit reuses the live per-open session, and
+   * falls back to a stable per-instance id only until an open has been registered. Pass one ONLY if
+   * your host runs its own session lifecycle and owns the id the server should correlate on.
    */
   sessionId?: string;
   /** Tenant/app id used to namespace the queue's default storage key (`wireai:evtq:<appId>`). */
@@ -162,6 +169,22 @@ export const createAnalytics = (
   const resolveSessionId = (): string =>
     config.sessionId ?? getCurrentSessionId() ?? instanceSessionId;
 
+  // A frozen id is almost always a mistake (it silently flattens every open into ONE session), so
+  // name it once at construction — same dev-only channel as the email-shape guard below.
+  if (config.sessionId) {
+    warnInDev(
+      "[wireai] createAnalytics({ sessionId }) PINS every event from this instance to that one " +
+        "frozen id and opts out of the live per-open session (app.session_started) — lifecycle " +
+        "analytics collapse onto a single device-scoped id. Remove it unless your host runs its " +
+        "own session lifecycle.",
+    );
+  }
+
+  // The auto-detected host app version, read ONCE here (cheap, sync, never throws). It backs the
+  // `user_context.app_version` fallback below: without it a host that passes no `config.appVersion`
+  // got the detected version on `device.appVersion` only, leaving the user_context field absent.
+  const detectedAppVersion = detectAppVersion();
+
   // The mutable rich user-context: seeded at init, updated via `setUserContext`. Resolved fresh on
   // every event so a post-mount update (login) takes effect immediately. Declared before the envelope
   // provider so the provider can read the current `userContext.appVersion` (see below).
@@ -177,21 +200,18 @@ export const createAnalytics = (
     typeof config.userContext?.deviceKey === "string" && config.userContext.deviceKey.trim()
       ? config.userContext.deviceKey.trim()
       : undefined;
-  // Minted synchronously so `device_key` is never missing, even before the async storage read resolves.
-  let autoDeviceKey = mintDeviceId();
-  if (config.storage && !hostDeviceKeyAtInit) {
-    const storage = config.storage;
-    const deviceKey = deviceIdStorageKey(config.appId);
-    void storage
-      .getItem(deviceKey)
-      .then((saved) => {
-        const persisted = typeof saved === "string" && saved.trim() ? saved.trim() : undefined;
-        // Reuse the persisted per-install id across opens; on first run persist the freshly minted one.
-        if (persisted) autoDeviceKey = persisted;
-        else void storage.setItem(deviceKey, autoDeviceKey).catch(() => {});
-      })
-      .catch(() => {});
-  }
+  // The auto id comes from the ONE process-wide registry (`resolveAutoDeviceKey`), NOT a mint local to
+  // this instance. A host that also builds a `createWireActivation` instance used to get a SECOND,
+  // different auto id for the same install, splitting `device_key` across two id spaces — see the
+  // registry note in context/deviceId.ts. Resolved lazily per event so hydration is picked up.
+  const autoDeviceKeyOptions: ResolveAutoDeviceKeyOptions = {
+    appId: config.appId,
+    // A host-supplied deviceKey opts out of minting AND persisting (unchanged contract).
+    storage: hostDeviceKeyAtInit ? undefined : config.storage,
+  };
+  // Start hydration AT CONSTRUCTION (not at the first event) so the persisted id is adopted as early
+  // as it used to be. The return value is deliberately discarded — every event re-resolves.
+  if (!hostDeviceKeyAtInit) resolveAutoDeviceKey(autoDeviceKeyOptions);
 
   // A provider (not a fixed value) so `networkType`, the current session id, AND the effective app
   // version are evaluated fresh on every enqueue. An explicit `WireUserContext.appVersion` (a host that
@@ -241,8 +261,9 @@ export const createAnalytics = (
         ? userContext.deviceKey
         : undefined;
     const resolved = resolveUserContext(
-      { ...userContext, deviceKey: hostDeviceKey ?? autoDeviceKey },
-      { autoAppVersion: config.appVersion },
+      // `??` is lazy on purpose: a host-supplied key must never even touch the auto registry.
+      { ...userContext, deviceKey: hostDeviceKey ?? resolveAutoDeviceKey(autoDeviceKeyOptions) },
+      { autoAppVersion: config.appVersion ?? detectedAppVersion },
     );
     if (resolved.userContext) {
       event.user_context = { ...resolved.userContext, ...(event.user_context ?? {}) };

package/src/analytics/currentSession.ts

@@ -32,7 +32,22 @@
  * PROCESS-LOCAL, NOT PERSISTED: the slot lives on the runtime global, so it tracks the CURRENT
  * process's open and a fresh open overwrites it. There is no cross-launch state.
  * `resetCurrentSessionId` clears the slot so a unit test starts from a clean registry.
+ *
+ * ── WHY `ensureCurrentSessionId` EXISTS (the silent-drop contract) ─────────────────────────────
+ * The server's event model declares `session_id: str = Field(min_length=1)` — REQUIRED, non-empty.
+ * `POST /v1/events` validates each event inside a try/except that increments a `skipped` counter and
+ * still returns HTTP 200. So an event posted without a `session_id` is accepted by the wire and
+ * DISCARDED by the server, and a fire-and-forget client can never learn it happened. That is the
+ * worst of both: no error, no data. Screen tracking in a host that never mounted the lifecycle hook
+ * fell into exactly that hole — every screen view posted, 200'd, and dropped.
+ *
+ * `ensureCurrentSessionId` closes it: it returns the registered id when an open HAS been registered
+ * (unchanged behaviour for every host that fires `reportSessionStart` first), and otherwise mints one,
+ * REGISTERS it, and returns it — so every later event in the process correlates to that same id
+ * instead of each emitting its own orphan. A minted id is a fallback, not a substitute for a real
+ * app-open: it warns once in dev, naming the fix.
  */
+import { makeSessionId } from "./reportClientEvent";
 
 /**
  * Well-known key into the runtime-global symbol registry. `Symbol.for` (NOT a plain `Symbol()`) is
@@ -67,3 +82,71 @@ export const getCurrentSessionId = (): string | undefined =>
 export const resetCurrentSessionId = (): void => {
   globalSlot[CURRENT_SESSION_ID_SLOT] = undefined;
 };
+
+/** 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.
+ * Same idiom as `analyticsFacade.warnInDev` — deliberately duplicated rather than imported, so this
+ * module keeps its zero-import-weight for the tree-shaken analytics bundle.
+ *
+ * Returns whether it ACTUALLY warned, so the caller's once-flag is spent on a warning a developer
+ * saw. Marking "already warned" after a no-op would burn the single warning in prod, and the one
+ * dev build that needed it would then run silent.
+ */
+const warnInDev = (message: string): boolean => {
+  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+    console.warn(message);
+    return true;
+  }
+  return false;
+};
+
+/** The one-time message. Hoisted so a prod mint does not rebuild a string nobody will read. */
+const MINT_WARNING =
+  "[wireai] No app-open session was registered, so a session id was minted for this event " +
+  "(the server drops an event that has no session_id, and still answers 200). Mount " +
+  "useLifecycleEvents at your app root so events correlate to a real app-open.";
+
+/**
+ * "Have we already warned about a minted session id?" — its OWN `Symbol.for` slot, for the same
+ * cross-bundle reason as the id itself: a plain module `let` would warn once per inlined copy, i.e.
+ * once per bundle, not once per process. NOT cleared by `resetCurrentSessionId`: "warn once" is a
+ * process-lifetime promise, and a test that resets the id between mints is still one process.
+ */
+const MINT_WARNED_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:currentSessionIdMintWarned",
+);
+
+type GlobalWithWarnSlot = typeof globalThis & { [MINT_WARNED_SLOT]?: boolean };
+
+const warnSlot = globalThis as GlobalWithWarnSlot;
+
+/**
+ * The current per-open `session_id`, MINTING and registering one when no app-open has been
+ * registered yet. Always returns a non-empty string. Idempotent (a second call returns the same id)
+ * and never throws.
+ *
+ * Use this on every path that puts a `session_id` on the wire. The server REQUIRES a non-empty
+ * `session_id` and drops the event otherwise while still answering 200 (see the module header), so
+ * "no id yet" must never mean "send it without one".
+ *
+ * BACKWARD-COMPATIBLE BY CONSTRUCTION: when `reportSessionStart` / `useLifecycleEvents` has already
+ * registered the real per-open id, this is `getCurrentSessionId()` and nothing changes. It only ever
+ * mints in the case that used to produce a silently discarded event.
+ *
+ * A mint means the host never registered an app-open, so the minted id is one the server has not
+ * seen a `session_started` for — the events land, but the session is thinner than a real open.
+ * Hence the one-time dev warning naming the fix (mount `useLifecycleEvents` at the app root).
+ */
+export const ensureCurrentSessionId = (): string => {
+  const existing = globalSlot[CURRENT_SESSION_ID_SLOT];
+  if (typeof existing === "string" && existing.length > 0) return existing;
+  const minted = makeSessionId();
+  globalSlot[CURRENT_SESSION_ID_SLOT] = minted;
+  if (!warnSlot[MINT_WARNED_SLOT] && warnInDev(MINT_WARNING)) {
+    warnSlot[MINT_WARNED_SLOT] = true;
+  }
+  return minted;
+};

package/src/analytics/eventQueue.ts

@@ -24,7 +24,12 @@
  * `notifyOnline()`; persistence is the host-injected AsyncStorage-compatible subset.
  */
 import type { ContextEnvelope } from "./contextEnvelope";
-import { buildEventsRequest, type ClientEvent, type 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). */
@@ -241,6 +246,9 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
     const timer = setTimeout(() => controller?.abort(), 15_000);
     try {
       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

@@ -73,5 +73,24 @@ export {
 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

@@ -128,6 +128,44 @@ 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.
+ */
+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;
 };