@wireai/activation 0.10.0 → 0.12.0

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

@@ -1,20 +1,5 @@
 import { k as ReviewTarget, g as ReviewDecisionResponse, j as ReviewSubmission } from './types-CNUqMK0D.mjs';
 
-/**
- * transport.ts — kit → Wire server requests for the review module, all fire-and-forget
- * (analytics/reviews must never break the app). Mirrors analytics/reportClientEvent: a
- * thin fetch wrapper, Bearer tenant key, swallow every error.
- *
- *   • submitReview         → POST {serverUrl}/v1/reviews          (the review row)
- *   • fetchReviewDecision  → GET  {serverUrl}/v1/reviews/decision (best-effort, the AI seam)
- *   • reportAppEvent       → POST {serverUrl}/v1/events           (generic app.* namespace)
- *
- * `reportAppEvent` is the strategic extension: it lets a host report arbitrary in-app
- * events through the SAME transport (stored server-side as event_type='app_event',
- * question_key=<name>), which is what the backend review-firing rules evaluate on — and
- * it seeds the broader app-analytics stream. Keep payloads minimal + non-PII.
- */
-
 /**
  * POST a review (the 1-4 feedback path). Fire-and-forget: a missing target, a build error,
  * a missing `fetch`, or a network failure is swallowed and the call returns immediately.
@@ -109,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;
@@ -122,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-B31G0Cib.d.ts → transport-DsRe4epC.d.ts}

@@ -1,20 +1,5 @@
 import { k as ReviewTarget, g as ReviewDecisionResponse, j as ReviewSubmission } from './types-Buj9Lw9t.js';
 
-/**
- * transport.ts — kit → Wire server requests for the review module, all fire-and-forget
- * (analytics/reviews must never break the app). Mirrors analytics/reportClientEvent: a
- * thin fetch wrapper, Bearer tenant key, swallow every error.
- *
- *   • submitReview         → POST {serverUrl}/v1/reviews          (the review row)
- *   • fetchReviewDecision  → GET  {serverUrl}/v1/reviews/decision (best-effort, the AI seam)
- *   • reportAppEvent       → POST {serverUrl}/v1/events           (generic app.* namespace)
- *
- * `reportAppEvent` is the strategic extension: it lets a host report arbitrary in-app
- * events through the SAME transport (stored server-side as event_type='app_event',
- * question_key=<name>), which is what the backend review-firing rules evaluate on — and
- * it seeds the broader app-analytics stream. Keep payloads minimal + non-PII.
- */
-
 /**
  * POST a review (the 1-4 feedback path). Fire-and-forget: a missing target, a build error,
  * a missing `fetch`, or a network failure is swallowed and the call returns immediately.
@@ -109,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;
@@ -122,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

@@ -23,6 +23,15 @@
 - `attributionMetadata(a)` → shape install/ad attribution into `config.metadata` (forwarded to the agent).
 - `reportClientEvent(target, event)` / `reportClientEvents` / `makeSessionId` (ROOT-exported, not a subpath) → report device-only funnel events. Contract: `POST {serverUrl}/v1/events`, header `Authorization: Bearer {apiKey}`, body `{ "events": [ ... ] }`; `target = { serverUrl, apiKey }` from the config. `<WireOnboarding>` does this automatically: `dropped` on unmount-without-complete, `client_fallback` on degrade-to-static. Hosts must not double-report fallback.
 - `deriveAnswers(messages)`, `themeFromBrand({ primary })`, `defaultIllustrations`, `DemoOnboarding` (dev/QA, no account).
+
+## Subpath surfaces (beyond onboarding)
+
+The package is more than `<WireOnboarding>`. Tree-shakeable subpath exports (each keeps the onboarding UI out of an analytics-only bundle):
+
+- `@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.10.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

@@ -30,9 +30,25 @@ import { buildContextEnvelope, type ContextEnvelope } from "./contextEnvelope";
 import { getCurrentSessionId } from "./currentSession";
 import { createEventQueue, type EventQueue, type EventQueueOptions } from "./eventQueue";
 import { makeSessionId, type ClientEvent } from "./reportClientEvent";
-import { resolveUserContext, type WireUserContext } from "../context/userContext";
-import { mintDeviceId, deviceIdStorageKey } from "../context/deviceId";
-import { sanitizeUserId } from "../identity/userIdentity";
+import {
+  analyticsUserIdStorageKey,
+  clearPiiFromContext,
+  resolveUserContext,
+  type WireUserContext,
+} from "../context/userContext";
+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}. */
+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);
+  }
+};
 
 /** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
 export type AnalyticsProps = Record<string, unknown>;
@@ -48,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>`). */
@@ -76,6 +98,14 @@ export type CreateAnalyticsConfig = {
    * review/questionnaire gating + A/B stickiness. Supply `deviceKey` only to use your OWN id (it wins).
    */
   userContext?: WireUserContext;
+  /**
+   * ESCAPE HATCH for the email-shape guard. By default `identify(id)` and a `setUserContext({ userId })`
+   * REFUSE to bind an id that looks like an email (`local@domain.tld`) and warn in dev — because a
+   * raw email in the opaque `user_id` is a PII leak; an email belongs in the opt-in
+   * `userContext.userEmail` field. Set `true` ONLY if your real internal user id genuinely IS an
+   * email address and you accept it as the pseudonymous key. Default `false` (guard on).
+   */
+  allowEmailAsUserId?: boolean;
 };
 
 /** Optional queue tuning knobs, forwarded verbatim to {@link createEventQueue}. */
