@wireai/activation 0.1.1 → 0.2.0

package/dist/{analyticsEvent-DvjB92kK.d.ts → eventQueue-rV1dtJJR.d.ts}

@@ -1,9 +1,9 @@
-import { Platform } from 'react-native';
 import * as React from 'react';
 import * as wireai_rn from 'wireai-rn';
 import { Message } from 'wireai-rn';
 import { O as OnboardingTheme } from './types-BKfpdZzX.js';
 import { b as WireOnboardingStorage } from './types-CMuOexw0.js';
+import { Platform } from 'react-native';
 
 /**
  * deviceContext — collect a small, privacy-label-neutral snapshot of the device so
@@ -416,4 +416,131 @@ type AnalyticsEvent = {
  */
 declare const toAnalyticsEvent: (event: OnboardingEvent) => AnalyticsEvent;
 
-export { type AnalyticsEvent as A, type ClientEvent as C, type DeviceContext as D, type OnboardingResult as O, type StepValidator as S, WIRE_ONBOARDING_EVENTS as W, type ClientEventTarget as a, type ClientEventType as b, type WireOnboardingEventName as c, reportClientEvents as d, type WireOnboardingProps as e, type WireOnboardingConfig as f, type OnboardingEvent as g, type OnboardingCopy as h, type DeviceFormFactor as i, type OnboardingProgress as j, collectDeviceContext as k, makeSessionId as m, reportClientEvent as r, toAnalyticsEvent as t };
+/**
+ * contextEnvelope — a small, PRIVACY-NEUTRAL context bundle stamped onto every outgoing
+ * analytics event, giving the Wire dashboard the Sentry/Firebase-parity segmentation fields
+ * (device model, OS + version, screen, locale, timezone, form factor) plus a few host-injected
+ * scalars (session correlation id, app version + native build number, connectivity type).
+ *
+ * WHY a separate builder (not just `collectDeviceContext`): the envelope COMPOSES the existing
+ * device snapshot with the handful of extras a host can cheaply supply but the kit can't collect
+ * dependency-free (native build number, connectivity type). It never re-implements device
+ * collection — it reuses `collectDeviceContext()` verbatim (see device/deviceContext.ts).
+ *
+ * HARD PRIVACY RULE (why this file, like deviceContext.ts, adds nothing new):
+ *   NEVER GPS / location, NEVER an advertising id (IDFA / GAID), NEVER a device fingerprint.
+ *   Location is derived SERVER-SIDE from IP-geo only — nothing here carries a coordinate or an
+ *   ad id, so a host adopting this changes no App Privacy / Data Safety declaration. There is a
+ *   test (contextEnvelope.test.ts) that asserts the ABSENCE of any such field.
+ *
+ * DEPENDENCY-FREE: the only import is the kit's own `collectDeviceContext`. `networkType` and
+ * `appBuild` are HOST-INJECTED — there is no dependency-free RN core signal for either, so the
+ * envelope simply omits them when the host does not pass them (no forced peer dependency).
+ */
+
+/**
+ * The context stamped onto every event. `device` is always present (from
+ * `collectDeviceContext`); every scalar is optional and OMITTED when the host does not supply it.
+ */
+type ContextEnvelope = {
+    /** The privacy-neutral device snapshot (reused from `collectDeviceContext`). */
+    device: DeviceContext;
+    /** Correlation id for this app-open / flow (caller-supplied). */
+    sessionId?: string;
+    /** Host app version, e.g. "1.4.2" (mirrors `device.appVersion`; host-injected). */
+    appVersion?: string;
+    /** Host native build number, e.g. "412" (from `expo-constants` `nativeBuildVersion`). */
+    appBuild?: string;
+    /** Host connectivity signal, e.g. "wifi" | "cellular" (from `@react-native-community/netinfo`). */
+    networkType?: string;
+};
+/** Host-injected inputs for {@link buildContextEnvelope}. All optional; each is omitted when absent. */
+type ContextEnvelopeInput = {
+    sessionId?: string;
+    appVersion?: string;
+    appBuild?: string;
+    networkType?: string;
+};
+/**
+ * Build a fresh context envelope. Reuses `collectDeviceContext()` for the device block and layers
+ * the host-injected scalars on top. `appVersion` is additionally merged onto `device.appVersion`
+ * when the device block lacks it (mirroring how `useSessionStart` back-fills the host version).
+ *
+ * Returns a NEW object on every call (no shared mutable reference), so a caller can hold or mutate
+ * the result without leaking into the next envelope. Never throws — `collectDeviceContext` is
+ * itself guarded, and the rest is plain assignment.
+ */
+declare const buildContextEnvelope: (input?: ContextEnvelopeInput) => ContextEnvelope;
+
+/**
+ * eventQueue — the OFFLINE-FIRST, persistent transport buffer for client analytics events.
+ *
+ * The existing `reportClientEvents` is a blind fire-and-forget POST: it returns `void`, has no
+ * success signal, and drops events when the network is down. The analytics data story depends on
+ * NEVER losing an event offline, so this queue adds the missing durability layer on top of the
+ * same `POST {serverUrl}/v1/events` contract:
+ *
+ *   • Persists pending events to the host-injected `WireOnboardingStorage` (survives app kills).
+ *   • Batches them into one request body `{ events: [...] }`.
+ *   • Owns its OWN awaited `fetch` that reads `res.ok` — the only way to drive retry + dequeue,
+ *     since `reportClientEvents` cannot ack. A 2xx dequeues the batch; a non-ok / rejected / thrown
+ *     response keeps it and schedules an exponential backoff retry.
+ *   • Flushes on `enqueue`, on an explicit `flush()`, and on `notifyOnline()` (host reconnect).
+ *   • Caps the buffer (drop-OLDEST under pressure) and de-dups identical pending events.
+ *   • Stamps the current context envelope (device + host scalars) onto every event before send.
+ *
+ * FIRE-AND-FORGET (load-bearing): `enqueue` returns immediately and NEVER throws into the UI. A
+ * missing `fetch`, a hung/broken storage, a rejecting network, or a JSON error is swallowed and
+ * degrades gracefully — analytics must never be able to break the app. In-memory fallback covers
+ * the no-storage case (survives re-renders, not app kills).
+ *
+ * DEPENDENCY-FREE: no network-detection or persistence library. Connectivity is host-driven via
+ * `notifyOnline()`; persistence is the host-injected AsyncStorage-compatible subset.
+ */
+
+/** Envelope source: a fixed envelope or a provider evaluated at enqueue time (fresh network type). */
+type EnvelopeSource = ContextEnvelope | (() => ContextEnvelope | undefined);
+/** Options for {@link createEventQueue}. Only `target` is conceptually required to actually send. */
+type EventQueueOptions = {
+    /** Where to POST — the tenant transport (`serverUrl` + `apiKey`), same as `WireOnboardingConfig`. */
+    target: ClientEventTarget | undefined;
+    /**
+     * Host persistence (AsyncStorage-compatible subset). When omitted, the queue runs in the
+     * documented DEGRADED in-memory mode — it survives re-renders but not an app kill.
+     */
+    storage?: WireOnboardingStorage;
+    /** Tenant/app id used to namespace the default storage key (`wireai:evtq:<appId>`). */
+    appId?: string;
+    /** Explicit storage key override (wins over the `appId`-derived default). */
+    storageKey?: string;
+    /** The context envelope stamped onto every event before send (device + host scalars). */
+    envelope?: EnvelopeSource;
+    /** Max pending events; enqueuing past this DROPS THE OLDEST first (default 200). */
+    maxSize?: number;
+    /** Events per POST batch (default 20). */
+    batchSize?: number;
+    /** First retry delay in ms; doubles each failed attempt (default 1000). */
+    baseBackoffMs?: number;
+    /** Backoff ceiling in ms (default 30000). */
+    maxBackoffMs?: number;
+    /** Max AUTOMATIC backoff retries before pausing (default 6); `notifyOnline()`/`flush()` re-arm it. */
+    maxRetries?: number;
+};
+/** The queue's public surface. `enqueue` is fire-and-forget (returns immediately, never throws). */
+type EventQueue = {
+    /** Buffer one event (envelope-stamped), persist, and schedule a flush. Never throws. */
+    enqueue(event: ClientEvent): void;
+    /** Attempt an immediate drain of the pending buffer. Fire-and-forget. */
+    flush(): void;
+    /** Host reconnect signal: reset backoff and drain immediately. Fire-and-forget. */
+    notifyOnline(): void;
+    /** Current pending (in-memory) count. */
+    size(): number;
+};
+/**
+ * Create an offline-first event queue. Loads any persisted backlog on creation so a
+ * killed-and-relaunched app resumes where it left off. Returns the {@link EventQueue} surface.
+ */
+declare const createEventQueue: (options: EventQueueOptions) => EventQueue;
+
+export { type AnalyticsEvent as A, type ClientEvent as C, type DeviceContext as D, type EnvelopeSource as E, type OnboardingResult as O, type StepValidator as S, WIRE_ONBOARDING_EVENTS as W, type ClientEventTarget as a, type ClientEventType as b, type ContextEnvelope as c, type ContextEnvelopeInput as d, type EventQueue as e, type EventQueueOptions as f, type WireOnboardingEventName as g, buildContextEnvelope as h, createEventQueue as i, reportClientEvents as j, type WireOnboardingProps as k, type WireOnboardingConfig as l, makeSessionId as m, type OnboardingEvent as n, type OnboardingCopy as o, type DeviceFormFactor as p, type OnboardingProgress as q, reportClientEvent as r, collectDeviceContext as s, toAnalyticsEvent as t };

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-CxKi7Qd5.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-CxKi7Qd5.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-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';
 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 };