@wireai/activation 0.4.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.4.0",
+  "version": "0.8.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,11 @@
  * 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 { mintDeviceId, deviceIdStorageKey } from "../context/deviceId";
 import { sanitizeUserId } from "../identity/userIdentity";
 
 /** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
@@ -62,6 +65,17 @@ 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.
+   *
+   * NOTE on `deviceKey`: you do NOT need to supply one. When omitted, the kit auto-mints a stable,
+   * non-PII per-install `device_key`, persists it via `storage`, and reuses it every open (in-memory
+   * fallback without storage) — so `user_context.device_key` is ALWAYS present for the server's
+   * review/questionnaire gating + A/B stickiness. Supply `deviceKey` only to use your OWN id (it wins).
+   */
+  userContext?: WireUserContext;
 };
 
 /** Optional queue tuning knobs, forwarded verbatim to {@link createEventQueue}. */
@@ -81,6 +95,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,13 +118,58 @@ 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.
+  // 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).
+  let userContext: WireUserContext = { ...(config.userContext ?? {}) };
+
+  // Auto device id (the headline: "device" fully automatic). When the host supplies NO `deviceKey`,
+  // the kit mints ONE stable, non-PII per-install id, PERSISTS it via the host `storage`, and reuses it
+  // on every subsequent open — so `user_context.device_key` is ALWAYS present (the server's
+  // review/questionnaire gating + A/B stickiness both key on it) with zero host wiring. A host-supplied
+  // `deviceKey` still wins (see `applyContext`). Falls back to an in-memory id (stable for this
+  // instance) when no storage is available.
+  const hostDeviceKeyAtInit =
+    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(() => {});
+  }
+
+  // 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
+  // set the version ONLY inside `userContext`) now flows into `device.appVersion` too — not just
+  // `user_context.app_version` — so the server's `by_app_version` breakdown (which reads
+  // `device.appVersion`) agrees. Explicit wins over the auto-detected device version;
+  // `buildContextEnvelope` keeps the auto value when neither is set.
   const envelope = (): ContextEnvelope =>
     buildContextEnvelope({
-      sessionId,
-      appVersion: config.appVersion,
+      sessionId: resolveSessionId(),
+      appVersion: userContext.appVersion ?? config.appVersion,
       appBuild: config.appBuild,
       networkType: config.networkType,
     });
@@ -117,28 +182,67 @@ export const createAnalytics = (
     ...options,
   });
 
-  // Per-session, in-memory user binding. Persisted across launches when storage is provided.
-  let boundUserId: string | undefined;
+  // 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 => {
+    // Host `deviceKey` wins; otherwise the auto-minted/persisted per-install id fills it in so
+    // `user_context.device_key` is always present.
+    const hostDeviceKey =
+      typeof userContext.deviceKey === "string" && userContext.deviceKey.trim()
+        ? userContext.deviceKey
+        : undefined;
+    const resolved = resolveUserContext(
+      { ...userContext, deviceKey: hostDeviceKey ?? autoDeviceKey },
+      { 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 +252,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 +270,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 +284,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/deviceId.ts

@@ -0,0 +1,43 @@
+/**
+ * deviceId — mint a stable, NON-PII, per-install device id the kit owns when the host supplies
+ * none. This is the headline of "device fully automatic": the analytics façade auto-mints ONE id,
+ * persists it via the host's `storage` abstraction, and reuses it on every subsequent open — so
+ * `user_context.device_key` is ALWAYS present and the server's review/questionnaire gating +
+ * A/B stickiness (both key on `device_key`) work out of the box, with zero host wiring.
+ *
+ * WHY it is NOT PII and adds NO dependency (the kit's hard rules):
+ *   The id is a random token generated from `Date.now()` + `Math.random()` — it carries NO hardware
+ *   identifier, NO IDFA/GAID, NO fingerprint. It is a first-party per-install correlation key, the
+ *   same privacy category as a first-party cookie: it groups a single install's sessions and cannot
+ *   identify a person or be joined across apps. There is NO `uuid` (or any) dependency — a
+ *   time+random scheme is sufficient because the id is minted ONCE and then persisted, so global
+ *   uniqueness across the fleet is not required (a per-install collision is astronomically unlikely
+ *   and inconsequential — worst case two installs share a bucket).
+ *
+ * A host that wants its OWN device id still wins: pass `WireUserContext.deviceKey` and the kit uses
+ * that verbatim and never mints/persists an auto id.
+ */
+
+/** Prefix so an auto-minted id is visibly the kit's (distinguishable from a host-supplied `deviceKey`). */
+export const AUTO_DEVICE_ID_PREFIX = "wdev_";
+
+/** The storage key the façade persists the auto-minted id under (namespaced per `appId`). */
+export const deviceIdStorageKey = (appId?: string): string =>
+  `wireai:analytics:deviceKey:${appId ?? "default"}`;
+
+/** One 32-bit base-36 chunk of randomness. Two chunks are concatenated for a wider token. */
+const randomChunk = (): string =>
+  Math.floor(Math.random() * 0x100000000)
+    .toString(36)
+    .padStart(6, "0");
+
+/**
+ * Mint a fresh per-install device id. Dependency-free (`Date.now()` + `Math.random()`), never
+ * throws, and returns a NEW value on every call — the façade mints ONCE and persists, so this is
+ * called at most once per install (then the persisted value is reused). Two random chunks plus the
+ * timestamp keep the token wide enough that a per-install collision is not a practical concern.
+ */
+export const mintDeviceId = (): string => {
+  const time = Date.now().toString(36);
+  return `${AUTO_DEVICE_ID_PREFIX}${time}_${randomChunk()}${randomChunk()}`;
+};

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