@wireai/activation 0.11.0 → 0.12.1

package/dist/{currentSession-C0_odnIW.d.mts → currentSession-BlCeDP0f.d.mts}

@@ -349,16 +349,53 @@ type WireOnboardingProps = {
     /** Lifecycle hook for host-side analytics (started / per-turn / error). */
     onEvent?: (event: OnboardingEvent) => void;
     /**
-     * Host-injected, non-PII context the app already knows about the user — signup method,
-     * referral source, plan tier, a HASHED user id, etc. Same host-injection philosophy as
-     * `storage`: the kit collects nothing here; the host passes what it wants. Forwarded to the
-     * backend on the session metadata AND on client events so analytics can segment the funnel.
+     * **THIS IS WHERE THE JOIN KEY GOES.** `user_context.device_key` is the ONLY thing that joins an
+     * onboarding session to everything the app reports later (analytics, purchases, gate decisions).
+     * Build the value with the helper so the wire spelling is decided in one place:
+     *
+     * ```tsx
+     * <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
+     * // no device id of your own? read the kit's:
+     * <WireOnboarding userContext={activationJoinContext(resolveAutoDeviceKey({ appId, storage }))} ... />
+     * ```
+     *
+     * SINCE 0.12.2, leaving it out no longer silently empties the funnel: when you pass `storage` and
+     * this prop carries no `device_key`, the kit injects its OWN per-install key — the same one the
+     * analytics surfaces mint and persist — so the default wiring joins. Anything you DO pass wins
+     * verbatim and is never touched. See `autoJoinKey` for the opt-out and the two cases where the kit
+     * still cannot fill the gap (no `storage`, or you opted out), which keep warning in dev.
+     *
+     * Never hand-write `userContext={{ deviceKey }}`: the server's device lookup reads `device_key`,
+     * so a misspelled bucket produces a silently empty funnel rather than an error. And never join on
+     * `session_id` — an onboarding session id is the A2A `contextId` while an app-event session id is
+     * the per-open id, so intersecting those two id spaces returns zero rows every time.
+     *
+     * SECOND JOB, segmentation: anything else non-PII the app already knows — signup method, referral
+     * source, plan tier, a HASHED user id. Same host-injection philosophy as `storage`: the kit
+     * collects nothing here; the host passes what it wants. Forwarded to the backend on the session
+     * metadata AND on client events so analytics can segment the funnel.
      *
      * MUST NOT contain PII such as raw emails, names, or phone numbers — pass a hash if you need
      * a user key. Values are limited to primitives (`string | number | boolean`); the server caps
      * key count / size and drops deep nesting. Old servers ignore it (backward compatible).
      */
     userContext?: Record<string, string | number | boolean>;
+    /**
+     * OPT OUT of the automatic join key. Default `true`.
+     *
+     * By default (0.12.2+), an onboarding session that was given no `userContext.device_key` gets the
+     * kit's own per-install key injected — the SAME id `createAnalytics` / `createWireActivation` mint
+     * and persist — so the `activated` funnel joins without the host wiring anything. Pass
+     * `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session; that restores the
+     * pre-0.12.2 behavior exactly (nothing injected) and the dev warning fires again.
+     *
+     * Two things this flag does NOT do. It never overrides a `device_key` you passed — a host-supplied
+     * key always wins, whatever this is set to. And it cannot conjure a key without `storage`: with no
+     * persistence the kit's id is minted fresh every launch, and a per-launch key corrupts
+     * `min_sessions` instead of merely leaving the join empty, so the kit declines to inject and warns
+     * in dev instead.
+     */
+    autoJoinKey?: boolean;
     /**
      * The host's own user id, so onboarding sessions can be reconciled to real users later
      * (console sessions ↔ your user table / GA4 users). First-class alongside `userContext`.
@@ -722,6 +759,21 @@ interface ClearUserContextOptions {
  * 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 {
     /**
@@ -792,40 +844,82 @@ type IdentifyOnboardingOptions = {
 declare const identifyOnboarding: (opts: IdentifyOnboardingOptions) => Promise<boolean>;
 
 /**
- * currentSession — a tiny registry of the CURRENT per-open `session_id`.
+ * 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).
  *
- * 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).
+ * 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.
  *
- * 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.
+ * 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.
  *
- * ── 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-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;
+/**
+ * The AWAITABLE sibling of {@link resolveAutoDeviceKey}: resolve to the auto `device_key` AFTER the
+ * persisted id has been read back (or written, on a first run), so the caller stamps the id this
+ * install will keep rather than the one that was minted a millisecond ago.
  *
- * 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.
+ * WHY IT EXISTS: `resolveAutoDeviceKey` is synchronous by contract, so a caller firing at mount got
+ * the freshly minted id and the persisted one landed milliseconds later. For most events that is
+ * noise. For `app.session_started` it is the whole metric: the server computes `min_sessions` by
+ * counting distinct opens grouped by `device_key`, so a per-launch key there makes the counter
+ * structurally incapable of exceeding 1, and it splits `first_open` off from every event that
+ * follows it. Only a caller that can afford one storage read should use this; the fire-and-forget
+ * event paths must stay on the sync function.
  *
- * 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.
+ * Never throws or rejects: a missing, hung, or rejecting adapter resolves to the in-memory id, and
+ * with no `storage` it resolves immediately (there is nothing to hydrate from).
  */
+declare const hydrateAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => Promise<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.
@@ -835,5 +929,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 OnboardingEvent as B, type ClearUserContextOptions as C, type OnboardingCopy as D, type EventQueueOptions as E, type DeviceContext as F, type DeviceFormFactor as G, EXTRA_KEY_PREFIX as H, type IdentifyOnboardingOptions as I, type OnboardingProgress as J, type ResolveUserContextOptions as K, type ResolvedUserContext as L, collectDeviceContext as M, hashEmailFnv1a as N, type OnboardingResult as O, identifyOnboarding as P, isWireScalar as Q, RESERVED_USER_CONTEXT_KEYS as R, type StepValidator as S, namespaceExtra as T, USER_ID_MAX_LENGTH as U, resolveUserContext as V, type WireUserContext as W, sanitizeUserId as X, type ClientEvent as a, type ClientEventTarget as b, type ClientEventType as c, type ContextEnvelope as d, type ContextEnvelopeInput as e, type EnvelopeSource as f, type EventQueue as g, WIRE_ONBOARDING_EVENTS as h, type WireOnboardingEventName as i, analyticsUserIdStorageKey as j, buildContextEnvelope as k, clearPiiFromContext as l, clearUserContext as m, createEventQueue as n, getCurrentSessionId as o, looksLikeEmail as p, makeSessionId as q, reportClientEvent as r, reportClientEventAwait as s, reportClientEvents as t, reportClientEventsAwait as u, resetCurrentSessionId as v, setCurrentSessionId as w, toAnalyticsEvent as x, type WireOnboardingProps as y, type WireOnboardingConfig as z };
+export { hydrateAutoDeviceKey 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, identifyOnboarding as a0, isWireScalar as a1, mintDeviceId as a2, namespaceExtra as a3, resolveUserContext as a4, sanitizeUserId as a5, 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-DdnUq2HQ.d.ts → currentSession-BxEB37xt.d.ts}

