@wireai/activation 0.12.2 → 0.13.2

package/src/analytics/analyticsFacade.ts

@@ -38,17 +38,9 @@ import {
 } from "../context/userContext";
 import { resolveAutoDeviceKey, type ResolveAutoDeviceKeyOptions } from "../context/deviceId";
 import { detectAppVersion } from "../device/appVersion";
+import { resolveIdentity } from "../identity/identityRecord";
 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);
-  }
-};
+import { warnInDev } from "../utils/warnInDev";
 
 /** Arbitrary non-PII event properties. Serialized to the event's `meta` (a JSON string) on the wire. */
 export type AnalyticsProps = Record<string, unknown>;
@@ -204,6 +196,15 @@ export const createAnalytics = (
     typeof config.userContext?.deviceKey === "string" && config.userContext.deviceKey.trim()
       ? config.userContext.deviceKey.trim()
       : undefined;
+  // Record a HOST-supplied key on the process provenance registry, so a `<WireOnboarding>` mount that
+  // was NOT given one can tell "this app owns no device id" (fine, inject) from "this app owns one
+  // and forgot it here" (the silent third id space — K9). Recording only; nothing reads it here.
+  resolveIdentity({
+    value: hostDeviceKeyAtInit,
+    space: "device",
+    source: "host",
+    scope: config.appId,
+  });
   // The auto id comes from the ONE process-wide registry (`resolveAutoDeviceKey`), NOT a mint local to
   // this instance. A host that also builds a `createWireActivation` instance used to get a SECOND,
   // different auto id for the same install, splitting `device_key` across two id spaces — see the

package/src/analytics/currentSession.ts

@@ -48,6 +48,12 @@
  * app-open: it warns once in dev, naming the fix.
  */
 import { makeSessionId } from "./reportClientEvent";
+// The shared primitive returns whether it ACTUALLY warned, which the once-flag below depends on:
+// marking "already warned" after a prod no-op would burn the single warning and leave the one dev
+// build that needed it silent. (The old local copy justified itself as keeping this module
+// import-free for the tree-shaken analytics bundle; that had already lapsed — it imports
+// `makeSessionId` right here — and `utils/warnInDev` has no imports of its own.)
+import { warnInDev } from "../utils/warnInDev";
 
 /**
  * Well-known key into the runtime-global symbol registry. `Symbol.for` (NOT a plain `Symbol()`) is
@@ -83,26 +89,6 @@ export const resetCurrentSessionId = (): void => {
   globalSlot[CURRENT_SESSION_ID_SLOT] = undefined;
 };
 
-/** 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.
- * Same idiom as `analyticsFacade.warnInDev` — deliberately duplicated rather than imported, so this
- * module keeps its zero-import-weight for the tree-shaken analytics bundle.
- *
- * Returns whether it ACTUALLY warned, so the caller's once-flag is spent on a warning a developer
- * saw. Marking "already warned" after a no-op would burn the single warning in prod, and the one
- * dev build that needed it would then run silent.
- */
-const warnInDev = (message: string): boolean => {
-  if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-    console.warn(message);
-    return true;
-  }
-  return false;
-};
-
 /** The one-time message. Hoisted so a prod mint does not rebuild a string nobody will read. */
 const MINT_WARNING =
   "[wireai] No app-open session was registered, so a session id was minted for this event " +

package/src/analytics/eventQueue.ts

@@ -31,6 +31,7 @@ import {
   type ClientEventTarget,
 } from "./reportClientEvent";
 import type { WireOnboardingStorage } from "../session/persistedSession";
+import { warnInDev } from "../utils/warnInDev";
 
 /** Envelope source: a fixed envelope or a provider evaluated at enqueue time (fresh network type). */
 export type EnvelopeSource = ContextEnvelope | (() => ContextEnvelope | undefined);
