@wireai/activation 0.10.0 → 0.11.0

package/dist/{transport-Bzb-bcB2.d.mts → transport-BGW9uXZJ.d.mts}

@@ -1,20 +1,5 @@
 import { k as ReviewTarget, g as ReviewDecisionResponse, j as ReviewSubmission } from './types-CNUqMK0D.mjs';
 
-/**
- * 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 review row)
- *   • fetchReviewDecision  → GET  {serverUrl}/v1/reviews/decision (best-effort, the AI seam)
- *   • 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.
- */
-
 /**
  * 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.

package/dist/{transport-B31G0Cib.d.ts → transport-jUJd5kxu.d.ts}

@@ -1,20 +1,5 @@
 import { k as ReviewTarget, g as ReviewDecisionResponse, j as ReviewSubmission } from './types-Buj9Lw9t.js';
 
-/**
- * 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 review row)
- *   • fetchReviewDecision  → GET  {serverUrl}/v1/reviews/decision (best-effort, the AI seam)
- *   • 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.
- */
-
 /**
  * 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.

package/llms.txt

@@ -23,6 +23,14 @@
 - `attributionMetadata(a)` → shape install/ad attribution into `config.metadata` (forwarded to the agent).
 - `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).
+
+## Subpath surfaces (beyond onboarding)
+
+The package is more than `<WireOnboarding>`. Tree-shakeable subpath exports (each keeps the onboarding UI out of an analytics-only bundle):
+
+- `@wireai/activation/analytics`: `createAnalytics({ serverUrl, apiKey, storage })` (Segment/PostHog-shaped `track` / `screen` / `identify` / `setUserContext` / `reset` over an offline-first queue), `createScreenTracker` / `screenTrackingHandler` (auto screen views), `reportAppEvent`, `createEventQueue`, `clearUserContext` (logout). Rich `WireUserContext` supports an opt-in `userEmail` (raw by default, `hashEmail` to fold) and auto-mints a persisted per-install `device_key`. `identify` refuses email-shaped ids unless `allowEmailAsUserId`. See the README "Rich user context & PII" section.
+- `@wireai/activation/reviews`: the in-app review gate. `useReviewGate`, `fetchReviewDecision` (server AI seam; a `{fire:false}` survives intact), `ReviewGate` UI. `minSessions` defaults to 2 (never prompts on the first session; a server decision still overrides).
+- `@wireai/activation/questionnaire`: the pre-onboarding questionnaire gate. `useQuestionnaireGate`, `fetchQuestionnaireDecision` (same server seam; a body without a boolean `fire` resolves to null, never shows).
 - `useWireActivation({ serverUrl, apiKey, deviceKey? })` → `{ track, sessionId, revalidation }` (ROOT-exported; React-free factory `createWireActivation(config)`). `await track(name, meta?)` POSTs an `app_event` (`question_key=name`) under the current session, resolves `true` on 2xx, and bumps `revalidation`; list `revalidation` in a `fetchReviewDecision` / `fetchQuestionnaireDecision` effect's deps so a review/questionnaire gate re-fetches and fires off an in-app action instead of the host hand-rolling session-id + await-POST + revalidate.
 
 ## Files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.10.0",
+  "version": "0.11.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>",

package/src/analytics/analyticsFacade.ts

@@ -30,9 +30,24 @@ import { buildContextEnvelope, type ContextEnvelope } from "./contextEnvelope";
 import { getCurrentSessionId } from "./currentSession";
 import { createEventQueue, type EventQueue, type EventQueueOptions } from "./eventQueue";
 import { makeSessionId, type ClientEvent } from "./reportClientEvent";
-import { resolveUserContext, type WireUserContext } from "../context/userContext";
+import {
+  analyticsUserIdStorageKey,
+  clearPiiFromContext,
+  resolveUserContext,
+  type WireUserContext,
+} from "../context/userContext";
 import { mintDeviceId, deviceIdStorageKey } from "../context/deviceId";
-import { sanitizeUserId } from "../identity/userIdentity";
+import { looksLikeEmail, sanitizeUserId } from "../identity/userIdentity";
+
+/** RN sets this global; absent under node/SSR. Read defensively via {@link warnInDev}. */
+declare const __DEV__: boolean | undefined;
+
+/** Emit a one-line developer warning, but ONLY in a dev build (RN `__DEV__`). No-op in prod/tests. */
+const warnInDev = (message: string): void => {
+  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+    console.warn(message);
+  }
+};
 
 /** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
 export type AnalyticsProps = Record<string, unknown>;
@@ -76,6 +91,14 @@ export type CreateAnalyticsConfig = {
    * review/questionnaire gating + A/B stickiness. Supply `deviceKey` only to use your OWN id (it wins).
    */
   userContext?: WireUserContext;
