@wireai/activation 0.1.0 → 0.2.0

package/src/analytics/screenTracking.ts

@@ -0,0 +1,122 @@
+/**
+ * screenTracking — an OPT-IN, dependency-free automatic screen-view helper.
+ *
+ * Given the host app's navigation STATE (or a nav ref, via the useScreenTracking hook), this
+ * emits exactly ONE `screen` app-event per REAL screen change through the kit's existing
+ * `reportAppEvent` transport (`POST {serverUrl}/v1/events`, `event_type='app_event'`,
+ * `question_key='screen'`, `meta={ screen }`). Param-only changes and re-renders are de-duped
+ * away because we resolve and compare the route NAME only — never the params.
+ *
+ * Dependency-free core: this file imports NO navigation library. React-Navigation / expo-router
+ * are host concerns; the host supplies plain state objects and refs, typed structurally here
+ * (`NavigationStateLike`). It is also React-free — the optional React glue lives in
+ * `useScreenTracking.ts`. `reportAppEvent` is imported from the pure `../reviews/transport`
+ * module (NOT the `../reviews` barrel, which would drag the review UI into an analytics-only
+ * bundle and defeat tree-shaking).
+ *
+ * Privacy: only the route NAME ever leaves the device. Route params, query strings, and any
+ * user data are never read into the event. Fire-and-forget — this never throws into the UI.
+ */
+import { reportAppEvent } from "../reviews/transport";
+
+/** A single route inside a React-Navigation-shaped state (structural — no `@react-navigation`). */
+export interface NavigationRouteLike {
+  name: string;
+  /** A nested navigator's own state, when this route hosts one. */
+  state?: NavigationStateLike;
+  /** Route params are intentionally left `unknown` — this helper never reads them. */
+  params?: unknown;
+}
+
+/** A React-Navigation-shaped navigator state (structural type; no library import). */
+export interface NavigationStateLike {
+  /** Index of the active route within `routes`. */
+  index?: number;
+  routes?: NavigationRouteLike[];
+}
+
+/** Options for {@link createScreenTracker}. */
+export interface ScreenTrackerOptions {
+  /**
+   * Where to POST. `{ serverUrl, apiKey }` — same shape the kit's review/analytics config
+   * exposes. When omitted, the tracker still de-dups and fires `onScreen`, but sends nothing.
+   */
+  target?: { serverUrl: string; apiKey: string };
+  /** The onboarding/session id to correlate screen views with, when known. */
+  sessionId?: string;
+  /** A stable, non-PII device id — groups a device's sessions server-side. */
+  deviceKey?: string;
+  /** Called on every REAL screen change (after de-dup), before the network emit. */
+  onScreen?: (screen: string) => void;
+  /**
+   * Per-screen filter. Return `false` to skip the NETWORK emit for a screen (last-screen memory
+   * is still advanced + `onScreen` still fires) — e.g. to keep a sensitive route out of analytics.
+   */
+  shouldTrack?: (screen: string) => boolean;
+}
+
+/** The screen tracker returned by {@link createScreenTracker}. */
+export interface ScreenTracker {
+  /** Report the active screen. Ignores `undefined`/empty and de-dups repeats of the last screen. */
+  track: (screen: string | undefined) => void;
+  /** Clear the last-screen memory (e.g. on logout) so the next `track` always emits. */
+  reset: () => void;
+}
+
+/**
+ * Walk a React-Navigation-shaped state to the DEEPEST active route and return its NAME (never
+ * its params). Recurses `routes[index]` while a nested `.state` exists. Returns `undefined` for
+ * a missing/empty/malformed state — the caller treats that as "nothing to report".
+ */
+export const getActiveRouteName = (
+  state: NavigationStateLike | undefined,
+): string | undefined => {
+  let current: NavigationStateLike | undefined = state;
+  let name: string | undefined;
+  // Bounded by the finite nesting depth of a real navigator tree.
+  while (current && Array.isArray(current.routes) && current.routes.length > 0) {
+    const index = typeof current.index === "number" ? current.index : 0;
+    const route = current.routes[index];
+    if (!route) break;
+    name = route.name;
+    current = route.state;
+  }
+  return name;
+};
+
+/**
+ * Build a stateful screen tracker. `track` de-dups against the last reported screen so only a
+ * REAL change emits; `reset` clears that memory. Fire-and-forget throughout — a missing `target`
+ * skips the network but keeps the de-dup + `onScreen` behaviour intact.
+ */
+export const createScreenTracker = (options: ScreenTrackerOptions = {}): ScreenTracker => {
+  let lastScreen: string | undefined;
+  return {
+    track: (screen: string | undefined): void => {
+      if (!screen || screen === lastScreen) return;
+      lastScreen = screen;
+      options.onScreen?.(screen);
+      if (options.shouldTrack && !options.shouldTrack(screen)) return;
+      reportAppEvent(options.target, "screen", {
+        sessionId: options.sessionId,
+        deviceKey: options.deviceKey,
+        meta: { screen },
+      });
+    },
+    reset: (): void => {
+      lastScreen = undefined;
+    },
+  };
+};
+
+/**
+ * Adapt a tracker into a React-Navigation `onStateChange` handler — the one-place wiring:
+ *
+ *   <NavigationContainer onStateChange={screenTrackingHandler(tracker)}>
+ *
+ * It resolves the deepest active route name and hands it to `tracker.track` (which de-dups).
+ */
+export const screenTrackingHandler =
+  (tracker: ScreenTracker) =>
+  (state: NavigationStateLike | undefined): void =>
+    tracker.track(getActiveRouteName(state));

