@wireai/activation 0.4.0 → 0.8.0

package/dist/{eventQueue-CA1d8Fmn.d.mts → currentSession-d9CrBxwe.d.mts}

@@ -11,9 +11,12 @@ import { Platform } from 'react-native';
  * 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.
  *
@@ -36,7 +39,15 @@ 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;
@@ -55,9 +66,11 @@ 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;
 };
@@ -179,11 +192,12 @@ 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;
 };
@@ -451,7 +465,7 @@ 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;
@@ -466,9 +480,10 @@ type ContextEnvelopeInput = {
     networkType?: string;
 };
 /**
- * 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
@@ -547,4 +562,125 @@ type EventQueue = {
  */
 declare const createEventQueue: (options: EventQueueOptions) => EventQueue;
 
-export { type AnalyticsEvent as A, type ClientEvent as C, type DeviceContext as D, type EventQueueOptions as E, type OnboardingResult as O, type StepValidator as S, WIRE_ONBOARDING_EVENTS as W, type ClientEventTarget as a, type ClientEventType as b, type ContextEnvelope as c, type ContextEnvelopeInput as d, type EnvelopeSource as e, type EventQueue as f, type WireOnboardingEventName as g, buildContextEnvelope as h, createEventQueue as i, reportClientEvents as j, type WireOnboardingProps as k, type WireOnboardingConfig as l, makeSessionId as m, type OnboardingEvent as n, type OnboardingCopy as o, type DeviceFormFactor as p, type OnboardingProgress as q, reportClientEvent as r, collectDeviceContext as s, toAnalyticsEvent as t };
+/**
+ * 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.
+ */
+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.
+ */
+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. */
+declare const RESERVED_USER_CONTEXT_KEYS: readonly ["device_key", "app_version", "app_build", "network_type", "session_count", "returning", "platform", "user_email", "user_email_hashed"];
+/** The prefix applied to every host `extra` key so it can never collide with a reserved key. */
+declare const EXTRA_KEY_PREFIX: "custom.";
+/** A finite scalar the wire accepts. Non-finite numbers (NaN/Infinity) are NOT scalars here. */
+declare const isWireScalar: (value: unknown) => value is string | number | boolean;
+/**
+ * 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`.
+ */
+declare const hashEmailFnv1a: (email: string) => string;
+/**
+ * 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).
+ */
+declare const namespaceExtra: (extra: Record<string, unknown> | undefined) => Record<string, string | number | boolean>;
+/** Options for {@link resolveUserContext}. */
+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.
+ */
+declare const resolveUserContext: (ctx?: WireUserContext, opts?: ResolveUserContextOptions) => ResolvedUserContext;
+
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+declare const setCurrentSessionId: (id: string | undefined) => void;
+/** The current per-open `session_id`, or `undefined` when no app-open has been registered yet. */
+declare const getCurrentSessionId: () => string | undefined;
+/** Test-only: forget the current session id so a unit test starts from a clean registry. */
+declare const resetCurrentSessionId: () => void;
+
+export { type AnalyticsEvent as A, collectDeviceContext as B, type ClientEvent as C, type DeviceContext as D, type EventQueueOptions as E, hashEmailFnv1a as F, isWireScalar as G, namespaceExtra as H, resolveUserContext as I, type OnboardingResult as O, RESERVED_USER_CONTEXT_KEYS as R, type StepValidator as S, type WireUserContext as W, type ClientEventTarget as a, type ClientEventType as b, type ContextEnvelope as c, type ContextEnvelopeInput as d, type EnvelopeSource as e, type EventQueue as f, WIRE_ONBOARDING_EVENTS as g, type WireOnboardingEventName as h, buildContextEnvelope as i, createEventQueue as j, getCurrentSessionId as k, reportClientEvents as l, makeSessionId as m, resetCurrentSessionId as n, type WireOnboardingProps as o, type WireOnboardingConfig as p, type OnboardingEvent as q, reportClientEvent as r, setCurrentSessionId as s, toAnalyticsEvent as t, type OnboardingCopy as u, type DeviceFormFactor as v, EXTRA_KEY_PREFIX as w, type OnboardingProgress as x, type ResolveUserContextOptions as y, type ResolvedUserContext as z };

package/dist/{eventQueue-CrNB9gzH.d.ts → currentSession-f7LWcdWG.d.ts}

@@ -11,9 +11,12 @@ import { Platform } from 'react-native';
  * 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.
  *
@@ -36,7 +39,15 @@ 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;
@@ -55,9 +66,11 @@ 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;
 };
@@ -179,11 +192,12 @@ 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;
 };
@@ -451,7 +465,7 @@ 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;
@@ -466,9 +480,10 @@ type ContextEnvelopeInput = {
     networkType?: string;
 };
 /**
- * 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
@@ -547,4 +562,125 @@ type EventQueue = {
  */
 declare const createEventQueue: (options: EventQueueOptions) => EventQueue;
 