+  /**
+   * ESCAPE HATCH for the email-shape guard. By default `identify(id)` and a `setUserContext({ userId })`
+   * REFUSE to bind an id that looks like an email (`local@domain.tld`) and warn in dev — because a
+   * raw email in the opaque `user_id` is a PII leak; an email belongs in the opt-in
+   * `userContext.userEmail` field. Set `true` ONLY if your real internal user id genuinely IS an
+   * email address and you accept it as the pseudonymous key. Default `false` (guard on).
+   */
+  allowEmailAsUserId?: boolean;
 };
 
 /** Optional queue tuning knobs, forwarded verbatim to {@link createEventQueue}. */
@@ -101,6 +124,16 @@ export type Analytics = {
    * binds like {@link identify}. Takes effect on subsequent events. Fire-and-forget.
    */
   setUserContext(partial: Partial<WireUserContext>): void;
+  /**
+   * LOGOUT: unbind the current user so a shared device never attributes user B's events to user A.
+   * Clears the in-memory `boundUserId`, strips the PII / pseudonymous fields (`userId`, `userEmail`,
+   * `extra`) from the bound {@link WireUserContext} (keeping the non-PII `device_key` + `appVersion`,
+   * which group a DEVICE not a user), and removes the persisted `wireai:analytics:userId:<appId>`
+   * key so it cannot be rehydrated on the next launch. Subsequent events are anonymous until the
+   * next `identify` / `setUserContext`. Fire-and-forget; mirrors the `reset()` convention on the
+   * screen tracker. The standalone `clearUserContext({ storage, appId })` covers the `wire` path.
+   */
+  reset(): void;
   /** Attempt an immediate drain of the pending buffer. Fire-and-forget. */
   flush(): void;
   /** Host reconnect signal: reset backoff and drain now. Fire-and-forget. */
@@ -185,7 +218,7 @@ export const createAnalytics = (
   // Per-session, in-memory user binding. Seeded from the init context, then persisted across
   // launches when storage is provided.
   let boundUserId: string | undefined = sanitizeUserId(config.userContext?.userId);
-  const storageKey = `wireai:analytics:userId:${config.appId ?? "default"}`;
+  const storageKey = analyticsUserIdStorageKey(config.appId);
 
   if (config.storage) {
     void config.storage
@@ -217,6 +250,19 @@ export const createAnalytics = (
     if (boundUserId && !event.user_id) event.user_id = boundUserId;
   };
 
+  // Email-shape guard for the OPAQUE user id. A raw email bound as `user_id` is a PII leak (it
+  // belongs in the opt-in `user_context.user_email`), so refuse it and warn in dev — unless the host
+  // opted in via `allowEmailAsUserId`. Returns the id to bind, or `undefined` to refuse.
+  const guardUserId = (clean: string): string | undefined => {
+    if (config.allowEmailAsUserId || !looksLikeEmail(clean)) return clean;
+    warnInDev(
+      "[wireai] identify() was called with an email-shaped id. A raw email must NOT be the opaque " +
+        "user_id (PII leak) — pass it as userContext.userEmail instead. Binding was skipped. Set " +
+        "allowEmailAsUserId:true on createAnalytics if your user id genuinely is an email.",
+    );
+    return undefined;
+  };
+
   const setUserContext = (partial: Partial<WireUserContext>): void => {
     if (!partial || typeof partial !== "object") return;
     // Deep-merge `extra` so a partial update adds keys instead of replacing the whole map.
@@ -226,14 +272,27 @@ export const createAnalytics = (
         : undefined;
     userContext = { ...userContext, ...partial };
     if (mergedExtra) userContext.extra = mergedExtra;
-    // A user id supplied here binds like `identify` so subsequent events carry `user_id`.
+    // A user id supplied here binds like `identify` so subsequent events carry `user_id` — through
+    // the SAME email-shape guard (a raw email must not become the opaque user_id).
     const uid = sanitizeUserId(partial.userId);
     if (uid) {
-      boundUserId = uid;
-      if (config.storage) void config.storage.setItem(storageKey, uid).catch(() => {});
+      const bindable = guardUserId(uid);
+      if (bindable) {
+        boundUserId = bindable;
+        if (config.storage) void config.storage.setItem(storageKey, bindable).catch(() => {});
+      }
     }
   };
 
+  const reset = (): void => {
+    // In-memory binding cleared: subsequent events carry no user_id until the next identify.
+    boundUserId = undefined;
+    // Strip PII from the rich context but keep the device-scope fields (device_key / app_version).
+    userContext = clearPiiFromContext(userContext);
+    // Remove the persisted binding so a relaunch can't rehydrate the previous user's id.
+    if (config.storage) void config.storage.removeItem(storageKey).catch(() => {});
+  };
+
   const track = (event: string, props?: AnalyticsProps): void => {
     if (!event) return;
     const clientEvent: ClientEvent = {
@@ -264,16 +323,19 @@ export const createAnalytics = (
     const clean = sanitizeUserId(userId);
     // Blank / non-string → no binding, no event (sanitizeUserId returns undefined). >128 → truncated.
     if (!clean) return;
-    boundUserId = clean;
+    // Email-shape guard: refuse to bind (and emit) a raw email as the opaque user_id unless opted in.
+    const bindable = guardUserId(clean);
+    if (!bindable) return;
+    boundUserId = bindable;
     if (config.storage) {
-      void config.storage.setItem(storageKey, clean).catch(() => {});
+      void config.storage.setItem(storageKey, bindable).catch(() => {});
     }
     const clientEvent: ClientEvent = {
       event_type: "identify",
       // Reuse the LIVE per-open session id (see `resolveSessionId`) so the server binds identity to
       // the session it already saw instead of back-filling a phantom `session_started`.
       session_id: resolveSessionId(),
-      user_id: clean,
+      user_id: bindable,
     };
     if (traits && Object.keys(traits).length > 0) clientEvent.meta = JSON.stringify(traits);
     applyContext(clientEvent);
@@ -285,6 +347,7 @@ export const createAnalytics = (
     screen,
     identify,
     setUserContext,
+    reset,
     flush: queue.flush,
     notifyOnline: queue.notifyOnline,
     size: queue.size,

package/src/analytics/eventQueue.ts

@@ -24,7 +24,7 @@
  * `notifyOnline()`; persistence is the host-injected AsyncStorage-compatible subset.
  */
 import type { ContextEnvelope } from "./contextEnvelope";
-import type { ClientEvent, ClientEventTarget } from "./reportClientEvent";
+import { buildEventsRequest, type ClientEvent, type ClientEventTarget } from "./reportClientEvent";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 
 /** Envelope source: a fixed envelope or a provider evaluated at enqueue time (fresh network type). */
@@ -161,6 +161,11 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   const stamp = (event: ClientEvent): ClientEvent => {
     const env = resolveEnvelope();
     const stamped: ClientEvent = { ...event };
+    // Client enqueue timestamp: distinguishes a GENUINE repeat (same event fired seconds apart)
+    // from a REDUNDANT re-enqueue of the same instant. The de-dup signature below includes it, so
+    // two identical events enqueued in the same millisecond still collapse (a re-render), while the
+    // same action repeated later carries a fresh `ts` and survives. A caller-set `ts` is preserved.
+    if (stamped.ts === undefined) stamped.ts = Date.now();
     if (!env) return stamped;
     if (!stamped.device && env.device) stamped.device = env.device;
     if (!stamped.session_id && env.sessionId) stamped.session_id = env.sessionId;
@@ -227,19 +232,15 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   // 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;
+    // Build the /v1/events request through the ONE canonical builder (url + headers + body) so this
+    // queue never re-describes the endpoint. The abort-timeout stays: the queue owns retry/dequeue,
+    // so a hung request must be cut loose to schedule a backoff rather than block the drain forever.
+    const req = buildEventsRequest(target, events);
+    if (!req) return false;
     const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
     const timer = setTimeout(() => controller?.abort(), 15_000);
     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 }),
-        signal: controller?.signal,
-      });
+      const res = await fetch(req.url, { ...req.init, signal: controller?.signal });
       return !!(res && (res as { ok?: boolean }).ok);
     } catch {
       return false;

package/src/analytics/index.ts

@@ -64,5 +64,14 @@ export type {
 // ─── The thin optional React hook over the façade ─────────────────────────────
 export { useAnalytics } from "./useAnalytics";
 
+// ─── Logout / reset helpers + the email-shape guard (analytics-focused surface) ─
+export {
+  clearUserContext,
+  clearPiiFromContext,
+  analyticsUserIdStorageKey,
+} from "../context/userContext";
+export type { ClearUserContextOptions } from "../context/userContext";
+export { looksLikeEmail } from "../identity/userIdentity";
+
 // ─── Current per-open session registry (identify/app-events reuse the live session) ───
 export { getCurrentSessionId, setCurrentSessionId, resetCurrentSessionId } from "./currentSession";

package/src/analytics/reportClientEvent.ts

@@ -76,6 +76,16 @@ export type ClientEvent = {
    * Lets the backend reconcile onboarding sessions to real users. Old servers ignore it.
    */
   user_id?: string;
+  /**
+   * Client-stamped epoch-ms timestamp of when the event was ENQUEUED on the device. Optional and
+   * ADDITIVE: the offline queue stamps it at enqueue time (see `createEventQueue`) so two otherwise
+   * byte-identical events fired seconds apart (a genuine repeat, e.g. the user taps "share" twice)
+   * are NOT collapsed by the queue's identical-JSON de-dup — while two truly simultaneous
+   * re-enqueues of the same instant (a redundant re-render) still share a `ts` and collapse. A raw
+   * `Date.now()`, never a wall-clock the server trusts (the server derives its own receive time);
+   * an old/strict server that does not model it simply ignores the unknown field.
+   */
+  ts?: number;
 };
 
 /** Where to POST. Derived from `WireOnboardingConfig` (`serverUrl` + `apiKey`). */
@@ -102,8 +112,8 @@ export const makeSessionId = (): string =>
  * copy of the endpoint path, headers, or envelope shape to drift. Returns `null` when there is
  * nothing to send (no target / no events) or serialization throws, so callers just bail.
  */
-const buildEventsRequest = (
-  target: ClientEventTarget | undefined,
+export const buildEventsRequest = (
+  target: { serverUrl: string; apiKey?: string } | undefined,
   events: ClientEvent[],
 ): { url: string; init: RequestInit } | null => {
   if (!target?.serverUrl || events.length === 0) return null;

package/src/context/userContext.ts

@@ -23,6 +23,7 @@
  * dependency-free FNV-1a fold (see {@link hashEmailFnv1a}) — no crypto library, no async.
  */
 import { sanitizeUserId } from "../identity/userIdentity";
+import type { WireOnboardingStorage } from "../session/persistedSession";
 
 /**
  * The single, extensible user-context object. A host passes it ONCE (at analytics init) and may
@@ -152,6 +153,60 @@ export const namespaceExtra = (
   return out;
 };
 
+/**
+ * The storage key the analytics façade persists the bound opaque `user_id` under (namespaced per
+ * `appId`, mirroring {@link deviceIdStorageKey}). Exported so a logout path can target it directly.
+ */
+export const analyticsUserIdStorageKey = (appId?: string): string =>
+  `wireai:analytics:userId:${appId ?? "default"}`;
+
+/**
+ * Return a COPY of a {@link WireUserContext} with every USER-scoped (PII / pseudonymous) field
+ * removed — `userId`, `userEmail`, `hashEmail`, and `extra` — while KEEPING the non-PII device-scope
+ * fields (`appVersion`, `deviceKey`). This is the in-memory half of logout: after it, the same
+ * analytics instance keeps its stable `device_key` (which groups a DEVICE, not a user) but no longer
+ * stamps the previous user's id/email onto events. Pure; never mutates the input.
+ */
+export const clearPiiFromContext = (ctx: WireUserContext = {}): WireUserContext => {
+  const rest: WireUserContext = {};
+  if (typeof ctx.appVersion === "string") rest.appVersion = ctx.appVersion;
+  if (typeof ctx.deviceKey === "string") rest.deviceKey = ctx.deviceKey;
+  return rest;
+};
+
+/** Options for {@link clearUserContext}. */
+export interface ClearUserContextOptions {
+  /** Host persistence (AsyncStorage subset) — the persisted bound `user_id` is removed from here. */
+  storage?: WireOnboardingStorage;
+  /** Tenant/app id — namespaces the persisted key (`wireai:analytics:userId:<appId>`). */
+  appId?: string;
+}
+
+/**
+ * LOGOUT primitive: purge the persisted, bound opaque `user_id` for an app so the NEXT user on a
+ * shared device is not silently attributed to the previous one. Removes the
+ * `wireai:analytics:userId:<appId>` key that the analytics façade persists and reuses across
+ * launches. Fire-and-forget: a missing storage or a failing adapter resolves quietly.
+ *
+ * COVERAGE. The stateful `createAnalytics(...)` instance also exposes {@link Analytics.reset}, which
+ * does this AND clears the in-memory binding + PII in one call — prefer it when you hold the
+ * instance. This standalone helper covers the `createWireActivation` / `wire` path (whose config is
+ * captured immutably, so it has no `reset`): call `clearUserContext({ storage, appId })` on logout,
+ * and RECREATE the `wire` / analytics instance without the user's `userContext` (userId/userEmail)
+ * so no further events carry the previous user's identity. The non-PII per-install `device_key`
+ * (`wireai:analytics:deviceKey:<appId>`) is intentionally left in place — it groups a device, not a
+ * person, and stays stable across users of the same install.
+ */
+export const clearUserContext = async (opts: ClearUserContextOptions = {}): Promise<void> => {
+  const storage = opts.storage;
+  if (!storage) return;
+  try {
+    await storage.removeItem(analyticsUserIdStorageKey(opts.appId));
+  } catch {
+    /* best-effort, swallow — logout must never throw into the UI */
+  }
+};
+
 /** Options for {@link resolveUserContext}. */
 export interface ResolveUserContextOptions {
   /**

package/src/identity/userIdentity.ts

@@ -44,6 +44,16 @@ export const sanitizeUserId = (raw: unknown): string | undefined => {
   return trimmed.length > USER_ID_MAX_LENGTH ? trimmed.slice(0, USER_ID_MAX_LENGTH) : trimmed;
 };
 
+/**
+ * A permissive email-SHAPE test (`local@domain.tld`) — NOT an RFC validator. Its ONE job is to
+ * catch the common integration mistake of binding a RAW EMAIL as the opaque `user_id`: that leaks
+ * PII into the top-level id (which the server treats as an opaque key and may surface), when the
+ * email belongs in the opt-in `user_context.user_email` field instead. `identify()` uses this to
+ * refuse an email-shaped id (with a dev warning) unless the host opts in explicitly. Trims first.
+ */
+export const looksLikeEmail = (value: unknown): boolean =>
+  typeof value === "string" && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim());
+
 /** Options for {@link identifyOnboarding}. */
 export type IdentifyOnboardingOptions = {
   /** Tenant transport, same shape as `WireOnboardingConfig` (only these two fields are used). */

package/src/index.ts

@@ -141,7 +141,7 @@ export { detectAppVersion } from "./device/appVersion";
 export { detectNativeModel } from "./device/deviceModel";
 
 // ─── User identity (opaque pseudonymous id; late binding, dependency-free) ────
-export { identifyOnboarding, sanitizeUserId, USER_ID_MAX_LENGTH } from "./identity/userIdentity";
+export { identifyOnboarding, sanitizeUserId, looksLikeEmail, USER_ID_MAX_LENGTH } from "./identity/userIdentity";
 export type { IdentifyOnboardingOptions } from "./identity/userIdentity";
 
 // ─── Rich user context (one object → every event's user_context; opt-in email PII) ────
@@ -150,6 +150,9 @@ export {
   namespaceExtra,
   hashEmailFnv1a,
   isWireScalar,
+  clearUserContext,
+  clearPiiFromContext,
+  analyticsUserIdStorageKey,
   RESERVED_USER_CONTEXT_KEYS,
   EXTRA_KEY_PREFIX,
 } from "./context/userContext";
@@ -157,6 +160,7 @@ export type {
   WireUserContext,
   ResolvedUserContext,
   ResolveUserContextOptions,
+  ClearUserContextOptions,
 } from "./context/userContext";
 export { mintDeviceId, deviceIdStorageKey, AUTO_DEVICE_ID_PREFIX } from "./context/deviceId";
 

package/src/questionnaire/transport.ts

@@ -75,7 +75,11 @@ export const fetchQuestionnaireDecision = async (
     const res = await fetch(url, { headers });
     if (!res || !res.ok) return null;
     const json = (await res.json()) as QuestionnaireDecisionResponse | null;
-    return json ?? null;
+    // A body without a boolean `fire` is not a decision. Guard it explicitly (mirrors
+    // `fetchReviewDecision`) rather than letting `{}` through as a truthy object a gate would treat
+    // as a verdict (`{}.fire === undefined` is falsy, so it would silently read as "never fire").
+    if (!json || typeof json.fire !== "boolean") return null;
+    return json;
   } catch {
     /* unreachable / non-2xx / bad JSON / missing-fetch - never show */
     return null;

package/src/reviews/decision.ts

@@ -64,7 +64,14 @@ export const resolveRules = (config: {
   oncePerVersion?: boolean;
 }): GateRules => ({
   enabled: config.enabled ?? true,
-  minSessions: config.minSessions ?? 0,
+  // FAIL-CLOSED on the first session (behavior change, 0.11.0). An unconfigured host with no
+  // server decision must NOT prompt on the very first mount: `minSessions` defaults to 2 so the
+  // gate needs at least a second session before the LOCAL rules can fire. This is the client-side
+  // floor only — a server `decision` (from `fetchReviewDecision`) still OVERRIDES everything, and a
+  // host that genuinely wants first-session prompting can set `minSessions: 1` (or `0`) explicitly.
+  // Mirrors the 2026-07-16 incident: a first-session user, no server decision, got the prompt and
+  // left 1 star. See `evaluateGate` (`min_sessions` reason) and the CHANGELOG.
+  minSessions: config.minSessions ?? 2,
   minEvents: config.minEvents ?? 0,
   cooldownDays: config.cooldownDays ?? 0,
   oncePerVersion: config.oncePerVersion ?? true,

package/src/reviews/transport.ts

@@ -12,6 +12,7 @@
  * 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 { buildEventsRequest, type ClientEvent } from "../analytics/reportClientEvent";
 import type { ReviewDecisionResponse, ReviewSubmission, ReviewTarget } from "./types";
 
 /**
@@ -178,9 +179,6 @@ export const reportAppEvent = (
 ): 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,
@@ -192,11 +190,11 @@ export const reportAppEvent = (
     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(() => {
+    // Route through the ONE canonical /v1/events builder (url + headers + body) instead of
+    // re-describing the endpoint here; still fire-and-forget.
+    const req = buildEventsRequest(target, [event as unknown as ClientEvent]);
+    if (!req) return;
+    void fetch(req.url, req.init).catch(() => {
       /* best-effort, swallow */
     });
   } catch {

package/src/session-analytics/lifecycle.ts

@@ -34,7 +34,7 @@
  * 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 { buildEventsRequest, 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";
@@ -141,16 +141,11 @@ const routeLifecycleEvent = (event: Record<string, unknown>, opts: LifecycleEven
       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(() => {
+    // Route the direct-POST fallback through the ONE canonical /v1/events builder (url + headers +
+    // body) instead of re-describing the endpoint here; still fire-and-forget.
+    const req = buildEventsRequest(opts.target, [event as unknown as ClientEvent]);
+    if (!req) return;
+    void fetch(req.url, req.init).catch(() => {
       // Network/transport error — analytics is best-effort, swallow.
     });
   } catch {

package/src/session-analytics/useLifecycleEvents.ts

@@ -28,7 +28,7 @@ import { useEffect, useRef } from "react";
 import { AppState, Platform, type AppStateStatus } from "react-native";
 
 import { createEventQueue, type EnvelopeSource, type EventQueue } from "../analytics/eventQueue";
-import type { ClientEvent, ClientEventTarget } from "../analytics/reportClientEvent";
+import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
 import { collectDeviceContext } from "../device/deviceContext";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import { reportFirstOpen } from "./lifecycle";
@@ -114,7 +114,45 @@ export const useLifecycleEvents = (
     const targetOf = (cfg: LifecycleConfig | undefined): ClientEventTarget | undefined =>
       cfg?.serverUrl ? { serverUrl: cfg.serverUrl, apiKey: cfg.apiKey ?? "" } : undefined;
 
-    // 1) first_open — once ever (persisted flag + in-memory latch inside reportFirstOpen).
+    // ONE per-open session id for the MOUNT open, shared by first_open AND session_started below.
+    // WHY: `first_open` used to default to its OWN fresh `makeSessionId()` (via `buildLifecycleEvent`)
+    // while `session_started` minted a different one — so every install's `first_open` carried a
+    // session id the server never got a `session_started` for (a PHANTOM session the server
+    // back-filled). Minting one id here and handing it to both makes them agree, so the server sees
+    // `first_open` under the same session it saw `session_started` for. A later foreground open
+    // (below) mints its OWN fresh id — a new open is a new session.
+    const mountOpenSessionId = makeSessionId();
+
+    // session_start — the EXISTING emitter routed through the sink (offline-buffered, one guard).
+    // Accepts the per-open id so the mount open reuses `mountOpenSessionId`; omit it and the emitter
+    // mints a fresh id (a genuinely new open). Either way the once-guard dedupes within the open.
+    const fireSession = (sessionId?: string) => {
+      const { config: cfg, options: opts } = latest.current;
+      if (opts.enabled === false) return;
+      if (!cfg?.serverUrl && !opts.sink) return;
+      const device = collectDeviceContext();
+      // `device.appVersion` is auto-detected best-effort; an explicit host version always wins.
+      if (cfg?.appVersion) device.appVersion = cfg.appVersion;
+      reportSessionStart({
+        target: targetOf(cfg),
+        sink: resolveSink(),
+        sessionId,
+        userId: opts.userId,
+        deviceKey: opts.deviceKey,
+        sessionCount: opts.sessionCount,
+        appVersion: cfg?.appVersion ?? device.appVersion,
+        platform: Platform.OS,
+        device,
+        meta: opts.meta,
+      });
+    };
+
+    // 1) session_start FIRST (mount = an app-open), so the server has ingested `session_started`
+    //    for `mountOpenSessionId` before first_open references the same id.
+    fireSession(mountOpenSessionId);
+
+    // 2) first_open — once ever (persisted flag + in-memory latch inside reportFirstOpen), pinned to
+    //    the SAME per-open id so it is never a phantom session.
     {
       const { config: cfg, options: opts } = latest.current;
       if (opts.enabled !== false) {
@@ -124,6 +162,7 @@ export const useLifecycleEvents = (
         reportFirstOpen({
           target: targetOf(cfg),
           sink: resolveSink(),
+          sessionId: mountOpenSessionId,
           storage: cfg?.storage,
           appId: cfg?.appId,
           userId: opts.userId,
@@ -137,31 +176,6 @@ export const useLifecycleEvents = (
       }
     }
 
-    // 2) session_start — the EXISTING emitter routed through the sink (offline-buffered, one guard).
-    const fireSession = () => {
-      const { config: cfg, options: opts } = latest.current;
-      if (opts.enabled === false) return;
-      if (!cfg?.serverUrl && !opts.sink) return;
-      const device = collectDeviceContext();
-      // `device.appVersion` is auto-detected best-effort; an explicit host version always wins.
-      if (cfg?.appVersion) device.appVersion = cfg.appVersion;
-      reportSessionStart({
-        target: targetOf(cfg),
-        sink: resolveSink(),
-        // A fresh per-open id each fire; the emitter's once-guard dedupes within the open.
-        userId: opts.userId,
-        deviceKey: opts.deviceKey,
-        sessionCount: opts.sessionCount,
-        appVersion: cfg?.appVersion ?? device.appVersion,
-        platform: Platform.OS,
-        device,
-        meta: opts.meta,
-      });
-    };
-
-    // Mount = an app-open.
-    fireSession();
-
     // Foreground after a real background = a new app-open.
     let backgroundedAt: number | null = null;
     const onChange = (state: AppStateStatus) => {