@wireai/activation 0.1.1 → 0.3.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { e as WireOnboardingProps, f as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, g as OnboardingEvent, h as OnboardingCopy, a as ClientEventTarget, D as DeviceContext } from './analyticsEvent-B8v3BZjM.mjs';
-export { A as AnalyticsEvent, C as ClientEvent, b as ClientEventType, i as DeviceFormFactor, j as OnboardingProgress, W as WIRE_ONBOARDING_EVENTS, c as WireOnboardingEventName, k as collectDeviceContext, m as makeSessionId, r as reportClientEvent, d as reportClientEvents, t as toAnalyticsEvent } from './analyticsEvent-B8v3BZjM.mjs';
+import { k as WireOnboardingProps, l as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, n as OnboardingEvent, o as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, C as ClientEvent, e as EnvelopeSource } from './eventQueue-CA1d8Fmn.mjs';
+export { A as AnalyticsEvent, b as ClientEventType, p as DeviceFormFactor, q as OnboardingProgress, W as WIRE_ONBOARDING_EVENTS, g as WireOnboardingEventName, s as collectDeviceContext, m as makeSessionId, r as reportClientEvent, j as reportClientEvents, t as toAnalyticsEvent } from './eventQueue-CA1d8Fmn.mjs';
 import { O as 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';
@@ -937,6 +937,15 @@ interface ReportSessionStartOptions {
     meta?: Record<string, unknown>;
     /** Set `false` to bypass the once-per-open guard (default on). See {@link resetSessionStartGuard}. */
     once?: boolean;
+    /**
+     * OPTIONAL transport sink. When provided, the built `app.session_started` event is routed HERE
+     * (e.g. the offline-first event queue's `enqueue`) INSTEAD of this emitter's own direct `fetch`,
+     * while KEEPING the once-per-open guard above. This is how the lifecycle wiring
+     * (`useLifecycleEvents` / `wireLifecycleEvents`) offline-buffers session-start WITHOUT adding a
+     * second session emitter: one emitter, one guard, now durable. Omit it for the direct-POST path.
+     * A throwing sink is swallowed — analytics must never surface into the UI.
+     */
+    sink?: (event: ClientEvent) => void;
 }
 /** Test-only: forget every emitted session id so a unit test starts from a clean guard. */
 declare const resetSessionStartGuard: () => void;
@@ -977,4 +986,149 @@ interface UseSessionStartOptions {
  */
 declare const useSessionStart: (config: SessionStartConfig | undefined, options?: UseSessionStartOptions) => void;
 
-export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardHandoff, type CardHandoffProps, type CardHandoffVariant, ChipSelectCard, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseSessionStartOptions, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, featuresCacheKey, featuresEqual, fetchWireFeatures, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportSessionStart, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useIllustration, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, writeCachedFeatures };
+/**
+ * lifecycle — the TOP-OF-FUNNEL app lifecycle events that sit ABOVE onboarding: `app.first_open`
+ * (once ever per install) and `app.session_started` (per app-open). They compose with, and never
+ * duplicate, the events the funnel already records.
+ *
+ * WHERE THIS FITS (one funnel, no double counting):
+ *   • `app.first_open`      → THIS module, once ever (persisted flag). The in-app "install" proxy.
+ *   • `app.session_started` → the EXISTING {@link reportSessionStart} emitter (per app-open). This
+ *                             module REUSES it (routed through the offline queue), never re-emits.
+ *   • onboarding started / completed / activated → ALREADY recorded: the server writes
+ *     `session_started` + `completed` during the A2A flow, and the client reports `dropped` /
+ *     `client_fallback` / `identify` via `reportClientEvent`. This module does NOT touch them —
+ *     emitting them here would double-count. It only ADDS the two lifecycle events above them.
+ *
+ * WIRE CONTRACT (identical to `app.session_started`): both lifecycle events are stored as
+ * `event_type='app_event'` with the name in `question_key` (the server's `_event_name` returns
+ * `question_key` for an `app_event`, which a trigger matches). `app.first_open` uses the SAME
+ * `app.*` namespace + the SAME event shape as `app.session_started` — no bespoke `event_type`,
+ * no invented contract. `device_key` rides in the non-PII `user_context` bucket; `app_id` +
+ * `environment` are filled server-side.
+ *
+ * TWO FIRST-CLASS ENTRY POINTS (mirrors reportSessionStart vs useSessionStart):
+ *   • `reportFirstOpen(...)` / `wireLifecycleEvents(...)` — pure, React-free, for a host that owns
+ *     its own app-open path.
+ *   • `useLifecycleEvents(...)` — the batteries-included React hook (in `useLifecycleEvents.ts`).
+ *
+ * OFFLINE-FIRST: pass the Brief-01 event queue's `enqueue` as the `sink` and every lifecycle event
+ * is buffered + persisted + retried instead of a blind fetch. Without a sink they degrade to a
+ * direct fire-and-forget POST.
+ *
+ * PRIVACY (hard rule, same as the rest of the kit): NO GPS/location, NO advertising id. Nothing
+ * here carries a coordinate or an ad id — a host adopting it changes no store privacy declaration.
+ *
+ * FIRE-AND-FORGET: like every analytics path in the kit, nothing here throws into the UI, awaits
+ * in the caller, or hangs the app — storage reads race a short timeout, writes swallow errors.
+ */
+
+/** The canonical event name for the first-ever app open. Same `app.*` namespace as
+ *  {@link SESSION_STARTED_EVENT}; a trigger keys off this exact string. */
+declare const FIRST_OPEN_EVENT: "app.first_open";
+/** Storage key for the once-ever first-open flag, e.g. `wireai:first_open:myelino`. Mirrors the
+ *  `wireai:<concern>:<appId>` namespacing of {@link sessionStorageKey}. */
+declare const firstOpenStorageKey: (appId: string) => string;
+/** Test-only: forget the first-open latch so a unit test starts from a clean process state. */
+declare const resetFirstOpenLatch: () => void;
+/** Shared inputs for a lifecycle event. Everything is optional except a transport (`target` for the
+ *  direct-POST fallback, or a `sink`). A pre-auth open (no user yet) is a valid device-only event. */
+interface LifecycleEventInput {
+    /** Where to POST if no `sink` is wired (the tenant transport, same as `WireOnboardingConfig`). */
+    target?: ClientEventTarget;
+    /** Preferred transport: route the built event HERE (the offline queue's `enqueue`). */
+    sink?: (event: ClientEvent) => void;
+    /** The per-open session id. Defaults to a fresh `makeSessionId()`. */
+    sessionId?: string;
+    /** The host's OPAQUE pseudonymous user id (NOT PII). Sanitized + capped; omitted pre-auth. */
+    userId?: string;
+    /** A stable, non-PII device id the host owns. Rides in `user_context.device_key`. */
+    deviceKey?: string;
+    /** The host's local open-counter value. Drives `returning` + "Nth session". */
+    sessionCount?: number;
+    /** Host app version (e.g. "1.4.2"), if cheaply available. */
+    appVersion?: string;
+    /** Platform string (e.g. "ios"), if cheaply available. */
+    platform?: string;
+    /** An optional richer device snapshot (from `collectDeviceContext()`); the hook fills this. */
+    device?: DeviceContext;
+    /** Small non-PII extras, stored as a JSON string in the event `meta`. */
+    meta?: Record<string, unknown>;
+}
+/** Options for {@link reportFirstOpen}. Adds the once-ever persistence inputs on top of the shared
+ *  lifecycle inputs. Without `storage` it degrades to the in-memory latch (once per process). */
+interface ReportFirstOpenOptions extends LifecycleEventInput {
+    /** Host persistence (AsyncStorage subset). The once-ever flag lives here — it is what survives an
+     *  app kill. Omit it for the documented degraded (in-memory, once-per-process) mode. */
+    storage?: WireOnboardingStorage;
+    /** Tenant/app id — namespaces the persisted flag (`wireai:first_open:<appId>`). */
+    appId?: string;
+}
+/**
+ * Emit `app.first_open` EXACTLY ONCE EVER per install. Fire-and-forget; returns immediately.
+ *
+ *   • With `storage`: reads the persisted flag (`wireai:first_open:<appId>`). Absent → emit, then
+ *     write the flag (survives app kills, so a second launch is a no-op). Present → no-op.
+ *   • Race guard: an in-memory latch is set SYNCHRONOUSLY before the async read, so two
+ *     near-simultaneous calls fire at most once.
+ *   • Without `storage`: degraded mode — fires once per PROCESS via the latch only (documented).
+ */
+declare const reportFirstOpen: (opts: ReportFirstOpenOptions) => void;
+/** Options for {@link wireLifecycleEvents}: the shared lifecycle inputs + first-open persistence. */
+interface WireLifecycleOptions extends ReportFirstOpenOptions {
+}
+/**
+ * Wire BOTH lifecycle events in one call for a host that owns its own app-open path (the non-hook
+ * counterpart to {@link useLifecycleEvents}). Fires `app.first_open` (once ever) and one
+ * `app.session_started` for THIS open through the EXISTING {@link reportSessionStart} emitter (so
+ * the once-per-open guard still applies — pass the same `sessionId` and it never double-fires).
+ * Route both through the same `sink` (the offline queue) to buffer them. Fire-and-forget.
+ */
+declare const wireLifecycleEvents: (opts: WireLifecycleOptions) => void;
+
+/** Tenant transport + host persistence for the lifecycle wiring. Same creds as `WireOnboardingConfig`. */
+interface LifecycleConfig {
+    /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
+    serverUrl?: string;
+    /** Tenant API key; sent as `Authorization: Bearer`. */
+    apiKey?: string;
+    /** Host app version (e.g. "1.4.2"), forwarded for release segmentation. Optional. */
+    appVersion?: string;
+    /** Tenant/app id — namespaces the first-open flag AND the hook's internal queue storage key. */
+    appId?: string;
+    /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag AND the
+     *  offline durability of the hook's internal queue. Omit it and both degrade to in-memory. */
+    storage?: WireOnboardingStorage;
+}
+/** Per-open identity + wiring the host supplies. All optional: a pre-auth open is device-only. */
+interface UseLifecycleEventsOptions {
+    /** The host's opaque pseudonymous user id (NOT PII). Omitted before the user authenticates. */
+    userId?: string;
+    /** The host's local open-counter value for this open. Drives `returning` + "Nth session". */
+    sessionCount?: number;
+    /** A stable, non-PII device id the host owns. Groups this device's sessions server-side. */
+    deviceKey?: string;
+    /** Small non-PII extras forwarded on the event `meta`. */
+    meta?: Record<string, unknown>;
+    /** Set `false` to disable firing (e.g. behind a consent gate). Default enabled. */
+    enabled?: boolean;
+    /**
+     * Explicit transport sink (e.g. an existing shared `EventQueue.enqueue`). When provided, BOTH
+     * lifecycle events route here and the hook does NOT create its own queue — pass this to share ONE
+     * offline queue across the kit's analytics (screen tracking + lifecycle).
+     */
+    sink?: (event: ClientEvent) => void;
+    /**
+     * Context envelope (or provider) for the hook's internally-created queue. Ignored when `sink` is
+     * supplied (the host's queue owns envelope stamping).
+     */
+    envelope?: EnvelopeSource;
+}
+/**
+ * Fire `app.first_open` (once ever) + `app.session_started` (per open), offline-buffered. Returns
+ * nothing — a side-effecting hook. Safe to call with inline options (read through a ref, so
+ * changing `userId`/`sessionCount` never re-fires a session).
+ */
+declare const useLifecycleEvents: (config: LifecycleConfig | undefined, options?: UseLifecycleEventsOptions) => void;
+
+export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardHandoff, type CardHandoffProps, type CardHandoffVariant, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import { e as WireOnboardingProps, f as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, g as OnboardingEvent, h as OnboardingCopy, a as ClientEventTarget, D as DeviceContext } from './analyticsEvent-DvjB92kK.js';
-export { A as AnalyticsEvent, C as ClientEvent, b as ClientEventType, i as DeviceFormFactor, j as OnboardingProgress, W as WIRE_ONBOARDING_EVENTS, c as WireOnboardingEventName, k as collectDeviceContext, m as makeSessionId, r as reportClientEvent, d as reportClientEvents, t as toAnalyticsEvent } from './analyticsEvent-DvjB92kK.js';
+import { k as WireOnboardingProps, l as WireOnboardingConfig, O as OnboardingResult, S as StepValidator, n as OnboardingEvent, o as OnboardingCopy, a as ClientEventTarget, D as DeviceContext, C as ClientEvent, e as EnvelopeSource } from './eventQueue-CrNB9gzH.js';
+export { A as AnalyticsEvent, b as ClientEventType, p as DeviceFormFactor, q as OnboardingProgress, W as WIRE_ONBOARDING_EVENTS, g as WireOnboardingEventName, s as collectDeviceContext, m as makeSessionId, r as reportClientEvent, j as reportClientEvents, t as toAnalyticsEvent } from './eventQueue-CrNB9gzH.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';
@@ -937,6 +937,15 @@ interface ReportSessionStartOptions {
     meta?: Record<string, unknown>;
     /** Set `false` to bypass the once-per-open guard (default on). See {@link resetSessionStartGuard}. */
     once?: boolean;
+    /**
+     * OPTIONAL transport sink. When provided, the built `app.session_started` event is routed HERE
+     * (e.g. the offline-first event queue's `enqueue`) INSTEAD of this emitter's own direct `fetch`,
+     * while KEEPING the once-per-open guard above. This is how the lifecycle wiring
+     * (`useLifecycleEvents` / `wireLifecycleEvents`) offline-buffers session-start WITHOUT adding a
+     * second session emitter: one emitter, one guard, now durable. Omit it for the direct-POST path.
+     * A throwing sink is swallowed — analytics must never surface into the UI.
+     */
+    sink?: (event: ClientEvent) => void;
 }
 /** Test-only: forget every emitted session id so a unit test starts from a clean guard. */
 declare const resetSessionStartGuard: () => void;
@@ -977,4 +986,149 @@ interface UseSessionStartOptions {
  */
 declare const useSessionStart: (config: SessionStartConfig | undefined, options?: UseSessionStartOptions) => void;
 
-export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardHandoff, type CardHandoffProps, type CardHandoffVariant, ChipSelectCard, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseSessionStartOptions, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, featuresCacheKey, featuresEqual, fetchWireFeatures, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportSessionStart, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useIllustration, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, writeCachedFeatures };
+/**
+ * lifecycle — the TOP-OF-FUNNEL app lifecycle events that sit ABOVE onboarding: `app.first_open`
+ * (once ever per install) and `app.session_started` (per app-open). They compose with, and never
+ * duplicate, the events the funnel already records.
+ *
+ * WHERE THIS FITS (one funnel, no double counting):
+ *   • `app.first_open`      → THIS module, once ever (persisted flag). The in-app "install" proxy.
+ *   • `app.session_started` → the EXISTING {@link reportSessionStart} emitter (per app-open). This
+ *                             module REUSES it (routed through the offline queue), never re-emits.
+ *   • onboarding started / completed / activated → ALREADY recorded: the server writes
+ *     `session_started` + `completed` during the A2A flow, and the client reports `dropped` /
+ *     `client_fallback` / `identify` via `reportClientEvent`. This module does NOT touch them —
+ *     emitting them here would double-count. It only ADDS the two lifecycle events above them.
+ *
+ * WIRE CONTRACT (identical to `app.session_started`): both lifecycle events are stored as
+ * `event_type='app_event'` with the name in `question_key` (the server's `_event_name` returns
+ * `question_key` for an `app_event`, which a trigger matches). `app.first_open` uses the SAME
+ * `app.*` namespace + the SAME event shape as `app.session_started` — no bespoke `event_type`,
+ * no invented contract. `device_key` rides in the non-PII `user_context` bucket; `app_id` +
+ * `environment` are filled server-side.
+ *
+ * TWO FIRST-CLASS ENTRY POINTS (mirrors reportSessionStart vs useSessionStart):
+ *   • `reportFirstOpen(...)` / `wireLifecycleEvents(...)` — pure, React-free, for a host that owns
+ *     its own app-open path.
+ *   • `useLifecycleEvents(...)` — the batteries-included React hook (in `useLifecycleEvents.ts`).
+ *
+ * OFFLINE-FIRST: pass the Brief-01 event queue's `enqueue` as the `sink` and every lifecycle event
+ * is buffered + persisted + retried instead of a blind fetch. Without a sink they degrade to a
+ * direct fire-and-forget POST.
+ *
+ * PRIVACY (hard rule, same as the rest of the kit): NO GPS/location, NO advertising id. Nothing
+ * here carries a coordinate or an ad id — a host adopting it changes no store privacy declaration.
+ *
+ * FIRE-AND-FORGET: like every analytics path in the kit, nothing here throws into the UI, awaits
+ * in the caller, or hangs the app — storage reads race a short timeout, writes swallow errors.
+ */
+
+/** The canonical event name for the first-ever app open. Same `app.*` namespace as
+ *  {@link SESSION_STARTED_EVENT}; a trigger keys off this exact string. */
+declare const FIRST_OPEN_EVENT: "app.first_open";
+/** Storage key for the once-ever first-open flag, e.g. `wireai:first_open:myelino`. Mirrors the
+ *  `wireai:<concern>:<appId>` namespacing of {@link sessionStorageKey}. */
+declare const firstOpenStorageKey: (appId: string) => string;
+/** Test-only: forget the first-open latch so a unit test starts from a clean process state. */
+declare const resetFirstOpenLatch: () => void;
+/** Shared inputs for a lifecycle event. Everything is optional except a transport (`target` for the
+ *  direct-POST fallback, or a `sink`). A pre-auth open (no user yet) is a valid device-only event. */
+interface LifecycleEventInput {
+    /** Where to POST if no `sink` is wired (the tenant transport, same as `WireOnboardingConfig`). */
+    target?: ClientEventTarget;
+    /** Preferred transport: route the built event HERE (the offline queue's `enqueue`). */
+    sink?: (event: ClientEvent) => void;
+    /** The per-open session id. Defaults to a fresh `makeSessionId()`. */
+    sessionId?: string;
+    /** The host's OPAQUE pseudonymous user id (NOT PII). Sanitized + capped; omitted pre-auth. */
+    userId?: string;
+    /** A stable, non-PII device id the host owns. Rides in `user_context.device_key`. */
+    deviceKey?: string;
+    /** The host's local open-counter value. Drives `returning` + "Nth session". */
+    sessionCount?: number;
+    /** Host app version (e.g. "1.4.2"), if cheaply available. */
+    appVersion?: string;
+    /** Platform string (e.g. "ios"), if cheaply available. */
+    platform?: string;
+    /** An optional richer device snapshot (from `collectDeviceContext()`); the hook fills this. */
+    device?: DeviceContext;
+    /** Small non-PII extras, stored as a JSON string in the event `meta`. */
+    meta?: Record<string, unknown>;
+}
+/** Options for {@link reportFirstOpen}. Adds the once-ever persistence inputs on top of the shared
+ *  lifecycle inputs. Without `storage` it degrades to the in-memory latch (once per process). */
+interface ReportFirstOpenOptions extends LifecycleEventInput {
+    /** Host persistence (AsyncStorage subset). The once-ever flag lives here — it is what survives an
+     *  app kill. Omit it for the documented degraded (in-memory, once-per-process) mode. */
+    storage?: WireOnboardingStorage;
+    /** Tenant/app id — namespaces the persisted flag (`wireai:first_open:<appId>`). */
+    appId?: string;
+}
+/**
+ * Emit `app.first_open` EXACTLY ONCE EVER per install. Fire-and-forget; returns immediately.
+ *
+ *   • With `storage`: reads the persisted flag (`wireai:first_open:<appId>`). Absent → emit, then
+ *     write the flag (survives app kills, so a second launch is a no-op). Present → no-op.
+ *   • Race guard: an in-memory latch is set SYNCHRONOUSLY before the async read, so two
+ *     near-simultaneous calls fire at most once.
+ *   • Without `storage`: degraded mode — fires once per PROCESS via the latch only (documented).
+ */
+declare const reportFirstOpen: (opts: ReportFirstOpenOptions) => void;
+/** Options for {@link wireLifecycleEvents}: the shared lifecycle inputs + first-open persistence. */
+interface WireLifecycleOptions extends ReportFirstOpenOptions {
+}
+/**
+ * Wire BOTH lifecycle events in one call for a host that owns its own app-open path (the non-hook
+ * counterpart to {@link useLifecycleEvents}). Fires `app.first_open` (once ever) and one
+ * `app.session_started` for THIS open through the EXISTING {@link reportSessionStart} emitter (so
+ * the once-per-open guard still applies — pass the same `sessionId` and it never double-fires).
+ * Route both through the same `sink` (the offline queue) to buffer them. Fire-and-forget.
+ */
+declare const wireLifecycleEvents: (opts: WireLifecycleOptions) => void;
+
+/** Tenant transport + host persistence for the lifecycle wiring. Same creds as `WireOnboardingConfig`. */
+interface LifecycleConfig {
+    /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
+    serverUrl?: string;
+    /** Tenant API key; sent as `Authorization: Bearer`. */
+    apiKey?: string;
+    /** Host app version (e.g. "1.4.2"), forwarded for release segmentation. Optional. */
+    appVersion?: string;
+    /** Tenant/app id — namespaces the first-open flag AND the hook's internal queue storage key. */
+    appId?: string;
+    /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag AND the
+     *  offline durability of the hook's internal queue. Omit it and both degrade to in-memory. */
+    storage?: WireOnboardingStorage;
+}
+/** Per-open identity + wiring the host supplies. All optional: a pre-auth open is device-only. */
+interface UseLifecycleEventsOptions {
+    /** The host's opaque pseudonymous user id (NOT PII). Omitted before the user authenticates. */
+    userId?: string;
+    /** The host's local open-counter value for this open. Drives `returning` + "Nth session". */
+    sessionCount?: number;
+    /** A stable, non-PII device id the host owns. Groups this device's sessions server-side. */
+    deviceKey?: string;
+    /** Small non-PII extras forwarded on the event `meta`. */
+    meta?: Record<string, unknown>;
+    /** Set `false` to disable firing (e.g. behind a consent gate). Default enabled. */
+    enabled?: boolean;
+    /**
+     * Explicit transport sink (e.g. an existing shared `EventQueue.enqueue`). When provided, BOTH
+     * lifecycle events route here and the hook does NOT create its own queue — pass this to share ONE
+     * offline queue across the kit's analytics (screen tracking + lifecycle).
+     */
+    sink?: (event: ClientEvent) => void;
+    /**
+     * Context envelope (or provider) for the hook's internally-created queue. Ignored when `sink` is
+     * supplied (the host's queue owns envelope stamping).
+     */
+    envelope?: EnvelopeSource;
+}
+/**
+ * Fire `app.first_open` (once ever) + `app.session_started` (per open), offline-buffered. Returns
+ * nothing — a side-effecting hook. Safe to call with inline options (read through a ref, so
+ * changing `userId`/`sessionCount` never re-fires a session).
+ */
+declare const useLifecycleEvents: (config: LifecycleConfig | undefined, options?: UseLifecycleEventsOptions) => void;
+
+export { AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardHandoff, type CardHandoffProps, type CardHandoffVariant, ChipSelectCard, ClientEvent, ClientEventTarget, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, DeviceContext, DoneBlock, ErrorBlock, FIRST_OPEN_EVENT, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, type LifecycleConfig, type LifecycleEventInput, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, OnboardingCopy, OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportFirstOpenOptions, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseLifecycleEventsOptions, type UseSessionStartOptions, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, type WireLifecycleOptions, WireOnboarding, WireOnboardingConfig, WireOnboardingProps, WireOnboardingStorage, attributionMetadata, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, featuresCacheKey, featuresEqual, fetchWireFeatures, firstOpenStorageKey, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportFirstOpen, reportSessionStart, resetFirstOpenLatch, resetSessionStartGuard, sanitizeUserId, themeFromBrand, useIllustration, useLifecycleEvents, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, wireLifecycleEvents, writeCachedFeatures };