-export { type AnalyticsEvent as A, type ClientEvent as C, type DeviceContext as D, type EventQueueOptions as E, type OnboardingResult as O, type StepValidator as S, WIRE_ONBOARDING_EVENTS as W, type ClientEventTarget as a, type ClientEventType as b, type ContextEnvelope as c, type ContextEnvelopeInput as d, type EnvelopeSource as e, type EventQueue as f, type WireOnboardingEventName as g, buildContextEnvelope as h, createEventQueue as i, reportClientEvents as j, type WireOnboardingProps as k, type WireOnboardingConfig as l, makeSessionId as m, type OnboardingEvent as n, type OnboardingCopy as o, type DeviceFormFactor as p, type OnboardingProgress as q, reportClientEvent as r, collectDeviceContext as s, toAnalyticsEvent as t };
+/**
+ * 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.
+ */
+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.
+ */
+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. */
+declare const RESERVED_USER_CONTEXT_KEYS: readonly ["device_key", "app_version", "app_build", "network_type", "session_count", "returning", "platform", "user_email", "user_email_hashed"];
+/** The prefix applied to every host `extra` key so it can never collide with a reserved key. */
+declare const EXTRA_KEY_PREFIX: "custom.";
+/** A finite scalar the wire accepts. Non-finite numbers (NaN/Infinity) are NOT scalars here. */
+declare const isWireScalar: (value: unknown) => value is string | number | boolean;
+/**
+ * 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`.
+ */
+declare const hashEmailFnv1a: (email: string) => string;
+/**
+ * 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).
+ */
+declare const namespaceExtra: (extra: Record<string, unknown> | undefined) => Record<string, string | number | boolean>;
+/** Options for {@link resolveUserContext}. */
+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.
+ */
+declare const resolveUserContext: (ctx?: WireUserContext, opts?: ResolveUserContextOptions) => ResolvedUserContext;
+
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+declare const setCurrentSessionId: (id: string | undefined) => void;
+/** The current per-open `session_id`, or `undefined` when no app-open has been registered yet. */
+declare const getCurrentSessionId: () => string | undefined;
+/** Test-only: forget the current session id so a unit test starts from a clean registry. */
+declare const resetCurrentSessionId: () => void;
+
+export { type AnalyticsEvent as A, collectDeviceContext as B, type ClientEvent as C, type DeviceContext as D, type EventQueueOptions as E, hashEmailFnv1a as F, isWireScalar as G, namespaceExtra as H, resolveUserContext as I, type OnboardingResult as O, RESERVED_USER_CONTEXT_KEYS as R, type StepValidator as S, type WireUserContext as W, type ClientEventTarget as a, type ClientEventType as b, type ContextEnvelope as c, type ContextEnvelopeInput as d, type EnvelopeSource as e, type EventQueue as f, WIRE_ONBOARDING_EVENTS as g, type WireOnboardingEventName as h, buildContextEnvelope as i, createEventQueue as j, getCurrentSessionId as k, reportClientEvents as l, makeSessionId as m, resetCurrentSessionId as n, type WireOnboardingProps as o, type WireOnboardingConfig as p, type OnboardingEvent as q, reportClientEvent as r, setCurrentSessionId as s, toAnalyticsEvent as t, type OnboardingCopy as u, type DeviceFormFactor as v, EXTRA_KEY_PREFIX as w, type OnboardingProgress as x, type ResolveUserContextOptions as y, type ResolvedUserContext as z };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { k as WireOnboardingProps, l as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, n as OnboardingEvent, o as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, C as ClientEvent, e as EnvelopeSource } from './eventQueue-CA1d8Fmn.mjs';
-export { A as AnalyticsEvent, b as ClientEventType, p as DeviceFormFactor, q as OnboardingProgress, W as WIRE_ONBOARDING_EVENTS, g as WireOnboardingEventName, s as collectDeviceContext, m as makeSessionId, r as reportClientEvent, j as reportClientEvents, t as toAnalyticsEvent } from './eventQueue-CA1d8Fmn.mjs';
+import { o as WireOnboardingProps, p as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, q as OnboardingEvent, u as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, C as ClientEvent, e as EnvelopeSource } from './currentSession-d9CrBxwe.mjs';
+export { A as AnalyticsEvent, b as ClientEventType, v as DeviceFormFactor, w as EXTRA_KEY_PREFIX, x as OnboardingProgress, R as RESERVED_USER_CONTEXT_KEYS, y as ResolveUserContextOptions, z as ResolvedUserContext, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, W as WireUserContext, B as collectDeviceContext, k as getCurrentSessionId, F as hashEmailFnv1a, G as isWireScalar, m as makeSessionId, H as namespaceExtra, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, I as resolveUserContext, s as setCurrentSessionId, t as toAnalyticsEvent } from './currentSession-d9CrBxwe.mjs';
 import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
 export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.mjs';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-C3qQBHsA.mjs';
