@wireai/activation 0.14.3 → 0.16.0

package/src/analytics/reportClientEvent.ts

@@ -24,6 +24,7 @@
  * Fire-and-forget: this never throws into the UI and never awaits — analytics must never
  * be able to break onboarding.
  */
+import { DEADLINE_EXPIRED, withDeadline } from "../utils/withDeadline";
 import type { DeviceContext } from "../device/deviceContext";
 
 /** Event types a CLIENT may report. The rest of the funnel is server-side; sending those
@@ -368,16 +369,24 @@ export const reportClientEventsOutcome = async (
     const req = buildEventsRequest(target, events);
     // No target / nothing serializable: there is no endpoint to retry against.
     if (!req) return "refused";
-    const res = await fetch(req.url, req.init);
-    if (!res || !res.ok) return "unreachable";
-    // ONE body read, used for both the verdict and the dev warning — it can only be read once.
-    const ack = await readEventsAck(res);
-    if (!ack || ack.skipped <= 0) return "delivered";
-    if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-      console.warn(describeDiscarded(ack));
-    }
-    // The server answered and declined THIS event. A retry is a re-decline.
-    return "refused";
+    // Under a deadline, BODY READ INCLUDED (see `utils/withDeadline`): this is the awaited path a
+    // host's `await wire.track()` sits on, and without a ceiling a hung POST parks it for the ~60s
+    // platform default. A ceiling cleared when the headers land would leave `readEventsAck` — which
+    // reads the body — uncapped, which is the `fetchWireFeatures` defect in a second place.
+    const outcome = await withDeadline(async (signal): Promise<SendOutcome> => {
+      const res = await fetch(req.url, { ...req.init, signal });
+      if (!res || !res.ok) return "unreachable";
+      // ONE body read, used for both the verdict and the dev warning — it can only be read once.
+      const ack = await readEventsAck(res);
+      if (!ack || ack.skipped <= 0) return "delivered";
+      if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+        console.warn(describeDiscarded(ack));
+      }
+      // The server answered and declined THIS event. A retry is a re-decline.
+      return "refused";
+    });
+    // A deadline that expired means nothing came back — retryable, exactly like a network error.
+    return outcome === DEADLINE_EXPIRED ? "unreachable" : outcome;
   } catch {
     // Unreachable / missing-fetch / network — best-effort, and retryable.
     return "unreachable";

package/src/analytics/useAnalytics.ts

@@ -1,8 +1,8 @@
 /**
  * useAnalytics — a THIN optional React hook over the pure {@link createAnalytics} factory.
  *
- * It builds ONE analytics instance for the component's lifetime and returns it, so re-renders
- * never rebuild the queue or lose the in-memory user binding. React is a REQUIRED peer of the
+ * It builds ONE analytics instance for the component's lifetime and returns a STABLE FACADE over
+ * it (see below), so re-renders never rebuild the queue or lose the in-memory user binding. React is a REQUIRED peer of the
  * kit, so importing it here is allowed; the hook adds NO other dependency. Mirrors the existing
  * `createScreenTracker` / `useScreenTracking` split — the factory stays React-free, this is the
  * glue.
@@ -25,6 +25,45 @@ import {
  * instance is stable for the component's lifetime, held in a ref). Returns the {@link Analytics}
  * surface so the component can `track` / `screen` / `identify` and drive `notifyOnline` on reconnect.
  */
