@wireai/activation 0.4.0 → 0.8.0

package/AGENTS.md

@@ -78,7 +78,7 @@ There is no `analytics` subpath: the app-event / analytics API is exported from
 | `serverUrl` | `string` | yes | Base server URL; the kit appends `/a2a`. |
 | `appId` | `string` | yes | Passed as the A2A `model` (informational; the key resolves the app). |
 | `metadata` | `Record<string, unknown>` | no | Merged into every A2A request (e.g. install attribution). The kit reserves `sessionId` + `supportedComponents`; do not override them. |
-| `appVersion` | `string` | no | Host app version string (e.g. `"1.4.2"`); forwarded to the backend + client events so analytics can segment the funnel by app version. |
+| `appVersion` | `string` | no | App version string (e.g. `"1.4.2"`); forwarded to the backend + client events so analytics can segment the funnel by app version. Auto-detected best-effort from `expo-constants`/`expo-application` (dependency-free) when omitted; pass it to override (yours wins). |
 
 ## App events / analytics (root export)
 

package/CHANGELOG.md

@@ -18,8 +18,100 @@ Historical entries below the rename keep the old package name on purpose.
 - Version reset to `0.1.0` to mark the start of the new package line. The GitHub repository
   stays `chohra-med/wireai-onboarding`.
 
+## [Unreleased]
+
+### Added: "device" is now fully automatic — auto-minted, persisted per-install `device_key`
+
+- The analytics façade (`createAnalytics`) now auto-mints a stable, NON-PII per-install `device_key`
+  when the host supplies none via `WireUserContext.deviceKey`. It is minted ONCE (`context/deviceId.ts`
+  — `mintDeviceId`, dependency-free time+random, no `uuid`), PERSISTED via the host's existing
+  `storage` (`WireOnboardingStorage`) under `deviceIdStorageKey(appId)`, and REUSED on every open;
+  with no storage it falls back to an in-memory id. Result: `user_context.device_key` is ALWAYS
+  present, so the server's review/questionnaire gating + A/B stickiness (both key on `device_key`)
+  work out of the box with zero host wiring. A host-supplied `deviceKey` still WINS (and opts out of
+  auto-minting). New exports: `mintDeviceId`, `deviceIdStorageKey`, `AUTO_DEVICE_ID_PREFIX`.
+
+### Fixed: `WireUserContext.appVersion` now flows into `device.appVersion` (not just `user_context`)
+
+- A host that set the app version ONLY inside `userContext` previously got it in
+  `user_context.app_version` but left `device.appVersion` on the auto-detected value — and the
+  server's `by_app_version` breakdown reads `device.appVersion`. The façade's context-envelope
+  provider now feeds `userContext.appVersion ?? config.appVersion` into `buildContextEnvelope`, so an
+  explicit `WireUserContext.appVersion` populates BOTH surfaces (explicit still wins over auto-detect).
+
+### Added: best-effort iOS `device.model`
+
+- `device.model` was Android-only (`Platform.constants.Model`); iOS `Platform.constants` exposes no
+  model. `collectDeviceContext` now fills iOS `model` best-effort via `detectNativeModel`
+  (`device/deviceModel.ts`), reading `expo-device`'s `modelName`/`modelId` through the SAME guarded,
+  variable-specifier require the kit already uses for `appVersion` — so it adds NO dependency and is
+  simply omitted when `expo-device` is absent. It reads a device CLASS (not a unique id / not the
+  user-set device name), so it changes no App Privacy / Data Safety declaration. ASYMMETRY documented
+  in the `DeviceContext.model` TSDoc: without `expo-device`, iOS `model` stays omitted; no native
+  dependency is added for it.
+
+- Backward compatible: no existing export renamed or removed; zero new dependencies. The one
+  behavior change is intentional — events now carry an auto `device_key` when the host omits one.
+
 ## [0.7.0] — Unreleased
 
