@wireai/activation 0.1.0 → 0.2.0

package/dist/decision-plDEOCkt.d.ts

@@ -0,0 +1,79 @@
+import { c as ReviewDecision, i as ReviewSubmission, e as RatingRoute } from './types-BhpXJGlg.js';
+
+/**
+ * decision.ts — the pure decision logic for the review gate.
+ *
+ * `decideReview` is the AI seam, mirroring `selectTourSteps` exactly: ONE function that
+ * turns an optional injected decision into the live verdict. No injected decision → the
+ * local rules stand; a server decision present → it OVERRIDES them. Building the seam now
+ * is the whole cost of being AI-ready: today the host passes local rules only; later the
+ * Wire server computes `{fire, reason}` from the onboarding learnings and the host passes
+ * it straight in — zero app changes.
+ *
+ *   // v1 (local rules only)
+ *   const verdict = decideReview(evaluateGate(rules, signals));
+ *
+ *   // AI on (server-provided decision wins)
+ *   const verdict = decideReview(evaluateGate(rules, signals), serverDecision);
+ *
+ * `evaluateGate`, `routeRating`, and `buildReviewSubmission` are pure so the gate logic
+ * is verifiable in isolation (the kit has no test runner; correctness lives in these).
+ */
+
+/**
+ * The seam. `decision` absent → the local verdict stands; present → it overrides.
+ * Same contract philosophy as `selectTourSteps(catalog, selection?)`.
+ */
+declare const decideReview: (local: ReviewDecision, decision?: ReviewDecision) => ReviewDecision;
+/** The signals the local rules evaluate against (read from injected sync storage + host). */
+interface GateSignals {
+    /** Sessions observed on this device (incl. the current one). */
+    sessions: number;
+    /** Tracked app events observed (host-owned). */
+    events: number;
+    /** Epoch ms of the last time the gate was shown, or null if never. */
+    lastShownAt: number | null;
+    /** Whether the once-per-version gate is already satisfied. */
+    seen: boolean;
+    /** Current epoch ms (injected so the function stays pure). */
+    now: number;
+}
+/** The resolved local rules (defaults applied). */
+interface GateRules {
+    enabled: boolean;
+    minSessions: number;
+    minEvents: number;
+    cooldownDays: number;
+    oncePerVersion: boolean;
+}
+/** Fill a partial `ReviewConfig` with the rule defaults. */
+declare const resolveRules: (config: {
+    enabled?: boolean;
+    minSessions?: number;
+    minEvents?: number;
+    cooldownDays?: number;
+    oncePerVersion?: boolean;
+}) => GateRules;
+/**
+ * Deterministic v1 local decision. Order: disabled → once-gate → min-sessions →
+ * min-events → cooldown → fire. Reasons mirror the server evaluator's vocabulary.
+ */
+declare const evaluateGate: (rules: GateRules, s: GateSignals) => ReviewDecision;
+/**
+ * Route a rating. 5 stars → the native store review; 1-4 → the feedback form. The
+ * sentiment question itself is neutral — this is the ONLY place 5 is treated specially,
+ * never a button labeled "rate us 5 stars" (see the store-policy notes in the README).
+ */
+declare const routeRating: (stars: number) => RatingRoute;
+/** Build the `POST /v1/reviews` body. Feedback text/contact belong ONLY here, never in events. */
+declare const buildReviewSubmission: (input: {
+    stars: number;
+    feedbackText?: string;
+    suggestion?: string;
+    contact?: string;
+    sessionId?: string;
+    source?: string;
+    meta?: Record<string, unknown>;
+}) => ReviewSubmission;
+
+export { type GateRules as G, type GateSignals as a, buildReviewSubmission as b, routeRating as c, decideReview as d, evaluateGate as e, resolveRules as r };

package/dist/eventQueue-CxKi7Qd5.d.mts

@@ -0,0 +1,546 @@
+import * as React from 'react';
+import * as wireai_rn from 'wireai-rn';
+import { Message } from 'wireai-rn';
+import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
+import { b as WireOnboardingStorage } from './types-CMuOexw0.mjs';
+import { Platform } from 'react-native';
+
+/**
+ * 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;
+
+/** 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;
+};
+
+/**
+ * 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;
+
+/**
+ * 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 };