@wireai/activation 0.9.1 → 0.9.2

package/package.json

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