+### Added: `WireUserContext` — one rich user-context object → every event's `user_context`
+
+- New `context/userContext.ts` + public export `WireUserContext`: a single, extensible object a host
+  passes ONCE (`appVersion?`, `deviceKey?`, `userId?`, `userEmail?` + `hashEmail?`, `extra?`) that the
+  kit flows into every analytics event. Pure `resolveUserContext(ctx, { autoAppVersion })` merges it
+  with ONE precedence rule — an explicit field WINS over the auto-detected `device`/`appVersion` —
+  and omits missing fields (never sent empty). Also exported: `namespaceExtra`, `hashEmailFnv1a`,
+  `isWireScalar`, `RESERVED_USER_CONTEXT_KEYS`, `EXTRA_KEY_PREFIX`.
+- Deliberate bucket separation (nothing leaks): `userId` → the event's TOP-LEVEL opaque `user_id`
+  (via `sanitizeUserId`, capped 128) and NEVER the `user_context` bucket; `deviceKey` →
+  `user_context.device_key` (NOT `session_id`); `appVersion` → `user_context.app_version`; `extra`
+  entries are coerced to `string | number | boolean` (non-scalars/NaN/Infinity dropped) and
+  NAMESPACED under a `custom.` key prefix so a host extra can never collide with a reserved key.
+- **`userEmail` is OPT-IN PII in its OWN field** (`user_context.user_email`) — never merged into
+  `userId`. The kit NEVER auto-collects it; a host passes it only with the user's consent (EU users:
+  personal data). Set `hashEmail: true` to send a dependency-free FNV-1a fold instead of the raw
+  address (`user_context.user_email_hashed: true`). NOTE: FNV-1a is a lightweight non-cryptographic
+  fold; for a cryptographic digest, pre-hash host-side (e.g. `expo-crypto` SHA-256) and pass that as
+  `userEmail` with `hashEmail` falsy. Documented in the field's TSDoc.
+- The analytics façade (`createAnalytics`) now accepts `userContext` at init AND exposes
+  `setUserContext(partial)` so a host can attach `userId`/`userEmail` at LOGIN without remounting;
+  both flow into subsequent `track`/`screen`/`identify` events' `user_context`. Backward compatible:
+  `createAnalytics({ serverUrl, apiKey })` with no `userContext` behaves exactly as before.
+
+### Fixed: `identify` + host app-events reuse the live per-open session (kills the phantom-session)
+
+- New `analytics/currentSession.ts` (`getCurrentSessionId` / `setCurrentSessionId` /
+  `resetCurrentSessionId`): a process-local registry of the CURRENT per-open `session_id`.
+  `reportSessionStart` registers each per-open id here on every app-open.
+- The façade's `identify` (and `track`/`screen` app-events) now source their `session_id` from
+  `config.sessionId ?? getCurrentSessionId() ?? <stable per-instance id>` — so identity binds to the
+  session the server ALREADY saw (via `app.session_started`) instead of minting a fresh id the server
+  back-fills into a synthetic session. This is what inflated the Morrow/Myelino session counts. An
+  explicit `config.sessionId` still freezes the id (opt-out). This is also the kit half of the #205
+  "align all app-events to the per-open session" follow-up. **No server change required** for the
+  normal flow (session-start fires on mount, identify at login); the only residual is an `identify`
+  fired before any open this launch, which falls back to the instance id.
+- `identifyOnboarding` gains a last-resort fallback to `getCurrentSessionId()` when no `contextId`
+  is captured or resolvable from storage, so a post-flow identify binds to the live open session
+  instead of no-oping. An explicit `contextId` (or a stored one) still wins.
+
+### Added: `device.appVersion` auto-detection — populate the `by_app_version` breakdown by default
+
+- `collectDeviceContext()` now carries a best-effort `appVersion` so the analytics
+  `by_app_version` funnel breakdown works out of the box, instead of staying empty until a host
+  remembers to pass `config.appVersion`. New `device/appVersion.ts` reads the version from
+  `expo-constants` (`expoConfig.version`, then `nativeAppVersion`) or `expo-application`
+  (`nativeApplicationVersion`) when present.
+- ADDS NO DEPENDENCY: the Expo modules are read through a guarded, variable-specifier `require`,
+  so a host WITHOUT them (e.g. bare React Native) never fails to bundle — the read simply yields
+  `undefined`. Nothing is added to `package.json`; no peer is forced.
+- An explicit host `config.appVersion` still WINS everywhere (the `WireOnboarding` device memo, the
+  `useSessionStart` / `useLifecycleEvents` hooks, and the analytics context envelope overwrite the
+  auto-detected value with the host's). The context envelope also mirrors the effective version
+  onto its outer `appVersion` scalar so `user_context.app_version` populates on facade events too.
+- New public export `detectAppVersion()` (alongside `collectDeviceContext`). Never throws.
+
 ### Added: session mapping — know when a user opens the app again
 
 - New `session-analytics/` module. `reportSessionStart(opts)` posts ONE standard

package/dist/analytics/index.d.mts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-BeO_Brcu.mjs';
-import { E as EventQueueOptions } from '../eventQueue-CA1d8Fmn.mjs';
-export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, W as WIRE_ONBOARDING_EVENTS, g as WireOnboardingEventName, h as buildContextEnvelope, i as createEventQueue, m as makeSessionId, r as reportClientEvent, j as reportClientEvents, t as toAnalyticsEvent } from '../eventQueue-CA1d8Fmn.mjs';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-d9CrBxwe.mjs';
+export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-d9CrBxwe.mjs';
 import '../types-A6pTxIZV.mjs';
 import '../types-BKfpdZzX.mjs';
 import '../types-GL_hQ0TN.mjs';
