pulse-updates 1.1.1 → 1.2.0

package/src/track.ts

@@ -20,7 +20,7 @@
  * everybody sees.
  */
 
-import type { ConfigContext } from './config';
+import type { ConfigContext, ConfigStorage } from './config';
 
 export interface TrackOptions {
   /**
@@ -43,9 +43,35 @@ export interface TrackOptions {
   /** Events held before the oldest are dropped. Default 500. */
   maxQueue?: number;
 
+  /** Persists the outbox across process death. Use the same storage passed to initPulse. */
+  storage?: ConfigStorage;
+
+  /** App-scoped persistence key. initPulse supplies one automatically. */
+  storageKey?: string;
+
+  /** Per-request timeout. Default 10s. */
+  timeoutMs?: number;
+
+  /** Maximum delivery attempts before an event is dropped. Default 10. */
+  maxAttempts?: number;
+
+  /** Return false until analytics consent exists. No event is retained before consent. */
+  hasConsent?: () => boolean;
+
+  /** Only these property keys may leave the process. */
+  propertyAllowlist?: readonly string[];
+
+  /** These allowed properties are replaced with "[REDACTED]". */
+  redactProperties?: readonly string[];
+
+  /** Foreground/background lifecycle used for a best-effort final flush. */
+  appState?: { addEventListener: (type: 'change', handler: (state: string) => void) => { remove: () => void } };
+
   /** Called with the event keys the server did not recognise. */
   onIgnored?: (events: string[]) => void;
 
+  onDropped?: (count: number, reason: 'queue-full' | 'max-attempts' | 'no-consent') => void;
+
   onError?: (error: unknown) => void;
 }
 
@@ -56,19 +82,27 @@ export interface TrackedEventInput {
 }
 
 interface QueuedEvent {
+  id: string;
   event: string;
   time: string;
   props: Record<string, string>;
+  attempts: number;
 }
 
 const DEFAULT_FLUSH_MS = 10_000;
 const DEFAULT_MAX_BATCH = 100;
 const DEFAULT_MAX_QUEUE = 500;
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_ATTEMPTS = 10;
+const DEFAULT_STORAGE_KEY = 'pulse.events.v1';
 
 let options: TrackOptions | null = null;
 let queue: QueuedEvent[] = [];
 let timer: ReturnType<typeof setInterval> | null = null;
 let sending = false;
+let nextAttemptAt = 0;
+let lifecycleSubscription: { remove: () => void } | null = null;
+let trackingGeneration = 0;
 
 /** Turns a config url into the track url; leaves an explicit track url alone. */
 function trackUrl(url: string): string {
@@ -79,8 +113,14 @@ function trackUrl(url: string): string {
 }
 
 export function configureTracking(opts: TrackOptions): void {
+  disposeTracking();
   options = opts;
+  queue = readQueue(opts);
+  nextAttemptAt = 0;
   startTimer();
+  lifecycleSubscription = opts.appState?.addEventListener('change', (state) => {
+    if (state !== 'active') void flushEvents();
+  }) ?? null;
 }
 
 /**
@@ -90,17 +130,29 @@ export function configureTracking(opts: TrackOptions): void {
  */
 export function track(event: string, props?: TrackedEventInput['props'], time?: Date): void {
   if (!options || !event) return;
+  if (options.hasConsent?.() === false) {
+    options.onDropped?.(1, 'no-consent');
+    return;
+  }
 
   const flat: Record<string, string> = {};
+  const allow = options.propertyAllowlist ? new Set(options.propertyAllowlist) : null;
+  const redact = new Set(options.redactProperties ?? []);
   for (const [key, value] of Object.entries(props ?? {})) {
     if (value === null || value === undefined) continue;
-    flat[key] = typeof value === 'string' ? value : String(value);
+    if (allow && !allow.has(key)) continue;
+    flat[key] = redact.has(key) ? '[REDACTED]' : (typeof value === 'string' ? value : String(value));
   }
 
-  queue.push({ event, time: (time ?? new Date()).toISOString(), props: flat });
+  queue.push({ id: randomEventId(), event, time: (time ?? new Date()).toISOString(), props: flat, attempts: 0 });
 
   const maxQueue = options.maxQueue ?? DEFAULT_MAX_QUEUE;
-  if (queue.length > maxQueue) queue = queue.slice(queue.length - maxQueue);
+  if (queue.length > maxQueue) {
+    const dropped = queue.length - maxQueue;
+    queue = queue.slice(dropped);
+    options.onDropped?.(dropped, 'queue-full');
+  }
+  persistQueue();
 
   if (queue.length >= (options.maxBatch ?? DEFAULT_MAX_BATCH)) void flushEvents();
 }
@@ -113,9 +165,10 @@ export function track(event: string, props?: TrackedEventInput['props'], time?:
  * after launch, when the first events of a session are the ones a funnel needs most.
  */
 export async function flushEvents(): Promise<number> {
-  if (!options || sending || queue.length === 0) return 0;
+  if (!options || sending || queue.length === 0 || Date.now() < nextAttemptAt) return 0;
 
   const opts = options;
+  const requestGeneration = trackingGeneration;
   const ctx = opts.getContext?.() ?? {};
 
   // Without a device id the server cannot put the event in an arm, and an empty id
@@ -125,8 +178,14 @@ export async function flushEvents(): Promise<number> {
 
   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;
+  const timeout = controller
+    ? setTimeout(() => controller.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+    : null;
+
   try {
     const response = await fetch(trackUrl(opts.url), {
       method: 'POST',
@@ -136,26 +195,36 @@ export async function flushEvents(): Promise<number> {
         userId: ctx.userId,
         platform: ctx.platform,
         appVersion: ctx.appVersion,
-        events: batch.map((e) => ({ event: e.event, time: e.time, props: e.props })),
+        events: batch.map((e) => ({ id: e.id, event: e.event, time: e.time, props: e.props })),
       }),
+      signal: controller?.signal,
     });
 
     if (!response.ok) {
       // Rate limited or briefly down: keep the events, try on the next tick.
-      queue = [...batch, ...queue];
+      if (requestGeneration === trackingGeneration && options === opts) {
+        requeueWithBackoff(batch, response.status);
+      } else {
+        restoreStaleBatch(opts, batch, response.status);
+      }
       if (response.status !== 429) opts.onError?.(new Error(`Pulse track failed: ${response.status}`));
       return 0;
     }
 
     const body = (await response.json()) as { accepted?: number; ignored?: string[] };
+    if (requestGeneration !== trackingGeneration || options !== opts) return body.accepted ?? 0;
     if (body.ignored && body.ignored.length > 0) opts.onIgnored?.(body.ignored);
+    nextAttemptAt = 0;
+    persistQueue();
     return body.accepted ?? 0;
   } catch (error) {
-    queue = [...batch, ...queue];
+    if (requestGeneration === trackingGeneration && options === opts) requeueWithBackoff(batch);
+    else restoreStaleBatch(opts, batch);
     opts.onError?.(error);
     return 0;
   } finally {
-    sending = false;
+    if (timeout) clearTimeout(timeout);
+    if (requestGeneration === trackingGeneration) sending = false;
   }
 }
 
@@ -164,14 +233,32 @@ export function pendingEventCount(): number {
   return queue.length;
 }
 
+export function getTrackingInfo(): {
+  queueDepth: number;
+  sending: boolean;
+  nextAttemptAt: number;
+} {
+  return { queueDepth: queue.length, sending, nextAttemptAt };
+}
+
+/** Stop timers and listeners while preserving the durable outbox. */
+export function disposeTracking(): void {
+  trackingGeneration += 1;
+  if (timer) clearInterval(timer);
+  timer = null;
+  lifecycleSubscription?.remove();
+  lifecycleSubscription = null;
+  persistQueue();
+  options = null;
+  sending = false;
+}
+
 export function stopTracking(): void {
-  if (timer) {
-    clearInterval(timer);
-    timer = null;
-  }
+  disposeTracking();
   options = null;
   queue = [];
   sending = false;
+  nextAttemptAt = 0;
 }
 
 function startTimer(): void {
@@ -182,3 +269,94 @@ function startTimer(): void {
   // and a CLI importing this should still be able to exit.
   (timer as unknown as { unref?: () => void }).unref?.();
 }
+
+function requeueWithBackoff(batch: QueuedEvent[], status?: number): void {
+  if (!options) return;
+  const maxAttempts = options.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);
+  }
+  queue = [...retryable, ...queue];
+  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));
+  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);
+  }
+  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;
+  }
+
+  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.
+  }
+}
+
+function storageKey(opts: TrackOptions): string {
+  return opts.storageKey?.trim() || DEFAULT_STORAGE_KEY;
+}
+
+function readQueue(opts: TrackOptions): QueuedEvent[] {
+  if (!opts.storage) return [];
+  try {
+    const raw = opts.storage.getString(storageKey(opts));
+    if (!raw) return [];
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return 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));
+  } catch {
+    return [];
+  }
+}
+
+function persistQueue(): void {
+  if (!options?.storage) return;
+  try {
+    options.storage.set(storageKey(options), JSON.stringify(queue));
+  } catch {
+    // Telemetry persistence must never become an app failure.
+  }
+}
+
+function randomEventId(): string {
+  const cryptoLike = globalThis.crypto as { randomUUID?: () => string } | undefined;
+  if (typeof cryptoLike?.randomUUID === 'function') return cryptoLike.randomUUID();
+  return `evt-${Date.now()}-${Math.random().toString(36).slice(2, 14)}`;
+}

package/src/usePulseUpdates.ts

@@ -27,6 +27,7 @@ export interface UsePulseUpdatesResult {
 }
 
 export function usePulseUpdates(): UsePulseUpdatesResult {
+  const [nativeState, setNativeState] = useState(PulseUpdates.getUpdatesState);
   const [isChecking, setIsChecking] = useState(false);
   const [isDownloading, setIsDownloading] = useState(false);
   const [availableUpdate, setAvailableUpdate] = useState<PulseManifest | null>(null);
@@ -35,11 +36,15 @@ export function usePulseUpdates(): UsePulseUpdatesResult {
 
   // Refresh state on mount to get latest values after configure
   useEffect(() => {
-    PulseUpdates.refreshStateAsync().catch(() => {});
+    const unsubscribe = PulseUpdates.onUpdatesStateChange(() => {
+      setNativeState(PulseUpdates.getUpdatesState());
+    });
+    void PulseUpdates.refreshStateAsync();
+    return unsubscribe;
   }, []);
 
   useEffect(() => {
-    if (!PulseUpdates.isEnabled) return;
+    if (!nativeState.isEnabled) return;
 
     const subscription = PulseUpdates.addUpdateListener((event) => {
       switch (event.type) {
@@ -59,10 +64,10 @@ export function usePulseUpdates(): UsePulseUpdatesResult {
     });
 
     return () => subscription.remove();
-  }, []);
+  }, [nativeState.isEnabled]);
 
   const checkForUpdate = useCallback(async (): Promise<UpdateCheckResult> => {
-    if (!PulseUpdates.isEnabled) {
+    if (!nativeState.isEnabled) {
       return { isAvailable: false };
     }
 
@@ -84,10 +89,10 @@ export function usePulseUpdates(): UsePulseUpdatesResult {
     } finally {
       setIsChecking(false);
     }
-  }, []);
+  }, [nativeState.isEnabled]);
 
   const downloadUpdate = useCallback(async (): Promise<UpdateFetchResult> => {
-    if (!PulseUpdates.isEnabled) {
+    if (!nativeState.isEnabled) {
       return { isNew: false };
     }
 
@@ -107,23 +112,23 @@ export function usePulseUpdates(): UsePulseUpdatesResult {
     } finally {
       setIsDownloading(false);
     }
-  }, []);
+  }, [nativeState.isEnabled]);
 
   const reload = useCallback(async (): Promise<void> => {
-    if (!PulseUpdates.isEnabled) return;
+    if (!nativeState.isEnabled) return;
     await PulseUpdates.reloadAsync();
-  }, []);
+  }, [nativeState.isEnabled]);
 
   return {
-    isEnabled: PulseUpdates.isEnabled,
+    isEnabled: nativeState.isEnabled,
     isChecking,
     isDownloading,
-    updateId: PulseUpdates.updateId,
-    runtimeVersion: PulseUpdates.runtimeVersion,
-    channel: PulseUpdates.channel,
-    manifest: PulseUpdates.manifest,
-    isEmbeddedLaunch: PulseUpdates.isEmbeddedLaunch,
-    createdAt: PulseUpdates.createdAt,
+    updateId: nativeState.updateId,
+    runtimeVersion: nativeState.runtimeVersion,
+    channel: nativeState.channel,
+    manifest: nativeState.manifest,
+    isEmbeddedLaunch: nativeState.isEmbeddedLaunch,
+    createdAt: nativeState.createdAt,
     build: PulseUpdates.getUpdateBuild(),
     availableUpdate,
     downloadedUpdate,