package/src/analytics/useScreenTracking.ts

@@ -0,0 +1,48 @@
+/**
+ * useScreenTracking — a THIN optional React hook over the pure screen-tracking core.
+ *
+ * It builds one tracker for the component's lifetime and subscribes to the host's navigation
+ * ref: it reports the current route on mount and on every `state` event, and unsubscribes on
+ * unmount. React is a REQUIRED peer of the kit, so importing it here is allowed; the hook adds
+ * NO navigation-library dependency — the ref is typed structurally (`NavigationRefLike`).
+ *
+ *   const navigationRef = useNavigationContainerRef(); // host's @react-navigation ref
+ *   useScreenTracking(navigationRef, { target, sessionId });
+ *   // ...<NavigationContainer ref={navigationRef}>
+ */
+import { useEffect, useRef } from "react";
+
+import { createScreenTracker, type ScreenTracker, type ScreenTrackerOptions } from "./screenTracking";
+
+/**
+ * The structural slice of a React-Navigation container ref this hook needs — no
+ * `@react-navigation` import. `getCurrentRoute` yields the active route; `addListener("state", …)`
+ * fires on every navigation state change and returns its own unsubscribe.
+ */
+export interface NavigationRefLike {
+  getCurrentRoute?: () => { name?: string } | undefined;
+  addListener?: (type: "state", callback: () => void) => () => void;
+}
+
+/**
+ * Subscribe screen tracking to a host navigation ref. Safe to call with a not-yet-ready ref
+ * (the effect no-ops until `addListener` exists). Returns nothing — it wires side effects only.
+ */
+export const useScreenTracking = (
+  navigationRef: NavigationRefLike | undefined,
+  options: ScreenTrackerOptions = {},
+): void => {
+  // One tracker per mount; kept in a ref so re-renders never rebuild the de-dup memory.
+  const trackerRef = useRef<ScreenTracker | undefined>(undefined);
+  if (!trackerRef.current) trackerRef.current = createScreenTracker(options);
+
+  useEffect(() => {
+    const tracker = trackerRef.current;
+    if (!tracker || !navigationRef?.addListener) return;
+    const report = (): void => tracker.track(navigationRef.getCurrentRoute?.()?.name);
+    report(); // initial screen on mount
+    const unsubscribe = navigationRef.addListener("state", report);
+    return unsubscribe;
+    // Re-subscribe only when the ref identity changes; option changes are read live off the closure.
+  }, [navigationRef]);
+};

package/src/coachmarks/index.ts

@@ -1,5 +1,5 @@
 /**
- * wireai-onboarding/coachmarks — the performance-first guided-tour engine.
+ * @wireai/activation/coachmarks — the performance-first guided-tour engine.
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-
  * free: importing this pulls in the optional peers `react-native-reanimated` and
@@ -9,7 +9,7 @@
  *
  *   import {
  *     CoachmarkProvider, useCoachmarkAnchor, useCoachmarkTour,
- *   } from "wireai-onboarding/coachmarks";
+ *   } from "@wireai/activation/coachmarks";
  */
 
 // ─── Root provider (mount once, around the NavigationContainer) ───────────────

package/src/features/WireFeaturesProvider.tsx

@@ -9,7 +9,7 @@
  *
  * NOTE on the built npm subpaths: React context is shared across the kit's subpath entries in the
  * SOURCE-consumption path (the monorepo apps) and in this test suite — one module instance, one
- * context. If you consume the built `wireai-onboarding/*` subpaths as separate bundles, pass the
+ * context. If you consume the built `@wireai/activation/*` subpaths as separate bundles, pass the
  * resolved flags (or a `featuresConfig`) to each surface explicitly instead of relying on context.
  */
 import React, { createContext, useContext, useMemo } from "react";

package/src/features/index.ts

@@ -1,12 +1,12 @@
 /**
- * wireai-onboarding feature controls — the per-module dashboard kill switches, consumed by the
+ * @wireai/activation feature controls — the per-module dashboard kill switches, consumed by the
  * kit with a HARD fail-open contract (a control-plane outage can never dark your app).
  *
  * These live in the CORE barrel (dependency-free: types + fetch + a React hook/provider). The
  * GATING is wired into the three client surfaces (coachmarks / showcase / reviews); onboarding
  * mode is server-owned, so the kit needs no gating there.
  *
- *   import { WireFeaturesProvider, fetchWireFeatures } from "wireai-onboarding";
+ *   import { WireFeaturesProvider, fetchWireFeatures } from "@wireai/activation";
  */
 export { fetchWireFeatures } from "./fetchWireFeatures";
 export { useWireFeatures } from "./useWireFeatures";

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * wireai-onboarding — premium, themable drop-in onboarding kit on top of the
+ * @wireai/activation — premium, themable drop-in onboarding kit on top of the
  * open-source wireai-rn SDK. Public surface.
  */
 
@@ -136,6 +136,23 @@ export type {
   UseSessionStartOptions,
 } from "./session-analytics";
 
