@wireai/activation 0.1.0 → 0.2.0

package/llms.txt

@@ -1,4 +1,4 @@
-# wireai-onboarding
+# @wireai/activation
 
 > A drop-in AI onboarding kit for React Native / Expo. One component, `<WireOnboarding>`, runs an
 > entire backend-orchestrated, AI-driven onboarding flow (themed cards, progress bar, a mid-flow
@@ -8,12 +8,12 @@
 
 ## What an agent needs to know
 
-- **Install:** `npm install wireai-onboarding wireai-rn` (react + react-native are peers).
-- **Metro (required):** `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` from `wireai-onboarding/metro` — pins one copy of react/react-native/wireai-rn/zod (prevents the dual-React crash).
+- **Install:** `npm install @wireai/activation wireai-rn` (react + react-native are peers).
+- **Metro (required):** `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` from `@wireai/activation/metro`, which pins one copy of react/react-native/wireai-rn/zod (prevents the dual-React crash).
 - **Two secrets:** an app `apiKey` (a `wai_…` key that resolves the tenant server-side) and the backend `serverUrl`. Created in the getwireai console or via the backend's `register_<app>.py`. Nothing renders without both.
 - **Render:** drop `<WireOnboarding config={wireConfigFromEnv({ appId })} theme={...} onComplete={persist} fallbackFlow={<YourStaticOnboarding/>} />` into the signup flow.
-- **Capture is deterministic** — `onComplete` returns `{ answers, raw }`; no second LLM call. Persist all answers through the app's normal profile-update path.
-- **It can never break onboarding** — pass `fallbackFlow` (your existing static onboarding) so a backend error/timeout degrades instead of dead-ending.
+- **Capture is deterministic.** `onComplete` returns `{ answers, raw }`; no second LLM call. Persist all answers through the app's normal profile-update path.
+- **It can never break onboarding.** Pass `fallbackFlow` (your existing static onboarding) so a backend error/timeout degrades instead of dead-ending.
 
 ## Helpers (the reusable substrate)
 
@@ -21,7 +21,7 @@
 - `isOnboardingEnabled({ remote? })` → the standard gate (transport present: apiKey + serverUrl). No on/off env flag; `remote` is an optional kill-switch the app passes in.
 - `WIRE_ONBOARDING_EVENTS` + `toAnalyticsEvent(event)` → canonical `wire_onboarding_*` funnel names; log via the app's own analytics.
 - `attributionMetadata(a)` → shape install/ad attribution into `config.metadata` (forwarded to the agent).
-- `reportClientEvent` / `makeSessionId` → report device-only funnel events to `POST /v1/events`. `<WireOnboarding>` does this automatically: `dropped` on unmount-without-complete, `client_fallback` on degrade-to-static. Hosts must not double-report fallback.
+- `reportClientEvent(target, event)` / `reportClientEvents` / `makeSessionId` (ROOT-exported, not a subpath) → report device-only funnel events. Contract: `POST {serverUrl}/v1/events`, header `Authorization: Bearer {apiKey}`, body `{ "events": [ ... ] }`; `target = { serverUrl, apiKey }` from the config. `<WireOnboarding>` does this automatically: `dropped` on unmount-without-complete, `client_fallback` on degrade-to-static. Hosts must not double-report fallback.
 - `deriveAnswers(messages)`, `themeFromBrand({ primary })`, `defaultIllustrations`, `DemoOnboarding` (dev/QA, no account).
 
 ## Files
@@ -33,4 +33,4 @@
 
 ## Fastest path
 
-Run the `wire-rn-integration` Claude skill — it detects the app's conventions, wires Metro, derives a theme, scaffolds the screen, wires a fallback, and type-checks. Otherwise use INTEGRATION_PROMPT.md.
+Run the `wire-rn-integration` Claude skill. It detects the app's conventions, wires Metro, derives a theme, scaffolds the screen, wires a fallback, and type-checks. Otherwise use INTEGRATION_PROMPT.md.

package/metro/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Type declarations for the `wireai-onboarding/metro` helper. This module runs in
+ * Type declarations for the `@wireai/activation/metro` helper. This module runs in
  * Node inside metro.config.js, so the config is loosely typed (`any`-ish) to avoid
  * coupling to a specific Metro/Expo version.
  */
@@ -11,7 +11,7 @@ export interface WithWireOnboardingOptions {
    */
   appRoot?: string;
   /**
-   * Absolute path to the kit's `src/` dir. When set, the `wireai-onboarding`
+   * Absolute path to the kit's `src/` dir. When set, the `@wireai/activation`
    * specifier maps here (source consumption) and the dir is added to watchFolders.
    * When omitted, the kit resolves from the installed package.
    */
@@ -19,7 +19,7 @@ export interface WithWireOnboardingOptions {
 }
 
 /**
- * Non-destructively wire the wireai-onboarding kit into an existing Metro config:
+ * Non-destructively wire the @wireai/activation kit into an existing Metro config:
  * pins single-instance deps to the app's copy, optionally maps the kit specifier
  * to source + watches it. Mutates and returns the same config object.
  */

package/metro/index.js

@@ -1,5 +1,5 @@
 /**
- * withWireOnboarding — one-call Metro wiring for the wireai-onboarding kit.
+ * withWireOnboarding — one-call Metro wiring for the @wireai/activation kit.
  *
  * This file runs in Node inside your app's `metro.config.js` (it is NOT React
  * Native code), so it's plain CommonJS with zero RN imports.
@@ -10,13 +10,13 @@
  *
  *   // External app (kit installed from git/tarball):
  *   const { getDefaultConfig } = require('expo/metro-config');
- *   const { withWireOnboarding } = require('wireai-onboarding/metro');
+ *   const { withWireOnboarding } = require('@wireai/activation/metro');
  *   module.exports = withWireOnboarding(getDefaultConfig(__dirname));
  *
  *   // Source consumer (monorepo app, kit resolved from its src/):
  *   const path = require('path');
  *   module.exports = withWireOnboarding(getDefaultConfig(__dirname), {
- *     source: path.join(__dirname, '../../getwire_ai/wireai-onboarding/src'),
+ *     source: path.join(__dirname, '../../wire-activation/src'),
  *   });
  *
  * @param {object} config  An existing Metro config object (e.g. from getDefaultConfig).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",
@@ -46,6 +46,20 @@
         "default": "./dist/index.js"
       }
     },
+    "./analytics": {
+      "react-native": {
+        "types": "./dist/analytics/index.d.ts",
+        "default": "./src/analytics/index.ts"
+      },
+      "import": {
+        "types": "./dist/analytics/index.d.mts",
+        "default": "./dist/analytics/index.mjs"
+      },
+      "require": {
+        "types": "./dist/analytics/index.d.ts",
+        "default": "./dist/analytics/index.js"
+      }
+    },
     "./coachmarks": {
       "react-native": {
         "types": "./dist/coachmarks/index.d.ts",

package/src/analytics/contextEnvelope.ts

@@ -0,0 +1,72 @@
+/**
+ * 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).
+ */
+import { collectDeviceContext, type DeviceContext } from "../device/deviceContext";
+
+/**
+ * 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.
+ */
+export 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. */
+export 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.
+ */
+export const buildContextEnvelope = (input: ContextEnvelopeInput = {}): ContextEnvelope => {
+  // Fresh copy so the returned envelope never aliases a cached device snapshot.
+  const device: DeviceContext = { ...collectDeviceContext() };
+
+  // Mirror useSessionStart: fill the host app version onto the device block when it lacks one.
+  if (input.appVersion && !device.appVersion) device.appVersion = input.appVersion;
+
+  const envelope: ContextEnvelope = { device };
+  if (input.sessionId) envelope.sessionId = input.sessionId;
+  if (input.appVersion) envelope.appVersion = input.appVersion;
+  if (input.appBuild) envelope.appBuild = input.appBuild;
+  if (input.networkType) envelope.networkType = input.networkType;
+
+  return envelope;
+};

package/src/analytics/eventQueue.ts

@@ -0,0 +1,331 @@
+/**
+ * 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.
+ */
+import type { ContextEnvelope } from "./contextEnvelope";
+import type { ClientEvent, ClientEventTarget } from "./reportClientEvent";
+import type { WireOnboardingStorage } from "../session/persistedSession";
+
+/** Envelope source: a fixed envelope or a provider evaluated at enqueue time (fresh network type). */
+export type EnvelopeSource = ContextEnvelope | (() => ContextEnvelope | undefined);
+
+/** Options for {@link createEventQueue}. Only `target` is conceptually required to actually send. */
+export 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). */
+export 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;
+};
+
+const DEFAULTS = {
+  maxSize: 200,
+  batchSize: 20,
+  baseBackoffMs: 1000,
+  maxBackoffMs: 30000,
+  maxRetries: 6,
+} as const;
+
+/** Ceiling on the persisted-backlog read — a hung adapter degrades to an empty start, never a stall. */
+const READ_TIMEOUT_MS = 1500;
+
+/** Internal buffered item. `id` is a local monotonic handle for deterministic dequeue-after-ack;
+ *  it is NEVER sent to the server. `sig` is the de-dup signature (serialized stamped event). */
+type QueuedItem = { id: number; event: ClientEvent; sig: string };
+
+/** Persisted shape — the local id + the (already envelope-stamped) event. `sig` is recomputed on load. */
+type PersistedItem = { id: number; event: ClientEvent };
+
+const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => resolve(undefined), ms);
+  });
+  return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+};
+
+/** Detach a timer from the event loop where the runtime supports it (Node test process / some RNs). */
+const unrefTimer = (timer: ReturnType<typeof setTimeout>): void => {
+  const t = timer as unknown as { unref?: () => void };
+  if (typeof t.unref === "function") t.unref();
+};
+
+const parsePersisted = (raw: string | null | undefined): PersistedItem[] => {
+  if (!raw) return [];
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    const items: PersistedItem[] = [];
+    for (const entry of parsed) {
+      if (
+        entry &&
+        typeof entry === "object" &&
+        typeof (entry as PersistedItem).id === "number" &&
+        (entry as PersistedItem).event &&
+        typeof (entry as PersistedItem).event === "object"
+      ) {
+        items.push(entry as PersistedItem);
+      }
+    }
+    return items;
+  } catch {
+    // Corrupt backlog → start empty; the next persist overwrites it.
+    return [];
+  }
+};
+
+/**
+ * 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.
+ */
+export const createEventQueue = (options: EventQueueOptions): EventQueue => {
+  const target = options.target;
+  const storage = options.storage;
+  const key = options.storageKey ?? `wireai:evtq:${options.appId ?? "default"}`;
+  const maxSize = options.maxSize ?? DEFAULTS.maxSize;
+  const batchSize = options.batchSize ?? DEFAULTS.batchSize;
+  const baseBackoffMs = options.baseBackoffMs ?? DEFAULTS.baseBackoffMs;
+  const maxBackoffMs = options.maxBackoffMs ?? DEFAULTS.maxBackoffMs;
+  const maxRetries = options.maxRetries ?? DEFAULTS.maxRetries;
+
+  let pending: QueuedItem[] = [];
+  let nextId = 0;
+  let flushing = false;
+  let attempt = 0;
+  let retryTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const resolveEnvelope = (): ContextEnvelope | undefined => {
+    try {
+      return typeof options.envelope === "function" ? options.envelope() : options.envelope;
+    } catch {
+      return undefined;
+    }
+  };
+
+  // Stamp the current envelope onto a COPY of the event (never mutate the caller's object):
+  //   device      → event.device       (when the event has none)
+  //   sessionId   → event.session_id   (when the event has none)
+  //   appVersion / appBuild / networkType → event.user_context (the non-PII bucket the server
+  //   sanitizes), never overwriting a key the caller already set.
+  const stamp = (event: ClientEvent): ClientEvent => {
+    const env = resolveEnvelope();
+    const stamped: ClientEvent = { ...event };
+    if (!env) return stamped;
+    if (!stamped.device && env.device) stamped.device = env.device;
+    if (!stamped.session_id && env.sessionId) stamped.session_id = env.sessionId;
+    const uc: Record<string, string | number | boolean> = { ...(stamped.user_context ?? {}) };
+    if (env.appVersion && uc.app_version === undefined) uc.app_version = env.appVersion;
+    if (env.appBuild && uc.app_build === undefined) uc.app_build = env.appBuild;
+    if (env.networkType && uc.network_type === undefined) uc.network_type = env.networkType;
+    if (Object.keys(uc).length > 0) stamped.user_context = uc;
+    return stamped;
+  };
+
+  const persist = (): void => {
+    if (!storage) return;
+    try {
+      if (pending.length === 0) {
+        void storage.removeItem(key).catch(() => {});
+        return;
+      }
+      const payload: PersistedItem[] = pending.map((item) => ({ id: item.id, event: item.event }));
+      void storage.setItem(key, JSON.stringify(payload)).catch(() => {});
+    } catch {
+      // Best-effort: a failed write just means the backlog is not durable this launch.
+    }
+  };
+
+  const enforceSizeCap = (): void => {
+    // Drop the OLDEST first so the newest events are never the ones lost under pressure.
+    if (pending.length > maxSize) pending.splice(0, pending.length - maxSize);
+  };
+
+  const safeSig = (event: ClientEvent): string => {
+    try {
+      return JSON.stringify(event);
+    } catch {
+      // Non-serializable event → give it a unique signature so it is never wrongly de-duped.
+      return `__nosig_${nextId}_${Math.random()}`;
+    }
+  };
+
+  // Load any persisted backlog. Anything enqueued before this settles stays in memory; we merge
+  // persisted (older) ahead of it and reassign monotonic ids so dequeue-after-ack is deterministic.
+  const loadPromise: Promise<void> = (async () => {
+    if (!storage) return;
+    try {
+      const persistedItems = parsePersisted(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS));
+      if (persistedItems.length === 0) return;
+      const events = [...persistedItems.map((p) => p.event), ...pending.map((p) => p.event)];
+      pending = [];
+      nextId = 0;
+      const seen = new Set<string>();
+      for (const event of events) {
+        const sig = safeSig(event);
+        if (seen.has(sig)) continue; // collapse duplicates carried across the merge
+        seen.add(sig);
+        pending.push({ id: nextId++, event, sig });
+      }
+      enforceSizeCap();
+      persist();
+    } catch {
+      // Unreadable backlog → start empty; nothing enqueued in-memory is lost.
+    }
+  })();
+
+  // The queue's OWN awaited POST. Reads `res.ok` to drive retry/dequeue. NEVER throws — a missing
+  // fetch, a rejecting network, or a JSON error resolves to `false` (batch stays, retry schedules).
+  const postBatch = async (events: ClientEvent[]): Promise<boolean> => {
+    if (!target?.serverUrl || events.length === 0) return false;
+    try {
+      const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
+      const headers: Record<string, string> = { "Content-Type": "application/json" };
+      if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ events }),
+      });
+      return !!(res && (res as { ok?: boolean }).ok);
+    } catch {
+      return false;
+    }
+  };
+
+  const clearRetry = (): void => {
+    if (retryTimer !== undefined) {
+      clearTimeout(retryTimer);
+      retryTimer = undefined;
+    }
+  };
+
+  const scheduleRetry = (): void => {
+    // Bounded automatic retry. Past the cap the backlog simply waits for the next
+    // `notifyOnline()` / `flush()` (both re-arm attempt), so events are paused, never dropped.
+    if (attempt >= maxRetries) return;
+    const delay = Math.min(baseBackoffMs * 2 ** attempt, maxBackoffMs);
+    attempt++;
+    clearRetry();
+    retryTimer = setTimeout(() => {
+      retryTimer = undefined;
+      void drain();
+    }, delay);
+    unrefTimer(retryTimer);
+  };
+
+  const drain = async (): Promise<void> => {
+    try {
+      await loadPromise;
+    } catch {
+      // load already swallows; guard the await defensively.
+    }
+    if (flushing) return;
+    flushing = true;
+    try {
+      while (pending.length > 0) {
+        const batch = pending.slice(0, batchSize);
+        const ok = await postBatch(batch.map((item) => item.event));
+        if (!ok) {
+          scheduleRetry();
+          return;
+        }
+        // Dequeue exactly the acked batch by id (pending may have grown while in flight).
+        const acked = new Set(batch.map((item) => item.id));
+        pending = pending.filter((item) => !acked.has(item.id));
+        persist();
+        attempt = 0;
+        clearRetry();
+      }
+    } finally {
+      flushing = false;
+    }
+  };
+
+  const flush = (): void => {
+    try {
+      void drain();
+    } catch {
+      // drain never throws synchronously, but guard the kick anyway.
+    }
+  };
+
+  const enqueue = (event: ClientEvent): void => {
+    try {
+      const stamped = stamp(event);
+      const sig = safeSig(stamped);
+      // Collapse a redundant re-enqueue of an identical pending event.
+      for (const item of pending) {
+        if (item.sig === sig) return;
+      }
+      pending.push({ id: nextId++, event: stamped, sig });
+      enforceSizeCap();
+      persist();
+      // Only kick a drain when no retry is already pending — avoids hammering fetch while offline.
+      if (retryTimer === undefined) flush();
+    } catch {
+      // Fire-and-forget: nothing in enqueue may surface to the UI.
+    }
+  };
+
+  const notifyOnline = (): void => {
+    // Host reconnected: reset the backoff and drain now.
+    attempt = 0;
+    clearRetry();
+    flush();
+  };
+
+  const size = (): number => pending.length;
+
+  return { enqueue, flush, notifyOnline, size };
+};