@@ -85,6 +86,66 @@ const DEFAULTS = {
 /** Ceiling on the persisted-backlog read — a hung adapter degrades to an empty start, never a stall. */
 const READ_TIMEOUT_MS = 1500;
 
+// ── One storage slot per QUEUE, not per appId (K4) ───────────────────────────────────────────────
+//
+// The default key was derived from `appId` alone, so two `createAnalytics` instances for one tenant —
+// the documented double-wiring, a façade for `track`/`screen` plus an activation instance — shared ONE
+// persisted backlog while keeping SEPARATE in-memory buffers. Every symptom of that is silent:
+// each `persist()` overwrites the other's blob with its own view of "pending"; a queue that drains to
+// empty calls `removeItem` and DELETES a sibling's still-pending events; and on relaunch whatever
+// survived is loaded by both instances and sent twice. `useLifecycleEvents` already avoided all of it
+// by handing its queue a dedicated explicit key — this generalizes that.
+//
+// A `Symbol.for` slot for the same reason as every other registry here: tsup inlines a copy of this
+// module into each bundle, and a plain module `let` would let the `.` and `./analytics` copies each
+// think they were the first claimant of the same key.
+const QUEUE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:eventQueueKeys");
+
+type GlobalWithQueueKeys = typeof globalThis & { [QUEUE_KEY_SLOT]?: Set<string> };
+
+const queueKeyGlobal = globalThis as GlobalWithQueueKeys;
+
+const claimedQueueKeys = (): Set<string> => {
+  const existing = queueKeyGlobal[QUEUE_KEY_SLOT];
+  if (existing) return existing;
+  const created = new Set<string>();
+  queueKeyGlobal[QUEUE_KEY_SLOT] = created;
+  return created;
+};
+
+/**
+ * Claim `preferred` for this queue, or the next free `preferred#N` when a live queue already holds it.
+ *
+ * ONLY the appId-derived DEFAULT is ever rotated. An EXPLICIT `storageKey` is the host (or
+ * `useLifecycleEvents`) declaring which slot a queue owns, and that hook re-creates its queue on every
+ * remount — rotating there would silently walk it off its own backlog once per remount, which is a
+ * worse bug than the one being fixed.
+ */
+const claimQueueKey = (preferred: string, explicit: boolean): string => {
+  const claimed = claimedQueueKeys();
+  if (explicit || !claimed.has(preferred)) {
+    claimed.add(preferred);
+    return preferred;
+  }
+  let ordinal = 2;
+  while (claimed.has(`${preferred}#${ordinal}`)) ordinal++;
+  const key = `${preferred}#${ordinal}`;
+  claimed.add(key);
+  warnInDev(
+    `[wireai] a second event queue was created for the same appId, and "${preferred}" is already ` +
+      "claimed by a live one. Two queues sharing one storage slot overwrite each other's backlog, " +
+      "delete each other's pending events when one drains to empty, and double-send on relaunch, so " +
+      `this queue was given "${key}" instead. Prefer ONE analytics instance per app; if you really ` +
+      "need two, pass an explicit `storageKey` to each so the slots are yours to reason about.",
+  );
+  return key;
+};
+
+/** Test-only: forget every claimed queue key. A real RELAUNCH is a new process, so a test that
+ *  simulates one in-process must call this or its second queue reads as a concurrent sibling.
+ *  Exported from `@wireai/activation/analytics`, matching `resetAutoDeviceKeys` / `resetCurrentSessionId`. */
+export const resetEventQueueKeys = (): void => claimedQueueKeys().clear();
+
 /** Internal buffered item. `id` is a local monotonic handle for deterministic dequeue-after-ack;
  *  it is NEVER sent to the server. `sig` is the de-dup signature (serialized stamped event). */
 type QueuedItem = { id: number; event: ClientEvent; sig: string };
@@ -137,7 +198,14 @@ const parsePersisted = (raw: string | null | undefined): PersistedItem[] => {
 export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   const target = options.target;
   const storage = options.storage;
-  const key = options.storageKey ?? `wireai:evtq:${options.appId ?? "default"}`;
+  // One slot per QUEUE (K4): an explicit key is taken verbatim; the appId-derived default is rotated
+  // to `…#2` when a live queue already holds it, so two instances can never share one backlog.
+  //
+  // Only claimed when there IS storage. The defect is entirely about the persisted slot, and a
+  // storage-less queue (the documented degraded in-memory mode) never reads or writes the key — so
+  // claiming there would warn about a collision that cannot happen.
+  const defaultKey = options.storageKey ?? `wireai:evtq:${options.appId ?? "default"}`;
+  const key = storage ? claimQueueKey(defaultKey, options.storageKey !== undefined) : defaultKey;
   const maxSize = options.maxSize ?? DEFAULTS.maxSize;
   const batchSize = options.batchSize ?? DEFAULTS.batchSize;
   const baseBackoffMs = options.baseBackoffMs ?? DEFAULTS.baseBackoffMs;
@@ -170,6 +238,8 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
     // 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.
+    // This stays a NUMBER in the queue (the de-dup signature depends on it); `buildEventsRequest`
+    // serializes it to the ISO8601 string the server requires at send time.
     if (stamped.ts === undefined) stamped.ts = Date.now();
     if (!env) return stamped;
     if (!stamped.device && env.device) stamped.device = env.device;

package/src/analytics/index.ts

@@ -49,7 +49,7 @@ export { buildContextEnvelope } from "./contextEnvelope";
 export type { ContextEnvelope, ContextEnvelopeInput } from "./contextEnvelope";
 
 // ─── Offline-first, persistent, batched + retried event queue (dependency-free) ─
-export { createEventQueue } from "./eventQueue";
+export { createEventQueue, resetEventQueueKeys } from "./eventQueue";
 export type { EventQueue, EventQueueOptions, EnvelopeSource } from "./eventQueue";
 
 // ─── Developer-facing analytics façade (track / screen / identify) over the queue ─

package/src/analytics/reportClientEvent.ts

@@ -77,15 +77,24 @@ export type ClientEvent = {
    */
   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.
+   * Client-stamped timestamp of when the event was ENQUEUED on the device. Optional and ADDITIVE.
+   *
+   * TWO REPRESENTATIONS, on purpose:
+   *  - INTERNAL (epoch-ms `number`): what the offline queue stamps 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. The de-dup signature depends on this number.
+   *  - WIRE (ISO8601 UTC `string`): what actually leaves the device. {@link buildEventsRequest}
+   *    converts the number on its way out, because the server declares `ts: str | None` and
+   *    pydantic v2 does NOT coerce a number into it — a numeric `ts` made the server answer HTTP
+   *    200 with `{written: 0, skipped: N, errors: [{field: "ts", reason: "validation_error"}]}`,
+   *    silently discarding EVERY `app_event` through 0.13.0.
+   *
+   * A caller-set ISO string is passed through as-is. Never a wall-clock the server trusts (it
+   * derives its own receive time); an old/strict server that does not model it ignores the field.
    */
-  ts?: number;
+  ts?: number | string;
 };
 
 /** Where to POST. Derived from `WireOnboardingConfig` (`serverUrl` + `apiKey`). */
@@ -105,12 +114,46 @@ export type ClientEventTarget = {
 export const makeSessionId = (): string =>
   `wire_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 
+/**
+ * Serialize the internal epoch-ms `ts` to the ISO8601 UTC string the WIRE requires.
+ *
+ * The server's event model declares `ts: str | None` and pydantic v2 does NOT coerce int → str, so
+ * a numeric `ts` fails per-event validation: the endpoint still answers HTTP 200, but with
+ * `{written: 0, skipped: N, errors: [{index, reason: "validation_error", field: "ts"}]}` — every
+ * `app_event` from `track()`/`screen()` silently discarded behind a green response.
+ *
+ * WHY HERE and not at the queue's `stamp()`: this is the single choke point all FOUR send paths go
+ * through (offline queue, fire-and-forget, awaitable, session-start). Converting here leaves the
+ * queue's numeric `ts` — and therefore its identical-JSON de-dup signature — exactly as it was, and
+ * it also converts the persisted 0.13.0 backlogs (which hold a numeric `ts`) on their way out.
+ *
+ * NEVER mutates the caller's event: an event that needs a change is copied. A string `ts` (a
+ * caller-set ISO stamp) and an absent `ts` pass through untouched. A non-finite (`NaN`/`Infinity`)
+ * or out-of-range number — the latter makes `toISOString` throw — drops the `ts` field from the
+ * copy rather than killing the whole batch.
+ */
+const toWireEvents = (events: ClientEvent[]): ClientEvent[] =>
+  events.map((event) => {
+    if (typeof event.ts !== "number") return event;
+    const { ts, ...rest } = event;
+    if (!Number.isFinite(ts)) return rest;
+    try {
+      return { ...rest, ts: new Date(ts).toISOString() };
+    } catch {
+      // Out-of-range epoch-ms — send the event WITHOUT a ts rather than lose the batch.
+      return rest;
+    }
+  });
+
 /**
  * The ONE place the `/v1/events` POST is described (url + method + headers + body). Both the
  * fire-and-forget {@link reportClientEvents} and the awaitable {@link reportClientEventsAwait}
  * build their request here so there is a SINGLE definition of the events transport — no second
  * 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.
+ *
+ * It is also where the internal epoch-ms `ts` becomes the wire's ISO8601 string — see
+ * {@link toWireEvents} for why the conversion belongs at this choke point.
  */
 export const buildEventsRequest = (
   target: { serverUrl: string; apiKey?: string } | undefined,
@@ -121,23 +164,91 @@ export const buildEventsRequest = (
     const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
     const headers: Record<string, string> = { "Content-Type": "application/json" };
     if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-    return { url, init: { method: "POST", headers, body: JSON.stringify({ events }) } };
+    const body = JSON.stringify({ events: toWireEvents(events) });
+    return { url, init: { method: "POST", headers, body } };
   } catch {
     // URL construction or JSON serialization failed — nothing to send.
     return null;
   }
 };
 
+/** What the `/v1/events` endpoint says in its 200 body. The deployed server DOES send `errors[]`,
+ *  each entry carrying `{index, reason, field}` — `field` names the property that failed validation
+ *  (it is what identified the `ts` rejection), so it is folded into the reason string here. Still
+ *  read defensively: an older server sends no `errors` at all. */
+type EventsAck = { written?: number; skipped: number; reasons: string[] };
+
+/**
+ * Read the `/v1/events` ACK body. Resolves `undefined` when there is nothing readable — no `.json`
+ * (an old server, a bare test mock), an already-consumed body, or a hostile response object. NEVER
+ * throws, and NEVER dev-gated: the `skipped` count is a RETURN VALUE for the awaitable path, not only
+ * a warning, so it has to be read in production too.
+ *
+ * ⚠️ The body can be read exactly once, so a caller that both decides on `skipped` AND warns must do
+ * both from ONE call to this.
+ */
+const readEventsAck = async (res: unknown): Promise<EventsAck | undefined> => {
+  try {
+    const json = (res as { json?: () => Promise<unknown> } | null | undefined)?.json;
+    if (typeof json !== "function") return undefined;
+    const body = (await Promise.resolve(json.call(res))) as
+      | { written?: unknown; skipped?: unknown; errors?: unknown }
+      | null
+      | undefined;
+    const skipped = body?.skipped;
+    if (typeof skipped !== "number" || !Number.isFinite(skipped)) return undefined;
+    const reasons = Array.isArray(body?.errors)
+      ? body.errors
+          .map((e) => {
+            const entry = e as { reason?: unknown; field?: unknown } | null;
+            const reason = entry?.reason;
+            if (typeof reason !== "string") return undefined;
+            // `field` is the whole point of a validation error — a bare "validation_error" sends the
+            // reader hunting; "validation_error (field: ts)" names the property the server refused.
+            const field = entry?.field;
+            return typeof field === "string" && field.length > 0
+              ? `${reason} (field: ${field})`
+              : reason;
+          })
+          .filter((r): r is string => typeof r === "string")
+      : [];
+    return { written: typeof body?.written === "number" ? body.written : undefined, skipped, reasons };
+  } catch {
+    // Unreadable / already-consumed body / hostile object — best-effort, treat as "no ack".
+    return undefined;
+  }
+};
+
+/**
+ * The DISCARDED warning text, built from what the server ACTUALLY said.
+ *
+ * It used to staple a cause onto a bare integer — "the usual cause is a missing or empty session_id".
+ * Since `ensureCurrentSessionId` shipped, no kit path can emit an event without a `session_id`, so
+ * that is now the LEAST likely explanation, and naming it sent every reader looking in the one place
+ * the problem is not. The endpoint folds four real failures and two idempotent no-ops into one
+ * integer, so unless the server volunteers reasons, the honest thing to report is the count and where
+ * the reason lives.
+ */
+const describeDiscarded = (ack: EventsAck): string =>
+  `[wireai] the server ACCEPTED the /v1/events POST but DISCARDED ${ack.skipped} event(s) ` +
+  "(skipped in the response body) — they are gone, not retried. The server reported: " +
+  `skipped=${ack.skipped}${ack.written !== undefined ? `, written=${ack.written}` : ""}` +
+  (ack.reasons.length > 0
+    ? `, reasons: ${ack.reasons.join(", ")}.`
+    : ". It gave no reason (the endpoint folds every rejection into one count), so check the " +
+      "server's ingest log for this request rather than guessing.");
+
 /** RN sets this global; absent under node/SSR. Read defensively inside {@link warnOnSkippedEvents}. */
 declare const __DEV__: boolean | undefined;
 
 /**
  * Read the `/v1/events` ACK body and warn (dev builds only) when the server DISCARDED events.
  *
- * The endpoint answers HTTP **200** with `{ ok, written, skipped }` — an event it refuses (a missing
- * `session_id`, a malformed payload) is counted in `skipped`, never surfaced in the status code. Every
- * send path here reads `res.ok` alone, so a whole batch can evaporate behind a green response. This
- * consumes the body of the PERSISTENT paths (the offline queue + session-start) and names the count.
+ * The endpoint answers HTTP **200** with `{ ok, written, skipped }` — an event it refuses is counted
+ * in `skipped`, never surfaced in the status code. Every send path here reads `res.ok` alone, so a
+ * whole batch can evaporate behind a green response. As of 0.13.0 ALL FOUR send paths consume the ack:
+ * the offline queue, session-start, the fire-and-forget POST, and the awaitable one (which also acts
+ * on it — see {@link reportClientEventsAwait}).
  *
  * LOG ONLY: returns immediately, never throws, and never influences retry / dequeue / return values.
  * A response with no usable `.json` (an old server, a test mock) is silently ignored.
@@ -149,25 +260,10 @@ declare const __DEV__: boolean | undefined;
 export const warnOnSkippedEvents = (res: unknown): void => {
   if (typeof __DEV__ === "undefined" || !__DEV__) return;
   if (typeof console === "undefined" || !console.warn) return;
-  try {
-    const json = (res as { json?: () => Promise<unknown> } | null | undefined)?.json;
-    if (typeof json !== "function") return;
-    void Promise.resolve(json.call(res))
-      .then((body) => {
-        const skipped = (body as { skipped?: unknown } | null | undefined)?.skipped;
-        if (typeof skipped !== "number" || skipped <= 0) return;
-        console.warn(
-          `[wireai] the server ACCEPTED the /v1/events POST but DISCARDED ${skipped} event(s) ` +
-            "(skipped in the response body) — they are gone, not retried. The usual cause is an " +
-            "event with a missing or empty session_id.",
-        );
-      })
-      .catch(() => {
-        // Unreadable / already-consumed body — best-effort logging, swallow.
-      });
-  } catch {
-    // A hostile response object — swallow.
-  }
+  void readEventsAck(res).then((ack) => {
+    if (!ack || ack.skipped <= 0) return;
+    console.warn(describeDiscarded(ack));
+  });
 };
 
 /**
@@ -182,9 +278,16 @@ export const reportClientEvents = (
   try {
     const req = buildEventsRequest(target, events);
     if (!req) return;
-    void fetch(req.url, req.init).catch(() => {
-      // Network/transport error — analytics is best-effort, swallow.
-    });
+    void fetch(req.url, req.init)
+      .then((res) => {
+        // Still fire-and-forget — nothing is retried, nothing is returned. But a batch that
+        // evaporated behind a 200 is exactly what this path used to make invisible, so in dev it
+        // now says so, like the queue and session-start paths already did.
+        warnOnSkippedEvents(res);
+      })
+      .catch(() => {
+        // Network/transport error — analytics is best-effort, swallow.
+      });
   } catch {
     // A missing `fetch` — swallow.
   }
@@ -201,8 +304,17 @@ export const reportClientEvent = (
  * `/v1/events` path, but resolve only once the server has RESPONDED — so a decision re-fetch fired
  * immediately after is guaranteed to see the event in the session stream (this is the guarantee
  * `wire.track` needs before it triggers decision revalidation). Never throws: a missing/invalid
- * target, a missing `fetch`, a network error, or a non-2xx status all resolve to `false`. Resolves
- * `true` only on a 2xx response.
+ * target, a missing `fetch`, a network error, or a non-2xx status all resolve to `false`.
+ *
+ * ⚠️ 0.13.0: a 2xx is NO LONGER SUFFICIENT. The endpoint answers HTTP 200 with `{ ok, written,
+ * skipped }` and counts an event it refuses in `skipped`, so this used to resolve `true` for an event
+ * the server had thrown away — and `wire.track` then bumped decision revalidation, making every
+ * subscribed gate re-fetch against a stream the action never entered. It now reads the ack and
+ * resolves `false` when the server reports a positive `skipped`.
+ *
+ * BACKWARD COMPATIBLE BY CONSTRUCTION: only an explicit positive `skipped` demotes a 200. An old
+ * server that sends no such field, a body that cannot be parsed, or a response with no `.json` at all
+ * resolves `true` exactly as before — the change can produce no false negatives.
  */
 export const reportClientEventsAwait = async (
   target: ClientEventTarget | undefined,
@@ -212,7 +324,14 @@ export const reportClientEventsAwait = async (
     const req = buildEventsRequest(target, events);
     if (!req) return false;
     const res = await fetch(req.url, req.init);
-    return Boolean(res && res.ok);
+    if (!res || !res.ok) return false;
+    // 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 true;
+    if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+      console.warn(describeDiscarded(ack));
+    }
+    return false;
   } catch {
     // Unreachable / missing-fetch / network — best-effort, report failure.
     return false;