@@ -120,6 +120,17 @@ 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}. */
 type AnalyticsOptions = Partial<Pick<EventQueueOptions, "maxSize" | "batchSize" | "baseBackoffMs" | "maxBackoffMs" | "maxRetries">>;
@@ -135,6 +146,12 @@ 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. */

package/dist/analytics/index.d.ts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DLpd1v5_.js';
-import { E as EventQueueOptions } from '../eventQueue-CrNB9gzH.js';
-export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, W as WIRE_ONBOARDING_EVENTS, g as WireOnboardingEventName, h as buildContextEnvelope, i as createEventQueue, m as makeSessionId, r as reportClientEvent, j as reportClientEvents, t as toAnalyticsEvent } from '../eventQueue-CrNB9gzH.js';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-f7LWcdWG.js';
+export { A as AnalyticsEvent, C as ClientEvent, a as ClientEventTarget, b as ClientEventType, c as ContextEnvelope, d as ContextEnvelopeInput, e as EnvelopeSource, f as EventQueue, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, i as buildContextEnvelope, j as createEventQueue, k as getCurrentSessionId, m as makeSessionId, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, s as setCurrentSessionId, t as toAnalyticsEvent } from '../currentSession-f7LWcdWG.js';
 import '../types-BhpXJGlg.js';
 import '../types-BKfpdZzX.js';
 import '../types-GL_hQ0TN.js';
@@ -120,6 +120,17 @@ 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}. */
 type AnalyticsOptions = Partial<Pick<EventQueueOptions, "maxSize" | "batchSize" | "baseBackoffMs" | "maxBackoffMs" | "maxRetries">>;
@@ -135,6 +146,12 @@ 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. */

package/dist/analytics/index.js

@@ -3,6 +3,13 @@
 var react = require('react');
 var reactNative = require('react-native');
 
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
 // src/reviews/transport.ts
 var reportAppEvent = (target, name, options = {}) => {
   if (!(target == null ? void 0 : target.serverUrl) || !name) return;
@@ -157,6 +164,98 @@ var toAnalyticsEvent = (event) => {
     }
   }
 };