+/**
+ * The STABLE object the host holds, delegating to whatever instance is live AT CALL TIME.
+ *
+ * ── WHY THE HOOK CANNOT JUST RETURN THE INSTANCE ─────────────────────────────────────────────────
+ * React's StrictMode dev remount runs a mount effect **setup → cleanup → setup with no intervening
+ * render**. The cleanup below disposes the instance and nulls the ref; the component is still
+ * mounted, and no render happens to rebuild it. So the object the host was handed at render is a
+ * DISPOSED one: `EventQueue.enqueue` returns early when disposed, which makes every `track()` on it
+ * a silent no-op — no error, no warning, `size()` stays 0 — until the host's next render. Dev builds
+ * only (production `<StrictMode>` is a passthrough), but dev is where a developer verifies that
+ * their analytics work.
+ *
+ * ── WHY THIS SHAPE AND NOT THE TWO OBVIOUS ALTERNATIVES ──────────────────────────────────────────
+ * • Stop nulling the ref in the cleanup → the render guard reads `!ref.current`, so a real
+ *   credentials change would never rebuild. That trades a dev-only silence for a production one.
+ * • A `disposedRef` the render guard reads → the defining property of this window is that NO RENDER
+ *   HAPPENS in it. Any repair spelled at render time re-closes the same hole one line lower.
+ * What has to keep working is the reference the host is ALREADY HOLDING, and only a stable
+ * indirection can do that. It also fixes the ordinary credentials-swap case for free: a host that
+ * captured the instance in a callback used to hold the pre-swap queue.
+ *
+ * ⚠️ A facade is safe only while it is COMPLETE. `Analytics` growing a member this forgets would be
+ * `undefined` on the object every host holds — a TypeError with a green typecheck, since the facade
+ * is written against the very declaration that changed. `test/canary/strictModeInstanceHandoff`
+ * compares the runtime key sets against `createAnalytics` and goes red the day they drift.
+ */
+const stableAnalyticsFacade = (live: () => Analytics | undefined): Analytics => ({
+  track: (event, props) => live()?.track(event, props),
+  screen: (name, props) => live()?.screen(name, props),
+  identify: (userId, traits) => live()?.identify(userId, traits),
+  setUserContext: (partial) => live()?.setUserContext(partial),
+  reset: () => live()?.reset(),
+  flush: () => live()?.flush(),
+  notifyOnline: () => live()?.notifyOnline(),
+  // After a real unmount there is no instance and nothing pending on it — 0 is the honest answer.
+  size: () => live()?.size() ?? 0,
+  dispose: () => live()?.dispose(),
+});
+
 export const useAnalytics = (
   config: CreateAnalyticsConfig,
   options: AnalyticsOptions = {},
@@ -32,6 +71,10 @@ export const useAnalytics = (
   // One instance per mount; kept in a ref so re-renders never rebuild the queue or drop the binding.
   const ref = useRef<Analytics | undefined>(undefined);
   const prevKeys = useRef<string>("");
+  // The construction inputs, read fresh, so the rebuild below uses the CURRENT config rather than
+  // the first render's closure.
+  const inputs = useRef({ config, options });
+  inputs.current = { config, options };
 
   const currentKeys = `${config.serverUrl}|${config.apiKey}|${config.appId}`;
   if (!ref.current || prevKeys.current !== currentKeys) {
@@ -44,6 +87,34 @@ export const useAnalytics = (
     ref.current = createAnalytics(config, options);
   }
 
+  // Built once and never replaced: it is the whole point that the host's reference outlives every
+  // instance behind it.
+  const facade = useRef<Analytics | undefined>(undefined);
+  if (!facade.current) facade.current = stableAnalyticsFacade(() => ref.current);
+
+  // ⛔ DECLARED FIRST, AND THAT ORDER IS LOAD-BEARING. React runs every cleanup, then every setup.
+  // With the device-key effect below declared first, its second setup would run while `ref.current`
+  // was still `undefined` (this effect not having re-run yet), `?.setUserContext` would silently
+  // no-op, and the host's real device key would be dropped for the life of the mount — which is the
+  // very defect the paragraph below exists to describe.
+  //
+  // SETUP: rebuild the instance this effect's own cleanup disposed. On a first mount there is
+  // nothing to do (render just built one); after StrictMode's cleanup→setup there is, and no render
+  // is coming to do it.
+  // UNMOUNT: give the storage claim and the retry timer back. A screen that mounts this hook is
+  // built and torn down repeatedly (navigation, Fast Refresh, StrictMode's double-invoke), and each
+  // rebuild used to leave the previous queue holding the appId's slot — so every remount after the
+  // first persisted into `…#2`, `…#3`, and the next launch read none of them.
+  useEffect(() => {
+    if (!ref.current) {
+      ref.current = createAnalytics(inputs.current.config, inputs.current.options);
+    }
+    return () => {
+      ref.current?.dispose();
+      ref.current = undefined;
+    };
+  }, []);
+
   // A LATE-ARRIVING host device key must still reach the instance.
   //
   // `createAnalytics` copies `config.userContext` into a closure at construction and never re-reads
@@ -64,17 +135,5 @@ export const useAnalytics = (
     if (hostDeviceKey) ref.current?.setUserContext({ deviceKey: hostDeviceKey });
   }, [hostDeviceKey]);
 
-  // UNMOUNT: give the storage claim and the retry timer back. A screen that mounts this hook is
-  // built and torn down repeatedly (navigation, Fast Refresh, StrictMode's double-invoke), and each
-  // rebuild used to leave the previous queue holding the appId's slot — so every remount after the
-  // first persisted into `…#2`, `…#3`, and the next launch read none of them.
-  useEffect(
-    () => () => {
-      ref.current?.dispose();
-      ref.current = undefined;
-    },
-    [],
-  );
-
-  return ref.current;
+  return facade.current;
 };

package/src/analytics/wireDoctor.ts

@@ -8,13 +8,18 @@
  * numeric `ts` did exactly that through 0.13.0. This turns that class of loss from something you
  * discover in a funnel report weeks later into something the first run tells you.
  *
- * SHAPE: four independent checks, each a `{name, ok, detail}` unit that can be read (and tested)
+ * SHAPE: five independent checks, each a `{name, ok, detail}` unit that can be read (and tested)
  * without the others. The report is data, never a thrown error and never a side effect on the host:
  *
  *   1. `target`      : is there a server URL and a key, and do they look like a key and a URL?
  *   2. `reachability`: is the server actually there? (`GET /v1/events/contract`, public and cheap)
  *   3. `storage`      : can the offline queue persist? (a write / read / delete probe)
  *   4. `round_trip`   : does a REAL event survive REAL server validation? (a `dry_run` POST)
+ *   5. `join_key`     : will those events be JOINABLE? (read-only; needs `join`)
+ *
+ * Checks 1-4 all answer "does an event leave and get accepted". NONE of them answers "can it be
+ * joined", and an integration with no `user_context.device_key` writes every event, passes every
+ * one of those four, and still reports a permanent ZERO in the activated funnel. That is check 5.
  *
  * NEVER THROWS, under any input, any network condition, or any hostile response object. A doctor
  * that can crash the screen it is diagnosing is worse than no doctor.
@@ -34,6 +39,9 @@
  *   const report = await wireDoctor({
  *     target: { serverUrl: "https://api.example.com", apiKey: DRIVELINE_KEY },
  *     storage: AsyncStorage,
+ *     // The same values you hand <WireOnboarding>. Omit `join` and the join_key check FAILS,
+ *     // because a report that never looked at the join cannot honestly read green.
+ *     join: { appId: WIRE_APP_ID, userContext },
  *   });
  *   console.log(report.ok, report.checks);
  */
@@ -49,6 +57,12 @@ import {
   type ClientEventTarget,
 } from "./reportClientEvent";
 import type { WireOnboardingStorage } from "../session/persistedSession";
+// The SAME key builder the analytics side persists the auto id under, and the SAME predicate
+// `resolveIdentity` gates on — imported rather than re-typed, so the doctor can never drift into
+// answering about a key the kit does not actually use. `isUsableIdentityValue` is the PURE half:
+// calling `resolveIdentity` here would write this reader into the provenance census (see below).
+import { deviceIdStorageKey } from "../context/deviceId";
+import { isUsableIdentityValue } from "../identity/identityRecord";
 
 /** RN sets this global; absent under node/SSR. Read defensively, exactly as `warnOnSkippedEvents` does. */
 declare const __DEV__: boolean | undefined;
@@ -56,7 +70,8 @@ declare const __DEV__: boolean | undefined;
 /** One diagnosis. `name` is stable and machine-readable; `detail` is for a human reading a console. */
 export type WireDoctorCheck = {
   /**
-   * Stable id: `target` | `reachability` | `storage` | `round_trip` | `dev_only` | `internal_error`.
+   * Stable id: `target` | `reachability` | `storage` | `round_trip` | `join_key` | `dev_only` |
+   * `internal_error`.
    *
    * `dev_only` means ONE thing and only that thing: `__DEV__` is unset or false, so nothing ran.
    * `internal_error` is the separate catch-all for a failure that got past every check's own
@@ -75,6 +90,20 @@ export type WireDoctorReport = {
   checks: WireDoctorCheck[];
 };
 
+/**
+ * What the join check needs: the same three values the host hands `<WireOnboarding>`. Pass the very
+ * props you pass the component — anything reconstructed here would diagnose a DIFFERENT integration
+ * than the one that ships.
+ */
+export type WireDoctorJoinTarget = {
+  /** The same `config.appId`. It namespaces the persisted auto key, so the wrong one reads the wrong slot. */
+  appId?: string;
+  /** The same `userContext` prop. Only `device_key` is read; nothing else is inspected or reported. */
+  userContext?: Record<string, string | number | boolean>;
+  /** The same `autoJoinKey` prop. `false` is the documented opt-out from the kit's auto-join. */
+  autoJoinKey?: boolean;
+};
+
 /** Input for {@link wireDoctor}. `storage` is optional: without it the queue runs in-memory only. */
 export type WireDoctorOptions = {
   /** The same `{serverUrl, apiKey}` the kit is configured with. */
@@ -84,6 +113,11 @@ export type WireDoctorOptions = {
    * check reports the DEGRADED in-memory mode rather than failing.
    */
   storage?: WireOnboardingStorage;
+  /**
+   * The join-key inputs. OMITTING THIS FAILS THE `join_key` CHECK — deliberately, and see
+   * {@link checkJoinKey} for why a skipped join check may not read as a pass.
+   */
+  join?: WireDoctorJoinTarget;
 };
 
 /**
@@ -284,6 +318,110 @@ const checkRoundTrip = async (target: ClientEventTarget): Promise<WireDoctorChec
   );
 };
 
+/**
+ * CHECK 5: will an onboarding session carry the JOIN KEY?
+ *
+ * WHY THIS IS NOT COVERED BY THE OTHER FOUR: they prove events LEAVE and are ACCEPTED. None of them
+ * proves the events can be JOINED. `user_context.device_key` is the only thing that stitches an
+ * onboarding session to everything the app reports later, so without it every event is written,
+ * every check is green, and the `activated` funnel still reads a permanent ZERO. Two real consumers
+ * shipped exactly that. A doctor that passes an integration whose funnel can never be non-zero is
+ * reporting on the wrong question.
+ *
+ * ⛔ STRICTLY READ-ONLY, and that constraint shapes the whole check. It would be far easier to call
+ * `hydrateDeviceIdentity` and read `.durable` off the result — but that MINTS, registers on the
+ * process-wide registry, and persists. Two things forbid it: this module's own contract ("mints no
+ * `globalThis` slot", "never a side effect on the host"), and the 0.15.1 defect where a propless
+ * READER wrote into the census it read, so the host's real `appId` registering afterwards made the
+ * census read two and the reader answered `undefined` for the rest of the process. A diagnostic that
+ * causes the defect class it diagnoses is worse than no diagnostic. So this check only ever READS:
+ * one `getItem`, plus pure predicates. Same reason it uses {@link isUsableIdentityValue} and not
+ * `resolveIdentity` — the latter WRITES the provenance registry for a `host`-sourced value.
+ *
+ * The verdicts mirror `WireOnboarding`'s own three auto-join conditions, in its order.
+ */
+const checkJoinKey = async (
+  join: WireDoctorJoinTarget | undefined,
+  storage: WireOnboardingStorage | undefined,
+  storageOk: boolean,
+): Promise<WireDoctorCheck> => {
+  // NOT a pass. The whole module already rules that a check which never ran may not report healthy
+  // (that is why `dev_only` is `ok: false`), and this is the same shape: a green report that never
+  // looked at the join is precisely the outcome this check exists to remove.
+  if (!join) {
+    return check(
+      "join_key",
+      false,
+      "NOT EVALUATED: pass `join: { appId, userContext, autoJoinKey }` — the same values you pass " +
+        "<WireOnboarding> — so the doctor can tell whether this integration's sessions will be joinable. " +
+        "It is reported as a failure rather than skipped because every other check can pass while the " +
+        "funnel reads a permanent zero.",
+    );
+  }
+  // A host-supplied key ALWAYS wins and is never touched by the kit, so nothing else matters.
+  // ⛔ The key's VALUE is never reported, the same discipline the target check applies to the apiKey.
+  if (isUsableIdentityValue(join.userContext?.device_key)) {
+    return check(
+      "join_key",
+      true,
+      "user_context.device_key is supplied by the host, so onboarding sessions join the rest of the funnel.",
+    );
+  }
+  if (join.autoJoinKey === false) {
+    return check(
+      "join_key",
+      false,
+      "no user_context.device_key AND autoJoinKey is false, so these onboarding sessions are UNLINKED " +
+        "by choice: they join nothing the app reports later and the activated funnel reads zero. " +
+        "Supply user_context.device_key, or drop autoJoinKey:false to let the kit inject its own.",
+    );
+  }
+  if (!storage) {
+    return check(
+      "join_key",
+      false,
+      "no user_context.device_key, and the kit cannot auto-inject one without storage: an unpersisted key " +
+        "differs every launch, which corrupts the server's session counting rather than just leaving it " +
+        "empty, so the kit declines it. Pass AsyncStorage (or an MMKV wrapper) to <WireOnboarding>.",
+    );
+  }
+  if (!storageOk) {
+    return check(
+      "join_key",
+      false,
+      "no user_context.device_key, and the storage check above FAILED — the kit refuses a non-durable auto " +
+        "key, so it will inject nothing and these sessions will not join. Fix the storage adapter first.",
+    );
+  }
+  let persisted: string | null = null;
+  try {
+    persisted = await storage.getItem(deviceIdStorageKey(join.appId));
+  } catch {
+    return check(
+      "join_key",
+      false,
+      "no user_context.device_key, and reading the persisted auto key threw, so it is unknown whether the " +
+        "kit can supply one. Treat this as the storage adapter being unreliable.",
+    );
+  }
+  if (isUsableIdentityValue(persisted)) {
+    return check(
+      "join_key",
+      true,
+      "no host device_key, but a durable auto join key is already persisted for this appId, so sessions join.",
+    );
+  }
+  // First run on this install: nothing persisted YET. That is the normal cold start, not a fault —
+  // the kit mints and persists on first mount, and the storage check above already proved a real
+  // write/read round trip, which is the condition the kit gates that injection on.
+  return check(
+    "join_key",
+    true,
+    "no host device_key and none persisted yet (first run): the kit will mint and persist its own on first " +
+      "mount, and the storage check above proved the write/read round trip that injection is gated on.",
+  );
+};
+
 /**
  * Run the full diagnosis. Resolves a report; NEVER throws and NEVER rejects.
  *
@@ -307,16 +445,23 @@ export const wireDoctor = async (options: WireDoctorOptions): Promise<WireDoctor
   }
   try {
     const target = options?.target;
-    const checks: WireDoctorCheck[] = [checkTarget(target)];
+    const targetCheck = checkTarget(target);
+    const checks: WireDoctorCheck[] = [targetCheck];
     // Reachability and the round trip both need a usable target; running them against a broken one
     // would report a network failure and bury the real cause, which check 1 already named.
-    if (checks[0]!.ok && target) {
+    const targetUsable = targetCheck.ok && !!target;
+    if (targetUsable && target) {
       checks.push(await checkReachability(target.serverUrl));
-      checks.push(await checkStorage(options?.storage));
+    }
+    const storageCheck = await checkStorage(options?.storage);
+    checks.push(storageCheck);
+    if (targetUsable && target) {
       checks.push(await checkRoundTrip(target));
-    } else {
-      checks.push(await checkStorage(options?.storage));
     }
+    // Last, and it runs in BOTH branches: the join question is independent of the target entirely.
+    // An integration can have a perfect server and a permanently unjoinable funnel, which is the
+    // whole reason this check exists — so a broken target must not hide it.
+    checks.push(await checkJoinKey(options?.join, options?.storage, storageCheck.ok));
     return { ok: checks.every((c) => c.ok), checks };
   } catch {
     // Belt and braces: every check above already swallows its own failures, so reaching here means

package/src/coachmarks/CoachmarkProvider.tsx

@@ -1,12 +1,13 @@
 import React, { useEffect } from "react";
 
-import { useResolvedFeatures } from "../features/WireFeaturesProvider";
+import { useResolvedFeaturesState } from "../features/WireFeaturesProvider";
 import type { WireFeatures, WireFeaturesConfig } from "../features/types";
 import { CoachmarkOverlayHost } from "./CoachmarkOverlayHost";
 import {
   getCoachmarkStorage,
   setCoachmarkStorage,
   setCoachmarksEnabled,
+  setCoachmarksResolved,
   setCoachmarkTesting,
 } from "./runtime";
 import type { CoachmarkStorage } from "./types";
@@ -36,6 +37,11 @@ export interface CoachmarkProviderProps {
    * pre-resolved `features`, OR a `featuresConfig` (serverUrl + apiKey) to lazily fetch once, OR
    * mount a `WireFeaturesProvider` above (context is read automatically). Omit all three and
    * coachmarks stay on (fail-open) — zero behavior change for hosts that never adopt flags.
+   *
+   * While a fetch is still in flight, a NEW tour does not arm (so a tenant who switched the module
+   * off gets no first impression), and a tour already in flight is never torn down. Nothing is
+   * spent by that wait: no once-gate is consumed, so an ON answer plays the tour in full. A failed
+   * fetch is an answer — fail-open is unchanged.
    */
   features?: WireFeatures;
   /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
@@ -69,17 +75,30 @@ export const CoachmarkProvider: React.FC<CoachmarkProviderProps> = ({
   children,
 }) => {
   // Resolve the coachmarks kill switch: explicit `features` → context → lazy fetch → all-on.
-  const flags = useResolvedFeatures({ flags: features, config: featuresConfig });
-  const coachmarksOn = flags.coachmarks.enabled;
+  // `settled` is what separates "on because the tenant says so" from "on because nobody has asked
+  // yet" — the flags alone cannot tell those apart, and the second one is a guess.
+  const { flags, settled } = useResolvedFeaturesState({
+    flags: features,
+    config: featuresConfig,
+  });
+  // NEVER publish a `false` verdict on a guess. The kill switch is TERMINAL for a tour in flight
+  // (`useCoachmarkTour` subscribes and exits on a flip to false), so holding the surface by writing
+  // it false while the fetch is in flight would end the tour of every ENABLED tenant on every cold
+  // start — a worse defect than the one this fixes. The wait is published separately below, where
+  // it blocks only the ARM of a NEW tour. (While unsettled the resolved flags ARE the all-on
+  // defaults, so this `true` is not overriding a tenant answer; it is naming the guess as one.)
+  const coachmarksOn = settled ? flags.coachmarks.enabled : true;
 
   // Apply during render so gates + the kill switch are readable before any child effect fires.
   setCoachmarkStorage(storage);
   setCoachmarkTesting(isTestingCoachmark);
+  setCoachmarksResolved(settled);
   setCoachmarksEnabled(coachmarksOn);
 
   useEffect(() => {
     setCoachmarkStorage(storage);
     setCoachmarkTesting(isTestingCoachmark);
+    setCoachmarksResolved(settled);
     setCoachmarksEnabled(coachmarksOn);
     return () => {
       // Only clear if THIS provider's storage is still the live singleton — a
@@ -87,10 +106,12 @@ export const CoachmarkProvider: React.FC<CoachmarkProviderProps> = ({
       if (getCoachmarkStorage() === storage) {
         setCoachmarkStorage(null);
       }
-      // Restore the fail-open default so a torn-down provider never leaves coachmarks dark.
+      // Restore the fail-open defaults so a torn-down provider never leaves coachmarks dark, nor
+      // leaves a tour that outlives it unable to arm.
       setCoachmarksEnabled(true);
+      setCoachmarksResolved(true);
     };
-  }, [storage, isTestingCoachmark, coachmarksOn]);
+  }, [storage, isTestingCoachmark, coachmarksOn, settled]);
 
   return (
     <>