@wireai/activation 0.10.0 → 0.12.0

package/src/reviews/transport.ts

@@ -12,6 +12,8 @@
  * 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 { ensureCurrentSessionId } from "../analytics/currentSession";
+import { buildEventsRequest, type ClientEvent } from "../analytics/reportClientEvent";
 import type { ReviewDecisionResponse, ReviewSubmission, ReviewTarget } from "./types";
 
 /**
@@ -156,7 +158,11 @@ export const fetchReviewDecision = async (
 
 /** 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. */
+  /**
+   * The onboarding/session id to correlate with, when known. Optional: when omitted the event
+   * still carries the CURRENT per-open session id (`ensureCurrentSessionId()`), because an event
+   * with no `session_id` is dropped server-side behind a 200. Pass one only to override.
+   */
   sessionId?: string;
   /** A stable, non-PII device id — the review-decision endpoint reads it for min-sessions. */
   deviceKey?: string;
@@ -170,6 +176,16 @@ export interface ReportAppEventOptions {
  * stable identifier and `meta` small + non-PII.
  *
  *   reportAppEvent(target, "content_share", { sessionId, deviceKey });
+ *
+ * ── `session_id` IS NON-NEGOTIABLE ON THE WIRE ───────────────────────────────────────────
+ * The server's event model declares `session_id` required + non-empty, and `POST /v1/events`
+ * validates per event inside a try/except that counts the failure as `skipped` and STILL returns
+ * HTTP 200. An event sent without a `session_id` is therefore accepted and discarded, and a
+ * fire-and-forget caller never finds out. This used to be reachable through the ordinary API:
+ * `options.sessionId` was optional, so a host calling `reportAppEvent(target, "screen", { deviceKey })`
+ * posted every screen view into that hole. So the id is no longer conditional — an explicit
+ * `sessionId` wins, otherwise the CURRENT per-open id is used (minted + registered if no app-open
+ * has been registered yet).
  */
 export const reportAppEvent = (
   target: ReviewTarget | undefined,
@@ -178,25 +194,26 @@ 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}`;
+    // An explicit id wins; a missing OR BLANK one falls back to the current per-open id. A bare
+    // `??` would let `sessionId: ""` through, and the server rejects an empty string exactly like
+    // a missing key (`min_length=1`), so the blank case has to fall back too.
+    const supplied = options.sessionId ?? "";
     const event: Record<string, unknown> = {
       event_type: "app_event",
       question_key: name,
+      session_id: supplied.trim().length > 0 ? supplied : ensureCurrentSessionId(),
     };
-    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(() => {
+    // 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/reviews/useReviewGate.ts

@@ -19,10 +19,12 @@ import { useResolvedFeatures } from "../features/WireFeaturesProvider";
 import { decideReview, evaluateGate, resolveRules } from "./decision";
 import { sameDecision, shallowEqual } from "./equality";
 import {
+  bumpSessionCount,
   readInt,
   resolveStorage,
   reviewLastShownKey,
   reviewSeenKey,
+  reviewSessionOpenKey,
   reviewSessionsKey,
   writeInt,
 } from "./runtime";
@@ -70,14 +72,17 @@ export const useReviewGate = ({
   const seenKey = reviewSeenKey(config.id, config.oncePerVersion === false ? undefined : config.appVersion);
   const lastKey = reviewLastShownKey(config.id);
   const sessionsKey = reviewSessionsKey(config.id);
+  const sessionOpenKey = reviewSessionOpenKey(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];
+  // Read (and bump) the app-open counter. IDEMPOTENT per app-open, NOT per mount: `bumpSessionCount`
+  // keys off the live per-open session id (or a per-process id when no host wired the lifecycle
+  // events), so a remount, a navigation return, or React StrictMode's dev double-invoke of this
+  // initializer all read the same number back instead of inflating it. Before this, `sessions`
+  // counted mounts, so the fail-closed `minSessions: 2` default could be satisfied inside the user's
+  // very first app open — the exact scenario it was added to prevent.
+  const sessions = useState(() =>
+    bumpSessionCount(resolveStorage(storage), sessionsKey, sessionOpenKey),
+  )[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.

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 {
@@ -217,11 +212,18 @@ export interface WireLifecycleOptions extends ReportFirstOpenOptions {}
  * Route both through the same `sink` (the offline queue) to buffer them. Fire-and-forget.
  */
 export const wireLifecycleEvents = (opts: WireLifecycleOptions): void => {
-  reportFirstOpen(opts);
+  // ONE per-open id for BOTH events when the caller supplies none. Without this, `reportFirstOpen`
+  // fell through to `buildLifecycleEvent`'s own `makeSessionId()` while `reportSessionStart` minted a
+  // DIFFERENT one — so `app.first_open` carried a session id the server never saw a `session_started`
+  // for and back-filled into a phantom session, inflating session counts. `useLifecycleEvents` already
+  // pinned this (it mints `mountOpenSessionId`); the React-free entry point did not, so the identical
+  // bug was still reachable from the documented non-hook path.
+  const sessionId = opts.sessionId ?? makeSessionId();
+  reportFirstOpen({ ...opts, sessionId });
   reportSessionStart({
     target: opts.target,
     sink: opts.sink,
-    sessionId: opts.sessionId,
+    sessionId,
     userId: opts.userId,
     deviceKey: opts.deviceKey,
     sessionCount: opts.sessionCount,

package/src/session-analytics/reportSessionStart.ts

@@ -32,7 +32,12 @@
  * never be able to break the app.
  */
 import { setCurrentSessionId } from "../analytics/currentSession";
-import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
+import {
+  makeSessionId,
+  warnOnSkippedEvents,
+  type ClientEvent,
+  type ClientEventTarget,
+} from "../analytics/reportClientEvent";
 import type { DeviceContext } from "../device/deviceContext";
 import { sanitizeUserId } from "../identity/userIdentity";
 
@@ -162,9 +167,15 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
       method: "POST",
       headers,
       body: JSON.stringify({ events: [event] }),
-    }).catch(() => {
-      // Network/transport error — analytics is best-effort, swallow.
-    });
+    })
+      .then((res) => {
+        // A 200 can still carry `skipped:N` — the server took the request and threw the event away.
+        // Log-only; this path has nothing to retry either way.
+        warnOnSkippedEvents(res);
+      })
+      .catch(() => {
+        // Network/transport error — analytics is best-effort, swallow.
+      });
   } catch {
     // URL construction, JSON serialization, a throwing sink, or a missing fetch — swallow.
   }

package/src/session-analytics/useLifecycleEvents.ts

@@ -28,7 +28,8 @@ 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 { resolveAutoDeviceKey } from "../context/deviceId";
 import { collectDeviceContext } from "../device/deviceContext";
 import type { WireOnboardingStorage } from "../session/persistedSession";
 import { reportFirstOpen } from "./lifecycle";
@@ -114,7 +115,70 @@ 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).
+    /**
+     * The `device_key` these lifecycle events ride under. A host-supplied id always wins.
+     *
+     * WHY THE FALLBACK EXISTS: `min_sessions` (the review / questionnaire firing rule, and the
+     * "fire on the user's Nth session" recipe in the README) is computed SERVER-SIDE by counting
+     * distinct `app.session_started` events grouped by `user_context.device_key`. A host that took
+     * the batteries-included path and passed no `deviceKey` emitted those events with NO device key
+     * at all — while its `createAnalytics` / `createWireActivation` events carried an auto-minted
+     * one. Two disjoint identity spaces again: the counter the rule reads could never increase, so
+     * `min_sessions` was structurally unsatisfiable and the gate never fired from the server side.
+     *
+     * ONLY WITH `storage`: the auto id is per-INSTALL only when it can be persisted. With no
+     * storage it would be per-LAUNCH, which would make every open look like a brand-new device and
+     * corrupt `min_sessions` in the other direction. So no storage → no fallback, same as before.
+     */
+    const resolveDeviceKey = (
+      cfg: LifecycleConfig | undefined,
+      opts: UseLifecycleEventsOptions,
+    ): string | undefined => {
+      const host = typeof opts.deviceKey === "string" && opts.deviceKey.trim() ? opts.deviceKey : undefined;
+      if (host) return host;
+      if (!cfg?.storage) return undefined;
+      return resolveAutoDeviceKey({ appId: cfg.appId, storage: cfg.storage });
+    };
+
+    // 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: resolveDeviceKey(cfg, opts),
+        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,10 +188,11 @@ export const useLifecycleEvents = (
         reportFirstOpen({
           target: targetOf(cfg),
           sink: resolveSink(),
+          sessionId: mountOpenSessionId,
           storage: cfg?.storage,
           appId: cfg?.appId,
           userId: opts.userId,
-          deviceKey: opts.deviceKey,
+          deviceKey: resolveDeviceKey(cfg, opts),
           sessionCount: opts.sessionCount,
           appVersion: cfg?.appVersion ?? device.appVersion,
           platform: Platform.OS,
@@ -137,31 +202,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) => {