@wireai/activation 0.12.0 → 0.12.2

package/dist/{currentSession-DsSDHqor.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`.
@@ -863,6 +900,23 @@ interface ResolveAutoDeviceKeyOptions {
  * 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.
+ *
+ * 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.
+ *
+ * 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;
 
@@ -894,4 +948,4 @@ declare const resetCurrentSessionId: () => void;
  */
 declare const ensureCurrentSessionId: () => string;
 
-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 };
+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-D6RiVtc8.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`.
@@ -863,6 +900,23 @@ interface ResolveAutoDeviceKeyOptions {
  * 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.
+ *
+ * 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.
+ *
+ * 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;
 
@@ -894,4 +948,4 @@ declare const resetCurrentSessionId: () => void;
  */
 declare const ensureCurrentSessionId: () => string;
 
-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 };
+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/index.d.mts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { H as WireOnboardingProps, I as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, J as OnboardingEvent, K as OnboardingCopy, c as ClientEventTarget, L as DeviceContext, W as WireUserContext, b as ClientEvent, g as EnvelopeSource } from './currentSession-DsSDHqor.mjs';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, d as ClientEventType, M as DeviceFormFactor, D as DeviceKeyStorage, N as EXTRA_KEY_PREFIX, P as IdentifyOnboardingOptions, Q as OnboardingProgress, T as RESERVED_USER_CONTEXT_KEYS, R as ResolveAutoDeviceKeyOptions, U as ResolveUserContextOptions, V as ResolvedUserContext, X as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, Y as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, Z as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, _ as hashEmailFnv1a, $ as identifyOnboarding, a0 as isWireScalar, s as looksLikeEmail, t as makeSessionId, a1 as mintDeviceId, a2 as namespaceExtra, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, a3 as resolveUserContext, a4 as sanitizeUserId, F as setCurrentSessionId, G as toAnalyticsEvent } from './currentSession-DsSDHqor.mjs';
+import { H as WireOnboardingProps, I as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, J as OnboardingEvent, K as OnboardingCopy, c as ClientEventTarget, L as DeviceContext, W as WireUserContext, b as ClientEvent, g as EnvelopeSource } from './currentSession-BlCeDP0f.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, d as ClientEventType, M as DeviceFormFactor, D as DeviceKeyStorage, N as EXTRA_KEY_PREFIX, P as IdentifyOnboardingOptions, Q as OnboardingProgress, T as RESERVED_USER_CONTEXT_KEYS, R as ResolveAutoDeviceKeyOptions, U as ResolveUserContextOptions, V as ResolvedUserContext, X as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, Y as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, Z as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, _ as hashEmailFnv1a, $ as hydrateAutoDeviceKey, a0 as identifyOnboarding, a1 as isWireScalar, s as looksLikeEmail, t as makeSessionId, a2 as mintDeviceId, a3 as namespaceExtra, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, a4 as resolveUserContext, a5 as sanitizeUserId, F as setCurrentSessionId, G as toAnalyticsEvent } from './currentSession-BlCeDP0f.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';
@@ -1278,24 +1278,9 @@ declare const readCachedFeatures: (storage: WireOnboardingStorage, key: string)
 /** Persist `{ features, ts }` under `key` — fire-and-forget, all errors swallowed. */
 declare const writeCachedFeatures: (storage: WireOnboardingStorage, key: string, features: WireFeatures) => void;
 
-/**
- * wireConfigFromEnv — stop re-authoring env gating in every app. Reads the Wire AI
- * tenant key + server URL from the standard Expo public env vars and returns a
- * ready `WireOnboardingConfig`, or `null` when the key/URL are missing (so a host
- * can fall through to a static onboarding without writing the `if (!key)` itself).
- *
- *   EXPO_PUBLIC_WIREAI_API_KEY=...      (required)
- *   EXPO_PUBLIC_WIREAI_SERVER_URL=...   (required)
- *
- *   const config = wireConfigFromEnv({ appId: "morrow" });
- *   if (!config) return <StaticOnboarding />;
- *   return <WireOnboarding config={config} ... />;
- *
- * `appId` defaults to `EXPO_PUBLIC_WIREAI_APP_ID` (or "default"); pass overrides to
- * set `appId`/`metadata` or to substitute the key/URL programmatically.
- */
-
 type WireConfigOverrides = Partial<WireOnboardingConfig>;
