@wireai/activation 0.9.0 → 0.9.2

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

@@ -20,17 +20,42 @@ import { k as ReviewTarget, g as ReviewDecisionResponse, j as ReviewSubmission }
  * a missing `fetch`, or a network failure is swallowed and the call returns immediately.
  */
 declare const submitReview: (target: ReviewTarget | undefined, review: ReviewSubmission) => void;
-/** Options for the best-effort review decision fetch. */
+/**
+ * Options for the best-effort review decision fetch.
+ *
+ * ── WHAT THE DEPLOYED SERVER ACTUALLY READS (verified 2026-07-17) ────────────────────────
+ *
+ * `GET /v1/reviews/decision` declares exactly two query params — `session_id` and
+ * `device_key` — plus the `Authorization` header. That is the whole wire. Verified against
+ * the deployed OpenAPI schema, not against intent.
+ *
+ * This type is CLOSED on purpose. Hosts that hand-rolled this fetch invented `user_id` and
+ * `session_count` query params believing "the server ignores what it doesn't read, so passing
+ * it is always safe". Both are no-ops: the route declares neither. `session_count` is real, but
+ * only on the questionnaire POST body — which is precisely how it copy-pasted its way into a
+ * reviews call site and sat there doing nothing. They cost a wire lie — a call site that reads as though
+ * identity and a session counter reach the firing brain when neither does. So they are not
+ * offered here. Pass identity as `deviceKey`; the session count the server reasons about is the
+ * one IT derives from the event stream keyed by `deviceKey`, not one the client asserts.
+ *
+ * The client-side session floor is a LOCAL rule, not a wire param: use `ReviewConfig.minSessions`
+ * (evaluated by `useReviewGate` against the kit's own `wire_review_<id>_sessions` counter).
+ */
 interface FetchReviewDecisionOptions {
     /**
      * The onboarding session id, when there IS one. OPTIONAL on purpose: the review gate lives on
      * the home feed, where a user legitimately has no onboarding session. `deviceKey` is the real
-     * identity for this call. (Today's prod still requires `session_id` and answers 422 without it;
-     * the server relaxation is unmerged. A 422 is a non-2xx, so it returns null like any other
-     * failure, and the local rules stand. Permissive wire: do NOT make this required here.)
+     * identity for this call. (The server relaxed `session_id` to optional on 2026-07-16 and the
+     * relaxation IS deployed — the route no longer 422s without it. Permissive wire: do NOT make
+     * this required here.)
      */
     sessionId?: string;
-    /** A stable, non-PII device id. The decision endpoint reads it for cooldown + min-sessions. */
+    /**
+     * A stable, non-PII device id — THE identity for this call. The decision endpoint reads it for
+     * cooldown + min-sessions, and it is the key the server groups a device's events under. A host
+     * whose own identity is a user id passes that id here rather than reaching for a `user_id`
+     * param the route does not declare.
+     */
     deviceKey?: string;
 }
 /**
@@ -57,12 +82,29 @@ interface FetchReviewDecisionOptions {
  *   • else → null, and ONLY then. Null means "the server genuinely has no opinion", which is
  *            the one case where falling back to local rules is correct.
  *
- * Never throws: unreachable, non-2xx (incl. today's 422), bad JSON, or a missing `fetch` all
- * resolve to null. The kit does not call this internally; a host awaits it and passes the
- * result straight to `useReviewGate({ decision })`.
+ * Never throws: unreachable, non-2xx, bad JSON, or a missing `fetch` all resolve to null. The
+ * kit does not call this internally; a host awaits it and passes the result straight to
+ * `useReviewGate({ decision })`.
+ *
+ * ── DON'T RACE THIS AGAINST A LOCAL TIMER ────────────────────────────────────────────────
+ *
+ * The return type is `ReviewDecisionResponse`, which carries `arm` alongside `{fire, reason}`.
+ * Hand the WHOLE object to the gate and echo `arm` into the submission's `meta.firing_arm`;
+ * narrowing it to `{fire, reason}` on the way through silently kills per-arm attribution
+ * across a reweighting of the experiment.
+ *
+ * A host that starts its own dwell timer in parallel with this fetch has built a race a slow
+ * server loses: the timer fires, the local rules show the prompt, and the `{fire:false}` still
+ * in flight arrives too late to stop it. Do not hand-roll that. `useReviewGate` already owns
+ * the wait — set `ReviewConfig.timeoutFallbackMs` and the local rules stay parked until either
+ * the decision lands or the window expires, whichever comes first.
  *
  *   const decision = await fetchReviewDecision(target, { deviceKey });
- *   const gate = useReviewGate({ config, decision: decision ?? undefined, storage });
+ *   const gate = useReviewGate({
+ *     config: { id: "home", minSessions: 2, timeoutFallbackMs: 3000 },
+ *     decision: decision ?? undefined, // pass it whole — keep `arm`
+ *     storage,
+ *   });
  */
 declare const fetchReviewDecision: (target: ReviewTarget | undefined, options?: FetchReviewDecisionOptions) => Promise<ReviewDecisionResponse | null>;
 /** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */

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

