@wireai/activation 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.7.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/analytics/analyticsFacade.ts

@@ -31,6 +31,7 @@ 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. */
@@ -67,8 +68,12 @@ export type CreateAnalyticsConfig = {
   /**
    * 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.
+   * {@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;
 };
@@ -124,12 +129,47 @@ export const createAnalytics = (
   const resolveSessionId = (): string =>
     config.sessionId ?? getCurrentSessionId() ?? instanceSessionId;
 
-  // A provider (not a fixed value) so `networkType` + the current session id are 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: resolveSessionId(),
-      appVersion: config.appVersion,
+      appVersion: userContext.appVersion ?? config.appVersion,
       appBuild: config.appBuild,
       networkType: config.networkType,
     });
@@ -142,10 +182,6 @@ export const createAnalytics = (
     ...options,
   });
 
-  // 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);
@@ -165,7 +201,16 @@ export const createAnalytics = (
   // 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 });
+    // 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 ?? {}) };
     }

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/device/deviceContext.ts

@@ -21,6 +21,7 @@
 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";
@@ -36,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;
@@ -125,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

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/index.ts

@@ -118,6 +118,7 @@ export type { OnboardingAttribution } from "./attribution/attribution";
 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";
@@ -137,6 +138,7 @@ export type {
   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 {