+/** The env vars this helper reads. Exported so a host preflight can assert them itself. */
+declare const WIRE_ENV_VARS: readonly ["EXPO_PUBLIC_WIREAI_API_KEY", "EXPO_PUBLIC_WIREAI_SERVER_URL", "EXPO_PUBLIC_WIREAI_APP_ID"];
 declare const wireConfigFromEnv: (overrides?: WireConfigOverrides) => WireOnboardingConfig | null;
 
 type OnboardingFlagOptions = {
@@ -1840,6 +1825,11 @@ interface SessionStartConfig {
     apiKey?: string;
     /** Host app version (e.g. "1.4.2"), forwarded for release segmentation. Optional. */
     appVersion?: string;
+    /** Tenant/app id — namespaces the auto `device_key` fallback below. */
+    appId?: string;
+    /** Host storage (AsyncStorage subset). Present → `app.session_started` falls back to the kit's
+     *  persisted auto `device_key` when the host passes none. Absent → no fallback (see below). */
+    storage?: WireOnboardingStorage;
 }
 /** Per-open identity the host supplies. All optional: a pre-auth open is device-only. */
 interface UseSessionStartOptions {
@@ -2006,4 +1996,4 @@ interface UseLifecycleEventsOptions {
  */
 declare const useLifecycleEvents: (config: LifecycleConfig | undefined, options?: UseLifecycleEventsOptions) => void;
 
-export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardGridSelectCard, CardHandoff, type CardHandoffProps, type CardHandoffVariant, type CardOption, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, IconRegistryProvider, 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, PLAN_TIER_CONTEXT_KEY, type PlanTier, type PurchaseProps, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, type RevenueCatBridge, type RevenueCatBridgeConfig, type RevenueCatCustomerInfoLike, type RevenueCatEntitlementLike, type RevenueCatErrorLike, type RevenueCatOfferingLike, type RevenueCatPackageLike, type RevenueCatProductLike, type RevenueCatSink, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, type UseLifecycleEventsOptions, type UseSessionStartOptions, type UseWireActivation, WIRE_ICON_GLYPHS, WIRE_ICON_NAMES, WIRE_PURCHASE_EVENTS, type WireActivation, type WireActivationConfig, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireIcon, type WireIconFamily, type WireIconGlyph, type WireIconName, type WireIconProps, type WireIconRegistry, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, type WirePurchaseEventName, WireUserContext, activeEntitlement, attributionMetadata, bumpActivationRevalidation, createRevenueCatBridge, createWireActivation, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, describeEntitlement, describeFailure, describePackage, detectAppVersion, detectNativeModel, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, getActivationRevalidationVersion, isFeaturesFresh, isOnboardingEnabled, isUserCancelled, lookupIconGlyph, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetActivationRevalidation, resetFirstOpenLatch, resetSessionStartGuard, resolvePlanTier, subscribeActivationRevalidation, themeFromBrand, useActivationRevalidation, useHostIcon, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireActivation, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };
+export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardGridSelectCard, CardHandoff, type CardHandoffProps, type CardHandoffVariant, type CardOption, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, IconRegistryProvider, 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, PLAN_TIER_CONTEXT_KEY, type PlanTier, type PurchaseProps, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, type RevenueCatBridge, type RevenueCatBridgeConfig, type RevenueCatCustomerInfoLike, type RevenueCatEntitlementLike, type RevenueCatErrorLike, type RevenueCatOfferingLike, type RevenueCatPackageLike, type RevenueCatProductLike, type RevenueCatSink, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, type UseLifecycleEventsOptions, type UseSessionStartOptions, type UseWireActivation, WIRE_ENV_VARS, WIRE_ICON_GLYPHS, WIRE_ICON_NAMES, WIRE_PURCHASE_EVENTS, type WireActivation, type WireActivationConfig, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireIcon, type WireIconFamily, type WireIconGlyph, type WireIconName, type WireIconProps, type WireIconRegistry, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, type WirePurchaseEventName, WireUserContext, activeEntitlement, attributionMetadata, bumpActivationRevalidation, createRevenueCatBridge, createWireActivation, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, describeEntitlement, describeFailure, describePackage, detectAppVersion, detectNativeModel, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, getActivationRevalidationVersion, isFeaturesFresh, isOnboardingEnabled, isUserCancelled, lookupIconGlyph, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetActivationRevalidation, resetFirstOpenLatch, resetSessionStartGuard, resolvePlanTier, subscribeActivationRevalidation, themeFromBrand, useActivationRevalidation, useHostIcon, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireActivation, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { H as WireOnboardingProps, I as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, J as OnboardingEvent, K as OnboardingCopy, c as ClientEventTarget, L as DeviceContext, W as WireUserContext, b as ClientEvent, g as EnvelopeSource } from './currentSession-D6RiVtc8.js';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, d as ClientEventType, M as DeviceFormFactor, D as DeviceKeyStorage, N as EXTRA_KEY_PREFIX, P as IdentifyOnboardingOptions, Q as OnboardingProgress, T as RESERVED_USER_CONTEXT_KEYS, R as ResolveAutoDeviceKeyOptions, U as ResolveUserContextOptions, V as ResolvedUserContext, X as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, Y as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, Z as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, _ as hashEmailFnv1a, $ as identifyOnboarding, a0 as isWireScalar, s as looksLikeEmail, t as makeSessionId, a1 as mintDeviceId, a2 as namespaceExtra, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, a3 as resolveUserContext, a4 as sanitizeUserId, F as setCurrentSessionId, G as toAnalyticsEvent } from './currentSession-D6RiVtc8.js';
+import { H as WireOnboardingProps, I as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, J as OnboardingEvent, K as OnboardingCopy, c as ClientEventTarget, L as DeviceContext, W as WireUserContext, b as ClientEvent, g as EnvelopeSource } from './currentSession-BxEB37xt.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, d as ClientEventType, M as DeviceFormFactor, D as DeviceKeyStorage, N as EXTRA_KEY_PREFIX, P as IdentifyOnboardingOptions, Q as OnboardingProgress, T as RESERVED_USER_CONTEXT_KEYS, R as ResolveAutoDeviceKeyOptions, U as ResolveUserContextOptions, V as ResolvedUserContext, X as USER_ID_MAX_LENGTH, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, Y as activationJoinContext, k as analyticsUserIdStorageKey, m as clearPiiFromContext, n as clearUserContext, Z as collectDeviceContext, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, _ as hashEmailFnv1a, $ as hydrateAutoDeviceKey, a0 as identifyOnboarding, a1 as isWireScalar, s as looksLikeEmail, t as makeSessionId, a2 as mintDeviceId, a3 as namespaceExtra, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, a4 as resolveUserContext, a5 as sanitizeUserId, F as setCurrentSessionId, G as toAnalyticsEvent } from './currentSession-BxEB37xt.js';
 import { O as OnboardingTheme } from './types-BKfpdZzX.js';
 export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.js';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-Cdgns6--.js';
@@ -1278,24 +1278,9 @@ declare const readCachedFeatures: (storage: WireOnboardingStorage, key: string)
 /** Persist `{ features, ts }` under `key` — fire-and-forget, all errors swallowed. */
 declare const writeCachedFeatures: (storage: WireOnboardingStorage, key: string, features: WireFeatures) => void;
 
-/**
- * wireConfigFromEnv — stop re-authoring env gating in every app. Reads the Wire AI
- * tenant key + server URL from the standard Expo public env vars and returns a
- * ready `WireOnboardingConfig`, or `null` when the key/URL are missing (so a host
- * can fall through to a static onboarding without writing the `if (!key)` itself).
- *
- *   EXPO_PUBLIC_WIREAI_API_KEY=...      (required)
- *   EXPO_PUBLIC_WIREAI_SERVER_URL=...   (required)
- *
- *   const config = wireConfigFromEnv({ appId: "morrow" });
- *   if (!config) return <StaticOnboarding />;
- *   return <WireOnboarding config={config} ... />;
- *
- * `appId` defaults to `EXPO_PUBLIC_WIREAI_APP_ID` (or "default"); pass overrides to
- * set `appId`/`metadata` or to substitute the key/URL programmatically.
- */
-
 type WireConfigOverrides = Partial<WireOnboardingConfig>;
+/** The env vars this helper reads. Exported so a host preflight can assert them itself. */
+declare const WIRE_ENV_VARS: readonly ["EXPO_PUBLIC_WIREAI_API_KEY", "EXPO_PUBLIC_WIREAI_SERVER_URL", "EXPO_PUBLIC_WIREAI_APP_ID"];
 declare const wireConfigFromEnv: (overrides?: WireConfigOverrides) => WireOnboardingConfig | null;
 
 type OnboardingFlagOptions = {
@@ -1840,6 +1825,11 @@ interface SessionStartConfig {
     apiKey?: string;
     /** Host app version (e.g. "1.4.2"), forwarded for release segmentation. Optional. */
     appVersion?: string;
+    /** Tenant/app id — namespaces the auto `device_key` fallback below. */
+    appId?: string;
+    /** Host storage (AsyncStorage subset). Present → `app.session_started` falls back to the kit's
+     *  persisted auto `device_key` when the host passes none. Absent → no fallback (see below). */
+    storage?: WireOnboardingStorage;
 }
 /** Per-open identity the host supplies. All optional: a pre-auth open is device-only. */
 interface UseSessionStartOptions {
@@ -2006,4 +1996,4 @@ interface UseLifecycleEventsOptions {
  */
 declare const useLifecycleEvents: (config: LifecycleConfig | undefined, options?: UseLifecycleEventsOptions) => void;
 
-export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardGridSelectCard, CardHandoff, type CardHandoffProps, type CardHandoffVariant, type CardOption, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, IconRegistryProvider, 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, PLAN_TIER_CONTEXT_KEY, type PlanTier, type PurchaseProps, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, type RevenueCatBridge, type RevenueCatBridgeConfig, type RevenueCatCustomerInfoLike, type RevenueCatEntitlementLike, type RevenueCatErrorLike, type RevenueCatOfferingLike, type RevenueCatPackageLike, type RevenueCatProductLike, type RevenueCatSink, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, type UseLifecycleEventsOptions, type UseSessionStartOptions, type UseWireActivation, WIRE_ICON_GLYPHS, WIRE_ICON_NAMES, WIRE_PURCHASE_EVENTS, type WireActivation, type WireActivationConfig, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireIcon, type WireIconFamily, type WireIconGlyph, type WireIconName, type WireIconProps, type WireIconRegistry, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, type WirePurchaseEventName, WireUserContext, activeEntitlement, attributionMetadata, bumpActivationRevalidation, createRevenueCatBridge, createWireActivation, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, describeEntitlement, describeFailure, describePackage, detectAppVersion, detectNativeModel, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, getActivationRevalidationVersion, isFeaturesFresh, isOnboardingEnabled, isUserCancelled, lookupIconGlyph, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetActivationRevalidation, resetFirstOpenLatch, resetSessionStartGuard, resolvePlanTier, subscribeActivationRevalidation, themeFromBrand, useActivationRevalidation, useHostIcon, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireActivation, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };
+export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardGridSelectCard, CardHandoff, type CardHandoffProps, type CardHandoffVariant, type CardOption, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, IconRegistryProvider, 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, PLAN_TIER_CONTEXT_KEY, type PlanTier, type PurchaseProps, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, type RevenueCatBridge, type RevenueCatBridgeConfig, type RevenueCatCustomerInfoLike, type RevenueCatEntitlementLike, type RevenueCatErrorLike, type RevenueCatOfferingLike, type RevenueCatPackageLike, type RevenueCatProductLike, type RevenueCatSink, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, type UseLifecycleEventsOptions, type UseSessionStartOptions, type UseWireActivation, WIRE_ENV_VARS, WIRE_ICON_GLYPHS, WIRE_ICON_NAMES, WIRE_PURCHASE_EVENTS, type WireActivation, type WireActivationConfig, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireIcon, type WireIconFamily, type WireIconGlyph, type WireIconName, type WireIconProps, type WireIconRegistry, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, type WirePurchaseEventName, WireUserContext, activeEntitlement, attributionMetadata, bumpActivationRevalidation, createRevenueCatBridge, createWireActivation, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, describeEntitlement, describeFailure, describePackage, detectAppVersion, detectNativeModel, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, getActivationRevalidationVersion, isFeaturesFresh, isOnboardingEnabled, isUserCancelled, lookupIconGlyph, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetActivationRevalidation, resetFirstOpenLatch, resetSessionStartGuard, resolvePlanTier, subscribeActivationRevalidation, themeFromBrand, useActivationRevalidation, useHostIcon, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireActivation, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };