@wireai/activation 0.1.0

package/src/reviews/runtime.ts

@@ -0,0 +1,45 @@
+/**
+ * Runtime helpers for the review gate: the `wire_review_*` gate keys and small
+ * typed storage accessors. The gate reuses the SAME injected sync storage + global
+ * testing flag as the coachmark engine (see coachmarks/runtime), so a host that
+ * mounted CoachmarkProvider gets review gating for free — no second storage to wire.
+ */
+import type { CoachmarkStorage } from "../coachmarks/types";
+import { getCoachmarkStorage } from "../coachmarks/runtime";
+
+/** Once-gate key. Keyed by app version when `oncePerVersion` is on, so a new release re-enables. */
+export const reviewSeenKey = (id: string, version?: string): string =>
+  version ? `wire_review_${id}_${version}_seen` : `wire_review_${id}_seen`;
+
+/** Last-shown timestamp key (epoch ms), for the cooldown rule. */
+export const reviewLastShownKey = (id: string): string => `wire_review_${id}_last`;
+
+/** Session-count key, incremented once per gate mount, for the min-sessions rule. */
+export const reviewSessionsKey = (id: string): string => `wire_review_${id}_sessions`;
+
+/** Resolve the storage to use: an explicit override, else the provider-injected singleton. */
+export const resolveStorage = (
+  override?: CoachmarkStorage | null,
+): CoachmarkStorage | null => override ?? getCoachmarkStorage();
+
+/** Read an integer from sync storage (0 on a missing/unparseable/throwing read). */
+export const readInt = (storage: CoachmarkStorage | null, key: string): number => {
+  if (!storage) return 0;
+  try {
+    const raw = storage.getItem(key);
+    const n = raw == null ? 0 : parseInt(raw, 10);
+    return Number.isFinite(n) ? n : 0;
+  } catch {
+    return 0;
+  }
+};
+
+/** Write an integer to sync storage. Best-effort — a throwing adapter never breaks the gate. */
+export const writeInt = (storage: CoachmarkStorage | null, key: string, value: number): void => {
+  if (!storage) return;
+  try {
+    storage.setItem(key, String(value));
+  } catch {
+    // Best-effort.
+  }
+};

package/src/reviews/storeReview.ts

@@ -0,0 +1,62 @@
+/**
+ * storeReview.ts — the 5-star route: ask for a native in-app review, or fall back to
+ * opening the store listing.
+ *
+ * `expo-store-review` is an OPTIONAL peer, loaded lazily via a guarded dynamic import so
+ * the core kit never depends on it. When present + available, we call
+ * `StoreReview.requestReview()` (the OS decides whether to actually show the dialog — it is
+ * quota'd, ~3/year on iOS, and NEVER guaranteed). When absent/unavailable, we open the
+ * configured store URL as a graceful fallback. Both paths are best-effort and never throw.
+ *
+ * Store-policy: call this ONLY on the honest 5-star path, from a NEUTRAL prompt — never a
+ * button labeled "rate us 5 stars". See the README store-policy notes.
+ */
+import { Linking, Platform } from "react-native";
+
+import type { ReviewStoreConfig } from "./types";
+
+/** The store deep-link for the current platform, or null if none is configured. */
+export const storeUrl = (store: ReviewStoreConfig | undefined): string | null => {
+  if (!store) return null;
+  if (Platform.OS === "ios" && store.iosAppId) {
+    return `itms-apps://itunes.apple.com/app/id${store.iosAppId}?action=write-review`;
+  }
+  if (Platform.OS === "android" && store.androidPackage) {
+    return `market://details?id=${store.androidPackage}`;
+  }
+  return store.storeUrl ?? null;
+};
+
+/** Open the configured store listing. Best-effort; resolves false if there was nothing to open. */
+export const openStoreListing = async (
+  store: ReviewStoreConfig | undefined,
+): Promise<boolean> => {
+  const url = storeUrl(store);
+  if (!url) return false;
+  try {
+    await Linking.openURL(url);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Request the native in-app review when the optional peer is available; otherwise open the
+ * store listing. Returns the path taken so the caller can fire the right analytics.
+ */
+export const requestStoreReview = async (
+  store?: ReviewStoreConfig,
+): Promise<"native" | "store_url" | "none"> => {
+  try {
+    const mod = await import("expo-store-review");
+    if (mod && (await mod.isAvailableAsync())) {
+      await mod.requestReview();
+      return "native";
+    }
+  } catch {
+    // Peer not installed or the native call failed — fall through to the URL fallback.
+  }
+  const opened = await openStoreListing(store);
+  return opened ? "store_url" : "none";
+};

package/src/reviews/transport.ts

@@ -0,0 +1,89 @@
+/**
+ * transport.ts — kit → Wire server requests for the review module, all fire-and-forget
+ * (analytics/reviews must never break the app). Mirrors analytics/reportClientEvent: a
+ * thin fetch wrapper, Bearer tenant key, swallow every error.
+ *
+ *   • submitReview        → POST {serverUrl}/v1/reviews   (the 1-4 feedback body)
+ *   • reportAppEvent      → POST {serverUrl}/v1/events    (generic app.* namespace)
+ *
+ * `reportAppEvent` is the strategic extension: it lets a host report arbitrary in-app
+ * events through the SAME transport (stored server-side as event_type='app_event',
+ * question_key=<name>), which is what the backend review-firing rules evaluate on — and
+ * it seeds the broader app-analytics stream. Keep payloads minimal + non-PII.
+ */
+import type { ReviewSubmission, ReviewTarget } from "./types";
+
+/**
+ * POST a review (the 1-4 feedback path). Fire-and-forget: a missing target, a build error,
+ * a missing `fetch`, or a network failure is swallowed and the call returns immediately.
+ */
+export const submitReview = (
+  target: ReviewTarget | undefined,
+  review: ReviewSubmission,
+): void => {
+  if (!target?.serverUrl) return;
+  try {
+    const url = `${target.serverUrl.replace(/\/$/, "")}/v1/reviews`;
+    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(review),
+    }).catch(() => {
+      /* best-effort, swallow */
+    });
+  } catch {
+    /* URL/JSON/missing-fetch — swallow */
+  }
+};
+
+/** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */
+export interface ReportAppEventOptions {
+  /** The onboarding/session id to correlate with, when known. */
+  sessionId?: string;
+  /** A stable, non-PII device id — the review-decision endpoint reads it for min-sessions. */
+  deviceKey?: string;
+  /** Small non-PII extras. */
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Report a generic in-app event through the existing events transport. Stored server-side
+ * as `event_type='app_event'`, `question_key=<name>`. Fire-and-forget. Keep `name` a short
+ * stable identifier and `meta` small + non-PII.
+ *
+ *   reportAppEvent(target, "content_share", { sessionId, deviceKey });
+ */
+export const reportAppEvent = (
+  target: ReviewTarget | undefined,
+  name: string,
+  options: ReportAppEventOptions = {},
+): void => {
+  if (!target?.serverUrl || !name) return;
+  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 event: Record<string, unknown> = {
+      event_type: "app_event",
+      question_key: name,
+    };
+    if (options.sessionId) event.session_id = options.sessionId;
+    // device_key rides in the non-PII user_context bucket the server sanitizes; the
+    // review-decision endpoint reads it to group a device's sessions.
+    if (options.deviceKey) event.user_context = { device_key: options.deviceKey };
+    if (options.meta && Object.keys(options.meta).length > 0) {
+      event.meta = JSON.stringify(options.meta);
+    }
+    void fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ events: [event] }),
+    }).catch(() => {
+      /* best-effort, swallow */
+    });
+  } catch {
+    /* swallow */
+  }
+};

package/src/reviews/types.ts

@@ -0,0 +1,172 @@
+/**
+ * Shared types for the in-app review module (the sentiment gate).
+ *
+ * The gate asks a neutral question ("How's your experience?"), the user taps 1-5 stars,
+ * and the module routes: 5 stars to the native store review, 1-4 stars to a feather-light
+ * feedback form whose text is POSTed to the Wire server. WHEN the gate shows is decided by
+ * local rules OR a server-provided decision (the AI seam). Dependency-free type surface.
+ */
+import type { CoachmarkStorage } from "../coachmarks/types";
+import type { WireFeatures, WireFeaturesConfig } from "../features/types";
+
+/**
+ * The firing verdict — the SAME contract on both sides of the seam. `decideReview`
+ * turns local rules into one of these; a server `{fire, reason}` (from
+ * GET /v1/reviews/decision) is the exact same shape and OVERRIDES the local one.
+ */
+export interface ReviewDecision {
+  fire: boolean;
+  reason?: string;
+}
+
+/** Where to route a rating: 5 stars → the store, 1-4 → the feedback form. */
+export type RatingRoute = "store" | "feedback";
+
+/**
+ * Configurable store targets for the 5-star fallback path (used when the native
+ * `expo-store-review` peer is absent or unavailable). At least one is recommended.
+ */
+export interface ReviewStoreConfig {
+  /** Apple App Store numeric app id → itms-apps review deep link. */
+  iosAppId?: string;
+  /** Android package name → market:// details link. */
+  androidPackage?: string;
+  /** An explicit fallback URL (used when the platform-specific target is absent). */
+  storeUrl?: string;
+}
+
+/** Local firing rules — v1 of the decision, overridden by a server decision when present. */
+export interface ReviewConfig {
+  /** Gate key. Seen/last-shown/session keys derive from it (`wire_review_<id>_*`). */
+  id: string;
+  /** Master local switch. Default true. */
+  enabled?: boolean;
+  /** Require at least this many sessions on the device before showing. Default 0. */
+  minSessions?: number;
+  /** Require at least this many tracked app events before showing. Default 0. */
+  minEvents?: number;
+  /** Suppress a re-prompt within this many days of the last shown. Default 0 (off). */
+  cooldownDays?: number;
+  /** Show at most once per app version (seen-gate keyed by `appVersion`). Default true. */
+  oncePerVersion?: boolean;
+  /** The current app version, for the once-per-version seen gate. */
+  appVersion?: string;
+  /**
+   * Client fallback ONLY: if no server decision arrives within this many ms of mount,
+   * fall back to the local rules. Null/absent → evaluate local rules immediately.
+   */
+  timeoutFallbackMs?: number | null;
+}
+
+/** The four analytics moments, mirrored on the coachmark callback convention (no PII). */
+export type ReviewGateEventName =
+  | "review_prompt_shown"
+  | "review_rating_selected"
+  | "store_review_requested"
+  | "review_feedback_submitted";
+
+/** One analytics moment. `stars` is present on `review_rating_selected`; never any free text. */
+export interface ReviewGateEvent {
+  name: ReviewGateEventName;
+  /** The gate id (`config.id`). */
+  id: string;
+  /** The chosen rating, on `review_rating_selected`. */
+  stars?: number;
+}
+
+/** The POST body sent to `POST /v1/reviews` (mirrors the server `CreateReviewRequest`). */
+export interface ReviewSubmission {
+  stars: number;
+  /** The optional "why this rating" answer (the free-text opinion box). */
+  feedback_text?: string;
+  /** The optional "what can you suggest" answer (the smaller suggestion box). */
+  suggestion?: string;
+  contact?: string;
+  session_id?: string;
+  source?: string;
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * How the prompt is presented:
+ *   • "modal"  (default) — a centered popup: dimmed backdrop, card in the middle of the
+ *     screen, spring/fade entrance. What Malik asked for after the bottom-anchored inline
+ *     card rendered half-hidden.
+ *   • "inline" — the bare card, positioned by wherever the host mounts it (the legacy path).
+ */
+export type ReviewPresentation = "modal" | "inline";
+
+/** Where kit → server requests go (same tenant creds as the onboarding flow). */
+export interface ReviewTarget {
+  /** Base server URL (same as `WireOnboardingConfig.serverUrl`). */
+  serverUrl: string;
+  /** Tenant API key, sent as `Authorization: Bearer`. */
+  apiKey: string;
+}
+
+/** Props for the `ReviewGate` sentiment-gate component. */
+export interface ReviewGateProps {
+  /** App name, woven into the neutral prompt ("Enjoying <app>?"). */
+  appName?: string;
+  /** Store targets for the 5-star fallback path when the native peer is unavailable. */
+  store?: ReviewStoreConfig;
+  /** Where to POST a 1-4 feedback submission. Omit to skip the network (callbacks still fire). */
+  target?: ReviewTarget;
+  /** The onboarding/session id correlated with the review, when known. */
+  sessionId?: string;
+  /** Small non-PII extras stored with the review (e.g. device_key, app_version). */
+  meta?: Record<string, unknown>;
+  /** Fired at each analytics moment (host wires it to its own analytics). No PII. */
+  onEvent?: (event: ReviewGateEvent) => void;
+  /** Called once the gate is resolved (rated + routed, or dismissed). */
+  onResolved?: () => void;
+  /** Called when the gate first renders to the user (also fires `review_prompt_shown`). */
+  onShown?: () => void;
+  /** Partial theme merged over the active onboarding theme. */
+  theme?: Partial<import("../theme/types").OnboardingTheme>;
+  /** Show a Skip/Not now control. Default true (never a dead end). */
+  dismissible?: boolean;
+  /**
+   * How the prompt renders. Default "modal" — a centered popup over a dimmed backdrop with
+   * a spring/fade entrance. Pass "inline" for the legacy host-positioned bare card.
+   */
+  presentation?: ReviewPresentation;
+  /** The gate id, forwarded onto emitted events. */
+  id?: string;
+}
+
+/** Options for `useReviewGate` — the WHEN decision. */
+export interface UseReviewGateOptions {
+  config: ReviewConfig;
+  /** Server-provided decision (from GET /v1/reviews/decision). OVERRIDES local rules. */
+  decision?: ReviewDecision;
+  /** Current tracked app-event count (host-owned), for the `minEvents` rule. */
+  events?: number;
+  /** Sync gate storage. Defaults to the storage injected by CoachmarkProvider. */
+  storage?: CoachmarkStorage | null;
+  /** Testing override; defaults to the global `isTestingCoachmark` flag. */
+  isTesting?: boolean;
+  /**
+   * OPTIONAL feature-flag wiring — the review MASTER switch. When `flags.review.enabled` is false,
+   * the gate NEVER fires (`visible` stays false, verdict reason `feature_disabled`), whatever the
+   * local rules or a server decision say — it composes as an extra AND on top of the decision seam.
+   * Provide pre-resolved `features`, OR a `featuresConfig` to lazily fetch once, OR mount a
+   * `WireFeaturesProvider` above (context is read automatically). Omit all three and reviews stay
+   * on (fail-open), gated only by the existing rules.
+   */
+  features?: WireFeatures;
+  /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
+  featuresConfig?: WireFeaturesConfig;
+}
+
+/** What `useReviewGate` returns. */
+export interface ReviewGateController {
+  /** Whether the gate should be shown right now. */
+  visible: boolean;
+  /** The resolved verdict (local rules or the server override). For debugging/analytics. */
+  decision: ReviewDecision;
+  /** Persist the last-shown timestamp. Call when the gate becomes visible. */
+  markShown: () => void;
+  /** Write the once-per-version seen gate. Call when the gate is resolved. */
+  markResolved: () => void;
+}

package/src/reviews/useReviewGate.ts

@@ -0,0 +1,137 @@
+/**
+ * useReviewGate — owns WHEN the review gate shows.
+ *
+ * v1 decision = local rules from `config` (enabled / minSessions / minEvents / cooldownDays
+ * / oncePerVersion), evaluated against the same injected sync storage as the coachmark
+ * engine (`wire_review_*` keys). The AI seam: pass a server-provided `decision` and it
+ * OVERRIDES the local rules (see decideReview). The whole cost of being AI-ready is passing
+ * that object straight through.
+ *
+ * Fallback chain (matches the server design): (1) a server `decision` wins immediately;
+ * (2) no decision → after `timeoutFallbackMs` the local rules take over; (3) the once-gate
+ * (`wire_review_<id>_seen`) always applies locally, so a server bug can never spam the prompt.
+ * The global `isTestingCoachmark` flag force-shows the gate for QA replay.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import { hasSeenGate, isCoachmarkTesting, markSeenGate } from "../coachmarks/runtime";
+import { useResolvedFeatures } from "../features/WireFeaturesProvider";
+import { decideReview, evaluateGate, resolveRules } from "./decision";
+import { sameDecision, shallowEqual } from "./equality";
+import {
+  readInt,
+  resolveStorage,
+  reviewLastShownKey,
+  reviewSeenKey,
+  reviewSessionsKey,
+  writeInt,
+} from "./runtime";
+import type {
+  ReviewDecision,
+  ReviewGateController,
+  UseReviewGateOptions,
+} from "./types";
+
+/**
+ * Hold a stable reference for a value while its CONTENT is unchanged. Integrators
+ * pass inline `config` / `decision` objects (idiomatic React) whose identity flips
+ * every render; feeding those straight into the deps below would recompute the
+ * verdict — and mint a fresh verdict object — on every render, which loops any host
+ * that lists the returned verdict in its own effect. Comparing by value here keeps
+ * the reference (and everything derived from it) stable across identity-only churn.
+ */
+const useStableValue = <T,>(value: T, isEqual: (a: T, b: T) => boolean): T => {
+  const ref = useRef(value);
+  if (!isEqual(ref.current, value)) ref.current = value;
+  return ref.current;
+};
+
+export const useReviewGate = ({
+  config: configProp,
+  decision: decisionProp,
+  events = 0,
+  storage,
+  isTesting,
+  features,
+  featuresConfig,
+}: UseReviewGateOptions): ReviewGateController => {
+  // Tolerate inline-identity props: only adopt a new reference on a real value change.
+  const config = useStableValue(configProp, shallowEqual);
+  const decision = useStableValue(
+    decisionProp,
+    (a, b) => sameDecision(a, b),
+  );
+
+  // The review MASTER switch. Disabled → the gate never fires, composing as an extra AND over
+  // the local rules + the server decision seam below (fail-open: defaults to enabled).
+  const featureEnabled = useResolvedFeatures({ flags: features, config: featuresConfig }).review.enabled;
+
+  const testing = isTesting ?? isCoachmarkTesting();
+  const seenKey = reviewSeenKey(config.id, config.oncePerVersion === false ? undefined : config.appVersion);
+  const lastKey = reviewLastShownKey(config.id);
+  const sessionsKey = reviewSessionsKey(config.id);
+
+  // Read (and bump) the session counter ONCE per mount: this mount is a new session.
+  const sessions = useState(() => {
+    const store = resolveStorage(storage);
+    const next = readInt(store, sessionsKey) + 1;
+    writeInt(store, sessionsKey, next);
+    return next;
+  })[0];
+
+  // Gate the local rules behind an optional client-side timeout, so a reachable server
+  // gets a window to answer first. A present `decision` bypasses the wait entirely.
+  const hasServerDecision = decision != null;
+  const timeoutMs = config.timeoutFallbackMs;
+  const waits = !hasServerDecision && timeoutMs != null && timeoutMs > 0;
+  const [elapsed, setElapsed] = useState(!waits);
+  useEffect(() => {
+    if (!waits) {
+      setElapsed(true);
+      return;
+    }
+    const timer = setTimeout(() => setElapsed(true), timeoutMs as number);
+    return () => clearTimeout(timer);
+  }, [waits, timeoutMs]);
+
+  const { visible, verdict } = useMemo(() => {
+    // Master kill switch wins over everything, including QA replay: a tenant that turned reviews
+    // OFF must never see the gate, whatever the rules, the server decision, or testing say.
+    if (!featureEnabled) return { visible: false, verdict: { fire: false, reason: "feature_disabled" } as ReviewDecision };
+
+    // QA replay: force-show, bypassing rules + gates (safe: only via __DEV__ && bool).
+    if (testing) return { visible: true, verdict: { fire: true, reason: "testing" } as ReviewDecision };
+
+    const store = resolveStorage(storage);
+    const local = evaluateGate(resolveRules(config), {
+      sessions,
+      events,
+      lastShownAt: readInt(store, lastKey) || null,
+      seen: hasSeenGate(seenKey, storage, isTesting),
+      now: Date.now(),
+    });
+    const resolved = decideReview(local, decision);
+    // (3) the once-gate always wins locally, even over a server "fire".
+    const alreadySeen = hasSeenGate(seenKey, storage, isTesting);
+    const ready = hasServerDecision || elapsed;
+    return { visible: ready && resolved.fire && !alreadySeen, verdict: resolved };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [featureEnabled, testing, config, decision, events, sessions, elapsed, hasServerDecision, seenKey, lastKey, storage, isTesting]);
+
+  // Stable callbacks + a stable controller object, so a host can safely list any of
+  // them in its own effect deps without the effect re-firing every render.
+  const shownRef = useRef(false);
+  const markShown = useCallback(() => {
+    if (shownRef.current) return;
+    shownRef.current = true;
+    writeInt(resolveStorage(storage), lastKey, Date.now());
+  }, [storage, lastKey]);
+  const markResolved = useCallback(() => {
+    markSeenGate(seenKey, storage, isTesting);
+  }, [seenKey, storage, isTesting]);
+
+  return useMemo<ReviewGateController>(
+    () => ({ visible, decision: verdict, markShown, markResolved }),
+    [visible, verdict, markShown, markResolved],
+  );
+};

package/src/session/persistedSession.ts

@@ -0,0 +1,143 @@
+/**
+ * Session-id persistence — the kit caching its OWN correlation seed across app kills.
+ *
+ * WHY: the session id is minted per mount and forwarded to the backend as the A2A
+ * `contextId` (see WireOnboarding). Without persistence, an app KILL mid-onboarding
+ * mints a NEW id on relaunch — the server counts a second `session_started` and the
+ * orphaned first session reads as a phantom "drop", inflating the funnel's `started`
+ * denominator. Persisting `{ id, ts }` and reusing a still-fresh id keeps a
+ * kill-and-relaunch a SINGLE session in analytics.
+ *
+ * SCOPE: this persists the correlation seed ONLY — never answers. Answer persistence
+ * stays a host concern via `onComplete` (the kit/host boundary is unchanged).
+ *
+ * The host injects the storage via the `storage` prop (an AsyncStorage-compatible
+ * subset), keeping the kit dependency-free: an MMKV wrapper and AsyncStorage itself
+ * both fit. Every operation is best-effort — a broken or hung storage must NEVER
+ * break (or indefinitely gate) onboarding: reads race a short timeout, writes and
+ * removes swallow all errors.
+ */
+import { makeSessionId } from "../analytics/reportClientEvent";
+
+/**
+ * The storage the host injects. Deliberately the AsyncStorage-compatible subset so
+ * `@react-native-async-storage/async-storage` can be passed as-is, and an MMKV (or
+ * any other) wrapper is three one-line methods.
+ */
+export type WireOnboardingStorage = {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+};
+
+/**
+ * Matches the backend's session TTL (SESSION_TTL_SECONDS = 3600): an id older than
+ * this can't be resumed server-side anyway, so the client mints fresh past it.
+ */
+export const DEFAULT_SESSION_TTL_MS = 3_600_000;
+
+/** Ceiling on the storage read — a hung adapter degrades to a fresh mint, never a stuck gate. */
+const READ_TIMEOUT_MS = 1_500;
+
+/** Storage key for an app's cached session, e.g. `wireai:session:myelino`. */
+export const sessionStorageKey = (appId: string): string => `wireai:session:${appId}`;
+
+type PersistedSession = { id: string; ts: number };
+
+/** Resolved session for a mount: the id to use + whether it was restored from storage. */
+export type LoadedSession = {
+  id: string;
+  /** True when a stored, still-fresh id was reused — the flow resumes instead of starting. */
+  resumed: boolean;
+};
+
+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);
+  });
+  // Clear the timer once the race settles, so a won read doesn't leave a ≤ms no-op
+  // timer holding the closure alive.
+  return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+};
+
+const parsePersisted = (raw: string | null | undefined): PersistedSession | undefined => {
+  if (!raw) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      typeof (parsed as PersistedSession).id === "string" &&
+      typeof (parsed as PersistedSession).ts === "number"
+    ) {
+      return parsed as PersistedSession;
+    }
+  } catch {
+    // Corrupt entry → treat as absent; the caller mints fresh and overwrites it.
+  }
+  return undefined;
+};
+
+/**
+ * Resolve the session id for this mount: reuse the stored one while it's fresh
+ * (→ `resumed: true`), else mint via `makeSessionId`, persist it, and start clean.
+ * Never throws; never hangs past the read timeout.
+ */
+export const loadPersistedSession = async (
+  storage: WireOnboardingStorage,
+  key: string,
+  ttlMs: number = DEFAULT_SESSION_TTL_MS,
+): Promise<LoadedSession> => {
+  let stored: PersistedSession | undefined;
+  try {
+    stored = parsePersisted(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS));
+  } catch {
+    stored = undefined;
+  }
+  if (stored && Date.now() - stored.ts < ttlMs) {
+    return { id: stored.id, resumed: true };
+  }
+  const id = makeSessionId();
+  savePersistedSession(storage, key, id);
+  return { id, resumed: false };
+};
+
+/**
+ * Read the persisted session WITHOUT minting a fresh one (unlike `loadPersistedSession`).
+ * Returns the stored `{ id, ts }` or `undefined` when absent/corrupt/timed-out. Used by the
+ * post-onboarding `identifyOnboarding` helper to recover the contextId to bind a user to.
+ * Never throws; never hangs past the read timeout.
+ */
+export const peekPersistedSession = async (
+  storage: WireOnboardingStorage,
+  key: string,
+): Promise<{ id: string; ts: number } | undefined> => {
+  try {
+    return parsePersisted(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS));
+  } catch {
+    return undefined;
+  }
+};
+
+/** Persist `{ id, ts }` under `key` — fire-and-forget, all errors swallowed. */
+export const savePersistedSession = (
+  storage: WireOnboardingStorage,
+  key: string,
+  id: string,
+): void => {
+  try {
+    void storage.setItem(key, JSON.stringify({ id, ts: Date.now() })).catch(() => {});
+  } catch {
+    // Best-effort: a failed write just means the next launch starts a fresh session.
+  }
+};
+
+/** Remove the cached id (fired on completion) — fire-and-forget, all errors swallowed. */
+export const clearPersistedSession = (storage: WireOnboardingStorage, key: string): void => {
+  try {
+    void storage.removeItem(key).catch(() => {});
+  } catch {
+    // Best-effort.
+  }
+};

package/src/session-analytics/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Session-analytics barrel — session mapping for "the user opened the app again".
+ *
+ * The plain emitter (`reportSessionStart`) is dependency-free and lives in the CORE barrel too;
+ * the `useSessionStart` hook (React + AppState) is the batteries-included option. Both post the
+ * SAME `app.session_started` event into the stream the console/decision engines already read, so
+ * questionnaire firing (`min_count` / `min_sessions`) and per-user retention analytics come for
+ * free with ZERO server changes. See the README "Session mapping" section.
+ */
+export {
+  reportSessionStart,
+  resetSessionStartGuard,
+  SESSION_STARTED_EVENT,
+} from "./reportSessionStart";
+export type { ReportSessionStartOptions } from "./reportSessionStart";
+
+export { useSessionStart, BACKGROUND_SESSION_MS } from "./useSessionStart";
+export type { SessionStartConfig, UseSessionStartOptions } from "./useSessionStart";