@wireai/activation 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,230 +1,14 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
-import * as wireai_rn from 'wireai-rn';
-import { Message, WireAIComponent, WireAIResponse } from 'wireai-rn';
+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-rV1dtJJR.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-rV1dtJJR.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';
-import { b as WireOnboardingStorage, a as WireFeaturesConfig, W as WireFeatures } from './types-CMuOexw0.js';
-export { D as DEFAULT_SESSION_TTL_MS, L as LoadedSession, O as OnboardingMode, c as clearPersistedSession, l as loadPersistedSession, p as peekPersistedSession, s as savePersistedSession, d as sessionStorageKey } from './types-CMuOexw0.js';
 export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-Cdgns6--.js';
-import { Platform } from 'react-native';
-
-/** Transport + tenant config for the managed Wire AI onboarding backend (A2A). */
-type WireOnboardingConfig = {
-    /** Tenant API key (resolves the app server-side). */
-    apiKey: string;
-    /** Base server URL; the kit appends `/a2a`. */
-    serverUrl: string;
-    /** App id — passed as the A2A `model` (informational; the key resolves the app). */
-    appId: string;
-    /**
-     * Extra metadata merged into every A2A request (e.g. install attribution).
-     * NOTE: the kit reserves `sessionId` (correlation seed) and `supportedComponents`
-     * (the renderable card names this device advertises to the backend) — it sets both
-     * automatically, so don't override them here.
-     */
-    metadata?: Record<string, unknown>;
-    /**
-     * Host app version string (e.g. "1.4.2"). HOST-INJECTED — the kit adds no dependency to
-     * read it; hosts typically pass it from `expo-constants`
-     * (`Constants.expoConfig?.version`). Forwarded to the backend on the session metadata and
-     * on client events (merged into the `device` snapshot as `device.appVersion`) so analytics
-     * can segment the funnel by app version. Optional; omit if unknown.
-     */
-    appVersion?: string;
-};
-/**
- * A per-step validator, keyed by a base-question `key` (e.g. `username`). Runs
- * before the answer is sent to the backend. Return `{ ok: false, error }` to
- * block advancing and show the error inline on the card.
- */
-type StepValidator = (value: string) => Promise<{
-    ok: boolean;
-    error?: string;
-}>;
-/** Result handed to `onComplete` when the flow reaches its terminal StatusCard. */
-type OnboardingResult = {
-    /** Question-key → captured value, derived from the thread. */
-    answers: Record<string, unknown>;
-    /** The raw message thread, for custom downstream parsing. */
-    raw: Message[];
-};
-/**
- * Lifecycle events emitted as the flow runs, for host-side analytics. The kit owns
- * the thread loop, so this is how a host recovers per-turn telemetry it used to get
- * by driving the loop itself.
- *  - `started`: the very first message was sent to the backend. Carries `contextId` (the
- *               A2A session id). Capture it if you may need to bind a user AFTER the flow
- *               finishes (see `identifyOnboarding` and the `userId` prop).
- *  - `resumed`: a persisted session was restored after an app kill (fires INSTEAD of
- *               `started`, so host funnels don't double-count the same session). Also carries
- *               `contextId`. Requires the `storage` prop.
- *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen).
- *  - `error`: the backend errored or the first-card watchdog timed out.
- *  - `retry`: a transient failure is being auto-retried (`attempt` = 1-based).
- *  - `fallback`: retries are exhausted; the kit degraded to the static `fallbackFlow`
- *               (or handed off to `onError`). This is the client-side mirror of the
- *               backend's `llm_fallback` reliability event.
- */
-type OnboardingEvent = {
-    type: "started";
-    contextId: string;
-} | {
-    type: "resumed";
-    contextId: string;
-} | {
-    type: "turn";
-    step: number;
-    component?: string;
-} | {
-    type: "error";
-    reason: "backend" | "timeout";
-} | {
-    type: "retry";
-    reason: "backend" | "timeout";
-    attempt: number;
-} | {
-    type: "fallback";
-    reason: "backend" | "timeout";
-};
-/**
- * Copy overrides for the kit's built-in (English) strings, so a host can localize
- * the loaders / completion fallback via its own i18n. Any field left unset keeps
- * the kit default.
- */
-type OnboardingCopy = {
-    /** First "thinking" screen, before any card arrives. */
-    startingTitle: string;
-    startingHint: string;
-    /** While the persisted session id is being restored from `storage` (pre-mount gate). */
-    restoringTitle: string;
-    restoringHint: string;
-    /** Between-turns loader, while the next card is generated. */
-    thinkingTitle: string;
-    thinkingHint: string;
-    /** While a per-step validator is running. */
-    checkingTitle: string;
-    checkingHint: string;
-    /** Completion fallback when the backend omits a title/CTA. */
-    completeTitle: string;
-    completeCta: string;
-};
-type WireOnboardingProps = {
-    config: WireOnboardingConfig;
-    /** Partial theme merged over the neutral default. */
-    theme?: Partial<OnboardingTheme>;
-    /** Override the registered cards (defaults to the kit's `onboardingComponents`). */
-    components?: wireai_rn.WireAIComponent[];
-    /**
-     * App-supplied artwork for InterstitialCard, keyed by name. The backend names one
-     * via `illustration`; the kit slots the matching node (keeping itself dependency-free).
-     */
-    illustrations?: Record<string, React.ReactNode>;
-    /** Per-step validators keyed by base-question key, e.g. `{ username: checkUsername }`. */
-    validators?: Record<string, StepValidator>;
-    /** Fired once the flow reaches its terminal StatusCard. */
-    onComplete: (result: OnboardingResult) => void;
-    /**
-     * Retained for back-compat. NOTE: per-question Skip is now INTERNAL — the kit shows
-     * a Skip control only on screens the backend marks `skippable`, and it advances ONE
-     * question (it does not exit the flow). This callback is no longer wired to that control.
-     */
-    onSkip?: () => void;
-    /**
-     * Fired on a backend error or first-card timeout, AFTER retries are exhausted.
-     * When `fallbackFlow` is NOT supplied and this is provided, the host owns recovery
-     * (e.g. navigate to its own static onboarding) instead of the kit's inline retry.
-     */
-    onError?: (err: unknown) => void;
-    /**
-     * Your predefined STATIC onboarding, rendered in place when the AI flow fails and
-     * retries are exhausted — so a generation/backend/timeout error degrades to your
-     * static flow instead of breaking the app. Takes precedence over `onError`. This
-     * is the "it can never break your onboarding" guarantee: supply the same flow you
-     * shipped before adding Wire AI and the user always keeps moving.
-     */
-    fallbackFlow?: React.ReactNode;
-    /**
-     * Consecutive failures to auto-retry before degrading to `fallbackFlow`/`onError`.
-     * Default 1 (one silent retry, then degrade). 0 = degrade on the first failure.
-     */
-    maxRetries?: number;
-    /** 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.
-     *
-     * 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>;
-    /**
-     * 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`.
-     *
-     * An OPAQUE PSEUDONYMOUS string YOU own — your internal user id, NOT an email/name/phone.
-     * Trimmed and capped at 128 chars (longer is truncated). **No PII.**
-     *
-     * LATE BINDING: users often register DURING or AFTER onboarding, so this is fully optional
-     * and can arrive late:
-     *  - present at MOUNT → rides the A2A session-start metadata (server binds it at session start);
-     *  - CHANGES mid-session (e.g. the user just registered) → the kit emits an `identify` event
-     *    that attaches the id to the LIVE session;
-     *  - available only AFTER completion → capture the `contextId` from the `started`/`resumed`
-     *    `onEvent` while the flow runs, then call `identifyOnboarding({ contextId, userId })` once
-     *    the user registers. Completion clears the persisted session, so the captured `contextId`
-     *    is the reliable post-flow handle.
-     *
-     * Backward compatible: omit it and nothing changes; old servers ignore the extra field.
-     */
-    userId?: string;
-    /** Localized overrides for the kit's built-in English strings. */
-    copy?: Partial<OnboardingCopy>;
-    /**
-     * Approximate total number of screens, if known (e.g. the backend screen budget).
-     * Paces the progress bar as `step / approxScreens` (capped, never shown as a
-     * number) instead of the asymptotic default. A backend-supplied `progress.total`
-     * takes precedence when present.
-     */
-    approxScreens?: number;
-    /** First message that kicks off the backend flow. Default `"start"`. */
-    startMessage?: string;
-    /** Ms to wait for the first card before showing the error/retry state. Default 15000. */
-    startTimeoutMs?: number;
-    /**
-     * Host-injected storage for session-id persistence (AsyncStorage-compatible subset:
-     * pass `@react-native-async-storage/async-storage` as-is, or a small MMKV wrapper).
-     * When set, the kit caches its session id so an app KILL mid-onboarding resumes the
-     * SAME backend session instead of minting a new one — keeping the analytics funnel's
-     * `started` count honest (no phantom drops). Omit for the previous per-mount behavior.
-     * This persists the kit's own correlation seed only — never answers.
-     */
-    storage?: WireOnboardingStorage;
-    /**
-     * How long a persisted session id stays resumable, in ms. Default 3 600 000 (1h),
-     * matching the backend's session TTL. Only meaningful with `storage`.
-     */
-    sessionTtlMs?: number;
-    /**
-     * Override the storage key (default `wireai:session:<config.appId>`). Scope it
-     * per-user (e.g. append a user id) if one device can run onboarding for multiple
-     * accounts mid-flow. Only meaningful with `storage`.
-     */
-    persistKey?: string;
-};
-/** Backend-supplied progress, read off `response.props.progress` when present. */
-type OnboardingProgress = {
-    step: number;
-    total: number;
-    /** Base-question key for the CURRENT screen, when known (used to pick a validator). */
-    key?: string;
-    /** Whether the CURRENT screen may be skipped (backend-marked; default false → no Skip shown). */
-    skippable?: boolean;
-};
+import { WireAIComponent, Message, WireAIResponse } from 'wireai-rn';
+import { a as WireFeaturesConfig, W as WireFeatures, b as WireOnboardingStorage } from './types-CMuOexw0.js';
+export { D as DEFAULT_SESSION_TTL_MS, L as LoadedSession, O as OnboardingMode, c as clearPersistedSession, l as loadPersistedSession, p as peekPersistedSession, s as savePersistedSession, d as sessionStorageKey } from './types-CMuOexw0.js';
+import 'react-native';
 
 /**
  * WireOnboarding — the public host component. Drop it into a screen and it runs
@@ -764,160 +548,6 @@ declare const InterstitialCard: WireAIComponent;
 
 declare const onboardingComponents: WireAIComponent[];
 
-/**
- * deviceContext — collect a small, privacy-label-neutral snapshot of the device so
- * onboarding analytics can segment the funnel (platform / form factor / locale) WITHOUT
- * adding a single dependency to the kit or changing a host app's App Privacy / Data Safety
- * declarations.
- *
- * HARD RULE (why this file has no imports beyond React Native built-ins):
- *   The kit stays dependency-free. Everything here comes from `Platform`, `Dimensions`,
- *   `I18nManager`, and the standard `Intl` global. There are NO advertising IDs, NO
- *   `getUniqueId`/IDFA/GAID/fingerprinting APIs, and nothing that would require a new
- *   privacy-label entry. A host can adopt this without touching its store declarations.
- *
- * DEFENSIVE BY DESIGN: `collectDeviceContext()` never throws. Every read is guarded and
- * a missing/unavailable field is simply omitted (Hermes may ship without full `Intl`,
- * `Platform.constants` differs per OS and RN version, etc.). Analytics must never be able
- * to break onboarding.
- */
-
-/** Coarse device class. iOS uses the reported interface idiom; else a screen-size heuristic. */
-type DeviceFormFactor = "phone" | "tablet";
-/**
- * A privacy-label-neutral device snapshot. ALL fields except `platform` are optional and are
- * omitted when unavailable. Nothing here identifies a user or device uniquely.
- */
-type DeviceContext = {
-    /** `Platform.OS` — "ios" | "android" | "windows" | "macos" | "web". Always present. */
-    platform: typeof Platform.OS;
-    /** OS version string (iOS `osVersion`/`Platform.Version`, Android `Release`). */
-    osVersion?: string;
-    /** Android device brand (e.g. "samsung"). Android only. */
-    brand?: string;
-    /** Android device model (e.g. "SM-G991B"). Android only. */
-    model?: string;
-    /** iOS interface idiom ("phone" | "pad" | …), when reported. iOS only. */
-    interfaceIdiom?: string;
-    /** Derived device class. */
-    formFactor?: DeviceFormFactor;
-    /** `Dimensions.get('screen')` width in dp. */
-    screenWidth?: number;
-    /** `Dimensions.get('screen')` height in dp. */
-    screenHeight?: number;
-    /** Screen pixel density (`scale`). */
-    screenScale?: number;
-    /** Right-to-left layout (`I18nManager.isRTL`). */
-    isRTL?: boolean;
-    /** Resolved locale (e.g. "en-US"), from `Intl` when available. */
-    locale?: string;
-    /** IANA time zone (e.g. "Europe/Berlin"), from `Intl` when available. */
-    timeZone?: string;
-    /**
-     * Host app version (e.g. "1.4.2). HOST-INJECTED — NOT collected here. `WireOnboarding`
-     * merges `config.appVersion` into the snapshot; `collectDeviceContext()` never sets it.
-     * Hosts typically pass it from `expo-constants` (the kit itself adds no dependency).
-     */
-    appVersion?: string;
-};
-/**
- * Collect the device snapshot. Pure, synchronous, and never throws — call it once per
- * onboarding session. Missing fields are omitted rather than sent as null/undefined so the
- * payload (and the server's stored dict) stays compact.
- */
-declare const collectDeviceContext: () => DeviceContext;
-
-/**
- * reportClientEvent — forward DEVICE-ONLY onboarding events to the Wire AI analytics
- * backend (`POST {serverUrl}/v1/events`), completing the funnel for events the server
- * can't observe on its own.
- *
- * The backend already records the server-observable funnel during the A2A flow
- * (`session_started`, `screen_shown`, `answer_submitted`, `completed`, `llm_fallback`,
- * and even `screen_skipped` — it derives that from the kit's skip sentinel). The one
- * event no server request can capture is `dropped`: the user closing the app / unmounting
- * the flow without finishing. That's what this reporter is for.
- *
- * Contract (server: routers/onboarding.py → analytics/events.py):
- *   POST {serverUrl}/v1/events
- *   Authorization: Bearer {apiKey}
- *   { "events": [ { event_type, session_id, screen_index?, component?, question_key?,
- *                   latency_ms?, meta?, device?, user_context? } ] }
- * The server fills `app_id` + `environment` from the resolving key (never send app_id),
- * and silently skips malformed events — one bad payload never fails the batch.
- *
- * ⚠️ Correlation: `session_id` MUST equal the A2A `contextId` the server uses to key the
- * server-side events, or the funnel report (which groups by `session_id`) treats this as a
- * phantom session. See `makeSessionId` + WireOnboarding for how the kit seeds it.
- *
- * Fire-and-forget: this never throws into the UI and never awaits — analytics must never
- * be able to break onboarding.
- */
-
-/** Event types a CLIENT may report. The rest of the funnel is server-side; sending those
- *  here would double-count. `screen_skipped` is included for completeness, but the kit does
- *  NOT emit it — the backend already derives it from the skip sentinel (see OnboardingFlow).
- *  `client_fallback` is emitted by the kit when the AI flow degrades to the static fallback,
- *  so the dashboard's fallback-rate counts the whole-flow case (distinct from the server's
- *  per-turn `llm_fallback`). The server back-fills a `session_started` for it if unseen.
- *  This is the SINGLE fallback signal — hosts must NOT also report their own.
- *  `identify` binds the host's opaque `user_id` to this `session_id` (late binding — the user
- *  registered during/after onboarding). It carries no funnel weight; the server maps the
- *  session to the user and back-fills a `session_started` if it never saw the session. */
-type ClientEventType = "screen_skipped" | "dropped" | "client_fallback" | "identify";
-/** One client-reported event. Mirrors the server's `OnboardingEvent` (client-settable fields). */
-type ClientEvent = {
-    event_type: ClientEventType;
-    /** Must match the server-side A2A contextId for this onboarding (see makeSessionId). */
-    session_id: string;
-    /** 0-based index of the screen the event refers to (matches server `screen_shown`). */
-    screen_index?: number;
-    component?: string;
-    question_key?: string;
-    latency_ms?: number;
-    /** JSON-stringified extras; the server stores it verbatim. */
-    meta?: string;
-    /**
-     * Privacy-label-neutral device snapshot (platform / form factor / locale / host appVersion).
-     * Sent as an object; the server sanitizes + persists it and derives a coarse country. Old
-     * servers ignore this unknown field — fully backward compatible. See device/deviceContext.ts.
-     */
-    device?: DeviceContext;
-    /**
-     * Host-injected, non-PII context (signup method, referral, plan, hashed user id). Old servers
-     * ignore it. MUST NOT contain PII like raw emails — see the README `userContext` section.
-     */
-    user_context?: Record<string, string | number | boolean>;
-    /**
-     * The host's OPAQUE PSEUDONYMOUS user id (their internal id, NOT an email/name). Required on
-     * `identify`, optional (rides along) on other events. Trimmed + capped at 128 chars host-side.
-     * Lets the backend reconcile onboarding sessions to real users. Old servers ignore it.
-     */
-    user_id?: string;
-};
-/** Where to POST. Derived from `WireOnboardingConfig` (`serverUrl` + `apiKey`). */
-type ClientEventTarget = {
-    /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
-    serverUrl: string;
-    /** Tenant API key; sent as `Authorization: Bearer`. */
-    apiKey: string;
-};
-/**
- * A unique-per-onboarding session id. Used both as the client event `session_id` AND as the
- * seed the kit forwards to the backend so the SERVER adopts it as the A2A `contextId` — making
- * client and server agree (see WireOnboarding + the SDK-correlation note in the kit docs).
- * No crypto dependency: timestamp + random is collision-safe for a single device's onboarding.
- */
-declare const makeSessionId: () => string;
-/**
- * POST one or more client events, fire-and-forget. A missing/invalid target, a build error,
- * a missing `fetch`, or a network failure is swallowed — the call returns immediately and the
- * request (if any) runs in the background.
- */
-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;
-
 /**
  * OnboardingFlow — the inner engine. Mirrors the proven production-app usage of the SDK
  * (useWireAIThread + useWireAIAction + ComponentRenderer) and layers on the kit's
@@ -1034,7 +664,7 @@ declare const useWireFeatures: (config?: WireFeaturesConfig) => WireFeatures;
  *
  * NOTE on the built npm subpaths: React context is shared across the kit's subpath entries in the
  * SOURCE-consumption path (the monorepo apps) and in this test suite — one module instance, one
- * context. If you consume the built `wireai-onboarding/*` subpaths as separate bundles, pass the
+ * context. If you consume the built `@wireai/activation/*` subpaths as separate bundles, pass the
  * resolved flags (or a `featuresConfig`) to each surface explicitly instead of relying on context.
  */
 
@@ -1156,46 +786,6 @@ type OnboardingFlagOptions = {
 };
 declare const isOnboardingEnabled: (opts?: OnboardingFlagOptions) => boolean;
 
-/**
- * Canonical analytics names for the onboarding funnel. The kit already emits a typed
- * `OnboardingEvent` (`started | turn | error | retry | fallback`) — but one app logged them as
- * `onboarding_*` and another as `AI_ONBOARDING_*`, so the same funnel reads differently per app.
- * This maps the kit event to ONE canonical `wire_onboarding_*` name + params, and the app logs
- * it through whatever transport it already has (Firebase, Amplitude, console). The app still
- * owns the logger; only the NAMES are standardized.
- *
- *   <WireOnboarding
- *     onEvent={(e) => { const a = toAnalyticsEvent(e); logEvent(a.name, a.params); }}
- *     onComplete={(r) => { logEvent(WIRE_ONBOARDING_EVENTS.completed, { answers: Object.keys(r.answers).length }); persist(r); }}
- *   />
- *
- * `completed` has no kit `OnboardingEvent` (the kit signals completion via `onComplete`, not
- * `onEvent`) — the app logs it explicitly on `onComplete` using the constant below, so the
- * funnel name stays canonical.
- */
-
-declare const WIRE_ONBOARDING_EVENTS: {
-    readonly started: "wire_onboarding_started";
-    /** A persisted session was restored after an app kill (fires instead of `started`). */
-    readonly resumed: "wire_onboarding_resumed";
-    readonly turn: "wire_onboarding_turn";
-    readonly error: "wire_onboarding_error";
-    readonly retry: "wire_onboarding_retry";
-    readonly fallback: "wire_onboarding_fallback";
-    /** Logged by the host on `onComplete` (no matching kit `OnboardingEvent`). */
-    readonly completed: "wire_onboarding_completed";
-};
-type WireOnboardingEventName = (typeof WIRE_ONBOARDING_EVENTS)[keyof typeof WIRE_ONBOARDING_EVENTS];
-type AnalyticsEvent = {
-    name: WireOnboardingEventName;
-    params?: Record<string, unknown>;
-};
-/**
- * Map a kit `OnboardingEvent` to its canonical `{ name, params }`. Exhaustive over the union
- * (the `never` default makes a new event type a compile error here — intentional).
- */
-declare const toAnalyticsEvent: (event: OnboardingEvent) => AnalyticsEvent;
-
 /**
  * attribution — forward install/ad attribution to the onboarding agent so it can tailor the
  * first question by acquisition source (e.g. a paid-campaign install vs an organic one). The
@@ -1347,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;
@@ -1387,4 +986,149 @@ interface UseSessionStartOptions {
  */
 declare const useSessionStart: (config: SessionStartConfig | undefined, options?: UseSessionStartOptions) => void;
 
-export { type AnalyticsEvent, AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardHandoff, type CardHandoffProps, type CardHandoffVariant, ChipSelectCard, type ClientEvent, type ClientEventTarget, type ClientEventType, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, type DeviceContext, type DeviceFormFactor, DoneBlock, ErrorBlock, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, type OnboardingCopy, type OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, type OnboardingProgress, type OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, type StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseSessionStartOptions, WIRE_ONBOARDING_EVENTS, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireOnboarding, type WireOnboardingConfig, type WireOnboardingEventName, type WireOnboardingProps, WireOnboardingStorage, attributionMetadata, collectDeviceContext, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, featuresCacheKey, featuresEqual, fetchWireFeatures, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, makeSessionId, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportClientEvent, reportClientEvents, reportSessionStart, resetSessionStartGuard, sanitizeUserId, themeFromBrand, toAnalyticsEvent, 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 };