@@ -826,6 +826,73 @@ declare const attributionMetadata: (a: OnboardingAttribution) => {
     attribution: Record<string, unknown>;
 };
 
+/**
+ * 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.
+ */
+/** A `require`-like resolver. Injectable in tests; production uses the guarded runtime require. */
+type OptionalRequire$1 = (moduleName: string) => unknown;
+/**
+ * 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.
+ */
+declare const detectAppVersion: (requireModule?: OptionalRequire$1) => string | undefined;
+
+/**
+ * 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.
+ */
+/** A `require`-like resolver. Injectable in tests; production uses the guarded runtime require. */
+type OptionalRequire = (moduleName: string) => unknown;
+/**
+ * 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.
+ */
+declare const detectNativeModel: (requireModule?: OptionalRequire) => string | undefined;
+
 /** Max accepted user-id length. Longer strings are truncated (never rejected). Keep in sync
  *  with the server's `USER_ID_MAX_LENGTH` (analytics/events.py). */
 declare const USER_ID_MAX_LENGTH = 128;
@@ -873,38 +940,35 @@ type IdentifyOnboardingOptions = {
 declare const identifyOnboarding: (opts: IdentifyOnboardingOptions) => Promise<boolean>;
 
 /**
- * reportSessionStart — the ONE standard emitter for "the user opened the app again".
- *
- * Every app-open posts a single `app.session_started` event to the Wire analytics backend
- * (`POST {serverUrl}/v1/events`). That event does two jobs at once, with ZERO server changes:
- *
- *   1. SESSION MAPPING. It carries the host's opaque `userId` + a stable `deviceKey`, so the
- *      backend can group a user's (or a pre-auth device's) opens over time — "when did this
- *      user last use the app, and how many times". The device_key links the pre-auth opens to
- *      the user once `userId` arrives (here or via `identifyOnboarding`).
- *   2. QUESTIONNAIRE / RETENTION FIRING. It flows into the SAME event stream the server's
- *      decision engines read, so a questionnaire trigger `{event:"app.session_started", min_count:N}`
- *      (matched within a session) or a questionnaire `min_sessions:N` (distinct device sessions)
- *      fires on the user's Nth open with no new server endpoint.
+ * 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.
  *
- * WIRE CONTRACT (server: analytics/events.py + routers/onboarding.py `POST /v1/events`):
- *   The event is stored as `event_type='app_event'`, `question_key='app.session_started'` — the
- *   generic app.* namespace the reviews wave shipped. The server's `_event_name(ev)` returns the
- *   `question_key` for an `app_event`, which is what a trigger's `event` string matches. We do NOT
- *   send `event_type:'app.session_started'` — that name is not in the server's EVENT_TYPES and
- *   would be rejected. `device_key` rides in the non-PII `user_context` bucket, where the server's
- *   `_event_device_key(ev)` reads it to group a device's sessions. `app_id` + `environment` are
- *   filled server-side from the resolving key (never sent here).
+ * 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).
  *
- * SESSION ID DISTINCTION (important): the `session_id` on this event is a PER-OPEN id (a fresh
- * `makeSessionId()` each app-open) — it is NOT the onboarding A2A `contextId`. Onboarding runs
- * ONCE (first launch) and owns its own context id; session-start fires on EVERY open, so it needs
- * its own per-open id. Grouping over time is done by `device_key`/`user_id`, not by session_id.
- *
- * Fire-and-forget: like every analytics path in the kit, this never throws into the UI, never
- * awaits, and swallows a missing target / bad URL / missing fetch / network error. Analytics must
- * never be able to break the app.
+ * 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`). */
+declare const AUTO_DEVICE_ID_PREFIX = "wdev_";
+/** The storage key the façade persists the auto-minted id under (namespaced per `appId`). */
+declare const deviceIdStorageKey: (appId?: string) => string;
+/**
+ * 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.
  */
+declare const mintDeviceId: () => string;
 
 /** The canonical event name for an app-open. A trigger keys off this exact string. */
 declare const SESSION_STARTED_EVENT: "app.session_started";
@@ -1132,4 +1196,4 @@ interface UseLifecycleEventsOptions {
  */
 declare const useLifecycleEvents: (config: LifecycleConfig | undefined, options?: UseLifecycleEventsOptions) => void;
 
-export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardHandoff, type CardHandoffProps, type CardHandoffVariant, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };
+export { AUTO_DEVICE_ID_PREFIX, AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardHandoff, type CardHandoffProps, type CardHandoffVariant, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, detectAppVersion, detectNativeModel, deviceIdStorageKey, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, mergeTheme, mintDeviceId, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };