@wireai/activation 0.13.0 → 0.13.3

package/src/analytics/eventQueue.ts

@@ -86,7 +86,7 @@ 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) ───────────────────────────────────────────────
+// ── One storage slot per QUEUE, not per appId ────────────────────────────────────────────────────
 //
 // 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
@@ -153,10 +153,19 @@ type QueuedItem = { id: number; event: ClientEvent; sig: string };
 /** Persisted shape — the local id + the (already envelope-stamped) event. `sig` is recomputed on load. */
 type PersistedItem = { id: number; event: ClientEvent };
 
-const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+/**
+ * The verdict of a read that ran out of time. A DISTINCT value, and never `undefined` — an
+ * `undefined` here is byte-identical to "the adapter answered, there is no backlog", and that
+ * conflation destroys data silently: `parsePersisted(undefined)` gives `[]`, hydration takes its
+ * `length === 0` early return without throwing, and the next `persist()` writes the in-memory
+ * pending list over a blob nobody has read — or, with nothing pending, `removeItem`s it outright.
+ */
+const READ_TIMED_OUT: unique symbol = Symbol("wireai:storage-read-timeout");
+
+const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | typeof READ_TIMED_OUT> => {
   let timer: ReturnType<typeof setTimeout>;
-  const timeout = new Promise<undefined>((resolve) => {
-    timer = setTimeout(() => resolve(undefined), ms);
+  const timeout = new Promise<typeof READ_TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(READ_TIMED_OUT), ms);
   });
   return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
 };