@@ -20,17 +20,42 @@ import { k as ReviewTarget, g as ReviewDecisionResponse, j as ReviewSubmission }
  * a missing `fetch`, or a network failure is swallowed and the call returns immediately.
  */
 declare const submitReview: (target: ReviewTarget | undefined, review: ReviewSubmission) => void;
-/** Options for the best-effort review decision fetch. */
+/**
+ * Options for the best-effort review decision fetch.
+ *
+ * ── WHAT THE DEPLOYED SERVER ACTUALLY READS (verified 2026-07-17) ────────────────────────
+ *
+ * `GET /v1/reviews/decision` declares exactly two query params — `session_id` and
+ * `device_key` — plus the `Authorization` header. That is the whole wire. Verified against
+ * the deployed OpenAPI schema, not against intent.
+ *
+ * This type is CLOSED on purpose. Hosts that hand-rolled this fetch invented `user_id` and
+ * `session_count` query params believing "the server ignores what it doesn't read, so passing
+ * it is always safe". Both are no-ops: the route declares neither. `session_count` is real, but
+ * only on the questionnaire POST body — which is precisely how it copy-pasted its way into a
+ * reviews call site and sat there doing nothing. They cost a wire lie — a call site that reads as though
+ * identity and a session counter reach the firing brain when neither does. So they are not
+ * offered here. Pass identity as `deviceKey`; the session count the server reasons about is the
+ * one IT derives from the event stream keyed by `deviceKey`, not one the client asserts.
+ *
+ * The client-side session floor is a LOCAL rule, not a wire param: use `ReviewConfig.minSessions`
+ * (evaluated by `useReviewGate` against the kit's own `wire_review_<id>_sessions` counter).
+ */
 interface FetchReviewDecisionOptions {
     /**
      * The onboarding session id, when there IS one. OPTIONAL on purpose: the review gate lives on
      * the home feed, where a user legitimately has no onboarding session. `deviceKey` is the real
-     * identity for this call. (Today's prod still requires `session_id` and answers 422 without it;
-     * the server relaxation is unmerged. A 422 is a non-2xx, so it returns null like any other
-     * failure, and the local rules stand. Permissive wire: do NOT make this required here.)
+     * identity for this call. (The server relaxed `session_id` to optional on 2026-07-16 and the
+     * relaxation IS deployed — the route no longer 422s without it. Permissive wire: do NOT make
+     * this required here.)
      */
     sessionId?: string;
-    /** A stable, non-PII device id. The decision endpoint reads it for cooldown + min-sessions. */
+    /**
+     * A stable, non-PII device id — THE identity for this call. The decision endpoint reads it for
+     * cooldown + min-sessions, and it is the key the server groups a device's events under. A host
+     * whose own identity is a user id passes that id here rather than reaching for a `user_id`
+     * param the route does not declare.
+     */
     deviceKey?: string;
 }
 /**
@@ -57,12 +82,29 @@ interface FetchReviewDecisionOptions {
  *   • else → null, and ONLY then. Null means "the server genuinely has no opinion", which is
  *            the one case where falling back to local rules is correct.
  *
- * Never throws: unreachable, non-2xx (incl. today's 422), bad JSON, or a missing `fetch` all
- * resolve to null. The kit does not call this internally; a host awaits it and passes the
- * result straight to `useReviewGate({ decision })`.
+ * Never throws: unreachable, non-2xx, bad JSON, or a missing `fetch` all resolve to null. The
+ * kit does not call this internally; a host awaits it and passes the result straight to
+ * `useReviewGate({ decision })`.
+ *
+ * ── DON'T RACE THIS AGAINST A LOCAL TIMER ────────────────────────────────────────────────
+ *
+ * The return type is `ReviewDecisionResponse`, which carries `arm` alongside `{fire, reason}`.
+ * Hand the WHOLE object to the gate and echo `arm` into the submission's `meta.firing_arm`;
+ * narrowing it to `{fire, reason}` on the way through silently kills per-arm attribution
+ * across a reweighting of the experiment.
+ *
+ * A host that starts its own dwell timer in parallel with this fetch has built a race a slow
+ * server loses: the timer fires, the local rules show the prompt, and the `{fire:false}` still
+ * in flight arrives too late to stop it. Do not hand-roll that. `useReviewGate` already owns
+ * the wait — set `ReviewConfig.timeoutFallbackMs` and the local rules stay parked until either
+ * the decision lands or the window expires, whichever comes first.
  *
  *   const decision = await fetchReviewDecision(target, { deviceKey });
- *   const gate = useReviewGate({ config, decision: decision ?? undefined, storage });
+ *   const gate = useReviewGate({
+ *     config: { id: "home", minSessions: 2, timeoutFallbackMs: 3000 },
+ *     decision: decision ?? undefined, // pass it whole — keep `arm`
+ *     storage,
+ *   });
  */
 declare const fetchReviewDecision: (target: ReviewTarget | undefined, options?: FetchReviewDecisionOptions) => Promise<ReviewDecisionResponse | null>;
 /** Options for a reported app event. `deviceKey` groups a device's sessions server-side. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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/WireOnboarding.tsx

@@ -27,6 +27,7 @@ import {
   clearPersistedSession,
   loadPersistedSession,
   sessionStorageKey,
+  shouldClearOnComplete,
   DEFAULT_SESSION_TTL_MS,
   type LoadedSession,
 } from "./session/persistedSession";
@@ -52,6 +53,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   storage,
   sessionTtlMs = DEFAULT_SESSION_TTL_MS,
   persistKey,
+  retainSessionOnComplete,
   userContext,
   userId,
 }) => {
@@ -123,15 +125,24 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     };
   }, [storage, storageKey, sessionTtlMs, session]);
 
-  // Clear the cached id the moment the flow completes, so the next onboarding on this
-  // device starts a fresh session. Dropped/degraded paths deliberately do NOT clear —
+  // By DEFAULT, clear the cached id the moment the flow completes, so the next onboarding on
+  // this device starts a fresh session. Dropped/degraded paths deliberately do NOT clear —
   // a dropped session must stay resumable within the TTL.
+  //
+  // OPT-IN (`retainSessionOnComplete`): a multi-stage / replay-after-complete signup re-enters
+  // (often via a `key=` remount) WITHIN one signup. If we cleared, that re-entry would find no
+  // seed and mint a fresh `metadata.sessionId` → a phantom second `session_started` on the same
+  // funnel. When the host opts in, we LEAVE the seed in place so the re-entry resumes the SAME
+  // session (one funnel start); freshness for a genuinely new run then rides the TTL (past
+  // `sessionTtlMs` → fresh mint) and an explicit new-run signal (a changed `persistKey`).
+  // `shouldClearOnComplete` is the pure, unit-tested seam; the `storage` guard is unchanged, so a
+  // host that does not opt in lands on the byte-for-byte legacy clear-on-complete path.
   const handleComplete = useCallback(
     (result: OnboardingResult) => {
-      if (storage) clearPersistedSession(storage, storageKey);
+      if (storage && shouldClearOnComplete(retainSessionOnComplete)) clearPersistedSession(storage, storageKey);
       onComplete(result);
     },
-    [storage, storageKey, onComplete],
+    [storage, storageKey, retainSessionOnComplete, onComplete],
   );
 
   const sessionId = session?.id ?? "";

package/src/analytics/eventQueue.ts

@@ -224,10 +224,25 @@ 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;
+  // The outcome of one POST attempt:
+  //   "ok"    → the server accepted the batch (2xx) → dequeue it.
+  //   "drop"  → a BATCH-SPECIFIC permanent error (this batch will never be accepted no matter how
+  //             often we retry) → discard it and continue, so it can't block the good events behind
+  //             it (head-of-line). See DROP_STATUSES.
+  //   "retry" → transient or tenant-wide (network/5xx/429/auth) → keep the batch and back off.
+  type PostResult = "ok" | "drop" | "retry";
+
+  // Statuses where retrying THIS batch is futile because the batch itself is the problem — a
+  // malformed body (400/422), a too-large body (413), or a wrong route (404). Dropping a poison
+  // batch is what stops it from stalling the whole backlog. Deliberately NOT here: 401/403 (auth is
+  // tenant-wide, not batch-specific — dropping would silently lose EVERY event on a recoverable
+  // credential blip, so we keep retrying/pausing instead) and 429/5xx (transient).
+  const DROP_STATUSES = new Set([400, 404, 413, 422]);
+
+  // The queue's OWN awaited POST. Classifies the response to drive dequeue/drop/retry. NEVER throws —
+  // a missing fetch, a rejecting network, or an abort resolves to "retry" (batch stays, retry schedules).
+  const postBatch = async (events: ClientEvent[]): Promise<PostResult> => {
+    if (!target?.serverUrl || events.length === 0) return "retry";
     const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
     const timer = setTimeout(() => controller?.abort(), 15_000);
     try {
@@ -240,9 +255,12 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
         body: JSON.stringify({ events }),
         signal: controller?.signal,
       });
-      return !!(res && (res as { ok?: boolean }).ok);
+      if (res && (res as { ok?: boolean }).ok) return "ok";
+      const status = (res as { status?: number } | undefined)?.status;
+      if (typeof status === "number" && DROP_STATUSES.has(status)) return "drop";
+      return "retry";
     } catch {
-      return false;
+      return "retry";
     } finally {
       clearTimeout(timer);
     }
@@ -280,12 +298,13 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
     try {
       while (pending.length > 0) {
         const batch = pending.slice(0, batchSize);
-        const ok = await postBatch(batch.map((item) => item.event));
-        if (!ok) {
+        const result = await postBatch(batch.map((item) => item.event));
+        if (result === "retry") {
           scheduleRetry();
           return;
         }
-        // Dequeue exactly the acked batch by id (pending may have grown while in flight).
+        // "ok" (accepted) or "drop" (poison batch discarded so it can't block the rest): remove
+        // exactly this batch by id (pending may have grown while in flight) and keep draining.
         const acked = new Set(batch.map((item) => item.id));
         pending = pending.filter((item) => !acked.has(item.id));
         persist();

package/src/questionnaire/transport.ts

@@ -75,7 +75,15 @@ 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 exactly as the mirror
+    // `fetchReviewDecision` does. Without this, a malformed 2xx body flows straight through:
+    // `{}` reads as a truthy verdict whose `fire` is undefined (silently "never fire", killing
+    // a questionnaire the local rules would have shown), and a stringy `{fire:"yes"}` reads as
+    // FIRE while carrying no `questionnaire`, so the host renders a gate with an undefined
+    // definition. Only a genuine boolean-`fire` body is a decision; everything else → null (the
+    // server has no opinion → the local rules stand).
+    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/transport.ts

@@ -39,17 +39,42 @@ export const submitReview = (
   }
 };
 
-/** Options for the best-effort review decision fetch. */
+/**
+ * Options for the best-effort review decision fetch.
+ *
+ * ── WHAT THE DEPLOYED SERVER ACTUALLY READS (verified 2026-07-17) ────────────────────────
+ *
+ * `GET /v1/reviews/decision` declares exactly two query params — `session_id` and
+ * `device_key` — plus the `Authorization` header. That is the whole wire. Verified against
+ * the deployed OpenAPI schema, not against intent.
+ *
+ * This type is CLOSED on purpose. Hosts that hand-rolled this fetch invented `user_id` and
+ * `session_count` query params believing "the server ignores what it doesn't read, so passing
+ * it is always safe". Both are no-ops: the route declares neither. `session_count` is real, but
+ * only on the questionnaire POST body — which is precisely how it copy-pasted its way into a
+ * reviews call site and sat there doing nothing. They cost a wire lie — a call site that reads as though
+ * identity and a session counter reach the firing brain when neither does. So they are not
+ * offered here. Pass identity as `deviceKey`; the session count the server reasons about is the
+ * one IT derives from the event stream keyed by `deviceKey`, not one the client asserts.
+ *
+ * The client-side session floor is a LOCAL rule, not a wire param: use `ReviewConfig.minSessions`
+ * (evaluated by `useReviewGate` against the kit's own `wire_review_<id>_sessions` counter).
+ */
 export interface FetchReviewDecisionOptions {
   /**
    * The onboarding session id, when there IS one. OPTIONAL on purpose: the review gate lives on
    * the home feed, where a user legitimately has no onboarding session. `deviceKey` is the real
-   * identity for this call. (Today's prod still requires `session_id` and answers 422 without it;
-   * the server relaxation is unmerged. A 422 is a non-2xx, so it returns null like any other
-   * failure, and the local rules stand. Permissive wire: do NOT make this required here.)
+   * identity for this call. (The server relaxed `session_id` to optional on 2026-07-16 and the
+   * relaxation IS deployed — the route no longer 422s without it. Permissive wire: do NOT make
+   * this required here.)
    */
   sessionId?: string;
-  /** A stable, non-PII device id. The decision endpoint reads it for cooldown + min-sessions. */
+  /**
+   * A stable, non-PII device id — THE identity for this call. The decision endpoint reads it for
+   * cooldown + min-sessions, and it is the key the server groups a device's events under. A host
+   * whose own identity is a user id passes that id here rather than reaching for a `user_id`
+   * param the route does not declare.
+   */
   deviceKey?: string;
 }
 
