@wireai/activation 0.10.0 → 0.12.0

package/dist/{currentSession-D0Vq7_VE.d.ts → currentSession-D6RiVtc8.d.ts}

@@ -152,6 +152,16 @@ type ClientEvent = {
      * Lets the backend reconcile onboarding sessions to real users. Old servers ignore it.
      */
     user_id?: string;
+    /**
+     * Client-stamped epoch-ms timestamp of when the event was ENQUEUED on the device. Optional and
+     * ADDITIVE: the offline queue stamps it at enqueue time (see `createEventQueue`) so two otherwise
+     * byte-identical events fired seconds apart (a genuine repeat, e.g. the user taps "share" twice)
+     * are NOT collapsed by the queue's identical-JSON de-dup — while two truly simultaneous
+     * re-enqueues of the same instant (a redundant re-render) still share a `ts` and collapse. A raw
+     * `Date.now()`, never a wall-clock the server trusts (the server derives its own receive time);
+     * an old/strict server that does not model it simply ignores the unknown field.
+     */
+    ts?: number;
 };
 /** Where to POST. Derived from `WireOnboardingConfig` (`serverUrl` + `apiKey`). */
 type ClientEventTarget = {
@@ -676,6 +686,57 @@ declare const hashEmailFnv1a: (email: string) => string;
  * are DROPPED. Returns an object (possibly empty).
  */
 declare const namespaceExtra: (extra: Record<string, unknown> | undefined) => Record<string, string | number | boolean>;
+/**
+ * The storage key the analytics façade persists the bound opaque `user_id` under (namespaced per
+ * `appId`, mirroring {@link deviceIdStorageKey}). Exported so a logout path can target it directly.
+ */
+declare const analyticsUserIdStorageKey: (appId?: string) => string;
+/**
+ * Return a COPY of a {@link WireUserContext} with every USER-scoped (PII / pseudonymous) field
+ * removed — `userId`, `userEmail`, `hashEmail`, and `extra` — while KEEPING the non-PII device-scope
+ * fields (`appVersion`, `deviceKey`). This is the in-memory half of logout: after it, the same
+ * analytics instance keeps its stable `device_key` (which groups a DEVICE, not a user) but no longer
+ * stamps the previous user's id/email onto events. Pure; never mutates the input.
+ */
+declare const clearPiiFromContext: (ctx?: WireUserContext) => WireUserContext;
+/** Options for {@link clearUserContext}. */
+interface ClearUserContextOptions {
+    /** Host persistence (AsyncStorage subset) — the persisted bound `user_id` is removed from here. */
+    storage?: WireOnboardingStorage;
+    /** Tenant/app id — namespaces the persisted key (`wireai:analytics:userId:<appId>`). */
+    appId?: string;
+}
+/**
+ * LOGOUT primitive: purge the persisted, bound opaque `user_id` for an app so the NEXT user on a
+ * shared device is not silently attributed to the previous one. Removes the
+ * `wireai:analytics:userId:<appId>` key that the analytics façade persists and reuses across
+ * launches. Fire-and-forget: a missing storage or a failing adapter resolves quietly.
+ *
+ * COVERAGE. The stateful `createAnalytics(...)` instance also exposes {@link Analytics.reset}, which
+ * does this AND clears the in-memory binding + PII in one call — prefer it when you hold the
+ * instance. This standalone helper covers the `createWireActivation` / `wire` path (whose config is
+ * captured immutably, so it has no `reset`): call `clearUserContext({ storage, appId })` on logout,
+ * and RECREATE the `wire` / analytics instance without the user's `userContext` (userId/userEmail)
+ * so no further events carry the previous user's identity. The non-PII per-install `device_key`
+ * (`wireai:analytics:deviceKey:<appId>`) is intentionally left in place — it groups a device, not a
+ * person, and stays stable across users of the same install.
+ */
+declare const clearUserContext: (opts?: ClearUserContextOptions) => Promise<void>;
+/**
+ * The `userContext` value to hand `<WireOnboarding userContext={...} />` so an onboarding session
+ * and the app's later events (purchases, actions, screens) share ONE join key.
+ *
+ * WHY it exists as a named function instead of an inline object literal: the wire key is
+ * `device_key`, the prop-facing name is `deviceKey`, and the analytics surfaces auto-mint the value
+ * for you. A host that hand-writes `userContext={{ deviceKey }}` produces a bucket the server's
+ * device lookup does not read, and the resulting funnel is silently EMPTY rather than wrong. This is
+ * the one place that spelling is decided.
+ *
+ * Pass the SAME `deviceKey` you gave `createAnalytics` / `createWireActivation`. `session_id` is not
+ * a join key across those two families: an onboarding session id is the A2A `contextId` and an
+ * app-event session id is the per-open id, so intersecting them returns nothing.
+ */
+declare const activationJoinContext: (deviceKey: string) => Record<string, string | number | boolean>;
 /** Options for {@link resolveUserContext}. */
 interface ResolveUserContextOptions {
     /**
@@ -691,41 +752,120 @@ interface ResolveUserContextOptions {
  */
 declare const resolveUserContext: (ctx?: WireUserContext, opts?: ResolveUserContextOptions) => ResolvedUserContext;
 
+/** 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;
+/**
+ * Normalize a host-supplied user id: trim, drop empty, and cap at {@link USER_ID_MAX_LENGTH}.
+ * Returns `undefined` for a missing/blank/non-string value so callers can `if (id)`-gate.
+ * PII is a host concern — this only bounds length, it does not (and cannot) detect an email.
+ */
+declare const sanitizeUserId: (raw: unknown) => string | undefined;
+/**
+ * A permissive email-SHAPE test (`local@domain.tld`) — NOT an RFC validator. Its ONE job is to
+ * catch the common integration mistake of binding a RAW EMAIL as the opaque `user_id`: that leaks
+ * PII into the top-level id (which the server treats as an opaque key and may surface), when the
+ * email belongs in the opt-in `user_context.user_email` field instead. `identify()` uses this to
+ * refuse an email-shaped id (with a dev warning) unless the host opts in explicitly. Trims first.
+ */
+declare const looksLikeEmail: (value: unknown) => boolean;
+/** Options for {@link identifyOnboarding}. */
+type IdentifyOnboardingOptions = {
+    /** Tenant transport, same shape as `WireOnboardingConfig` (only these two fields are used). */
+    config: {
+        serverUrl: string;
+        apiKey: string;
+    };
+    /** The host's opaque user id to bind. Trimmed + capped; NO PII. */
+    userId: string;
+    /**
+     * The onboarding session id to bind to (the A2A contextId) — the `contextId` field carried on
+     * the `started`/`resumed` `onEvent`. Pass this when you captured it there. Required after the
+     * flow COMPLETED, since completion clears the persisted session. Wins over the storage lookup.
+     */
+    contextId?: string;
+    /**
+     * The SAME host storage you passed to `<WireOnboarding storage={…} />`. When `contextId` is
+     * omitted, the helper reads the persisted contextId from it (works while the session is still
+     * persisted — i.e. dropped or mid-flow, before completion clears it).
+     */
+    storage?: WireOnboardingStorage;
+    /** App id, to derive the default storage key `wireai:session:<appId>` when reading from storage. */
+    appId?: string;
+    /** Storage key override — pass the same `persistKey` you gave `<WireOnboarding>`, if any. */
+    persistKey?: string;
+};
 /**
- * currentSession — a tiny registry of the CURRENT per-open `session_id`.
+ * Attach a host user id to an onboarding session AFTER the fact (post-registration), by sending
+ * an `identify` client event to `/v1/events`. Resolves the contextId from an explicit
+ * `contextId` or, failing that, from the persisted session in the host `storage`.
  *
- * 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 "phantom-session" bug).
+ * Fire-and-forget under the hood (never throws, never blocks onboarding). Resolves to `true`
+ * when an identify event was dispatched, `false` when it couldn't (no user id, no server url,
+ * or no resolvable contextId).
+ */
+declare const identifyOnboarding: (opts: IdentifyOnboardingOptions) => Promise<boolean>;
+
+/**
+ * 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.
  *
- * 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.
+ * 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).
  *
- * ── WHY A globalThis SLOT, NOT A PLAIN MODULE VARIABLE ────────────────────────────────────────
- * This module is exported from TWO package entry points — the main `.` bundle (`src/index.ts`) and
- * the `./analytics` subpath (`src/analytics/index.ts`). Under `dist` resolution (node `import`/
- * `require`, which is how tests, SSR and some tooling load the kit) tsup inlines a SEPARATE copy of
- * this module into each bundle, so a plain `let` would give the SETTER (reached via `.` →
- * `reportSessionStart`) and the READER (reached via `./analytics` → façade / `userIdentity`) TWO
- * different variables: the reader would see `undefined` even after an open set the id, and gating
- * would fire under a null session id. On-device this was masked only because Metro's `react-native`
- * export condition resolves both subpaths back to this one `src/` file (a single instance) — a
- * bundler accident, not a guarantee.
+ * 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 persistence subset {@link resolveAutoDeviceKey} needs (a strict subset of `WireOnboardingStorage`). */
+type DeviceKeyStorage = {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+};
+/** Options for {@link resolveAutoDeviceKey}. Omitting `storage` gives a PROCESS-scoped id, not a
+ *  per-install one — see the caller notes: a caller with no persistence must decide whether a
+ *  per-launch id is better or worse than no id for its metric. */
+interface ResolveAutoDeviceKeyOptions {
+    /** Tenant/app id — namespaces both the registry entry and the storage slot. */
+    appId?: string;
+    /** Host persistence. Present → the id survives launches. Absent → process-scoped only. */
+    storage?: DeviceKeyStorage;
+}
+/**
+ * The ONE auto-minted `device_key` for an install, shared by every kit surface.
  *
- * The bundler-agnostic fix: keep the ONE live value in a well-known `globalThis` slot keyed by a
- * `Symbol.for(...)`. `Symbol.for` uses the runtime-global symbol registry, so every inlined copy of
- * this module resolves the SAME symbol and reads/writes the SAME slot — one identity no matter how
- * many times the module is duplicated across bundles. `globalThis` is present and identical in
- * Hermes/React Native, Node and SSR (we never touch `window`), so this is safe on every host.
+ * SYNCHRONOUS by contract (a fire-and-forget event path cannot await): returns the current live id
+ * immediately, minting one on first call. When `storage` is supplied it also kicks off a SINGLE
+ * hydration per `appId` that adopts the persisted id (or persists the freshly minted one). Callers
+ * should call this per EVENT rather than caching the return value, so an event built after hydration
+ * carries the persisted id.
  *
- * PROCESS-LOCAL, NOT PERSISTED: the slot lives on the runtime global, so it tracks the CURRENT
- * process's open and a fresh open overwrites it. There is no cross-launch state.
- * `resetCurrentSessionId` clears the slot so a unit test starts from a clean registry.
+ * A host-supplied `deviceKey` always wins — callers must short-circuit before reaching this.
+ * Never throws: a missing, hung, or rejecting storage adapter degrades to the in-memory id.
  */
+declare const resolveAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => string;
+/** Test-only: forget every auto id + hydration flag so a unit test starts from a clean registry. */
+declare const resetAutoDeviceKeys: () => void;
+
 /**
  * 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.
@@ -735,5 +875,23 @@ declare const setCurrentSessionId: (id: string | undefined) => void;
 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;
+/**
+ * The current per-open `session_id`, MINTING and registering one when no app-open has been
+ * registered yet. Always returns a non-empty string. Idempotent (a second call returns the same id)
+ * and never throws.
+ *
+ * Use this on every path that puts a `session_id` on the wire. The server REQUIRES a non-empty
+ * `session_id` and drops the event otherwise while still answering 200 (see the module header), so
+ * "no id yet" must never mean "send it without one".
+ *
+ * BACKWARD-COMPATIBLE BY CONSTRUCTION: when `reportSessionStart` / `useLifecycleEvents` has already
+ * registered the real per-open id, this is `getCurrentSessionId()` and nothing changes. It only ever
+ * mints in the case that used to produce a silently discarded event.
+ *
+ * A mint means the host never registered an app-open, so the minted id is one the server has not
+ * seen a `session_started` for — the events land, but the session is thinner than a real open.
+ * Hence the one-time dev warning naming the fix (mount `useLifecycleEvents` at the app root).
+ */
+declare const ensureCurrentSessionId: () => string;
 
-export { type AnalyticsEvent as A, type ResolveUserContextOptions as B, type ClientEvent as C, type DeviceContext as D, type EventQueueOptions as E, type ResolvedUserContext as F, collectDeviceContext as G, hashEmailFnv1a as H, isWireScalar as I, namespaceExtra as J, resolveUserContext as K, 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, reportClientEventAwait as l, makeSessionId as m, reportClientEvents as n, reportClientEventsAwait as o, resetCurrentSessionId as p, type WireOnboardingProps as q, reportClientEvent as r, setCurrentSessionId as s, toAnalyticsEvent as t, type WireOnboardingConfig as u, type OnboardingEvent as v, type OnboardingCopy as w, type DeviceFormFactor as x, EXTRA_KEY_PREFIX as y, type OnboardingProgress as z };
+export { identifyOnboarding as $, AUTO_DEVICE_ID_PREFIX as A, resolveAutoDeviceKey as B, type ClearUserContextOptions as C, type DeviceKeyStorage as D, type EventQueueOptions as E, setCurrentSessionId as F, toAnalyticsEvent as G, type WireOnboardingProps as H, type WireOnboardingConfig as I, type OnboardingEvent as J, type OnboardingCopy as K, type DeviceContext as L, type DeviceFormFactor as M, EXTRA_KEY_PREFIX as N, type OnboardingResult as O, type IdentifyOnboardingOptions as P, type OnboardingProgress as Q, type ResolveAutoDeviceKeyOptions as R, type StepValidator as S, RESERVED_USER_CONTEXT_KEYS as T, type ResolveUserContextOptions as U, type ResolvedUserContext as V, type WireUserContext as W, USER_ID_MAX_LENGTH as X, activationJoinContext as Y, collectDeviceContext as Z, hashEmailFnv1a as _, type AnalyticsEvent as a, isWireScalar as a0, mintDeviceId as a1, namespaceExtra as a2, resolveUserContext as a3, sanitizeUserId as a4, type ClientEvent as b, type ClientEventTarget as c, type ClientEventType as d, type ContextEnvelope as e, type ContextEnvelopeInput as f, type EnvelopeSource as g, type EventQueue as h, WIRE_ONBOARDING_EVENTS as i, type WireOnboardingEventName as j, analyticsUserIdStorageKey as k, buildContextEnvelope as l, clearPiiFromContext as m, clearUserContext as n, createEventQueue as o, deviceIdStorageKey as p, ensureCurrentSessionId as q, getCurrentSessionId as r, looksLikeEmail as s, makeSessionId as t, reportClientEvent as u, reportClientEventAwait as v, reportClientEvents as w, reportClientEventsAwait as x, resetAutoDeviceKeys as y, resetCurrentSessionId as z };

package/dist/{currentSession-DdDkprpM.d.mts → currentSession-DsSDHqor.d.mts}

@@ -152,6 +152,16 @@ type ClientEvent = {
      * Lets the backend reconcile onboarding sessions to real users. Old servers ignore it.
      */
     user_id?: string;
+    /**
+     * Client-stamped epoch-ms timestamp of when the event was ENQUEUED on the device. Optional and
+     * ADDITIVE: the offline queue stamps it at enqueue time (see `createEventQueue`) so two otherwise
+     * byte-identical events fired seconds apart (a genuine repeat, e.g. the user taps "share" twice)
+     * are NOT collapsed by the queue's identical-JSON de-dup — while two truly simultaneous
+     * re-enqueues of the same instant (a redundant re-render) still share a `ts` and collapse. A raw
+     * `Date.now()`, never a wall-clock the server trusts (the server derives its own receive time);
+     * an old/strict server that does not model it simply ignores the unknown field.
+     */
+    ts?: number;
 };
 /** Where to POST. Derived from `WireOnboardingConfig` (`serverUrl` + `apiKey`). */
 type ClientEventTarget = {
@@ -676,6 +686,57 @@ declare const hashEmailFnv1a: (email: string) => string;
  * are DROPPED. Returns an object (possibly empty).
  */
 declare const namespaceExtra: (extra: Record<string, unknown> | undefined) => Record<string, string | number | boolean>;
+/**
+ * The storage key the analytics façade persists the bound opaque `user_id` under (namespaced per
+ * `appId`, mirroring {@link deviceIdStorageKey}). Exported so a logout path can target it directly.
+ */
+declare const analyticsUserIdStorageKey: (appId?: string) => string;
+/**
+ * Return a COPY of a {@link WireUserContext} with every USER-scoped (PII / pseudonymous) field
+ * removed — `userId`, `userEmail`, `hashEmail`, and `extra` — while KEEPING the non-PII device-scope
+ * fields (`appVersion`, `deviceKey`). This is the in-memory half of logout: after it, the same
+ * analytics instance keeps its stable `device_key` (which groups a DEVICE, not a user) but no longer
+ * stamps the previous user's id/email onto events. Pure; never mutates the input.
+ */
+declare const clearPiiFromContext: (ctx?: WireUserContext) => WireUserContext;
+/** Options for {@link clearUserContext}. */
+interface ClearUserContextOptions {
+    /** Host persistence (AsyncStorage subset) — the persisted bound `user_id` is removed from here. */
+    storage?: WireOnboardingStorage;
+    /** Tenant/app id — namespaces the persisted key (`wireai:analytics:userId:<appId>`). */
+    appId?: string;
+}
+/**
+ * LOGOUT primitive: purge the persisted, bound opaque `user_id` for an app so the NEXT user on a
+ * shared device is not silently attributed to the previous one. Removes the
+ * `wireai:analytics:userId:<appId>` key that the analytics façade persists and reuses across
+ * launches. Fire-and-forget: a missing storage or a failing adapter resolves quietly.
+ *
+ * COVERAGE. The stateful `createAnalytics(...)` instance also exposes {@link Analytics.reset}, which
+ * does this AND clears the in-memory binding + PII in one call — prefer it when you hold the
+ * instance. This standalone helper covers the `createWireActivation` / `wire` path (whose config is
+ * captured immutably, so it has no `reset`): call `clearUserContext({ storage, appId })` on logout,
+ * and RECREATE the `wire` / analytics instance without the user's `userContext` (userId/userEmail)
+ * so no further events carry the previous user's identity. The non-PII per-install `device_key`
+ * (`wireai:analytics:deviceKey:<appId>`) is intentionally left in place — it groups a device, not a
+ * person, and stays stable across users of the same install.
+ */
+declare const clearUserContext: (opts?: ClearUserContextOptions) => Promise<void>;
+/**
+ * The `userContext` value to hand `<WireOnboarding userContext={...} />` so an onboarding session
+ * and the app's later events (purchases, actions, screens) share ONE join key.
+ *
+ * WHY it exists as a named function instead of an inline object literal: the wire key is
+ * `device_key`, the prop-facing name is `deviceKey`, and the analytics surfaces auto-mint the value
+ * for you. A host that hand-writes `userContext={{ deviceKey }}` produces a bucket the server's
+ * device lookup does not read, and the resulting funnel is silently EMPTY rather than wrong. This is
+ * the one place that spelling is decided.
+ *
+ * Pass the SAME `deviceKey` you gave `createAnalytics` / `createWireActivation`. `session_id` is not
+ * a join key across those two families: an onboarding session id is the A2A `contextId` and an
+ * app-event session id is the per-open id, so intersecting them returns nothing.
+ */
+declare const activationJoinContext: (deviceKey: string) => Record<string, string | number | boolean>;
 /** Options for {@link resolveUserContext}. */
 interface ResolveUserContextOptions {
     /**
@@ -691,41 +752,120 @@ interface ResolveUserContextOptions {
  */
 declare const resolveUserContext: (ctx?: WireUserContext, opts?: ResolveUserContextOptions) => ResolvedUserContext;
 
+/** 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;
+/**
+ * Normalize a host-supplied user id: trim, drop empty, and cap at {@link USER_ID_MAX_LENGTH}.
+ * Returns `undefined` for a missing/blank/non-string value so callers can `if (id)`-gate.
+ * PII is a host concern — this only bounds length, it does not (and cannot) detect an email.
+ */
+declare const sanitizeUserId: (raw: unknown) => string | undefined;
+/**
+ * A permissive email-SHAPE test (`local@domain.tld`) — NOT an RFC validator. Its ONE job is to
+ * catch the common integration mistake of binding a RAW EMAIL as the opaque `user_id`: that leaks
+ * PII into the top-level id (which the server treats as an opaque key and may surface), when the
+ * email belongs in the opt-in `user_context.user_email` field instead. `identify()` uses this to
+ * refuse an email-shaped id (with a dev warning) unless the host opts in explicitly. Trims first.
+ */
+declare const looksLikeEmail: (value: unknown) => boolean;
+/** Options for {@link identifyOnboarding}. */
+type IdentifyOnboardingOptions = {
+    /** Tenant transport, same shape as `WireOnboardingConfig` (only these two fields are used). */
+    config: {
+        serverUrl: string;
+        apiKey: string;
+    };
+    /** The host's opaque user id to bind. Trimmed + capped; NO PII. */
+    userId: string;
+    /**
+     * The onboarding session id to bind to (the A2A contextId) — the `contextId` field carried on
+     * the `started`/`resumed` `onEvent`. Pass this when you captured it there. Required after the
+     * flow COMPLETED, since completion clears the persisted session. Wins over the storage lookup.
+     */
+    contextId?: string;
+    /**
+     * The SAME host storage you passed to `<WireOnboarding storage={…} />`. When `contextId` is
+     * omitted, the helper reads the persisted contextId from it (works while the session is still
+     * persisted — i.e. dropped or mid-flow, before completion clears it).
+     */
+    storage?: WireOnboardingStorage;
+    /** App id, to derive the default storage key `wireai:session:<appId>` when reading from storage. */
+    appId?: string;
+    /** Storage key override — pass the same `persistKey` you gave `<WireOnboarding>`, if any. */
+    persistKey?: string;
+};
 /**
- * currentSession — a tiny registry of the CURRENT per-open `session_id`.
+ * Attach a host user id to an onboarding session AFTER the fact (post-registration), by sending
+ * an `identify` client event to `/v1/events`. Resolves the contextId from an explicit
+ * `contextId` or, failing that, from the persisted session in the host `storage`.
  *
- * 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 "phantom-session" bug).
+ * Fire-and-forget under the hood (never throws, never blocks onboarding). Resolves to `true`
+ * when an identify event was dispatched, `false` when it couldn't (no user id, no server url,
+ * or no resolvable contextId).
+ */
+declare const identifyOnboarding: (opts: IdentifyOnboardingOptions) => Promise<boolean>;
+
+/**
+ * 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.
  *
- * 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.
+ * 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).
  *
- * ── WHY A globalThis SLOT, NOT A PLAIN MODULE VARIABLE ────────────────────────────────────────
- * This module is exported from TWO package entry points — the main `.` bundle (`src/index.ts`) and
- * the `./analytics` subpath (`src/analytics/index.ts`). Under `dist` resolution (node `import`/
- * `require`, which is how tests, SSR and some tooling load the kit) tsup inlines a SEPARATE copy of
- * this module into each bundle, so a plain `let` would give the SETTER (reached via `.` →
- * `reportSessionStart`) and the READER (reached via `./analytics` → façade / `userIdentity`) TWO
- * different variables: the reader would see `undefined` even after an open set the id, and gating
- * would fire under a null session id. On-device this was masked only because Metro's `react-native`
- * export condition resolves both subpaths back to this one `src/` file (a single instance) — a
- * bundler accident, not a guarantee.
+ * 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 persistence subset {@link resolveAutoDeviceKey} needs (a strict subset of `WireOnboardingStorage`). */
+type DeviceKeyStorage = {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+};
+/** Options for {@link resolveAutoDeviceKey}. Omitting `storage` gives a PROCESS-scoped id, not a
+ *  per-install one — see the caller notes: a caller with no persistence must decide whether a
+ *  per-launch id is better or worse than no id for its metric. */
+interface ResolveAutoDeviceKeyOptions {
+    /** Tenant/app id — namespaces both the registry entry and the storage slot. */
+    appId?: string;
+    /** Host persistence. Present → the id survives launches. Absent → process-scoped only. */
+    storage?: DeviceKeyStorage;
+}
+/**
+ * The ONE auto-minted `device_key` for an install, shared by every kit surface.
  *
- * The bundler-agnostic fix: keep the ONE live value in a well-known `globalThis` slot keyed by a
- * `Symbol.for(...)`. `Symbol.for` uses the runtime-global symbol registry, so every inlined copy of
- * this module resolves the SAME symbol and reads/writes the SAME slot — one identity no matter how
- * many times the module is duplicated across bundles. `globalThis` is present and identical in
- * Hermes/React Native, Node and SSR (we never touch `window`), so this is safe on every host.
+ * SYNCHRONOUS by contract (a fire-and-forget event path cannot await): returns the current live id
+ * immediately, minting one on first call. When `storage` is supplied it also kicks off a SINGLE
+ * hydration per `appId` that adopts the persisted id (or persists the freshly minted one). Callers
+ * should call this per EVENT rather than caching the return value, so an event built after hydration
+ * carries the persisted id.
  *
- * PROCESS-LOCAL, NOT PERSISTED: the slot lives on the runtime global, so it tracks the CURRENT
- * process's open and a fresh open overwrites it. There is no cross-launch state.
- * `resetCurrentSessionId` clears the slot so a unit test starts from a clean registry.
+ * A host-supplied `deviceKey` always wins — callers must short-circuit before reaching this.
+ * Never throws: a missing, hung, or rejecting storage adapter degrades to the in-memory id.
  */
+declare const resolveAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => string;
+/** Test-only: forget every auto id + hydration flag so a unit test starts from a clean registry. */
+declare const resetAutoDeviceKeys: () => void;
+
 /**
  * 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.
@@ -735,5 +875,23 @@ declare const setCurrentSessionId: (id: string | undefined) => void;
 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;
+/**
+ * The current per-open `session_id`, MINTING and registering one when no app-open has been
+ * registered yet. Always returns a non-empty string. Idempotent (a second call returns the same id)
+ * and never throws.
+ *
+ * Use this on every path that puts a `session_id` on the wire. The server REQUIRES a non-empty
+ * `session_id` and drops the event otherwise while still answering 200 (see the module header), so
+ * "no id yet" must never mean "send it without one".
+ *
+ * BACKWARD-COMPATIBLE BY CONSTRUCTION: when `reportSessionStart` / `useLifecycleEvents` has already
+ * registered the real per-open id, this is `getCurrentSessionId()` and nothing changes. It only ever
+ * mints in the case that used to produce a silently discarded event.
+ *
+ * A mint means the host never registered an app-open, so the minted id is one the server has not
+ * seen a `session_started` for — the events land, but the session is thinner than a real open.
+ * Hence the one-time dev warning naming the fix (mount `useLifecycleEvents` at the app root).
+ */
+declare const ensureCurrentSessionId: () => string;
 
-export { type AnalyticsEvent as A, type ResolveUserContextOptions as B, type ClientEvent as C, type DeviceContext as D, type EventQueueOptions as E, type ResolvedUserContext as F, collectDeviceContext as G, hashEmailFnv1a as H, isWireScalar as I, namespaceExtra as J, resolveUserContext as K, 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, reportClientEventAwait as l, makeSessionId as m, reportClientEvents as n, reportClientEventsAwait as o, resetCurrentSessionId as p, type WireOnboardingProps as q, reportClientEvent as r, setCurrentSessionId as s, toAnalyticsEvent as t, type WireOnboardingConfig as u, type OnboardingEvent as v, type OnboardingCopy as w, type DeviceFormFactor as x, EXTRA_KEY_PREFIX as y, type OnboardingProgress as z };
+export { identifyOnboarding as $, AUTO_DEVICE_ID_PREFIX as A, resolveAutoDeviceKey as B, type ClearUserContextOptions as C, type DeviceKeyStorage as D, type EventQueueOptions as E, setCurrentSessionId as F, toAnalyticsEvent as G, type WireOnboardingProps as H, type WireOnboardingConfig as I, type OnboardingEvent as J, type OnboardingCopy as K, type DeviceContext as L, type DeviceFormFactor as M, EXTRA_KEY_PREFIX as N, type OnboardingResult as O, type IdentifyOnboardingOptions as P, type OnboardingProgress as Q, type ResolveAutoDeviceKeyOptions as R, type StepValidator as S, RESERVED_USER_CONTEXT_KEYS as T, type ResolveUserContextOptions as U, type ResolvedUserContext as V, type WireUserContext as W, USER_ID_MAX_LENGTH as X, activationJoinContext as Y, collectDeviceContext as Z, hashEmailFnv1a as _, type AnalyticsEvent as a, isWireScalar as a0, mintDeviceId as a1, namespaceExtra as a2, resolveUserContext as a3, sanitizeUserId as a4, type ClientEvent as b, type ClientEventTarget as c, type ClientEventType as d, type ContextEnvelope as e, type ContextEnvelopeInput as f, type EnvelopeSource as g, type EventQueue as h, WIRE_ONBOARDING_EVENTS as i, type WireOnboardingEventName as j, analyticsUserIdStorageKey as k, buildContextEnvelope as l, clearPiiFromContext as m, clearUserContext as n, createEventQueue as o, deviceIdStorageKey as p, ensureCurrentSessionId as q, getCurrentSessionId as r, looksLikeEmail as s, makeSessionId as t, reportClientEvent as u, reportClientEventAwait as v, reportClientEvents as w, reportClientEventsAwait as x, resetAutoDeviceKeys as y, resetCurrentSessionId as z };