@wireai/activation 0.4.0 → 0.8.0

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,9 @@
  */
 import { Dimensions, I18nManager, Platform } from "react-native";
 
+import { detectAppVersion } from "./appVersion";
+import { detectNativeModel } from "./deviceModel";
+
 /** Coarse device class. iOS uses the reported interface idiom; else a screen-size heuristic. */
 export type DeviceFormFactor = "phone" | "tablet";
 
@@ -31,7 +37,15 @@ export type DeviceContext = {
   osVersion?: string;
   /** Android device brand (e.g. "samsung"). Android only. */
   brand?: string;
-  /** Android device model (e.g. "SM-G991B"). Android only. */
+  /**
+   * Device model. On Android it is read directly from `Platform.constants.Model` (e.g. "SM-G991B").
+   * iOS `Platform.constants` exposes NO model, so on iOS it is a BEST-EFFORT read of `expo-device`'s
+   * `modelName` ("iPhone 14 Pro"), falling back to `modelId` ("iPhone15,2") — dependency-free via a
+   * guarded require (see device/deviceModel.ts). ASYMMETRY: without `expo-device` installed, iOS
+   * `model` is omitted (there is no dependency-free iOS model in the already-used RN surface, and the
+   * kit will not add a native dep for it); Android needs no extra module. Not PII (a device class,
+   * not a unique id), so it changes no privacy-label declaration.
+   */
   model?: string;
   /** iOS interface idiom ("phone" | "pad" | …), when reported. iOS only. */
   interfaceIdiom?: string;
@@ -50,9 +64,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;
 };
@@ -118,6 +134,10 @@ export const collectDeviceContext = (): DeviceContext => {
         ctx.interfaceIdiom = idiom;
         iosIdiom = idiom;
       }
+      // iOS has no model in `Platform.constants`; best-effort via `expo-device` (adds no dep,
+      // omitted when the module is absent — see device/deviceModel.ts).
+      const iosModel = detectNativeModel();
+      if (iosModel) ctx.model = iosModel;
     }
   } catch {
     // ignore per-OS constant reads
@@ -154,5 +174,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/device/deviceModel.ts

@@ -0,0 +1,93 @@
+/**
+ * deviceModel — best-effort, DEPENDENCY-FREE detection of the device MODEL on iOS.
+ *
+ * WHY this exists (the asymmetry it closes): `collectDeviceContext` already reports `device.model`
+ * on Android straight from `Platform.constants.Model` (e.g. "SM-G991B"), but iOS `Platform.constants`
+ * exposes NO model — only `osVersion` / `interfaceIdiom`. So the analytics `by_model` breakdown was
+ * Android-only. This module fills the iOS gap with the SAME zero-dependency technique the kit already
+ * uses for `appVersion` (see device/appVersion.ts): a GUARDED, VARIABLE-specifier `require` of the
+ * common Expo `expo-device` module. If the host has it, iOS gets a model out of the box; if not, the
+ * require simply throws and is swallowed and iOS `model` stays omitted — nothing is forced, nothing
+ * is added to `package.json`, and a host without `expo-device` never fails to bundle.
+ *
+ * WHY it is NOT PII: `expo-device`'s `modelName` ("iPhone 14 Pro") and `modelId` ("iPhone15,2") are a
+ * device CLASS shared by millions of units — the same privacy category as the Android `Model` the kit
+ * already sends. It is NOT a unique device id / IDFA / fingerprint, so surfacing it changes no App
+ * Privacy / Data Safety declaration (identical guarantee to the rest of deviceContext). It deliberately
+ * does NOT read `expo-device`'s `deviceName` (that is the user-set name, e.g. "Malik's iPhone", and IS
+ * personal data).
+ *
+ * NEVER THROWS: every read is guarded; a missing/odd value yields `undefined`, never an exception.
+ */
+
+// 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 model string. */
+const coerceModel = (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 often 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 device model via `expo-device`, preferring the human-readable `modelName`
+ * ("iPhone 14 Pro") and falling back to the identifier `modelId` ("iPhone15,2"). Returns the first
+ * real string, or `undefined` when `expo-device` is absent. Pure and never throws.
+ *
+ * `requireModule` is injectable so tests can exercise the "found" path without the native module;
+ * production defaults to the guarded runtime require above.
+ */
+export const detectNativeModel = (
+  requireModule: OptionalRequire = runtimeRequire,
+): string | undefined => {
+  try {
+    const device = safeInterop(requireModule, "expo-device");
+    if (device) {
+      const modelName = coerceModel(device.modelName);
+      if (modelName) return modelName;
+      const modelId = coerceModel(device.modelId);
+      if (modelId) return modelId;
+    }
+  } catch {
+    // Any unexpected read error → undefined; analytics must never crash onboarding.
+  }
+  return undefined;
+};

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(

package/src/index.ts

@@ -117,11 +117,36 @@ export type { OnboardingAttribution } from "./attribution/attribution";
 // ─── Device context (privacy-label-neutral, dependency-free) ──────────────────
 export { collectDeviceContext } from "./device/deviceContext";
 export type { DeviceContext, DeviceFormFactor } from "./device/deviceContext";
+export { detectAppVersion } from "./device/appVersion";
+export { detectNativeModel } from "./device/deviceModel";
 
 // ─── User identity (opaque pseudonymous id; late binding, dependency-free) ────
 export { identifyOnboarding, sanitizeUserId, USER_ID_MAX_LENGTH } from "./identity/userIdentity";
 export type { IdentifyOnboardingOptions } from "./identity/userIdentity";
 
+// ─── Rich user context (one object → every event's user_context; opt-in email PII) ────
+export {
+  resolveUserContext,
+  namespaceExtra,
+  hashEmailFnv1a,
+  isWireScalar,
+  RESERVED_USER_CONTEXT_KEYS,
+  EXTRA_KEY_PREFIX,
+} from "./context/userContext";
+export type {
+  WireUserContext,
+  ResolvedUserContext,
+  ResolveUserContextOptions,
+} from "./context/userContext";
+export { mintDeviceId, deviceIdStorageKey, AUTO_DEVICE_ID_PREFIX } from "./context/deviceId";
+
+// ─── Current per-open session registry (identify/app-events reuse the live session) ───
+export {
+  getCurrentSessionId,
+  setCurrentSessionId,
+  resetCurrentSessionId,
+} from "./analytics/currentSession";
+
 // ─── Session mapping (one `app.session_started` per app-open → /v1/events) ─────
 export {
   reportSessionStart,

package/src/session-analytics/reportSessionStart.ts

@@ -31,6 +31,7 @@
  * awaits, and swallows a missing target / bad URL / missing fetch / network error. Analytics must
  * never be able to break the app.
  */
+import { setCurrentSessionId } from "../analytics/currentSession";
 import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
 import type { DeviceContext } from "../device/deviceContext";
 import { sanitizeUserId } from "../identity/userIdentity";
@@ -104,6 +105,12 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
 
   const sessionId = opts.sessionId ?? makeSessionId();
 
+  // Register this open as the CURRENT per-open session so the analytics façade's `identify` /
+  // app-events reuse the id the server sees here (via `app.session_started`) instead of minting a
+  // fresh one it would back-fill into a phantom session. Idempotent; set before the once-guard so
+  // even a guard-deduped repeat keeps the current id pointing at this open.
+  setCurrentSessionId(sessionId);
+
   // Once-per-open guard: skip a repeat emit for a session id we already sent.
   if (opts.once !== false) {
     if (_emitted.has(sessionId)) return;

package/src/session-analytics/useLifecycleEvents.ts

@@ -119,7 +119,8 @@ export const useLifecycleEvents = (
       const { config: cfg, options: opts } = latest.current;
       if (opts.enabled !== false) {
         const device = collectDeviceContext();
-        if (cfg?.appVersion && !device.appVersion) device.appVersion = cfg.appVersion;
+        // `device.appVersion` is auto-detected best-effort; an explicit host version always wins.
+        if (cfg?.appVersion) device.appVersion = cfg.appVersion;
         reportFirstOpen({
           target: targetOf(cfg),
           sink: resolveSink(),
@@ -142,7 +143,8 @@ export const useLifecycleEvents = (
       if (opts.enabled === false) return;
       if (!cfg?.serverUrl && !opts.sink) return;
       const device = collectDeviceContext();
-      if (cfg?.appVersion && !device.appVersion) device.appVersion = cfg.appVersion;
+      // `device.appVersion` is auto-detected best-effort; an explicit host version always wins.
+      if (cfg?.appVersion) device.appVersion = cfg.appVersion;
       reportSessionStart({
         target: targetOf(cfg),
         sink: resolveSink(),

package/src/session-analytics/useSessionStart.ts

@@ -72,7 +72,8 @@ export const useSessionStart = (
       if (opts.enabled === false) return;
       const target: ClientEventTarget = { serverUrl: cfg.serverUrl, apiKey: cfg.apiKey ?? "" };
       const device = collectDeviceContext();
-      if (cfg.appVersion && !device.appVersion) device.appVersion = cfg.appVersion;
+      // `device.appVersion` is auto-detected best-effort; an explicit host version always wins.
+      if (cfg.appVersion) device.appVersion = cfg.appVersion;
       reportSessionStart({
         target,
         // A fresh per-open id each fire; the emitter's once-guard dedupes within the open.

package/src/types.ts

@@ -24,11 +24,12 @@ export type WireOnboardingConfig = {
    */
   metadata?: Record<string, unknown>;
   /**
-   * Host app version string (e.g. "1.4.2"). HOST-INJECTED — the kit adds no dependency to
-   * read it; hosts typically pass it from `expo-constants`
-   * (`Constants.expoConfig?.version`). Forwarded to the backend on the session metadata and
-   * on client events (merged into the `device` snapshot as `device.appVersion`) so analytics
-   * can segment the funnel by app version. Optional; omit if unknown.
+   * Host app version string (e.g. "1.4.2"). OPTIONAL — when omitted, the kit makes a best-effort
+   * auto-detection from `expo-constants` (`Constants.expoConfig?.version` / `nativeAppVersion`) or
+   * `expo-application` (`nativeApplicationVersion`) WITHOUT adding a dependency (a host that lacks
+   * those modules just gets no version — see device/appVersion.ts). Pass this to override the
+   * auto-detected value (it always wins). Forwarded to the backend on the session metadata and on
+   * client events (as `device.appVersion`) so analytics can segment the funnel by app version.
    */
   appVersion?: string;
 };