@wireai/activation 0.9.1 → 0.10.0

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

@@ -175,6 +175,17 @@ declare const makeSessionId: () => string;
 declare const reportClientEvents: (target: ClientEventTarget | undefined, events: ClientEvent[]) => void;
 /** Convenience single-event wrapper around {@link reportClientEvents}. */
 declare const reportClientEvent: (target: ClientEventTarget | undefined, event: ClientEvent) => void;
+/**
+ * AWAITABLE sibling of {@link reportClientEvents}: POST one or more client events through the SAME
+ * `/v1/events` path, but resolve only once the server has RESPONDED — so a decision re-fetch fired
+ * immediately after is guaranteed to see the event in the session stream (this is the guarantee
+ * `wire.track` needs before it triggers decision revalidation). Never throws: a missing/invalid
+ * target, a missing `fetch`, a network error, or a non-2xx status all resolve to `false`. Resolves
+ * `true` only on a 2xx response.
+ */
+declare const reportClientEventsAwait: (target: ClientEventTarget | undefined, events: ClientEvent[]) => Promise<boolean>;
+/** Convenience single-event wrapper around {@link reportClientEventsAwait}. */
+declare const reportClientEventAwait: (target: ClientEventTarget | undefined, event: ClientEvent) => Promise<boolean>;
 
 /** Transport + tenant config for the managed Wire AI onboarding backend (A2A). */
 type WireOnboardingConfig = {
@@ -391,6 +402,22 @@ type WireOnboardingProps = {
      * accounts mid-flow. Only meaningful with `storage`.
      */
     persistKey?: string;
+    /**
+     * OPT-IN: keep the persisted session seed alive ACROSS completion, so a multi-stage or
+     * replay-after-complete re-entry WITHIN one signup (typically a `key=` remount) resumes the
+     * SAME session instead of minting a fresh `metadata.sessionId` — which the backend would adopt
+     * as a second `contextId`, double-counting a `session_started` on the funnel.
+     *
+     * Default (omitted / `false`): a completion CLEARS the seed, so the next onboarding on this
+     * device starts fresh — the legacy single-stage behavior. Leave it unset and NOTHING changes.
+     *
+     * When `true`: the seed survives completion, and freshness for a genuinely new run is governed
+     * by the TTL (past `sessionTtlMs` → a fresh seed is minted) and an explicit new-run signal
+     * (scope a new `persistKey`, e.g. a per-signup id, to force a fresh seed within the TTL).
+     *
+     * Only meaningful with `storage`. Dropped/degraded sessions are unaffected (they never clear).
+     */
+    retainSessionOnComplete?: boolean;
 };
 /** Backend-supplied progress, read off `response.props.progress` when present. */
 type OnboardingProgress = {
@@ -665,7 +692,7 @@ interface ResolveUserContextOptions {
 declare const resolveUserContext: (ctx?: WireUserContext, opts?: ResolveUserContextOptions) => ResolvedUserContext;
 
 /**
- * currentSession — a tiny module-level registry of the CURRENT per-open `session_id`.
+ * currentSession — a tiny registry of the CURRENT per-open `session_id`.
  *
  * WHY it exists (kills the phantom-session): the per-open emitters (`reportSessionStart` and the
  * `useSessionStart` / `useLifecycleEvents` hooks) mint a fresh `session_id` for each app-open and
@@ -678,8 +705,26 @@ declare const resolveUserContext: (ctx?: WireUserContext, opts?: ResolveUserCont
  * server already ingested. `reportSessionStart` writes the current id here on every open; the façade
  * reads it so `identify`/app-events correlate to the real session instead of minting a phantom.
  *
- * DEPENDENCY-FREE + PROCESS-LOCAL: a plain module variable. It is intentionally NOT persisted — it
- * tracks the CURRENT process's open, and a fresh open always overwrites it. No cross-launch state.
+ * ── 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.
+ *
+ * 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.
+ *
+ * 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.
  */
 /**
  * Record the current per-open `session_id`. Called by `reportSessionStart` when it emits an
@@ -691,4 +736,4 @@ declare const getCurrentSessionId: () => string | undefined;
 /** Test-only: forget the current session id so a unit test starts from a clean registry. */
 declare const resetCurrentSessionId: () => void;
 
-export { type AnalyticsEvent as A, collectDeviceContext as B, type ClientEvent as C, type DeviceContext as D, type EventQueueOptions as E, hashEmailFnv1a as F, isWireScalar as G, namespaceExtra as H, resolveUserContext as I, type OnboardingResult as O, RESERVED_USER_CONTEXT_KEYS as R, type StepValidator as S, type WireUserContext as W, type ClientEventTarget as a, type ClientEventType as b, type ContextEnvelope as c, type ContextEnvelopeInput as d, type EnvelopeSource as e, type EventQueue as f, WIRE_ONBOARDING_EVENTS as g, type WireOnboardingEventName as h, buildContextEnvelope as i, createEventQueue as j, getCurrentSessionId as k, reportClientEvents as l, makeSessionId as m, resetCurrentSessionId as n, type WireOnboardingProps as o, type WireOnboardingConfig as p, type OnboardingEvent as q, reportClientEvent as r, setCurrentSessionId as s, toAnalyticsEvent as t, type OnboardingCopy as u, type DeviceFormFactor as v, EXTRA_KEY_PREFIX as w, type OnboardingProgress as x, type ResolveUserContextOptions as y, type ResolvedUserContext as z };
+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 };

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

@@ -175,6 +175,17 @@ declare const makeSessionId: () => string;
 declare const reportClientEvents: (target: ClientEventTarget | undefined, events: ClientEvent[]) => void;
 /** Convenience single-event wrapper around {@link reportClientEvents}. */
 declare const reportClientEvent: (target: ClientEventTarget | undefined, event: ClientEvent) => void;
+/**
+ * AWAITABLE sibling of {@link reportClientEvents}: POST one or more client events through the SAME
+ * `/v1/events` path, but resolve only once the server has RESPONDED — so a decision re-fetch fired
+ * immediately after is guaranteed to see the event in the session stream (this is the guarantee
+ * `wire.track` needs before it triggers decision revalidation). Never throws: a missing/invalid
+ * target, a missing `fetch`, a network error, or a non-2xx status all resolve to `false`. Resolves
+ * `true` only on a 2xx response.
+ */
+declare const reportClientEventsAwait: (target: ClientEventTarget | undefined, events: ClientEvent[]) => Promise<boolean>;
+/** Convenience single-event wrapper around {@link reportClientEventsAwait}. */
+declare const reportClientEventAwait: (target: ClientEventTarget | undefined, event: ClientEvent) => Promise<boolean>;
 
 /** Transport + tenant config for the managed Wire AI onboarding backend (A2A). */
 type WireOnboardingConfig = {
@@ -391,6 +402,22 @@ type WireOnboardingProps = {
      * accounts mid-flow. Only meaningful with `storage`.
      */
     persistKey?: string;
+    /**
+     * OPT-IN: keep the persisted session seed alive ACROSS completion, so a multi-stage or
+     * replay-after-complete re-entry WITHIN one signup (typically a `key=` remount) resumes the
+     * SAME session instead of minting a fresh `metadata.sessionId` — which the backend would adopt
+     * as a second `contextId`, double-counting a `session_started` on the funnel.
+     *
+     * Default (omitted / `false`): a completion CLEARS the seed, so the next onboarding on this
+     * device starts fresh — the legacy single-stage behavior. Leave it unset and NOTHING changes.
+     *
+     * When `true`: the seed survives completion, and freshness for a genuinely new run is governed
+     * by the TTL (past `sessionTtlMs` → a fresh seed is minted) and an explicit new-run signal
+     * (scope a new `persistKey`, e.g. a per-signup id, to force a fresh seed within the TTL).
+     *
+     * Only meaningful with `storage`. Dropped/degraded sessions are unaffected (they never clear).
+     */
+    retainSessionOnComplete?: boolean;
 };
 /** Backend-supplied progress, read off `response.props.progress` when present. */
 type OnboardingProgress = {
@@ -665,7 +692,7 @@ interface ResolveUserContextOptions {
 declare const resolveUserContext: (ctx?: WireUserContext, opts?: ResolveUserContextOptions) => ResolvedUserContext;
 
 /**
- * currentSession — a tiny module-level registry of the CURRENT per-open `session_id`.
+ * currentSession — a tiny registry of the CURRENT per-open `session_id`.
  *
  * WHY it exists (kills the phantom-session): the per-open emitters (`reportSessionStart` and the
  * `useSessionStart` / `useLifecycleEvents` hooks) mint a fresh `session_id` for each app-open and
@@ -678,8 +705,26 @@ declare const resolveUserContext: (ctx?: WireUserContext, opts?: ResolveUserCont
  * server already ingested. `reportSessionStart` writes the current id here on every open; the façade
  * reads it so `identify`/app-events correlate to the real session instead of minting a phantom.
  *
- * DEPENDENCY-FREE + PROCESS-LOCAL: a plain module variable. It is intentionally NOT persisted — it
- * tracks the CURRENT process's open, and a fresh open always overwrites it. No cross-launch state.
+ * ── 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.
+ *
+ * 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.
+ *
+ * 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.
  */
 /**
  * Record the current per-open `session_id`. Called by `reportSessionStart` when it emits an
@@ -691,4 +736,4 @@ declare const getCurrentSessionId: () => string | undefined;
 /** Test-only: forget the current session id so a unit test starts from a clean registry. */
 declare const resetCurrentSessionId: () => void;
 
-export { type AnalyticsEvent as A, collectDeviceContext as B, type ClientEvent as C, type DeviceContext as D, type EventQueueOptions as E, hashEmailFnv1a as F, isWireScalar as G, namespaceExtra as H, resolveUserContext as I, type OnboardingResult as O, RESERVED_USER_CONTEXT_KEYS as R, type StepValidator as S, type WireUserContext as W, type ClientEventTarget as a, type ClientEventType as b, type ContextEnvelope as c, type ContextEnvelopeInput as d, type EnvelopeSource as e, type EventQueue as f, WIRE_ONBOARDING_EVENTS as g, type WireOnboardingEventName as h, buildContextEnvelope as i, createEventQueue as j, getCurrentSessionId as k, reportClientEvents as l, makeSessionId as m, resetCurrentSessionId as n, type WireOnboardingProps as o, type WireOnboardingConfig as p, type OnboardingEvent as q, reportClientEvent as r, setCurrentSessionId as s, toAnalyticsEvent as t, type OnboardingCopy as u, type DeviceFormFactor as v, EXTRA_KEY_PREFIX as w, type OnboardingProgress as x, type ResolveUserContextOptions as y, type ResolvedUserContext as z };
+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 };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { o as WireOnboardingProps, p as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, q as OnboardingEvent, u as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, C as ClientEvent, e as EnvelopeSource } from './currentSession-Bs2JfTJ8.mjs';
-export { A as AnalyticsEvent, b as ClientEventType, v as DeviceFormFactor, w as EXTRA_KEY_PREFIX, x as OnboardingProgress, R as RESERVED_USER_CONTEXT_KEYS, y as ResolveUserContextOptions, z as ResolvedUserContext, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, W as WireUserContext, B as collectDeviceContext, k as getCurrentSessionId, F as hashEmailFnv1a, G as isWireScalar, m as makeSessionId, H as namespaceExtra, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, I as resolveUserContext, s as setCurrentSessionId, t as toAnalyticsEvent } from './currentSession-Bs2JfTJ8.mjs';
+import { q as WireOnboardingProps, u as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, v as OnboardingEvent, w as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, W as WireUserContext, C as ClientEvent, e as EnvelopeSource } from './currentSession-DdDkprpM.mjs';
+export { A as AnalyticsEvent, b as ClientEventType, x as DeviceFormFactor, y as EXTRA_KEY_PREFIX, z as OnboardingProgress, R as RESERVED_USER_CONTEXT_KEYS, B as ResolveUserContextOptions, F as ResolvedUserContext, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, G as collectDeviceContext, k as getCurrentSessionId, H as hashEmailFnv1a, I as isWireScalar, m as makeSessionId, J as namespaceExtra, r as reportClientEvent, l as reportClientEventAwait, n as reportClientEvents, o as reportClientEventsAwait, p as resetCurrentSessionId, K as resolveUserContext, s as setCurrentSessionId, t as toAnalyticsEvent } from './currentSession-DdDkprpM.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';
@@ -1513,6 +1513,119 @@ declare const deviceIdStorageKey: (appId?: string) => string;
  */
 declare const mintDeviceId: () => string;
 
+/**
+ * Tenant transport + context inputs for {@link createWireActivation}. `serverUrl`/`apiKey` are the
+ * SAME creds as onboarding (never a second key); everything else is optional.
+ */
+type WireActivationConfig = {
+    /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
+    serverUrl: string;
+    /** Tenant API key; sent as `Authorization: Bearer`. */
+    apiKey: string;
+    /**
+     * A stable, non-PII device id → `user_context.device_key` (the server's review/questionnaire
+     * gating + A/B stickiness key on it). When omitted, the kit auto-mints ONE per-install id, persists
+     * it via `storage` when given, and reuses it — so `device_key` is ALWAYS present. Host-supplied wins.
+     */
+    deviceKey?: string;
+    /**
+     * Optional rich context stamped onto every tracked event's `user_context` (opaque `userId` →
+     * top-level `user_id`, opt-in `userEmail`, namespaced `extra`). `deviceKey` here is equivalent to
+     * the top-level one (top-level wins). Same shape the analytics façade accepts.
+     */
+    userContext?: WireUserContext;
+    /** Tenant/app id — namespaces the auto-minted device-key storage slot. */
+    appId?: string;
+    /** Host app version → `user_context.app_version` when no explicit `userContext.appVersion` is set. */
+    appVersion?: string;
+    /** Host persistence (AsyncStorage-compatible subset) so the auto-minted device key survives launches. */
+    storage?: WireOnboardingStorage;
+};
+/** The kit-owned activation surface. `sessionId` is a live getter (reads `getCurrentSessionId()`). */
+type WireActivation = {
+    /**
+     * Awaitable action report: POST `event_type='app_event'`, `question_key=<name>`, optional `meta`,
+     * under the CURRENT session id + `user_context.device_key`. Resolves `true` once the server has
+     * stored it (2xx) and THEN bumps decision revalidation; resolves `false` (no bump) when there is no
+     * current session, a blank name, or the POST fails. Never throws.
+     */
+    track(name: string, meta?: Record<string, unknown>): Promise<boolean>;
+    /** The CURRENT per-open session id (the kit's canonical `getCurrentSessionId()`), or `undefined`. */
+    readonly sessionId: string | undefined;
+    /** Subscribe to decision revalidation (bumped by a successful `track`). Returns an unsubscribe fn. */
+    subscribeRevalidation(listener: () => void): () => void;
+    /** The current revalidation version — include in a decision-fetch effect's deps to re-fetch on bump. */
+    getRevalidationVersion(): number;
+};
+/**
+ * Create a bound activation instance for a tenant transport. Resolves the device key once (explicit >
+ * `userContext.deviceKey` > auto-minted + persisted). Pure + React-free.
+ */
+declare const createWireActivation: (config: WireActivationConfig) => WireActivation;
+
+/**
+ * Subscribe a component to decision revalidation. Returns the current version; list it in a
+ * decision-fetch effect's deps so a `bumpActivationRevalidation()` (which a successful `track` does)
+ * re-runs the fetch. The kit-owned replacement for a host's hand-rolled `useActivationRevalidation`.
+ */
+declare const useActivationRevalidation: () => number;
+/** What {@link useWireActivation} returns: the awaitable `track`, the live `sessionId`, and the tick. */
+type UseWireActivation = {
+    /** Awaitable action report that auto-revalidates on success (see {@link WireActivation.track}). */
+    track: WireActivation["track"];
+    /** The CURRENT per-open session id (read fresh each render), or `undefined`. */
+    sessionId: string | undefined;
+    /** Monotonic counter that increments on every successful `track()` — a re-fetch trigger. */
+    revalidation: number;
+};
+/**
+ * Build a per-mount activation instance. `config` is read once at first render (the instance is
+ * stable for the component's lifetime, keyed on the transport creds + device key); the returned
+ * `revalidation` re-renders the component whenever any `track()` succeeds.
+ */
+declare const useWireActivation: (config: WireActivationConfig) => UseWireActivation;
+
+/**
+ * activation revalidation — a tiny kit-owned pub/sub the review / questionnaire decision fetches
+ * subscribe to, so they RE-FETCH their server decision AFTER a trigger action, not only on mount.
+ *
+ * WHY THIS EXISTS (subsumes Morrow's hand-rolled `activation-revalidation.ts`): a host mounts the
+ * review / questionnaire gate on the home screen and fetches its `/decision` verdict once, in a
+ * mount-scoped effect. But the screen stays mounted while the user goes elsewhere to perform the
+ * triggering action (journal a win, complete a task); the server's firing rule is trigger-based AND
+ * session-scoped, so the mount fetch ran BEFORE the trigger event existed and never re-runs. Bumping
+ * this store after the action POSTs re-runs the gate's decision fetch (it lists the version in its
+ * deps) → the server now sees the trigger → `{fire:true}`.
+ *
+ * `wire.track()` bumps this automatically on a successful POST, so a consumer no longer hand-rolls
+ * an await-then-bump: it subscribes (via {@link useActivationRevalidation} in `useWireActivation`)
+ * and re-fetches when the version changes.
+ *
+ * ── WHY A globalThis SLOT, NOT MODULE-LOCAL STATE (same reasoning as currentSession) ─────────────
+ * This module can be reached from more than one package entry (the main `.` barrel exposes the
+ * revalidation surface; the gates live under the `./reviews` / `./questionnaire` subpaths). Under
+ * `dist` resolution tsup inlines a SEPARATE copy of a module into each bundle, so plain module-local
+ * `version` + `listeners` would give the BUMPER (main entry, via `wire.track`) and a SUBSCRIBER a
+ * different store — the bump would never reach the listener, exactly the defect-B failure mode. So
+ * the ONE store lives in a `globalThis` slot keyed by `Symbol.for(...)`: every inlined copy resolves
+ * the same symbol and shares one store, on Hermes/RN, Node and SSR alike.
+ */
+/**
+ * Signal every activation subscriber to re-fetch its server decision. `wire.track()` calls this on a
+ * successful POST (await the post first so the re-fetch sees the event). A throwing subscriber never
+ * breaks the notify loop — each listener is isolated.
+ */
+declare const bumpActivationRevalidation: () => void;
+/**
+ * Subscribe to revalidation. Returns an unsubscribe fn. Shaped for `useSyncExternalStore`
+ * (see {@link useActivationRevalidation} in `useWireActivation`).
+ */
+declare const subscribeActivationRevalidation: (listener: () => void) => (() => void);
+/** The current revalidation version — include it in a decision-fetch effect's deps to re-fetch on bump. */
+declare const getActivationRevalidationVersion: () => number;
+/** Test-only: reset the shared store between cases (clears version + listeners). */
+declare const resetActivationRevalidation: () => void;
+
 /** The canonical event name for an app-open. A trigger keys off this exact string. */
 declare const SESSION_STARTED_EVENT: "app.session_started";
 /** Options for {@link reportSessionStart}. Everything except `target` is optional so a pre-auth
@@ -1739,4 +1852,4 @@ interface UseLifecycleEventsOptions {
  */
 declare const useLifecycleEvents: (config: LifecycleConfig | undefined, options?: UseLifecycleEventsOptions) => void;
 
-export { AUTO_DEVICE_ID_PREFIX, 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, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, WIRE_ICON_GLYPHS, WIRE_ICON_NAMES, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireIcon, type WireIconFamily, type WireIconGlyph, type WireIconName, type WireIconProps, type WireIconRegistry, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, detectAppVersion, detectNativeModel, deviceIdStorageKey, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, lookupIconGlyph, mergeTheme, mintDeviceId, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useHostIcon, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };
+export { AUTO_DEVICE_ID_PREFIX, 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, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, type UseWireActivation, WIRE_ICON_GLYPHS, WIRE_ICON_NAMES, 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, WireUserContext, attributionMetadata, bumpActivationRevalidation, createWireActivation, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, detectAppVersion, detectNativeModel, deviceIdStorageKey, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, getActivationRevalidationVersion, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, lookupIconGlyph, mergeTheme, mintDeviceId, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetActivationRevalidation, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, 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 { o as WireOnboardingProps, p as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, q as OnboardingEvent, u as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, C as ClientEvent, e as EnvelopeSource } from './currentSession-61dcm3V-.js';
-export { A as AnalyticsEvent, b as ClientEventType, v as DeviceFormFactor, w as EXTRA_KEY_PREFIX, x as OnboardingProgress, R as RESERVED_USER_CONTEXT_KEYS, y as ResolveUserContextOptions, z as ResolvedUserContext, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, W as WireUserContext, B as collectDeviceContext, k as getCurrentSessionId, F as hashEmailFnv1a, G as isWireScalar, m as makeSessionId, H as namespaceExtra, r as reportClientEvent, l as reportClientEvents, n as resetCurrentSessionId, I as resolveUserContext, s as setCurrentSessionId, t as toAnalyticsEvent } from './currentSession-61dcm3V-.js';
+import { q as WireOnboardingProps, u as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, v as OnboardingEvent, w as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, W as WireUserContext, C as ClientEvent, e as EnvelopeSource } from './currentSession-D0Vq7_VE.js';
+export { A as AnalyticsEvent, b as ClientEventType, x as DeviceFormFactor, y as EXTRA_KEY_PREFIX, z as OnboardingProgress, R as RESERVED_USER_CONTEXT_KEYS, B as ResolveUserContextOptions, F as ResolvedUserContext, g as WIRE_ONBOARDING_EVENTS, h as WireOnboardingEventName, G as collectDeviceContext, k as getCurrentSessionId, H as hashEmailFnv1a, I as isWireScalar, m as makeSessionId, J as namespaceExtra, r as reportClientEvent, l as reportClientEventAwait, n as reportClientEvents, o as reportClientEventsAwait, p as resetCurrentSessionId, K as resolveUserContext, s as setCurrentSessionId, t as toAnalyticsEvent } from './currentSession-D0Vq7_VE.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';
@@ -1513,6 +1513,119 @@ declare const deviceIdStorageKey: (appId?: string) => string;
  */
 declare const mintDeviceId: () => string;
 
+/**
+ * Tenant transport + context inputs for {@link createWireActivation}. `serverUrl`/`apiKey` are the
+ * SAME creds as onboarding (never a second key); everything else is optional.
+ */
+type WireActivationConfig = {
+    /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
+    serverUrl: string;
+    /** Tenant API key; sent as `Authorization: Bearer`. */
+    apiKey: string;
+    /**
+     * A stable, non-PII device id → `user_context.device_key` (the server's review/questionnaire
+     * gating + A/B stickiness key on it). When omitted, the kit auto-mints ONE per-install id, persists
+     * it via `storage` when given, and reuses it — so `device_key` is ALWAYS present. Host-supplied wins.
+     */
+    deviceKey?: string;
+    /**
+     * Optional rich context stamped onto every tracked event's `user_context` (opaque `userId` →
+     * top-level `user_id`, opt-in `userEmail`, namespaced `extra`). `deviceKey` here is equivalent to
+     * the top-level one (top-level wins). Same shape the analytics façade accepts.
+     */
+    userContext?: WireUserContext;
+    /** Tenant/app id — namespaces the auto-minted device-key storage slot. */
+    appId?: string;
+    /** Host app version → `user_context.app_version` when no explicit `userContext.appVersion` is set. */
+    appVersion?: string;
+    /** Host persistence (AsyncStorage-compatible subset) so the auto-minted device key survives launches. */
+    storage?: WireOnboardingStorage;
+};
+/** The kit-owned activation surface. `sessionId` is a live getter (reads `getCurrentSessionId()`). */
+type WireActivation = {
+    /**
+     * Awaitable action report: POST `event_type='app_event'`, `question_key=<name>`, optional `meta`,
+     * under the CURRENT session id + `user_context.device_key`. Resolves `true` once the server has
+     * stored it (2xx) and THEN bumps decision revalidation; resolves `false` (no bump) when there is no
+     * current session, a blank name, or the POST fails. Never throws.
+     */
+    track(name: string, meta?: Record<string, unknown>): Promise<boolean>;
+    /** The CURRENT per-open session id (the kit's canonical `getCurrentSessionId()`), or `undefined`. */
+    readonly sessionId: string | undefined;
+    /** Subscribe to decision revalidation (bumped by a successful `track`). Returns an unsubscribe fn. */
+    subscribeRevalidation(listener: () => void): () => void;
+    /** The current revalidation version — include in a decision-fetch effect's deps to re-fetch on bump. */
+    getRevalidationVersion(): number;
+};
+/**
+ * Create a bound activation instance for a tenant transport. Resolves the device key once (explicit >
+ * `userContext.deviceKey` > auto-minted + persisted). Pure + React-free.
+ */
+declare const createWireActivation: (config: WireActivationConfig) => WireActivation;
+
+/**
+ * Subscribe a component to decision revalidation. Returns the current version; list it in a
+ * decision-fetch effect's deps so a `bumpActivationRevalidation()` (which a successful `track` does)
+ * re-runs the fetch. The kit-owned replacement for a host's hand-rolled `useActivationRevalidation`.
+ */
+declare const useActivationRevalidation: () => number;
+/** What {@link useWireActivation} returns: the awaitable `track`, the live `sessionId`, and the tick. */
+type UseWireActivation = {
+    /** Awaitable action report that auto-revalidates on success (see {@link WireActivation.track}). */
+    track: WireActivation["track"];
+    /** The CURRENT per-open session id (read fresh each render), or `undefined`. */
+    sessionId: string | undefined;
+    /** Monotonic counter that increments on every successful `track()` — a re-fetch trigger. */
+    revalidation: number;
+};
+/**
+ * Build a per-mount activation instance. `config` is read once at first render (the instance is
+ * stable for the component's lifetime, keyed on the transport creds + device key); the returned
+ * `revalidation` re-renders the component whenever any `track()` succeeds.
+ */
+declare const useWireActivation: (config: WireActivationConfig) => UseWireActivation;
+
+/**
+ * activation revalidation — a tiny kit-owned pub/sub the review / questionnaire decision fetches
+ * subscribe to, so they RE-FETCH their server decision AFTER a trigger action, not only on mount.
+ *
+ * WHY THIS EXISTS (subsumes Morrow's hand-rolled `activation-revalidation.ts`): a host mounts the
+ * review / questionnaire gate on the home screen and fetches its `/decision` verdict once, in a
+ * mount-scoped effect. But the screen stays mounted while the user goes elsewhere to perform the
+ * triggering action (journal a win, complete a task); the server's firing rule is trigger-based AND
+ * session-scoped, so the mount fetch ran BEFORE the trigger event existed and never re-runs. Bumping
+ * this store after the action POSTs re-runs the gate's decision fetch (it lists the version in its
+ * deps) → the server now sees the trigger → `{fire:true}`.
+ *
+ * `wire.track()` bumps this automatically on a successful POST, so a consumer no longer hand-rolls
+ * an await-then-bump: it subscribes (via {@link useActivationRevalidation} in `useWireActivation`)
+ * and re-fetches when the version changes.
+ *
+ * ── WHY A globalThis SLOT, NOT MODULE-LOCAL STATE (same reasoning as currentSession) ─────────────
+ * This module can be reached from more than one package entry (the main `.` barrel exposes the
+ * revalidation surface; the gates live under the `./reviews` / `./questionnaire` subpaths). Under
+ * `dist` resolution tsup inlines a SEPARATE copy of a module into each bundle, so plain module-local
+ * `version` + `listeners` would give the BUMPER (main entry, via `wire.track`) and a SUBSCRIBER a
+ * different store — the bump would never reach the listener, exactly the defect-B failure mode. So
+ * the ONE store lives in a `globalThis` slot keyed by `Symbol.for(...)`: every inlined copy resolves
+ * the same symbol and shares one store, on Hermes/RN, Node and SSR alike.
+ */
+/**
+ * Signal every activation subscriber to re-fetch its server decision. `wire.track()` calls this on a
+ * successful POST (await the post first so the re-fetch sees the event). A throwing subscriber never
+ * breaks the notify loop — each listener is isolated.
+ */
+declare const bumpActivationRevalidation: () => void;
+/**
+ * Subscribe to revalidation. Returns an unsubscribe fn. Shaped for `useSyncExternalStore`
+ * (see {@link useActivationRevalidation} in `useWireActivation`).
+ */
+declare const subscribeActivationRevalidation: (listener: () => void) => (() => void);
+/** The current revalidation version — include it in a decision-fetch effect's deps to re-fetch on bump. */
+declare const getActivationRevalidationVersion: () => number;
+/** Test-only: reset the shared store between cases (clears version + listeners). */
+declare const resetActivationRevalidation: () => void;
+
 /** The canonical event name for an app-open. A trigger keys off this exact string. */
 declare const SESSION_STARTED_EVENT: "app.session_started";
 /** Options for {@link reportSessionStart}. Everything except `target` is optional so a pre-auth
@@ -1739,4 +1852,4 @@ interface UseLifecycleEventsOptions {
  */
 declare const useLifecycleEvents: (config: LifecycleConfig | undefined, options?: UseLifecycleEventsOptions) => void;
 
-export { AUTO_DEVICE_ID_PREFIX, 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, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, WIRE_ICON_GLYPHS, WIRE_ICON_NAMES, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireIcon, type WireIconFamily, type WireIconGlyph, type WireIconName, type WireIconProps, type WireIconRegistry, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, detectAppVersion, detectNativeModel, deviceIdStorageKey, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, lookupIconGlyph, mergeTheme, mintDeviceId, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useHostIcon, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };
+export { AUTO_DEVICE_ID_PREFIX, 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, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, type UseWireActivation, WIRE_ICON_GLYPHS, WIRE_ICON_NAMES, 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, WireUserContext, attributionMetadata, bumpActivationRevalidation, createWireActivation, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, detectAppVersion, detectNativeModel, deviceIdStorageKey, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, getActivationRevalidationVersion, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, lookupIconGlyph, mergeTheme, mintDeviceId, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetActivationRevalidation, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, subscribeActivationRevalidation, themeFromBrand, useActivationRevalidation, useHostIcon, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireActivation, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };