pulse-updates 1.3.7 → 1.3.8

package/src/track.ts

@@ -52,7 +52,7 @@ export interface TrackOptions {
   /** Events per request. The server refuses more than 100. */
   maxBatch?: number;
 
-  /** Events held before the oldest are dropped. Default 500. */
+  /** Best-effort events held before the oldest are dropped. Durable idempotent rows are never evicted. Default 500. */
   maxQueue?: number;
 
   /** Persists the outbox across process death. Use the same storage passed to initPulse. */
@@ -64,10 +64,13 @@ export interface TrackOptions {
   /** Per-request timeout. Default 10s. */
   timeoutMs?: number;
 
-  /** Maximum delivery attempts before an event is dropped. Default 10. */
+  /** Maximum delivery attempts before a best-effort event is dropped. Durable idempotent events retry until server ACK. Default 10. */
   maxAttempts?: number;
 
-  /** Return false until analytics consent exists. No event is retained before consent. */
+  /**
+   * Return false until analytics consent exists. No event is retained before consent. Consent is
+   * sampled at enqueue; an event already durably accepted remains eligible for later delivery.
+   */
   hasConsent?: () => boolean;
 
   /** Only these property keys may leave the process. */
@@ -99,6 +102,8 @@ interface QueuedEvent {
   time: string;
   props: Record<string, string>;
   attempts: number;
+  /** Caller-owned events are retained until the server ACKs their stable id. */
+  durable?: true;
 }
 
 const DEFAULT_FLUSH_MS = 10_000;
@@ -118,6 +123,7 @@ let sending = false;
 let nextAttemptAt = 0;
 let lifecycleSubscription: { remove: () => void } | null = null;
 let trackingGeneration = 0;
+const asynchronousStorageAdapters = new WeakSet<object>();
 
 /** Turns a config url into the track url; leaves an explicit track url alone. */
 function trackUrl(url: string): string {
@@ -147,10 +153,52 @@ export function configureTracking(opts: TrackOptions): void {
  * caller has to wrap.
  */
 export function track(event: string, props?: TrackedEventInput['props'], time?: Date): void {
-  if (!options || !event) return;
-  if (options.hasConsent?.() === false) {
+  void enqueueEvent(randomEventId(), event, props, time, false);
+}
+
+/**
+ * Durably enqueue one logical event with a caller-owned UUID. Replaying the same id is safe:
+ * Pulse's server/read model deduplicates it, while the local outbox avoids duplicate rows that
+ * are still pending. `true` means the event is present in persistent storage, not delivered yet;
+ * once acknowledged, Track keeps it in that outbox through retries and process restarts until a
+ * successful server response removes it transactionally.
+ */
+export function trackIdempotent(
+  eventId: string,
+  event: string,
+  props?: TrackedEventInput['props'],
+  time?: Date,
+): boolean {
+  const normalizedId = eventId.trim().toLowerCase();
+  if (!UUID_PATTERN.test(normalizedId)) return false;
+  return enqueueEvent(normalizedId, event, props, time, true);
+}
+
+function enqueueEvent(
+  eventId: string,
+  event: string,
+  props: TrackedEventInput['props'],
+  time: Date | undefined,
+  requirePersistentAck: boolean,
+): boolean {
+  if (!options || !event) return false;
+  try {
+    if (options.hasConsent?.() === false) {
+      options.onDropped?.(1, 'no-consent');
+      return false;
+    }
+  } catch {
     options.onDropped?.(1, 'no-consent');
-    return;
+    return false;
+  }
+
+  if (requirePersistentAck) {
+    // Probe with the unchanged queue before accepting caller-owned data. This discovers custom
+    // adapters that secretly return a Promise without ever placing the terminal event in Track;
+    // the upstream Links outbox remains the single source of truth.
+    if (!options.storage
+      || !supportsDurableSyncWrites(options.storage)
+      || !persistQueue()) return false;
   }
 
   const flat: Record<string, string> = {};
@@ -162,25 +210,81 @@ export function track(event: string, props?: TrackedEventInput['props'], time?:
     flat[key] = redact.has(key) ? '[REDACTED]' : (typeof value === 'string' ? value : String(value));
   }
 
-  queue.push({ id: randomEventId(), event, time: (time ?? new Date()).toISOString(), props: flat, attempts: 0 });
+  let occurredAt: string;
+  try {
+    occurredAt = (time ?? new Date()).toISOString();
+  } catch {
+    return false;
+  }
+
+  const existing = queue.find((queued) => queued.id === eventId);
+  if (existing) {
+    const sameLogicalEvent = existing.event === event
+      && existing.time === occurredAt
+      && JSON.stringify(existing.props) === JSON.stringify(flat);
+    if (!sameLogicalEvent) return false;
+    if (requirePersistentAck && existing.durable !== true) {
+      existing.durable = true;
+      if (!persistQueue()) {
+        delete existing.durable;
+        persistQueue();
+        return false;
+      }
+    }
+    return true;
+  }
 
-  const maxQueue = options.maxQueue ?? DEFAULT_MAX_QUEUE;
-  if (queue.length > maxQueue) {
-    const dropped = queue.length - maxQueue;
-    queue = queue.slice(dropped);
-    options.onDropped?.(dropped, 'queue-full');
+  const queueBeforeDurableEnqueue = requirePersistentAck ? [...queue] : null;
+  queue.push({
+    id: eventId,
+    event,
+    time: occurredAt,
+    props: flat,
+    attempts: 0,
+    ...(requirePersistentAck ? { durable: true as const } : {}),
+  });
+
+  const maxQueue = Math.max(0, options.maxQueue ?? DEFAULT_MAX_QUEUE);
+  let dropped = 0;
+  while (queue.length > maxQueue) {
+    // Never evict a previously acknowledged durable event to make room. When every queued row
+    // is durable, the newest enqueue is refused and its upstream outbox remains authoritative.
+    const bestEffortIndex = queue.findIndex((queued) => queued.durable !== true);
+    if (bestEffortIndex < 0) {
+      // The queue can already exceed a newly lowered max after restart. Refuse only the newest
+      // durable enqueue; previously acknowledged records must still reach the server.
+      const newestIndex = queue.findIndex((queued) => queued.id === eventId);
+      if (newestIndex >= 0) {
+        queue.splice(newestIndex, 1);
+        dropped += 1;
+      }
+      break;
+    }
+    const index = bestEffortIndex;
+    queue.splice(index, 1);
+    dropped += 1;
   }
-  persistQueue();
+  const retained = queue.some((queued) => queued.id === eventId);
+  const persisted = persistQueue();
+  if (requirePersistentAck && (!retained || !persisted)) {
+    queue = queueBeforeDurableEnqueue ?? queue;
+    // If an adapter revealed itself as asynchronous only on the second write, schedule a
+    // compensating best-effort mirror without the caller-owned event.
+    persistQueue();
+    return false;
+  }
+  if (dropped > 0) options.onDropped?.(dropped, 'queue-full');
 
   if (queue.length >= (options.maxBatch ?? DEFAULT_MAX_BATCH)) void flushEvents();
+  return retained && (!requirePersistentAck || persisted);
 }
 
 /**
  * Send what is queued. Returns how many events the server accepted.
  *
- * Failures put the batch back at the front of the queue rather than dropping it: the
- * usual cause is a network that is about to come back, and the usual moment is right
- * after launch, when the first events of a session are the ones a funnel needs most.
+ * The batch remains in the durable queue while HTTP is in flight and is removed only after a
+ * successful response is also persisted locally. This intentionally permits duplicate replay
+ * after a crash, while a caller-owned event id lets the server/read model deduplicate it.
  */
 export async function flushEvents(): Promise<number> {
   if (!options || sending || queue.length === 0 || Date.now() < nextAttemptAt) return 0;
@@ -196,8 +300,6 @@ export async function flushEvents(): Promise<number> {
   const requestDeviceId = anonymousInstallation ? analyticsInstallationId : ctx.deviceId;
 
   const batch = queue.slice(0, opts.maxBatch ?? DEFAULT_MAX_BATCH);
-  queue = queue.slice(batch.length);
-  persistQueue();
   sending = true;
 
   const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
@@ -222,11 +324,9 @@ export async function flushEvents(): Promise<number> {
     });
 
     if (!response.ok) {
-      // Rate limited or briefly down: keep the events, try on the next tick.
+      // Rate limited or briefly down: the batch never left the durable queue.
       if (requestGeneration === trackingGeneration && options === opts) {
-        requeueWithBackoff(batch, response.status);
-      } else {
-        restoreStaleBatch(opts, batch, response.status);
+        markBatchForRetry(batch, response.status);
       }
       if (response.status !== 429) opts.onError?.(new Error(`Pulse track failed: ${response.status}`));
       return 0;
@@ -236,11 +336,15 @@ export async function flushEvents(): Promise<number> {
     if (requestGeneration !== trackingGeneration || options !== opts) return body.accepted ?? 0;
     if (body.ignored && body.ignored.length > 0) opts.onIgnored?.(body.ignored);
     nextAttemptAt = 0;
-    persistQueue();
+    if (!acknowledgeBatch(opts, batch)) {
+      // The server may already have accepted the ids. Keep and replay them rather than creating
+      // the loss window between remote ACK and local deletion.
+      nextAttemptAt = Date.now() + retryDelayFor(batch);
+      opts.onError?.(new Error('Pulse track acknowledgement was not persisted'));
+    }
     return body.accepted ?? 0;
   } catch (error) {
-    if (requestGeneration === trackingGeneration && options === opts) requeueWithBackoff(batch);
-    else restoreStaleBatch(opts, batch);
+    if (requestGeneration === trackingGeneration && options === opts) markBatchForRetry(batch);
     opts.onError?.(error);
     return 0;
   } finally {
@@ -292,59 +396,93 @@ function startTimer(): void {
   (timer as unknown as { unref?: () => void }).unref?.();
 }
 
-function requeueWithBackoff(batch: QueuedEvent[], status?: number): void {
+function markBatchForRetry(batch: QueuedEvent[], status?: number): void {
   if (!options) return;
   const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
-  const retryable: QueuedEvent[] = [];
+  const batchIds = new Set(batch.map((event) => event.id));
   let dropped = 0;
-  for (const event of batch) {
-    const next = { ...event, attempts: event.attempts + 1 };
-    if (next.attempts >= maxAttempts && status !== 429) dropped++;
-    else retryable.push(next);
-  }
-  queue = [...retryable, ...queue];
+  queue = queue.flatMap((event) => {
+    if (!batchIds.has(event.id)) return [event];
+    const next = { ...event, attempts: Math.min(event.attempts + 1, 100_000) };
+    if (next.durable !== true && next.attempts >= maxAttempts && status !== 429) {
+      dropped += 1;
+      return [];
+    }
+    return [next];
+  });
   if (dropped > 0) options.onDropped?.(dropped, 'max-attempts');
-  const attempts = retryable.reduce((max, event) => Math.max(max, event.attempts), 1);
-  const base = Math.min(60_000, 1_000 * 2 ** Math.min(attempts - 1, 6));
-  nextAttemptAt = Date.now() + base + Math.floor(Math.random() * Math.max(1, base / 4));
+  nextAttemptAt = Date.now() + retryDelayFor(batch.map((event) => ({
+    ...event,
+    attempts: Math.min(event.attempts + 1, 100_000),
+  })));
   persistQueue();
 }
 
-/**
- * An old request may fail after another app has been configured. Its rows belong in
- * the old app's outbox, never in the new app's in-memory queue. When the same app was
- * merely reconfigured, merge them back into the live queue so it need not restart to
- * see them; otherwise persist directly under the captured app-scoped key.
- */
-function restoreStaleBatch(opts: TrackOptions, batch: QueuedEvent[], status?: number): void {
-  const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
-  const retryable: QueuedEvent[] = [];
-  let dropped = 0;
-  for (const event of batch) {
-    const next = { ...event, attempts: event.attempts + 1 };
-    if (next.attempts >= maxAttempts && status !== 429) dropped++;
-    else retryable.push(next);
+function acknowledgeBatch(opts: TrackOptions, batch: QueuedEvent[]): boolean {
+  const acknowledgedIds = new Set(batch.map((event) => event.id));
+  const remaining = queue.filter((event) => !acknowledgedIds.has(event.id));
+  if (!opts.storage) {
+    queue = remaining;
+    return true;
   }
-  if (dropped > 0) opts.onDropped?.(dropped, 'max-attempts');
-  if (retryable.length === 0) return;
-
-  const currentOptions = options;
-  const sameOutbox = currentOptions?.storage === opts.storage &&
-    currentOptions !== null && storageKey(currentOptions) === storageKey(opts);
-  if (sameOutbox) {
-    queue = [...retryable, ...queue].slice(-(options?.maxQueue ?? DEFAULT_MAX_QUEUE));
-    persistQueue();
-    return;
+  const includesDurable = batch.some((event) => event.durable === true);
+  // Never schedule a destructive outbox write through an adapter already known to be async.
+  // The server may have accepted this batch, but retaining it for a deduplicated replay is safer
+  // than losing it during the gap before an asynchronous deletion reaches disk.
+  if (!supportsDurableSyncWrites(opts.storage)) {
+    if (includesDurable) return false;
+    queue = remaining;
+    // Best-effort events keep the historical AsyncStorage behavior: the in-memory batch drains
+    // after 2xx and the mirror may replay after a crash, but it cannot block or resend forever.
+    writeStorageValue(
+      opts.storage,
+      storageKey(opts),
+      JSON.stringify(remaining),
+      opts.onError,
+      true,
+    );
+    return true;
   }
-
-  if (!opts.storage) return;
-  try {
-    const stored = readQueue(opts);
-    const restored = [...retryable, ...stored].slice(-(opts.maxQueue ?? DEFAULT_MAX_QUEUE));
-    opts.storage.set(storageKey(opts), JSON.stringify(restored));
-  } catch {
-    // Best effort only; a telemetry recovery must not affect the new app session.
+  const persisted = writeStorageValue(
+    opts.storage,
+    storageKey(opts),
+    JSON.stringify(remaining),
+    opts.onError,
+    false,
+  );
+  if (!persisted) {
+    if (!includesDurable && !supportsDurableSyncWrites(opts.storage)) {
+      queue = remaining;
+      writeStorageValue(
+        opts.storage,
+        storageKey(opts),
+        JSON.stringify(remaining),
+        opts.onError,
+        true,
+      );
+      return true;
+    }
+    if (!supportsDurableSyncWrites(opts.storage)) {
+      // A conditional thenable may already have scheduled deletion. Immediately schedule the
+      // unchanged durable outbox behind it so a normal ordered async adapter restores the record.
+      writeStorageValue(
+        opts.storage,
+        storageKey(opts),
+        JSON.stringify(queue),
+        opts.onError,
+        true,
+      );
+    }
+    return false;
   }
+  queue = remaining;
+  return true;
+}
+
+function retryDelayFor(batch: QueuedEvent[]): number {
+  const attempts = batch.reduce((max, event) => Math.max(max, event.attempts), 1);
+  const base = Math.min(60_000, 1_000 * 2 ** Math.min(Math.max(attempts - 1, 0), 6));
+  return base + Math.floor(Math.random() * Math.max(1, base / 4));
 }
 
 function storageKey(opts: TrackOptions): string {
@@ -367,11 +505,15 @@ function resolveAnalyticsInstallationId(opts: TrackOptions): string {
 
   const generated = randomAnalyticsInstallationId();
   if (opts.storage) {
-    try {
-      opts.storage.set(analyticsInstallationIdStorageKey(opts), generated);
-    } catch {
-      // A telemetry identifier can stay memory-only when storage is unavailable.
-    }
+    // This identifier does not acknowledge delivery, so asynchronous best-effort persistence is
+    // acceptable. The helper still observes rejections and marks accidental thenable adapters.
+    writeStorageValue(
+      opts.storage,
+      analyticsInstallationIdStorageKey(opts),
+      generated,
+      opts.onError,
+      true,
+    );
   }
   return generated;
 }
@@ -383,25 +525,85 @@ function readQueue(opts: TrackOptions): QueuedEvent[] {
     if (!raw) return [];
     const parsed = JSON.parse(raw) as unknown;
     if (!Array.isArray(parsed)) return [];
-    return parsed.filter((item): item is QueuedEvent => Boolean(
+    const restored = parsed.filter((item): item is QueuedEvent => Boolean(
       item && typeof item === 'object' && typeof item.id === 'string' &&
       typeof item.event === 'string' && typeof item.time === 'string' &&
-      typeof item.props === 'object' && typeof item.attempts === 'number',
-    )).slice(-(opts.maxQueue ?? DEFAULT_MAX_QUEUE));
+      item.props && typeof item.props === 'object' && !Array.isArray(item.props) &&
+      typeof item.attempts === 'number' && Number.isSafeInteger(item.attempts) &&
+      item.attempts >= 0 && item.attempts <= 100_000 &&
+      ((item as QueuedEvent).durable === undefined || (item as QueuedEvent).durable === true),
+    ));
+    const maxQueue = Math.max(0, opts.maxQueue ?? DEFAULT_MAX_QUEUE);
+    if (restored.length <= maxQueue) return restored;
+    const selected = new Set<number>();
+    restored.forEach((event, index) => {
+      if (event.durable === true) selected.add(index);
+    });
+    // A lower max in a later app version may not erase already-ACKed durable rows. Fill any
+    // remaining capacity with the newest best-effort events, retaining original send order.
+    for (let index = restored.length - 1; index >= 0 && selected.size < maxQueue; index -= 1) {
+      if (restored[index]?.durable !== true) selected.add(index);
+    }
+    return restored.filter((_event, index) => selected.has(index));
   } catch {
     return [];
   }
 }
 
-function persistQueue(): void {
-  if (!options?.storage) return;
+function persistQueue(): boolean {
+  if (!options?.storage) return false;
+  // Best-effort track() still mirrors through AsyncStorage, but the return value stays false so
+  // trackIdempotent() cannot claim synchronous durability that the adapter has not provided.
+  return writeStorageValue(
+    options.storage,
+    storageKey(options),
+    JSON.stringify(queue),
+    options.onError,
+    true,
+  );
+}
+
+function supportsDurableSyncWrites(storage: ConfigStorage): boolean {
+  return storage.supportsDurableSyncWrites !== false
+    && !asynchronousStorageAdapters.has(storage as object);
+}
+
+function writeStorageValue(
+  storage: ConfigStorage,
+  key: string,
+  value: string,
+  onError: ((error: unknown) => void) | undefined,
+  allowKnownAsyncBestEffort: boolean,
+): boolean {
+  const declaredOrObservedAsync = !supportsDurableSyncWrites(storage);
+  if (declaredOrObservedAsync && !allowKnownAsyncBestEffort) return false;
   try {
-    options.storage.set(storageKey(options), JSON.stringify(queue));
-  } catch {
-    // Telemetry persistence must never become an app failure.
+    const result = (storage.set as unknown as (storageKey: string, stored: string) => unknown)(key, value);
+    if (isThenable(result)) {
+      asynchronousStorageAdapters.add(storage as object);
+      void Promise.resolve(result).catch((error) => reportStorageError(onError, error));
+      return false;
+    }
+    return !declaredOrObservedAsync;
+  } catch (error) {
+    reportStorageError(onError, error);
+    return false;
   }
 }
 
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (typeof value === 'object' && value !== null) || typeof value === 'function'
+    ? typeof (value as { then?: unknown }).then === 'function'
+    : false;
+}
+
+function reportStorageError(
+  onError: ((error: unknown) => void) | undefined,
+  error: unknown,
+): void {
+  try { onError?.(error); } catch { /* telemetry diagnostics never become an app failure */ }
+}
+
 function randomEventId(): string {
   const cryptoLike = globalThis.crypto as { randomUUID?: () => string } | undefined;
   if (typeof cryptoLike?.randomUUID === 'function') return cryptoLike.randomUUID();