@@ -77,12 +102,29 @@ export interface FetchReviewDecisionOptions {
  *   • else → null, and ONLY then. Null means "the server genuinely has no opinion", which is
  *            the one case where falling back to local rules is correct.
  *
- * Never throws: unreachable, non-2xx (incl. today's 422), bad JSON, or a missing `fetch` all
- * resolve to null. The kit does not call this internally; a host awaits it and passes the
- * result straight to `useReviewGate({ decision })`.
+ * Never throws: unreachable, non-2xx, bad JSON, or a missing `fetch` all resolve to null. The
+ * kit does not call this internally; a host awaits it and passes the result straight to
+ * `useReviewGate({ decision })`.
+ *
+ * ── DON'T RACE THIS AGAINST A LOCAL TIMER ────────────────────────────────────────────────
+ *
+ * The return type is `ReviewDecisionResponse`, which carries `arm` alongside `{fire, reason}`.
+ * Hand the WHOLE object to the gate and echo `arm` into the submission's `meta.firing_arm`;
+ * narrowing it to `{fire, reason}` on the way through silently kills per-arm attribution
+ * across a reweighting of the experiment.
+ *
+ * A host that starts its own dwell timer in parallel with this fetch has built a race a slow
+ * server loses: the timer fires, the local rules show the prompt, and the `{fire:false}` still
+ * in flight arrives too late to stop it. Do not hand-roll that. `useReviewGate` already owns
+ * the wait — set `ReviewConfig.timeoutFallbackMs` and the local rules stay parked until either
+ * the decision lands or the window expires, whichever comes first.
  *
  *   const decision = await fetchReviewDecision(target, { deviceKey });
- *   const gate = useReviewGate({ config, decision: decision ?? undefined, storage });
+ *   const gate = useReviewGate({
+ *     config: { id: "home", minSessions: 2, timeoutFallbackMs: 3000 },
+ *     decision: decision ?? undefined, // pass it whole — keep `arm`
+ *     storage,
+ *   });
  */
 export const fetchReviewDecision = async (
   target: ReviewTarget | undefined,

package/src/session/persistedSession.ts

@@ -141,3 +141,20 @@ export const clearPersistedSession = (storage: WireOnboardingStorage, key: strin
     // Best-effort.
   }
 };
+
+/**
+ * The opt-in decision for `WireOnboarding.handleComplete`: given the host's
+ * `retainSessionOnComplete` opt-in, whether a completion should CLEAR the persisted seed.
+ * (The caller still gates on `storage` being present — this only encodes the opt-in axis, so the
+ * legacy `if (storage) clearPersistedSession(...)` guard stays byte-for-byte for a host that does
+ * not opt in.)
+ *
+ *  - undefined / false (the default) → `true`: clear on completion, so the NEXT onboarding on this
+ *    device mints a fresh session. This is the legacy single-stage behavior (e.g. Myelino).
+ *  - true → `false`: LEAVE the seed in place so a same-signup re-entry/remount within the TTL
+ *    resumes the SAME session (one funnel start) instead of minting a phantom second `started`.
+ *    Freshness for a genuinely new run is then governed by the TTL (past `sessionTtlMs` → fresh
+ *    mint) and an explicit new-run signal (a changed `persistKey`).
+ */
+export const shouldClearOnComplete = (retainSessionOnComplete: boolean | undefined): boolean =>
+  !retainSessionOnComplete;

package/src/types.ts

@@ -211,6 +211,22 @@ export type WireOnboardingProps = {
    * accounts mid-flow. Only meaningful with `storage`.
    */
   persistKey?: string;
+  /**
+   * OPT-IN: keep the persisted session seed alive ACROSS completion, so a multi-stage or
+   * replay-after-complete re-entry WITHIN one signup (typically a `key=` remount) resumes the
+   * SAME session instead of minting a fresh `metadata.sessionId` — which the backend would adopt
+   * as a second `contextId`, double-counting a `session_started` on the funnel.
+   *
+   * Default (omitted / `false`): a completion CLEARS the seed, so the next onboarding on this
+   * device starts fresh — the legacy single-stage behavior. Leave it unset and NOTHING changes.
+   *
+   * When `true`: the seed survives completion, and freshness for a genuinely new run is governed
+   * by the TTL (past `sessionTtlMs` → a fresh seed is minted) and an explicit new-run signal
+   * (scope a new `persistKey`, e.g. a per-signup id, to force a fresh seed within the TTL).
+   *
+   * Only meaningful with `storage`. Dropped/degraded sessions are unaffected (they never clear).
+   */
+  retainSessionOnComplete?: boolean;
 };
 
 /** Backend-supplied progress, read off `response.props.progress` when present. */