package/src/analytics/index.ts

@@ -0,0 +1,47 @@
+/**
+ * @wireai/activation/analytics — the coherent analytics entry.
+ *
+ * Subpath export kept OUT of the main barrel so an analytics-only consumer never pulls in the
+ * onboarding / showcase / review UI (the kit's tree-shaking guarantee). It bundles the OPT-IN
+ * automatic screen-tracking helper with the pre-existing analytics primitives so a host has one
+ * import for "report app + onboarding events":
+ *
+ *   import { createScreenTracker, screenTrackingHandler, reportAppEvent } from "@wireai/activation/analytics";
+ *
+ * The screen-tracking core imports NO navigation library and NO React (the React glue is the thin
+ * `useScreenTracking` hook); `reportAppEvent` is pulled from `../reviews/transport` directly, not
+ * the `../reviews` barrel, to keep the review UI out of an analytics-only bundle.
+ */
+
+// ─── Automatic screen tracking (dependency-free core) ─────────────────────────
+export { createScreenTracker, getActiveRouteName, screenTrackingHandler } from "./screenTracking";
+export type {
+  ScreenTracker,
+  ScreenTrackerOptions,
+  NavigationStateLike,
+  NavigationRouteLike,
+} from "./screenTracking";
+
+// ─── The thin optional React hook over the core ───────────────────────────────
+export { useScreenTracking } from "./useScreenTracking";
+export type { NavigationRefLike } from "./useScreenTracking";
+
+// ─── The app-event transport this helper feeds (pure fetch, no review UI) ─────
+export { reportAppEvent } from "../reviews/transport";
+export type { ReportAppEventOptions } from "../reviews/transport";
+
+// ─── Device-only onboarding event reporters + session id seed ─────────────────
+export { reportClientEvent, reportClientEvents, makeSessionId } from "./reportClientEvent";
+export type { ClientEvent, ClientEventType, ClientEventTarget } from "./reportClientEvent";
+
+// ─── Canonical onboarding funnel names + kit-event mapper ──────────────────────
+export { WIRE_ONBOARDING_EVENTS, toAnalyticsEvent } from "./analyticsEvent";
+export type { WireOnboardingEventName, AnalyticsEvent } from "./analyticsEvent";
+
+// ─── Non-PII context envelope (device + host scalars) stamped onto every event ─
+export { buildContextEnvelope } from "./contextEnvelope";
+export type { ContextEnvelope, ContextEnvelopeInput } from "./contextEnvelope";
+
+// ─── Offline-first, persistent, batched + retried event queue (dependency-free) ─
+export { createEventQueue } from "./eventQueue";
+export type { EventQueue, EventQueueOptions, EnvelopeSource } from "./eventQueue";