@wireai/activation 0.4.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.4.0",
+  "version": "0.7.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/WireOnboarding.tsx

@@ -61,9 +61,10 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   const boundUserId = useMemo(() => sanitizeUserId(userId), [userId]);
 
   // Privacy-label-neutral device snapshot, collected once per mount (no advertising IDs, no
-  // fingerprinting — see device/deviceContext.ts). `config.appVersion` is host-injected and
-  // merged in here (collectDeviceContext never sets it). Attached to BOTH the A2A session
-  // metadata and every client event so the backend can segment the funnel by device.
+  // fingerprinting — see device/deviceContext.ts). `collectDeviceContext` already carries a
+  // best-effort auto-detected `appVersion`; an explicit host `config.appVersion` overrides it.
+  // Attached to BOTH the A2A session metadata and every client event so the backend can segment
+  // the funnel by device (and by app version).
   const device = useMemo<DeviceContext>(() => {
     const collected = collectDeviceContext();
     return config.appVersion ? { ...collected, appVersion: config.appVersion } : collected;

package/src/analytics/analyticsFacade.ts

@@ -27,8 +27,10 @@
  * FIRE-AND-FORGET: no method throws into the UI or blocks — the queue already guarantees that.
  */
 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 { sanitizeUserId } from "../identity/userIdentity";
 
 /** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
@@ -62,6 +64,13 @@ export type CreateAnalyticsConfig = {
   appBuild?: string;
   /** Host connectivity signal, e.g. "wifi" | "cellular" — read fresh per event via the provider. */
   networkType?: string;
+  /**
+   * The rich {@link WireUserContext} to stamp onto every event's `user_context` (device key, opaque
+   * user id, opt-in email, arbitrary `extra`). Passed ONCE here at init; updatable post-mount via
+   * {@link Analytics.setUserContext} (e.g. attach `userId`/`userEmail` at login). Optional — omit it
+   * and events carry only the device context, exactly as before.
+   */
+  userContext?: WireUserContext;
 };
 
 /** Optional queue tuning knobs, forwarded verbatim to {@link createEventQueue}. */
@@ -81,6 +90,12 @@ export type Analytics = {
   screen(name: string, props?: AnalyticsProps): void;
   /** Bind the host's opaque user id (per-session, in-memory) and emit an `identify` event. */
   identify(userId: string, traits?: AnalyticsProps): void;
+  /**
+   * Update the {@link WireUserContext} after init (e.g. attach `userId`/`userEmail` at login). Shallow
+   * merges the partial over the current context (`extra` is deep-merged); a supplied `userId` also
+   * binds like {@link identify}. Takes effect on subsequent events. Fire-and-forget.
+   */
+  setUserContext(partial: Partial<WireUserContext>): 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. */
@@ -98,12 +113,22 @@ export const createAnalytics = (
   config: CreateAnalyticsConfig,
   options: AnalyticsOptions = {},
 ): Analytics => {
-  const sessionId = config.sessionId ?? makeSessionId();
+  // A STABLE per-instance fallback id, used only when no explicit `config.sessionId` was given AND
+  // no per-open session has been registered yet (see `resolveSessionId`).
+  const instanceSessionId = config.sessionId ?? makeSessionId();
+
+  // The session id every event correlates to. Precedence: an explicit `config.sessionId` freezes the
+  // id (opt-out of the reuse); otherwise reuse the LIVE per-open session the server saw (via
+  // `app.session_started`) so `identify`/app-events don't mint a fresh id the server back-fills into a
+  // phantom session; finally fall back to the stable per-instance id when no open is registered yet.
+  const resolveSessionId = (): string =>
+    config.sessionId ?? getCurrentSessionId() ?? instanceSessionId;
 
-  // A provider (not a fixed value) so `networkType` is evaluated fresh on every enqueue.
+  // A provider (not a fixed value) so `networkType` + the current session id are evaluated fresh
+  // on every enqueue.
   const envelope = (): ContextEnvelope =>
     buildContextEnvelope({
-      sessionId,
+      sessionId: resolveSessionId(),
       appVersion: config.appVersion,
       appBuild: config.appBuild,
       networkType: config.networkType,
@@ -117,28 +142,62 @@ export const createAnalytics = (
     ...options,
   });
 
-  // Per-session, in-memory user binding. Persisted across launches when storage is provided.
-  let boundUserId: string | undefined;
+  // 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.
+  let userContext: WireUserContext = { ...(config.userContext ?? {}) };
+
+  // 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"}`;
 
   if (config.storage) {
     void config.storage
       .getItem(storageKey)
       .then((saved) => {
-        if (saved) boundUserId = saved;
+        // Don't clobber an explicit init-context user id with a stale persisted one.
+        if (saved && !boundUserId) boundUserId = saved;
       })
       .catch(() => {});
   }
 
+  // Stamp the resolved rich context onto an event: the `user_context` bucket (device_key, app_version,
+  // opt-in user_email, namespaced `custom.*`) and the top-level opaque `user_id`. Never overwrites a
+  // key the caller already set (so `identify`'s explicit `user_id` and any caller `user_context` win).
+  const applyContext = (event: ClientEvent): void => {
+    const resolved = resolveUserContext(userContext, { autoAppVersion: config.appVersion });
+    if (resolved.userContext) {
+      event.user_context = { ...resolved.userContext, ...(event.user_context ?? {}) };
+    }
+    if (boundUserId && !event.user_id) event.user_id = boundUserId;
+  };
+
+  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.
+    const mergedExtra =
+      partial.extra || userContext.extra
+        ? { ...(userContext.extra ?? {}), ...(partial.extra ?? {}) }
+        : undefined;
+    userContext = { ...userContext, ...partial };
+    if (mergedExtra) userContext.extra = mergedExtra;
+    // A user id supplied here binds like `identify` so subsequent events carry `user_id`.
+    const uid = sanitizeUserId(partial.userId);
+    if (uid) {
+      boundUserId = uid;
+      if (config.storage) void config.storage.setItem(storageKey, uid).catch(() => {});
+    }
+  };
+
   const track = (event: string, props?: AnalyticsProps): void => {
     if (!event) return;
     const clientEvent: ClientEvent = {
       event_type: "app_event",
-      session_id: sessionId,
+      session_id: resolveSessionId(),
       question_key: event,
     };
     if (props && Object.keys(props).length > 0) clientEvent.meta = JSON.stringify(props);
-    if (boundUserId) clientEvent.user_id = boundUserId;
+    applyContext(clientEvent);
     queue.enqueue(clientEvent);
   };
 
@@ -148,11 +207,11 @@ export const createAnalytics = (
     const meta = { screen: name, ...(props ?? {}) };
     const clientEvent: ClientEvent = {
       event_type: "app_event",
-      session_id: sessionId,
+      session_id: resolveSessionId(),
       question_key: "screen",
       meta: JSON.stringify(meta),
     };
-    if (boundUserId) clientEvent.user_id = boundUserId;
+    applyContext(clientEvent);
     queue.enqueue(clientEvent);
   };
 
@@ -166,10 +225,13 @@ export const createAnalytics = (
     }
     const clientEvent: ClientEvent = {
       event_type: "identify",
-      session_id: sessionId,
+      // 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,
     };
     if (traits && Object.keys(traits).length > 0) clientEvent.meta = JSON.stringify(traits);
+    applyContext(clientEvent);
     queue.enqueue(clientEvent);
   };
 
@@ -177,6 +239,7 @@ export const createAnalytics = (
     track,
     screen,
     identify,
+    setUserContext,
     flush: queue.flush,
     notifyOnline: queue.notifyOnline,
     size: queue.size,

package/src/analytics/contextEnvelope.ts

@@ -30,7 +30,7 @@ export type ContextEnvelope = {
   device: DeviceContext;
   /** Correlation id for this app-open / flow (caller-supplied). */
   sessionId?: string;
-  /** Host app version, e.g. "1.4.2" (mirrors `device.appVersion`; host-injected). */
+  /** App version, e.g. "1.4.2" (mirrors `device.appVersion`; host-injected, else auto-detected). */
   appVersion?: string;
   /** Host native build number, e.g. "412" (from `expo-constants` `nativeBuildVersion`). */
   appBuild?: string;
@@ -47,9 +47,10 @@ export type ContextEnvelopeInput = {
 };
 
 /**
- * Build a fresh context envelope. Reuses `collectDeviceContext()` for the device block and layers
- * the host-injected scalars on top. `appVersion` is additionally merged onto `device.appVersion`
- * when the device block lacks it (mirroring how `useSessionStart` back-fills the host version).
+ * Build a fresh context envelope. Reuses `collectDeviceContext()` for the device block (which
+ * already carries a best-effort auto-detected `appVersion`) and layers the host-injected scalars
+ * on top. An explicit `input.appVersion` overrides the auto-detected `device.appVersion`, and the
+ * outer `appVersion` scalar mirrors whichever version is effective.
  *
  * Returns a NEW object on every call (no shared mutable reference), so a caller can hold or mutate
  * the result without leaking into the next envelope. Never throws — `collectDeviceContext` is
@@ -59,12 +60,17 @@ export const buildContextEnvelope = (input: ContextEnvelopeInput = {}): ContextE
   // Fresh copy so the returned envelope never aliases a cached device snapshot.
   const device: DeviceContext = { ...collectDeviceContext() };
 
-  // Mirror useSessionStart: fill the host app version onto the device block when it lacks one.
-  if (input.appVersion && !device.appVersion) device.appVersion = input.appVersion;
+  // `device.appVersion` is auto-detected best-effort by `collectDeviceContext`; an explicit
+  // host `input.appVersion` always wins.
+  if (input.appVersion) device.appVersion = input.appVersion;
+
+  // The outer scalar mirrors the effective version (host-supplied, else auto-detected) so the
+  // queue can stamp `user_context.app_version` even when the host never passed one.
+  const effectiveAppVersion = input.appVersion ?? device.appVersion;
 
   const envelope: ContextEnvelope = { device };
   if (input.sessionId) envelope.sessionId = input.sessionId;
-  if (input.appVersion) envelope.appVersion = input.appVersion;
+  if (effectiveAppVersion) envelope.appVersion = effectiveAppVersion;
   if (input.appBuild) envelope.appBuild = input.appBuild;
   if (input.networkType) envelope.networkType = input.networkType;
 

package/src/analytics/currentSession.ts

@@ -0,0 +1,35 @@
+/**
+ * currentSession — a tiny module-level registry of the CURRENT per-open `session_id`.
+ *
+ * WHY it exists (kills the phantom-session): the per-open emitters (`reportSessionStart` and the
+ * `useSessionStart` / `useLifecycleEvents` hooks) mint a fresh `session_id` for each app-open and
+ * post `app.session_started` with it — so the SERVER knows that id. But other client paths
+ * (`identify`, host `app_event`s through the analytics façade) used to reference a DIFFERENT id
+ * (a frozen per-instance id), which the server had never seen, so it back-filled a synthetic
+ * `session_started` — inflating session counts (the Morrow/Myelino "phantom-session" bug).
+ *
+ * This registry is the single seam that lets those paths reuse the LIVE per-open session id the
+ * server already ingested. `reportSessionStart` writes the current id here on every open; the façade
+ * reads it so `identify`/app-events correlate to the real session instead of minting a phantom.
+ *
+ * DEPENDENCY-FREE + PROCESS-LOCAL: a plain module variable. It is intentionally NOT persisted — it
+ * tracks the CURRENT process's open, and a fresh open always overwrites it. No cross-launch state.
+ */
+
+let _currentSessionId: string | undefined;
+
+/**
+ * Record the current per-open `session_id`. Called by `reportSessionStart` when it emits an
+ * app-open. A blank / non-string id is ignored (the previous id stays current). Idempotent.
+ */
+export const setCurrentSessionId = (id: string | undefined): void => {
+  if (typeof id === "string" && id.length > 0) _currentSessionId = id;
+};
+
+/** The current per-open `session_id`, or `undefined` when no app-open has been registered yet. */
+export const getCurrentSessionId = (): string | undefined => _currentSessionId;
+
+/** Test-only: forget the current session id so a unit test starts from a clean registry. */
+export const resetCurrentSessionId = (): void => {
+  _currentSessionId = undefined;
+};

package/src/analytics/index.ts

@@ -57,3 +57,6 @@ export type {
 
 // ─── The thin optional React hook over the façade ─────────────────────────────
 export { useAnalytics } from "./useAnalytics";
+
+// ─── Current per-open session registry (identify/app-events reuse the live session) ───
+export { getCurrentSessionId, setCurrentSessionId, resetCurrentSessionId } from "./currentSession";

package/src/context/userContext.ts

@@ -0,0 +1,210 @@
+/**
+ * userContext — the ONE extensible object a host passes once and the kit flows into every
+ * analytics event's `user_context` (plus the top-level opaque `user_id`).
+ *
+ * WHY it exists: hosts already hand the kit fragments of "who this user is" — `config.appVersion`,
+ * `useSessionStart({ deviceKey, userId })`, `<WireOnboarding userContext={…} />` — but there was no
+ * single object that carries app version + device key + user id + (opt-in) email + arbitrary extras
+ * together, with one precedence rule, into every event. `WireUserContext` is that object;
+ * `resolveUserContext` is the pure merge that turns it into the wire shape.
+ *
+ * PRECEDENCE (the one rule): an explicit `WireUserContext` field WINS over the #42 auto-detected
+ * `device`/`appVersion`. A missing field is OMITTED, never sent empty.
+ *
+ * WHERE EACH FIELD LANDS (deliberate separation so nothing leaks across buckets):
+ *   • `userId`    → the event's TOP-LEVEL opaque `user_id` (via `sanitizeUserId`). NEVER the bucket.
+ *   • `userEmail` → its OWN key `user_context.user_email`. NEVER merged into `userId`. OPT-IN PII.
+ *   • `deviceKey` → `user_context.device_key` (the server's `_event_device_key` reads it there).
+ *   • `appVersion`→ `user_context.app_version` (and returned as `appVersion` for `device.appVersion`).
+ *   • `extra`     → NAMESPACED under a `custom.` key prefix, coerced to scalars, so a host extra can
+ *                   never collide with a reserved `user_context` key.
+ *
+ * DEPENDENCY-FREE: the only import is the kit's own `sanitizeUserId`. The optional email hash is a
+ * dependency-free FNV-1a fold (see {@link hashEmailFnv1a}) — no crypto library, no async.
+ */
+import { sanitizeUserId } from "../identity/userIdentity";
+
+/**
+ * The single, extensible user-context object. A host passes it ONCE (at analytics init) and may
+ * update it post-mount (e.g. attach `userId`/`userEmail` at login) via `setUserContext(partial)`.
+ * Every field is optional; missing fields are omitted from the wire payload.
+ */
+export interface WireUserContext {
+  /**
+   * Host app version, e.g. "1.4.2". EXPLICIT — wins over the #42 auto-detected `device.appVersion`.
+   * Lands in `user_context.app_version`. Omitted when neither this nor auto-detect yields a version.
+   */
+  appVersion?: string;
+  /**
+   * A stable, non-PII device id the host owns. Lands in `user_context.device_key` (NOT `session_id`),
+   * where the server groups a device's sessions. Host-supplied; the kit never mints or reads one.
+   */
+  deviceKey?: string;
+  /**
+   * The host's OPAQUE PSEUDONYMOUS user id (their internal id — NOT an email/name/phone). Sanitized +
+   * capped (see `sanitizeUserId`) and placed on the event's top-level `user_id`. NEVER the bucket.
+   */
+  userId?: string;
+  /**
+   * OPT-IN PII. The user's email, its OWN field (`user_context.user_email`) — NEVER merged into
+   * `userId`. The kit NEVER auto-collects this; a host passes it only WITH the user's consent (EU
+   * users: treat as personal data). For a non-reversible form, set {@link hashEmail} `true` (the kit
+   * folds it with a dependency-free hash and stamps `user_context.user_email_hashed: true`), OR
+   * pre-hash host-side with a cryptographic digest and pass that here with `hashEmail` falsy.
+   */
+  userEmail?: string;
+  /**
+   * When `true`, {@link userEmail} is folded with the kit's dependency-free {@link hashEmailFnv1a}
+   * before it leaves the device, and `user_context.user_email_hashed` is set `true`. NOTE: FNV-1a is
+   * a lightweight NON-cryptographic fold (obfuscation, not a secure digest). For a cryptographic
+   * hash, compute it host-side (e.g. SHA-256 via `expo-crypto`) and pass the digest as `userEmail`
+   * with `hashEmail` falsy. Default: raw email is sent as-is (opt-in already gated it upstream).
+   */
+  hashEmail?: boolean;
+  /**
+   * Arbitrary host context (signup method, referral, plan tier…). Each value is coerced to a scalar
+   * (`string | number | boolean`; non-scalars and non-finite numbers are DROPPED) and NAMESPACED
+   * under a `custom.` key prefix in `user_context` (e.g. `user_context["custom.referral"]`) so it can
+   * never collide with a reserved key. No raw PII — use {@link userEmail} for email.
+   */
+  extra?: Record<string, string | number | boolean>;
+}
+
+/**
+ * The wire-shaped result of {@link resolveUserContext}. `userContext` is the non-PII/opt-in-PII
+ * bucket stamped onto the event; `userId` is the top-level opaque id; `appVersion`/`deviceKey` are
+ * echoed for callers that also place them elsewhere (e.g. `device.appVersion`). Absent fields are
+ * omitted so a caller can spread this without sending empties.
+ */
+export interface ResolvedUserContext {
+  /** The opaque, sanitized user id → the event's top-level `user_id`. Omitted when unset/blank. */
+  userId?: string;
+  /** The stable device id → `user_context.device_key`. Omitted when unset. */
+  deviceKey?: string;
+  /** The effective app version (explicit > auto-detected) → `user_context.app_version`. */
+  appVersion?: string;
+  /** The `user_context` bucket (device_key, app_version, user_email[+ _hashed], custom.*). */
+  userContext?: Record<string, string | number | boolean>;
+}
+
+/** Reserved `user_context` keys the kit itself writes; host `extra` is namespaced away from these. */
+export const RESERVED_USER_CONTEXT_KEYS = [
+  "device_key",
+  "app_version",
+  "app_build",
+  "network_type",
+  "session_count",
+  "returning",
+  "platform",
+  "user_email",
+  "user_email_hashed",
+] as const;
+
+/** The prefix applied to every host `extra` key so it can never collide with a reserved key. */
+export const EXTRA_KEY_PREFIX = "custom." as const;
+
+/** A finite scalar the wire accepts. Non-finite numbers (NaN/Infinity) are NOT scalars here. */
+export const isWireScalar = (value: unknown): value is string | number | boolean => {
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return true;
+  if (t === "number") return Number.isFinite(value as number);
+  return false;
+};
+
+/**
+ * Fold an email to a stable, dependency-free 32-bit FNV-1a hex token (lowercased + trimmed first so
+ * the same address always folds identically). This is OBFUSCATION, not a cryptographic digest — it
+ * is not collision-resistant. For a real hash, pre-hash host-side and pass the digest as `userEmail`.
+ */
+export const hashEmailFnv1a = (email: string): string => {
+  const normalized = email.trim().toLowerCase();
+  let hash = 0x811c9dc5; // FNV offset basis (32-bit)
+  for (let i = 0; i < normalized.length; i++) {
+    hash ^= normalized.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193); // FNV prime (32-bit), kept in 32-bit via imul
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+};
+
+/** Trim a candidate string; return `undefined` for a non-string / blank so callers can `if`-gate. */
+const cleanString = (value: unknown): string | undefined => {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+};
+
+/**
+ * Coerce a host `extra` map into the namespaced, scalar-only bucket shape. Every kept value is
+ * placed under `custom.<key>`; non-scalar values (objects, arrays, null, functions, NaN/Infinity)
+ * are DROPPED. Returns an object (possibly empty).
+ */
+export const namespaceExtra = (
+  extra: Record<string, unknown> | undefined,
+): Record<string, string | number | boolean> => {
+  const out: Record<string, string | number | boolean> = {};
+  if (!extra || typeof extra !== "object") return out;
+  for (const [key, value] of Object.entries(extra)) {
+    const cleanKey = cleanString(key);
+    if (!cleanKey) continue;
+    if (!isWireScalar(value)) continue; // drop anything that isn't a finite scalar
+    out[`${EXTRA_KEY_PREFIX}${cleanKey}`] = value;
+  }
+  return out;
+};
+
+/** Options for {@link resolveUserContext}. */
+export interface ResolveUserContextOptions {
+  /**
+   * The kit's best-effort auto-detected app version (#42; from `detectAppVersion()`/the device
+   * snapshot). Used ONLY when the explicit `WireUserContext.appVersion` is absent — explicit wins.
+   */
+  autoAppVersion?: string;
+}
+
+/**
+ * Merge a {@link WireUserContext} into the wire shape with the precedence rule (explicit field >
+ * auto-detected). Pure, never throws. Missing fields are omitted so the result can be spread onto an
+ * event without sending empties.
+ */
+export const resolveUserContext = (
+  ctx: WireUserContext = {},
+  opts: ResolveUserContextOptions = {},
+): ResolvedUserContext => {
+  const result: ResolvedUserContext = {};
+  const bucket: Record<string, string | number | boolean> = {};
+
+  // userId → top-level opaque id (NEVER the bucket). Sanitized + capped host-side.
+  const userId = sanitizeUserId(ctx.userId);
+  if (userId) result.userId = userId;
+
+  // deviceKey → user_context.device_key (NOT session_id).
+  const deviceKey = cleanString(ctx.deviceKey);
+  if (deviceKey) {
+    result.deviceKey = deviceKey;
+    bucket.device_key = deviceKey;
+  }
+
+  // appVersion → explicit wins over auto-detected (#42); echoed for device.appVersion callers.
+  const appVersion = cleanString(ctx.appVersion) ?? cleanString(opts.autoAppVersion);
+  if (appVersion) {
+    result.appVersion = appVersion;
+    bucket.app_version = appVersion;
+  }
+
+  // userEmail → its OWN key. OPT-IN PII, optionally folded. NEVER touches userId.
+  const email = cleanString(ctx.userEmail);
+  if (email) {
+    if (ctx.hashEmail) {
+      bucket.user_email = hashEmailFnv1a(email);
+      bucket.user_email_hashed = true;
+    } else {
+      bucket.user_email = email;
+    }
+  }
+
+  // extra → namespaced + scalar-coerced.
+  Object.assign(bucket, namespaceExtra(ctx.extra));
+
+  if (Object.keys(bucket).length > 0) result.userContext = bucket;
+  return result;
+};

package/src/device/appVersion.ts

@@ -0,0 +1,103 @@
+/**
+ * appVersion — best-effort, DEPENDENCY-FREE auto-detection of the host app's version string.
+ *
+ * WHY this exists: analytics segments the funnel `by_app_version`, but that breakdown is only
+ * populated when a `device.appVersion` rides the event. `config.appVersion` (see types.ts) has
+ * always been the way to supply it — but it is easy for a host to forget, and then the release
+ * breakdown is silently empty. This module fills that gap: when the host does NOT pass a version,
+ * the kit makes a best-effort read of the app version the host already ships in its Expo config,
+ * so the breakdown works out of the box. An explicit `config.appVersion` always WINS over this.
+ *
+ * WHY it adds NO dependency (the kit's hard rule): `expo-constants` / `expo-application` are read
+ * through a GUARDED, VARIABLE-specifier `require`. Passing a variable (not a string literal) keeps
+ * Metro/esbuild from statically resolving the module, so a host that does NOT have it installed
+ * (e.g. bare React Native) never fails to bundle — the require simply throws at runtime and is
+ * swallowed. Nothing is added to `package.json`; nothing is forced on the host.
+ *
+ * PRIVACY: an app version string is not PII and identifies no user or device, so surfacing it
+ * changes no App Privacy / Data Safety declaration (same guarantee as the rest of deviceContext).
+ *
+ * NEVER THROWS: every read is guarded; a missing/odd value yields `undefined`, never an exception.
+ * Analytics must never be able to break onboarding.
+ */
+
+// Metro injects a module-scoped `require`; it is ABSENT in a pure-ESM runtime. Declared locally so
+// this type-checks without ambient Node types; the `typeof` guard keeps the reference ESM-safe.
+declare const require: ((id: string) => unknown) | undefined;
+
+/** A `require`-like resolver. Injectable in tests; production uses the guarded runtime require. */
+export type OptionalRequire = (moduleName: string) => unknown;
+
+/** Trim + reject non-strings/empties so we only ever emit a real version string. */
+export const coerceVersion = (value: unknown): string | undefined => {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+};
+
+/**
+ * Guarded runtime require. `moduleName` is a VARIABLE (a parameter), so bundlers cannot statically
+ * resolve it — a host without the module never fails to build; the call just throws and is caught.
+ */
+const runtimeRequire: OptionalRequire = (moduleName) => {
+  try {
+    if (typeof require !== "function") return undefined;
+    return require(moduleName);
+  } catch {
+    return undefined;
+  }
+};
+
+/** Read a module's `default` (Expo modules are consumed as default exports) or the namespace. */
+const interop = (mod: unknown): Record<string, unknown> | undefined => {
+  if (!mod || typeof mod !== "object") return undefined;
+  const def = (mod as { default?: unknown }).default;
+  if (def && typeof def === "object") return def as Record<string, unknown>;
+  return mod as Record<string, unknown>;
+};
+
+/** Resolve a module namespace, swallowing a throwing require (an uninstalled module throws). */
+const safeInterop = (
+  requireModule: OptionalRequire,
+  moduleName: string,
+): Record<string, unknown> | undefined => {
+  try {
+    return interop(requireModule(moduleName));
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Detect the host app version, preferring `expo-constants` (`expoConfig.version`, then
+ * `nativeAppVersion`) and finally `expo-application` (`nativeApplicationVersion`). Returns the
+ * first real string, or `undefined` when none of those are available. Pure and never throws.
+ *
+ * `requireModule` is injectable so tests can exercise the "found" path without the native modules;
+ * production defaults to the guarded runtime require above.
+ */
+export const detectAppVersion = (
+  requireModule: OptionalRequire = runtimeRequire,
+): string | undefined => {
+  try {
+    const constants = safeInterop(requireModule, "expo-constants");
+    if (constants) {
+      const expoConfig = constants.expoConfig;
+      if (expoConfig && typeof expoConfig === "object") {
+        const fromExpoConfig = coerceVersion((expoConfig as { version?: unknown }).version);
+        if (fromExpoConfig) return fromExpoConfig;
+      }
+      const fromNative = coerceVersion(constants.nativeAppVersion);
+      if (fromNative) return fromNative;
+    }
+
+    const application = safeInterop(requireModule, "expo-application");
+    if (application) {
+      const fromApplication = coerceVersion(application.nativeApplicationVersion);
+      if (fromApplication) return fromApplication;
+    }
+  } catch {
+    // Any unexpected read error → "unknown"; analytics must never crash onboarding.
+  }
+  return undefined;
+};

package/src/device/deviceContext.ts

@@ -4,9 +4,12 @@
  * adding a single dependency to the kit or changing a host app's App Privacy / Data Safety
  * declarations.
  *
- * HARD RULE (why this file has no imports beyond React Native built-ins):
+ * HARD RULE (why this file adds no dependency):
  *   The kit stays dependency-free. Everything here comes from `Platform`, `Dimensions`,
- *   `I18nManager`, and the standard `Intl` global. There are NO advertising IDs, NO
+ *   `I18nManager`, and the standard `Intl` global — plus a best-effort `appVersion` read via
+ *   `detectAppVersion()`, which itself adds NO dependency (it reaches for `expo-constants` /
+ *   `expo-application` through a guarded, variable-specifier require that a host without them
+ *   simply never resolves — see device/appVersion.ts). There are NO advertising IDs, NO
  *   `getUniqueId`/IDFA/GAID/fingerprinting APIs, and nothing that would require a new
  *   privacy-label entry. A host can adopt this without touching its store declarations.
  *
@@ -17,6 +20,8 @@
  */
 import { Dimensions, I18nManager, Platform } from "react-native";
 
+import { detectAppVersion } from "./appVersion";
+
 /** Coarse device class. iOS uses the reported interface idiom; else a screen-size heuristic. */
 export type DeviceFormFactor = "phone" | "tablet";
 
@@ -50,9 +55,11 @@ export type DeviceContext = {
   /** IANA time zone (e.g. "Europe/Berlin"), from `Intl` when available. */
   timeZone?: string;
   /**
-   * Host app version (e.g. "1.4.2). HOST-INJECTED — NOT collected here. `WireOnboarding`
-   * merges `config.appVersion` into the snapshot; `collectDeviceContext()` never sets it.
-   * Hosts typically pass it from `expo-constants` (the kit itself adds no dependency).
+   * Host app version (e.g. "1.4.2"). BEST-EFFORT auto-detected here via `detectAppVersion()`
+   * (reads `expo-constants` / `expo-application` when present; adds no dependency — see
+   * device/appVersion.ts). An explicit host-injected `config.appVersion` always WINS: the merge
+   * sites (`WireOnboarding`, the session-analytics hooks, the context envelope) overwrite this
+   * with the host value when one is supplied. Omitted when neither source yields a version.
    */
   appVersion?: string;
 };
@@ -154,5 +161,10 @@ export const collectDeviceContext = (): DeviceContext => {
     // Intl unavailable — omit locale/timeZone.
   }
 
+  // Best-effort host app version (adds no dependency; omitted when unavailable). An explicit
+  // `config.appVersion` overrides this downstream at the merge sites.
+  const appVersion = detectAppVersion();
+  if (appVersion) ctx.appVersion = appVersion;
+
   return ctx;
 };

package/src/identity/userIdentity.ts

@@ -20,6 +20,7 @@
  * ⚠️ NO PII. Pass an opaque id (or a hash), never a raw email/name/phone. The id is capped at
  * {@link USER_ID_MAX_LENGTH} chars (longer ids are truncated, not rejected).
  */
+import { getCurrentSessionId } from "../analytics/currentSession";
 import { reportClientEvent } from "../analytics/reportClientEvent";
 import {
   peekPersistedSession,
@@ -90,6 +91,10 @@ export const identifyOnboarding = async (
       contextId = stored?.id;
     }
   }
+  // Last resort: bind to the LIVE per-open session (registered by `reportSessionStart`) so a
+  // post-flow identify with no captured contextId still attaches to a session the server saw,
+  // instead of no-oping. The onboarding contextId (above) is still preferred when available.
+  if (!contextId) contextId = getCurrentSessionId();
   if (!contextId) return false;
 
   reportClientEvent(