+// ─── Lifecycle events (top-of-funnel: `app.first_open` once-ever + session_start) ──
+export {
+  reportFirstOpen,
+  wireLifecycleEvents,
+  resetFirstOpenLatch,
+  firstOpenStorageKey,
+  FIRST_OPEN_EVENT,
+  useLifecycleEvents,
+} from "./session-analytics";
+export type {
+  ReportFirstOpenOptions,
+  WireLifecycleOptions,
+  LifecycleEventInput,
+  LifecycleConfig,
+  UseLifecycleEventsOptions,
+} from "./session-analytics";
+
 // ─── Session persistence (host-injected storage; see the `storage` prop) ──────
 export {
   loadPersistedSession,

package/src/questionnaire/index.ts

@@ -1,5 +1,5 @@
 /**
- * wireai-onboarding/questionnaire - the skippable pre-onboarding questionnaire popup.
+ * @wireai/activation/questionnaire - the skippable pre-onboarding questionnaire popup.
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-free. The gate
  * asks one mandatory question ("what do you think about the app") plus two optional boxes,
@@ -8,7 +8,7 @@
  * at most once per user per questionnaire id. It reuses the shared `CenteredModal` shell (never
  * importing reviews/ internals for UI).
  *
- *   import { QuestionnaireGate, useQuestionnaireGate } from "wireai-onboarding/questionnaire";
+ *   import { QuestionnaireGate, useQuestionnaireGate } from "@wireai/activation/questionnaire";
  */
 
 // ─── The popup UI ───────────────────────────────────────────────────────────────

package/src/reviews/index.ts

@@ -1,5 +1,5 @@
 /**
- * wireai-onboarding/reviews — the in-app review sentiment gate.
+ * @wireai/activation/reviews — the in-app review sentiment gate.
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-free:
  * importing this pulls in the OPTIONAL peer `expo-store-review` (loaded lazily and only on
@@ -7,7 +7,7 @@
  * review and 1-4 to a feather-light feedback form POSTed to the Wire server, and decides
  * WHEN to show via local rules OR a server-provided decision (the AI seam).
  *
- *   import { ReviewGate, useReviewGate } from "wireai-onboarding/reviews";
+ *   import { ReviewGate, useReviewGate } from "@wireai/activation/reviews";
  */
 
 // ─── The gate UI ──────────────────────────────────────────────────────────────

package/src/session-analytics/index.ts

@@ -16,3 +16,23 @@ export type { ReportSessionStartOptions } from "./reportSessionStart";
 
 export { useSessionStart, BACKGROUND_SESSION_MS } from "./useSessionStart";
 export type { SessionStartConfig, UseSessionStartOptions } from "./useSessionStart";
+
+// ─── Top-of-funnel lifecycle events (first_open once-ever + session_start reused) ──
+export {
+  reportFirstOpen,
+  wireLifecycleEvents,
+  resetFirstOpenLatch,
+  firstOpenStorageKey,
+  FIRST_OPEN_EVENT,
+} from "./lifecycle";
+export type {
+  ReportFirstOpenOptions,
+  WireLifecycleOptions,
+  LifecycleEventInput,
+} from "./lifecycle";
+
+export { useLifecycleEvents } from "./useLifecycleEvents";
+export type {
+  LifecycleConfig,
+  UseLifecycleEventsOptions,
+} from "./useLifecycleEvents";

package/src/session-analytics/lifecycle.ts

@@ -0,0 +1,236 @@
+/**
+ * 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.
+ */
+import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
+import type { DeviceContext } from "../device/deviceContext";
+import { sanitizeUserId } from "../identity/userIdentity";
+import type { WireOnboardingStorage } from "../session/persistedSession";
+import { reportSessionStart, SESSION_STARTED_EVENT } from "./reportSessionStart";
+
+/** 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. */
+export const FIRST_OPEN_EVENT = "app.first_open" as const;
+
+/** Storage key for the once-ever first-open flag, e.g. `wireai:first_open:myelino`. Mirrors the
+ *  `wireai:<concern>:<appId>` namespacing of {@link sessionStorageKey}. */
+export const firstOpenStorageKey = (appId: string): string => `wireai:first_open:${appId}`;
+
+/** Ceiling on the flag read — a hung adapter degrades to the in-memory latch, never a stuck gate. */
+const READ_TIMEOUT_MS = 1_500;
+
+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));
+};
+
+// ── First-open in-memory latch ───────────────────────────────────────────────
+// Covers TWO cases the persisted flag can't: (1) two near-simultaneous calls in one process (the
+// flag read is async, so a synchronous latch is what guarantees at-most-one before any await), and
+// (2) the documented DEGRADED no-storage mode (fires once per process). Keyed by appId.
+const _firstOpenLatched = new Set<string>();
+
+/** Test-only: forget the first-open latch so a unit test starts from a clean process state. */
+export const resetFirstOpenLatch = (): void => {
+  _firstOpenLatched.clear();
+};
+
+/** 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. */
+export 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). */
+export 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;
+}
+
+/**
+ * Build the `app_event` payload shared by `app.first_open` and `app.session_started`. This is a
+ * BYTE-FOR-BYTE mirror of the field logic in {@link reportSessionStart} — same `event_type`, same
+ * `question_key`-as-name contract, same `user_context` bucket, same optional fields — so the two
+ * lifecycle events are one contract with two names. Do NOT let these diverge (see lifecycle.test).
+ */
+const buildLifecycleEvent = (questionKey: string, opts: LifecycleEventInput): Record<string, unknown> => {
+  const userContext: Record<string, string | number | boolean> = {};
+  if (opts.deviceKey) userContext.device_key = opts.deviceKey;
+  if (typeof opts.sessionCount === "number" && Number.isFinite(opts.sessionCount)) {
+    userContext.session_count = opts.sessionCount;
+    userContext.returning = opts.sessionCount > 1;
+  }
+  if (opts.appVersion) userContext.app_version = opts.appVersion;
+  if (opts.platform) userContext.platform = opts.platform;
+
+  const event: Record<string, unknown> = {
+    event_type: "app_event",
+    question_key: questionKey,
+    session_id: opts.sessionId ?? makeSessionId(),
+  };
+  const userId = sanitizeUserId(opts.userId);
+  if (userId) event.user_id = userId;
+  if (Object.keys(userContext).length > 0) event.user_context = userContext;
+  if (opts.device) event.device = opts.device;
+  if (opts.meta && Object.keys(opts.meta).length > 0) event.meta = JSON.stringify(opts.meta);
+  return event;
+};
+
+/** Route a built event to the wired sink, else a direct fire-and-forget POST. Never throws. */
+const routeLifecycleEvent = (event: Record<string, unknown>, opts: LifecycleEventInput): void => {
+  try {
+    if (opts.sink) {
+      opts.sink(event as ClientEvent);
+      return;
+    }
+    const target = opts.target;
+    if (!target?.serverUrl) return;
+    const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
+    void fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ events: [event] }),
+    }).catch(() => {
+      // Network/transport error — analytics is best-effort, swallow.
+    });
+  } catch {
+    // A throwing sink, URL/JSON error, or a missing fetch — swallow.
+  }
+};
+
+const emitFirstOpen = (opts: ReportFirstOpenOptions): void => {
+  routeLifecycleEvent(buildLifecycleEvent(FIRST_OPEN_EVENT, opts), opts);
+};
+
+/**
+ * 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).
+ */
+export const reportFirstOpen = (opts: ReportFirstOpenOptions): void => {
+  const appId = opts.appId ?? "default";
+
+  // Synchronous latch FIRST: guarantees at-most-one before any await (same-process race guard) and
+  // is the sole guard in the no-storage degraded mode.
+  if (_firstOpenLatched.has(appId)) return;
+  _firstOpenLatched.add(appId);
+
+  const storage = opts.storage;
+  if (!storage) {
+    // Degraded: no persistence to survive a kill → the latch fires it once per process.
+    emitFirstOpen(opts);
+    return;
+  }
+
+  const key = firstOpenStorageKey(appId);
+  void (async () => {
+    try {
+      const seen = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
+      // A prior launch already fired + wrote the flag → once-ever satisfied, no-op.
+      if (seen) return;
+      emitFirstOpen(opts);
+      try {
+        // Best-effort persist: a failed write just means the next launch may re-fire once.
+        void storage.setItem(key, JSON.stringify({ ts: Date.now() })).catch(() => {});
+      } catch {
+        // Missing/broken storage write — swallow.
+      }
+    } catch {
+      // Unreadable flag → the in-memory latch still caps us at one fire this process.
+      emitFirstOpen(opts);
+    }
+  })();
+};
+
+/** Options for {@link wireLifecycleEvents}: the shared lifecycle inputs + first-open persistence. */
+export 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.
+ */
+export const wireLifecycleEvents = (opts: WireLifecycleOptions): void => {
+  reportFirstOpen(opts);
+  reportSessionStart({
+    target: opts.target,
+    sink: opts.sink,
+    sessionId: opts.sessionId,
+    userId: opts.userId,
+    deviceKey: opts.deviceKey,
+    sessionCount: opts.sessionCount,
+    appVersion: opts.appVersion,
+    platform: opts.platform,
+    device: opts.device,
+    meta: opts.meta,
+  });
+};
+
+// Re-exported so callers wiring lifecycle events have the session name alongside the first-open one.
+export { SESSION_STARTED_EVENT };