@@ -198,7 +207,7 @@ const parsePersisted = (raw: string | null | undefined): PersistedItem[] => {
 export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   const target = options.target;
   const storage = options.storage;
-  // One slot per QUEUE (K4): an explicit key is taken verbatim; the appId-derived default is rotated
+  // One slot per QUEUE: 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
@@ -217,6 +226,13 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   let flushing = false;
   let attempt = 0;
   let retryTimer: ReturnType<typeof setTimeout> | undefined;
+  // The persisted blob exists but has NOT been read yet (the cold-start read blew its deadline and
+  // is still in flight). While this is true every write is suppressed: the only thing the queue
+  // could write is a view of `pending` that does not include the backlog it has not seen, and
+  // `setItem`/`removeItem` would destroy it. Cleared as soon as the slow read settles, whichever
+  // way it settles, so a read that ultimately fails resumes normal persistence rather than
+  // suppressing it for the life of the process.
+  let backlogUnread = false;
 
   const resolveEnvelope = (): ContextEnvelope | undefined => {
     try {
@@ -238,6 +254,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;
@@ -252,6 +270,8 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
 
   const persist = (): void => {
     if (!storage) return;
+    // NEVER write over a blob that has not been read yet. See `backlogUnread`.
+    if (backlogUnread) return;
     try {
       if (pending.length === 0) {
         void storage.removeItem(key).catch(() => {});
@@ -278,25 +298,70 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
     }
   };
 
-  // Load any persisted backlog. Anything enqueued before this settles stays in memory; we merge
-  // persisted (older) ahead of it and reassign monotonic ids so dequeue-after-ack is deterministic.
+  /**
+   * Merge a loaded backlog into the in-memory buffer: persisted (older) events go AHEAD of
+   * whatever was enqueued while the read was in flight, duplicates collapse, and the size cap
+   * applies as usual.
+   *
+   * Ids are minted FRESH from the running `nextId` rather than reset to 0. A drain may already be
+   * in flight holding a batch of ids it will filter out on ack, and re-numbering from 0 would make
+   * those ids point at different events — the ack would then dequeue (silently drop) whichever
+   * events happened to inherit them. Monotonic ids are never reused, so an in-flight ack stays
+   * correct whatever lands in between.
+   */
+  const mergePersisted = (persistedItems: PersistedItem[]): void => {
+    if (persistedItems.length === 0) return;
+    const seen = new Set(pending.map((item) => item.sig));
+    const restored: QueuedItem[] = [];
+    for (const persisted of persistedItems) {
+      const sig = safeSig(persisted.event);
+      if (seen.has(sig)) continue; // already in memory — collapse the duplicate
+      seen.add(sig);
+      restored.push({ id: nextId++, event: persisted.event, sig });
+    }
+    if (restored.length === 0) return;
+    pending = [...restored, ...pending];
+    enforceSizeCap();
+    persist();
+  };
+
+  // Load any persisted backlog. Anything enqueued before this settles stays in memory; the merge
+  // above puts persisted (older) events ahead of it.
+  //
+  // A read that blows READ_TIMEOUT_MS is NOT treated as "no backlog". The race only unblocks the
+  // DRAIN — the original read is kept and merged whenever it lands, and until then every write is
+  // suppressed so the unread blob survives intact.
   const loadPromise: Promise<void> = (async () => {
     if (!storage) return;
     try {
-      const persistedItems = parsePersisted(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS));
-      if (persistedItems.length === 0) return;
-      const events = [...persistedItems.map((p) => p.event), ...pending.map((p) => p.event)];
-      pending = [];
-      nextId = 0;
-      const seen = new Set<string>();
-      for (const event of events) {
-        const sig = safeSig(event);
-        if (seen.has(sig)) continue; // collapse duplicates carried across the merge
-        seen.add(sig);
-        pending.push({ id: nextId++, event, sig });
+      const read = Promise.resolve(storage.getItem(key));
+      // A rejecting read must not surface as an unhandled rejection when the race is won by the
+      // timeout; the recovery path below re-attaches its own handlers.
+      read.catch(() => {});
+      const raced = await withTimeout(read, READ_TIMEOUT_MS);
+      if (raced === READ_TIMED_OUT) {
+        backlogUnread = true;
+        warnInDev(
+          `[wireai] the persisted analytics backlog at "${key}" took longer than ${READ_TIMEOUT_MS}ms ` +
+            "to read, so the queue started without it. The stored events are NOT discarded: writes " +
+            "are held back until the read lands, and the backlog is merged in then. If you see this " +
+            "on every cold start, your storage adapter is too slow to be on the launch path.",
+        );
+        void read
+          .then((late) => {
+            backlogUnread = false;
+            mergePersisted(parsePersisted(late));
+            // Send whatever was just recovered; without this it would wait for the next enqueue.
+            flush();
+          })
+          .catch(() => {
+            // The slow read ultimately failed → nothing to preserve, resume normal persistence.
+            backlogUnread = false;
+            persist();
+          });
+        return;
       }
-      enforceSizeCap();
-      persist();
+      mergePersisted(parsePersisted(raced));
     } catch {
       // Unreadable backlog → start empty; nothing enqueued in-memory is lost.
     }

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,15 +164,18 @@ 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. `errors` is the server's planned per-event
- *  reason list; it is read defensively because no deployed server sends it yet. */
+/** 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[] };
 
 /**
@@ -153,7 +199,17 @@ const readEventsAck = async (res: unknown): Promise<EventsAck | undefined> => {
     if (typeof skipped !== "number" || !Number.isFinite(skipped)) return undefined;
     const reasons = Array.isArray(body?.errors)
       ? body.errors
-          .map((e) => (e as { reason?: unknown } | null)?.reason)
+          .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 };

package/src/cards/CardGridSelectCard.tsx

@@ -104,7 +104,7 @@ const _OptionCard: React.FC<OptionCardProps> = ({ opt, isSelected, multiSelect,
   const handlePressOut = useCallback(() => pressTo(1), [pressTo]);
 
   // Selected fill: accent border + tinted wash on an absolute overlay whose opacity crossfades
-  // (native driver — see EXTRACTED-SPEC.md D7). Reduce motion: snap.
+  // (native driver, never a color interpolation). Reduce motion: snap.
   const selectT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
   useEffect(() => {
     const anim = Animated.timing(selectT, {

package/src/cards/ChipSelectCard.tsx

@@ -80,7 +80,7 @@ const _ChipItem: React.FC<ChipItemProps> = ({ chip, isSelected, multiSelect, onT
   const handlePressOut = useCallback(() => pressTo(1), [pressTo]);
 
   // Selected fill: full accent pill, crossfaded in over 160ms on a native-driver
-  // opacity overlay (EXTRACTED-SPEC.md D7). Reduce motion: instant swap.
+  // opacity overlay, never a color interpolation. Reduce motion: instant swap.
   const fillT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
   useEffect(() => {
     const anim = Animated.timing(fillT, {
@@ -94,7 +94,7 @@ const _ChipItem: React.FC<ChipItemProps> = ({ chip, isSelected, multiSelect, onT
   }, [isSelected, reduced, fillT]);
 
   // Check pop on select (the width-slide of the canvas is a layout animation the
-  // native driver can't express — see EXTRACTED-SPEC.md D4).
+  // native driver can't express, so it stays on the JS driver deliberately).
   const checkT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
   useEffect(() => {
     if (!isSelected) {