@@ -101,6 +131,16 @@ export type Analytics = {
    * binds like {@link identify}. Takes effect on subsequent events. Fire-and-forget.
    */
   setUserContext(partial: Partial<WireUserContext>): void;
+  /**
+   * LOGOUT: unbind the current user so a shared device never attributes user B's events to user A.
+   * Clears the in-memory `boundUserId`, strips the PII / pseudonymous fields (`userId`, `userEmail`,
+   * `extra`) from the bound {@link WireUserContext} (keeping the non-PII `device_key` + `appVersion`,
+   * which group a DEVICE not a user), and removes the persisted `wireai:analytics:userId:<appId>`
+   * key so it cannot be rehydrated on the next launch. Subsequent events are anonymous until the
+   * next `identify` / `setUserContext`. Fire-and-forget; mirrors the `reset()` convention on the
+   * screen tracker. The standalone `clearUserContext({ storage, appId })` covers the `wire` path.
+   */
+  reset(): void;
   /** Attempt an immediate drain of the pending buffer. Fire-and-forget. */
   flush(): void;
   /** Host reconnect signal: reset backoff and drain now. Fire-and-forget. */
@@ -129,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).
@@ -144,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
@@ -185,7 +238,7 @@ export const createAnalytics = (
   // Per-session, in-memory user binding. Seeded from the init context, then persisted across
   // launches when storage is provided.
   let boundUserId: string | undefined = sanitizeUserId(config.userContext?.userId);
-  const storageKey = `wireai:analytics:userId:${config.appId ?? "default"}`;
+  const storageKey = analyticsUserIdStorageKey(config.appId);
 
   if (config.storage) {
     void config.storage
@@ -208,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 ?? {}) };
@@ -217,6 +271,19 @@ export const createAnalytics = (
     if (boundUserId && !event.user_id) event.user_id = boundUserId;
   };
 
+  // Email-shape guard for the OPAQUE user id. A raw email bound as `user_id` is a PII leak (it
+  // belongs in the opt-in `user_context.user_email`), so refuse it and warn in dev — unless the host
+  // opted in via `allowEmailAsUserId`. Returns the id to bind, or `undefined` to refuse.
+  const guardUserId = (clean: string): string | undefined => {
+    if (config.allowEmailAsUserId || !looksLikeEmail(clean)) return clean;
+    warnInDev(
+      "[wireai] identify() was called with an email-shaped id. A raw email must NOT be the opaque " +
+        "user_id (PII leak) — pass it as userContext.userEmail instead. Binding was skipped. Set " +
+        "allowEmailAsUserId:true on createAnalytics if your user id genuinely is an email.",
+    );
+    return undefined;
+  };
+
   const setUserContext = (partial: Partial<WireUserContext>): void => {
     if (!partial || typeof partial !== "object") return;
     // Deep-merge `extra` so a partial update adds keys instead of replacing the whole map.
@@ -226,14 +293,27 @@ export const createAnalytics = (
         : undefined;
     userContext = { ...userContext, ...partial };
     if (mergedExtra) userContext.extra = mergedExtra;
-    // A user id supplied here binds like `identify` so subsequent events carry `user_id`.
+    // A user id supplied here binds like `identify` so subsequent events carry `user_id` — through
+    // the SAME email-shape guard (a raw email must not become the opaque user_id).
     const uid = sanitizeUserId(partial.userId);
     if (uid) {
-      boundUserId = uid;
-      if (config.storage) void config.storage.setItem(storageKey, uid).catch(() => {});
+      const bindable = guardUserId(uid);
+      if (bindable) {
+        boundUserId = bindable;
+        if (config.storage) void config.storage.setItem(storageKey, bindable).catch(() => {});
+      }
     }
   };
 
+  const reset = (): void => {
+    // In-memory binding cleared: subsequent events carry no user_id until the next identify.
+    boundUserId = undefined;
+    // Strip PII from the rich context but keep the device-scope fields (device_key / app_version).
+    userContext = clearPiiFromContext(userContext);
+    // Remove the persisted binding so a relaunch can't rehydrate the previous user's id.
+    if (config.storage) void config.storage.removeItem(storageKey).catch(() => {});
+  };
+
   const track = (event: string, props?: AnalyticsProps): void => {
     if (!event) return;
     const clientEvent: ClientEvent = {
@@ -264,16 +344,19 @@ export const createAnalytics = (
     const clean = sanitizeUserId(userId);
     // Blank / non-string → no binding, no event (sanitizeUserId returns undefined). >128 → truncated.
     if (!clean) return;
-    boundUserId = clean;
+    // Email-shape guard: refuse to bind (and emit) a raw email as the opaque user_id unless opted in.
+    const bindable = guardUserId(clean);
+    if (!bindable) return;
+    boundUserId = bindable;
     if (config.storage) {
-      void config.storage.setItem(storageKey, clean).catch(() => {});
+      void config.storage.setItem(storageKey, bindable).catch(() => {});
     }
     const clientEvent: ClientEvent = {
       event_type: "identify",
       // Reuse the LIVE per-open session id (see `resolveSessionId`) so the server binds identity to
       // the session it already saw instead of back-filling a phantom `session_started`.
       session_id: resolveSessionId(),
-      user_id: clean,
+      user_id: bindable,
     };
     if (traits && Object.keys(traits).length > 0) clientEvent.meta = JSON.stringify(traits);
     applyContext(clientEvent);
@@ -285,6 +368,7 @@ export const createAnalytics = (
     screen,
     identify,
     setUserContext,
+    reset,
     flush: queue.flush,
     notifyOnline: queue.notifyOnline,
     size: queue.size,

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;
+};