package/src/session-analytics/reportSessionStart.ts

@@ -31,7 +31,7 @@
  * awaits, and swallows a missing target / bad URL / missing fetch / network error. Analytics must
  * never be able to break the app.
  */
-import { makeSessionId, type ClientEventTarget } from "../analytics/reportClientEvent";
+import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
 import type { DeviceContext } from "../device/deviceContext";
 import { sanitizeUserId } from "../identity/userIdentity";
 
@@ -68,6 +68,15 @@ export 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;
 }
 
 // ── Once-per-open guard ──────────────────────────────────────────────────────
@@ -89,7 +98,9 @@ export const resetSessionStartGuard = (): void => {
  */
 export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
   const target = opts.target;
-  if (!target?.serverUrl) return;
+  // A wired sink is a valid transport on its own — it owns the target (the queue's serverUrl), so
+  // this emitter needs its own `target` ONLY for the direct-fetch fallback.
+  if (!opts.sink && !target?.serverUrl) return;
 
   const sessionId = opts.sessionId ?? makeSessionId();
 
@@ -105,10 +116,6 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
   }
 
   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}`;
-
     // Non-PII correlation bucket. device_key is read by the server to group a device's sessions;
     // session_count / returning / app_version / platform feed per-user retention analytics.
     const userContext: Record<string, string | number | boolean> = {};
@@ -131,6 +138,19 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
     if (opts.device) event.device = opts.device;
     if (opts.meta && Object.keys(opts.meta).length > 0) event.meta = JSON.stringify(opts.meta);
 
+    // Preferred transport: an injected sink (the offline-first event queue's `enqueue`), which
+    // buffers + persists + retries. The once-guard above already ran, so this stays the single
+    // session emitter with a single guard — now durable.
+    if (opts.sink) {
+      opts.sink(event as ClientEvent);
+      return;
+    }
+
+    // Fallback: this emitter's own direct POST when no sink is wired.
+    if (!target?.serverUrl) return;
+    const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
     void fetch(url, {
       method: "POST",
       headers,
@@ -139,6 +159,6 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
       // Network/transport error — analytics is best-effort, swallow.
     });
   } catch {
-    // URL construction, JSON serialization, or a missing fetch — swallow.
+    // URL construction, JSON serialization, a throwing sink, or a missing fetch — swallow.
   }
 };