+
+// src/device/appVersion.ts
+var coerceVersion = (value) => {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+};
+var runtimeRequire = (moduleName) => {
+  try {
+    if (typeof __require !== "function") return void 0;
+    return __require(moduleName);
+  } catch {
+    return void 0;
+  }
+};
+var interop = (mod) => {
+  if (!mod || typeof mod !== "object") return void 0;
+  const def = mod.default;
+  if (def && typeof def === "object") return def;
+  return mod;
+};
+var safeInterop = (requireModule, moduleName) => {
+  try {
+    return interop(requireModule(moduleName));
+  } catch {
+    return void 0;
+  }
+};
+var detectAppVersion = (requireModule = runtimeRequire) => {
+  try {
+    const constants = safeInterop(requireModule, "expo-constants");
+    if (constants) {
+      const expoConfig = constants.expoConfig;
+      if (expoConfig && typeof expoConfig === "object") {
+        const fromExpoConfig = coerceVersion(expoConfig.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 {
+  }
+  return void 0;
+};
+
+// src/device/deviceModel.ts
+var coerceModel = (value) => {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+};
+var runtimeRequire2 = (moduleName) => {
+  try {
+    if (typeof __require !== "function") return void 0;
+    return __require(moduleName);
+  } catch {
+    return void 0;
+  }
+};
+var interop2 = (mod) => {
+  if (!mod || typeof mod !== "object") return void 0;
+  const def = mod.default;
+  if (def && typeof def === "object") return def;
+  return mod;
+};
+var safeInterop2 = (requireModule, moduleName) => {
+  try {
+    return interop2(requireModule(moduleName));
+  } catch {
+    return void 0;
+  }
+};
+var detectNativeModel = (requireModule = runtimeRequire2) => {
+  try {
+    const device = safeInterop2(requireModule, "expo-device");
+    if (device) {
+      const modelName = coerceModel(device.modelName);
+      if (modelName) return modelName;
+      const modelId = coerceModel(device.modelId);
+      if (modelId) return modelId;
+    }
+  } catch {
+  }
+  return void 0;
+};
+
+// src/device/deviceContext.ts
 var deriveFormFactor = (iosIdiom, width, height) => {
   if (iosIdiom === "pad") return "tablet";
   if (iosIdiom === "phone") return "phone";
@@ -202,6 +301,8 @@ var collectDeviceContext = () => {
         ctx.interfaceIdiom = idiom;
         iosIdiom = idiom;
       }
+      const iosModel = detectNativeModel();
+      if (iosModel) ctx.model = iosModel;
     }
   } catch {
   }
@@ -226,16 +327,20 @@ var collectDeviceContext = () => {
     if (resolved.timeZone) ctx.timeZone = resolved.timeZone;
   } catch {
   }
+  const appVersion = detectAppVersion();
+  if (appVersion) ctx.appVersion = appVersion;
   return ctx;
 };
 
 // src/analytics/contextEnvelope.ts
 var buildContextEnvelope = (input = {}) => {
+  var _a;
   const device = { ...collectDeviceContext() };
-  if (input.appVersion && !device.appVersion) device.appVersion = input.appVersion;
+  if (input.appVersion) device.appVersion = input.appVersion;
+  const effectiveAppVersion = (_a = input.appVersion) != null ? _a : device.appVersion;
   const envelope = { 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;
   return envelope;
@@ -449,6 +554,16 @@ var createEventQueue = (options) => {
   return { enqueue, flush, notifyOnline, size };
 };
 
+// src/analytics/currentSession.ts
+var _currentSessionId;
+var setCurrentSessionId = (id) => {
+  if (typeof id === "string" && id.length > 0) _currentSessionId = id;
+};
+var getCurrentSessionId = () => _currentSessionId;
+var resetCurrentSessionId = () => {
+  _currentSessionId = void 0;
+};
+
 // src/identity/userIdentity.ts
 var USER_ID_MAX_LENGTH = 128;
 var sanitizeUserId = (raw) => {
@@ -458,16 +573,109 @@ var sanitizeUserId = (raw) => {
   return trimmed.length > USER_ID_MAX_LENGTH ? trimmed.slice(0, USER_ID_MAX_LENGTH) : trimmed;
 };
 
+// src/context/userContext.ts
+var EXTRA_KEY_PREFIX = "custom.";
+var isWireScalar = (value) => {
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return true;
+  if (t === "number") return Number.isFinite(value);
+  return false;
+};
+var hashEmailFnv1a = (email) => {
+  const normalized = email.trim().toLowerCase();
+  let hash = 2166136261;
+  for (let i = 0; i < normalized.length; i++) {
+    hash ^= normalized.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+};
+var cleanString = (value) => {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+};
+var namespaceExtra = (extra) => {
+  const out = {};
+  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;
+    out[`${EXTRA_KEY_PREFIX}${cleanKey}`] = value;
+  }
+  return out;
+};
+var resolveUserContext = (ctx = {}, opts = {}) => {
+  var _a;
+  const result = {};
+  const bucket = {};
+  const userId = sanitizeUserId(ctx.userId);
+  if (userId) result.userId = userId;
+  const deviceKey = cleanString(ctx.deviceKey);
+  if (deviceKey) {
+    result.deviceKey = deviceKey;
+    bucket.device_key = deviceKey;
+  }
+  const appVersion = (_a = cleanString(ctx.appVersion)) != null ? _a : cleanString(opts.autoAppVersion);
+  if (appVersion) {
+    result.appVersion = appVersion;
+    bucket.app_version = appVersion;
+  }
+  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;
+    }
+  }
+  Object.assign(bucket, namespaceExtra(ctx.extra));
+  if (Object.keys(bucket).length > 0) result.userContext = bucket;
+  return result;
+};
+
+// src/context/deviceId.ts
+var AUTO_DEVICE_ID_PREFIX = "wdev_";
+var deviceIdStorageKey = (appId) => `wireai:analytics:deviceKey:${appId != null ? appId : "default"}`;
+var randomChunk = () => Math.floor(Math.random() * 4294967296).toString(36).padStart(6, "0");
+var mintDeviceId = () => {
+  const time = Date.now().toString(36);
+  return `${AUTO_DEVICE_ID_PREFIX}${time}_${randomChunk()}${randomChunk()}`;
+};
+
 // src/analytics/analyticsFacade.ts
 var createAnalytics = (config, options = {}) => {
-  var _a, _b;
-  const sessionId = (_a = config.sessionId) != null ? _a : makeSessionId();
-  const envelope = () => buildContextEnvelope({
-    sessionId,
-    appVersion: config.appVersion,
-    appBuild: config.appBuild,
-    networkType: config.networkType
-  });
+  var _a, _b, _c, _d, _e;
+  const instanceSessionId = (_a = config.sessionId) != null ? _a : makeSessionId();
+  const resolveSessionId = () => {
+    var _a2, _b2;
+    return (_b2 = (_a2 = config.sessionId) != null ? _a2 : getCurrentSessionId()) != null ? _b2 : instanceSessionId;
+  };
+  let userContext = { ...(_b = config.userContext) != null ? _b : {} };
+  const hostDeviceKeyAtInit = typeof ((_c = config.userContext) == null ? void 0 : _c.deviceKey) === "string" && config.userContext.deviceKey.trim() ? config.userContext.deviceKey.trim() : void 0;
+  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() : void 0;
+      if (persisted) autoDeviceKey = persisted;
+      else void storage.setItem(deviceKey, autoDeviceKey).catch(() => {
+      });
+    }).catch(() => {
+    });
+  }
+  const envelope = () => {
+    var _a2;
+    return buildContextEnvelope({
+      sessionId: resolveSessionId(),
+      appVersion: (_a2 = userContext.appVersion) != null ? _a2 : config.appVersion,
+      appBuild: config.appBuild,
+      networkType: config.networkType
+    });
+  };
   const queue = createEventQueue({
     target: { serverUrl: config.serverUrl, apiKey: config.apiKey },
     storage: config.storage,
@@ -475,23 +683,48 @@ var createAnalytics = (config, options = {}) => {
     envelope,
     ...options
   });
-  let boundUserId;
-  const storageKey = `wireai:analytics:userId:${(_b = config.appId) != null ? _b : "default"}`;
+  let boundUserId = sanitizeUserId((_d = config.userContext) == null ? void 0 : _d.userId);
+  const storageKey = `wireai:analytics:userId:${(_e = config.appId) != null ? _e : "default"}`;
   if (config.storage) {
     void config.storage.getItem(storageKey).then((saved) => {
-      if (saved) boundUserId = saved;
+      if (saved && !boundUserId) boundUserId = saved;
     }).catch(() => {
     });
   }
+  const applyContext = (event) => {
+    var _a2;
+    const hostDeviceKey = typeof userContext.deviceKey === "string" && userContext.deviceKey.trim() ? userContext.deviceKey : void 0;
+    const resolved = resolveUserContext(
+      { ...userContext, deviceKey: hostDeviceKey != null ? hostDeviceKey : autoDeviceKey },
+      { autoAppVersion: config.appVersion }
+    );
+    if (resolved.userContext) {
+      event.user_context = { ...resolved.userContext, ...(_a2 = event.user_context) != null ? _a2 : {} };
+    }
+    if (boundUserId && !event.user_id) event.user_id = boundUserId;
+  };
+  const setUserContext = (partial) => {
+    var _a2, _b2;
+    if (!partial || typeof partial !== "object") return;
+    const mergedExtra = partial.extra || userContext.extra ? { ...(_a2 = userContext.extra) != null ? _a2 : {}, ...(_b2 = partial.extra) != null ? _b2 : {} } : void 0;
+    userContext = { ...userContext, ...partial };
+    if (mergedExtra) userContext.extra = mergedExtra;
+    const uid = sanitizeUserId(partial.userId);
+    if (uid) {
+      boundUserId = uid;
+      if (config.storage) void config.storage.setItem(storageKey, uid).catch(() => {
+      });
+    }
+  };
   const track = (event, props) => {
     if (!event) return;
     const 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);
   };
   const screen = (name, props) => {
@@ -499,11 +732,11 @@ var createAnalytics = (config, options = {}) => {
     const meta = { screen: name, ...props != null ? props : {} };
     const 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);
   };
   const identify = (userId, traits) => {
@@ -516,16 +749,20 @@ var createAnalytics = (config, options = {}) => {
     }
     const 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);
   };
   return {
     track,
     screen,
     identify,
+    setUserContext,
     flush: queue.flush,
     notifyOnline: queue.notifyOnline,
     size: queue.size
@@ -548,11 +785,14 @@ exports.createAnalytics = createAnalytics;
 exports.createEventQueue = createEventQueue;
 exports.createScreenTracker = createScreenTracker;
 exports.getActiveRouteName = getActiveRouteName;
+exports.getCurrentSessionId = getCurrentSessionId;
 exports.makeSessionId = makeSessionId;
 exports.reportAppEvent = reportAppEvent;
 exports.reportClientEvent = reportClientEvent;
 exports.reportClientEvents = reportClientEvents;
+exports.resetCurrentSessionId = resetCurrentSessionId;
 exports.screenTrackingHandler = screenTrackingHandler;
+exports.setCurrentSessionId = setCurrentSessionId;
 exports.toAnalyticsEvent = toAnalyticsEvent;
 exports.useAnalytics = useAnalytics;
 exports.useScreenTracking = useScreenTracking;