@@ -349,16 +349,53 @@ type WireOnboardingProps = {
     /** Lifecycle hook for host-side analytics (started / per-turn / error). */
     onEvent?: (event: OnboardingEvent) => void;
     /**
-     * Host-injected, non-PII context the app already knows about the user — signup method,
-     * referral source, plan tier, a HASHED user id, etc. Same host-injection philosophy as
-     * `storage`: the kit collects nothing here; the host passes what it wants. Forwarded to the
-     * backend on the session metadata AND on client events so analytics can segment the funnel.
+     * **THIS IS WHERE THE JOIN KEY GOES.** `user_context.device_key` is the ONLY thing that joins an
+     * onboarding session to everything the app reports later (analytics, purchases, gate decisions).
+     * Build the value with the helper so the wire spelling is decided in one place:
+     *
+     * ```tsx
+     * <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
+     * // no device id of your own? read the kit's:
+     * <WireOnboarding userContext={activationJoinContext(resolveAutoDeviceKey({ appId, storage }))} ... />
+     * ```
+     *
+     * SINCE 0.12.2, leaving it out no longer silently empties the funnel: when you pass `storage` and
+     * this prop carries no `device_key`, the kit injects its OWN per-install key — the same one the
+     * analytics surfaces mint and persist — so the default wiring joins. Anything you DO pass wins
+     * verbatim and is never touched. See `autoJoinKey` for the opt-out and the two cases where the kit
+     * still cannot fill the gap (no `storage`, or you opted out), which keep warning in dev.
+     *
+     * Never hand-write `userContext={{ deviceKey }}`: the server's device lookup reads `device_key`,
+     * so a misspelled bucket produces a silently empty funnel rather than an error. And never join on
+     * `session_id` — an onboarding session id is the A2A `contextId` while an app-event session id is
+     * the per-open id, so intersecting those two id spaces returns zero rows every time.
+     *
+     * SECOND JOB, segmentation: anything else non-PII the app already knows — signup method, referral
+     * source, plan tier, a HASHED user id. Same host-injection philosophy as `storage`: the kit
+     * collects nothing here; the host passes what it wants. Forwarded to the backend on the session
+     * metadata AND on client events so analytics can segment the funnel.
      *
      * MUST NOT contain PII such as raw emails, names, or phone numbers — pass a hash if you need
      * a user key. Values are limited to primitives (`string | number | boolean`); the server caps
      * key count / size and drops deep nesting. Old servers ignore it (backward compatible).
      */
     userContext?: Record<string, string | number | boolean>;
+    /**
+     * OPT OUT of the automatic join key. Default `true`.
+     *
+     * By default (0.12.2+), an onboarding session that was given no `userContext.device_key` gets the
+     * kit's own per-install key injected — the SAME id `createAnalytics` / `createWireActivation` mint
+     * and persist — so the `activated` funnel joins without the host wiring anything. Pass
+     * `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session; that restores the
+     * pre-0.12.2 behavior exactly (nothing injected) and the dev warning fires again.
+     *
+     * Two things this flag does NOT do. It never overrides a `device_key` you passed — a host-supplied
+     * key always wins, whatever this is set to. And it cannot conjure a key without `storage`: with no
+     * persistence the kit's id is minted fresh every launch, and a per-launch key corrupts
+     * `min_sessions` instead of merely leaving the join empty, so the kit declines to inject and warns
+     * in dev instead.
+     */
+    autoJoinKey?: boolean;
     /**
      * The host's own user id, so onboarding sessions can be reconciled to real users later
      * (console sessions ↔ your user table / GA4 users). First-class alongside `userContext`.
@@ -722,6 +759,21 @@ interface ClearUserContextOptions {
  * 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 {
     /**
@@ -792,40 +844,82 @@ type IdentifyOnboardingOptions = {
 declare const identifyOnboarding: (opts: IdentifyOnboardingOptions) => Promise<boolean>;
 
 /**
- * currentSession — a tiny registry of the CURRENT per-open `session_id`.
+ * 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).
  *
- * 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).
+ * 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.
  *
- * 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.
+ * 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.
  *
- * ── 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-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;
+/**
+ * The AWAITABLE sibling of {@link resolveAutoDeviceKey}: resolve to the auto `device_key` AFTER the
+ * persisted id has been read back (or written, on a first run), so the caller stamps the id this
+ * install will keep rather than the one that was minted a millisecond ago.
  *
- * 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.
+ * WHY IT EXISTS: `resolveAutoDeviceKey` is synchronous by contract, so a caller firing at mount got
+ * the freshly minted id and the persisted one landed milliseconds later. For most events that is
+ * noise. For `app.session_started` it is the whole metric: the server computes `min_sessions` by
+ * counting distinct opens grouped by `device_key`, so a per-launch key there makes the counter
+ * structurally incapable of exceeding 1, and it splits `first_open` off from every event that
+ * follows it. Only a caller that can afford one storage read should use this; the fire-and-forget
+ * event paths must stay on the sync function.
  *
- * 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.
+ * Never throws or rejects: a missing, hung, or rejecting adapter resolves to the in-memory id, and
+ * with no `storage` it resolves immediately (there is nothing to hydrate from).
  */
+declare const hydrateAutoDeviceKey: (opts?: ResolveAutoDeviceKeyOptions) => Promise<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.
@@ -835,5 +929,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 OnboardingEvent as B, type ClearUserContextOptions as C, type OnboardingCopy as D, type EventQueueOptions as E, type DeviceContext as F, type DeviceFormFactor as G, EXTRA_KEY_PREFIX as H, type IdentifyOnboardingOptions as I, type OnboardingProgress as J, type ResolveUserContextOptions as K, type ResolvedUserContext as L, collectDeviceContext as M, hashEmailFnv1a as N, type OnboardingResult as O, identifyOnboarding as P, isWireScalar as Q, RESERVED_USER_CONTEXT_KEYS as R, type StepValidator as S, namespaceExtra as T, USER_ID_MAX_LENGTH as U, resolveUserContext as V, type WireUserContext as W, sanitizeUserId as X, type ClientEvent as a, type ClientEventTarget as b, type ClientEventType as c, type ContextEnvelope as d, type ContextEnvelopeInput as e, type EnvelopeSource as f, type EventQueue as g, WIRE_ONBOARDING_EVENTS as h, type WireOnboardingEventName as i, analyticsUserIdStorageKey as j, buildContextEnvelope as k, clearPiiFromContext as l, clearUserContext as m, createEventQueue as n, getCurrentSessionId as o, looksLikeEmail as p, makeSessionId as q, reportClientEvent as r, reportClientEventAwait as s, reportClientEvents as t, reportClientEventsAwait as u, resetCurrentSessionId as v, setCurrentSessionId as w, toAnalyticsEvent as x, type WireOnboardingProps as y, type WireOnboardingConfig as z };
+export { hydrateAutoDeviceKey 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, identifyOnboarding as a0, isWireScalar as a1, mintDeviceId as a2, namespaceExtra as a3, resolveUserContext as a4, sanitizeUserId as a5, 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 };