pulse-updates 1.1.0 → 1.2.0

package/src/init.ts

@@ -30,8 +30,21 @@ import {
   type ConfigContext,
   type ConfigStorage,
   type ConfigValue,
+  type ConfigSignature,
+  getConfigInfo,
+  getConfigBoolean,
+  getConfigNumber,
+  getConfigString,
+  getConfigJson,
 } from './config';
-import { configureTracking } from './track';
+import {
+  configureTracking,
+  disposeTracking,
+  flushEvents,
+  getTrackingInfo,
+  track,
+  type TrackedEventInput,
+} from './track';
 
 export interface InitPulseOptions {
   /** Where Pulse lives, e.g. https://pulse.example.com — no path. */
@@ -53,6 +66,9 @@ export interface InitPulseOptions {
   /** The store build, e.g. "5.2.0". Needed to target a rollout at a version. */
   appVersion?: string;
 
+  /** Locale override. When omitted the installed RN locale adapter is detected. */
+  language?: string;
+
   /**
    * A stable id for this install. Left out, one is minted and persisted.
    *
@@ -68,6 +84,19 @@ export interface InitPulseOptions {
   /** Attributes a rule can target — a plan, a storefront. Keep them few and stable. */
   getUserAttributes?: () => Record<string, string> | undefined;
 
+  /** Initial analytics consent or a live consent reader. Defaults to granted for compatibility. */
+  analyticsConsent?: boolean | (() => boolean);
+
+  /** Privacy guardrails applied to every track() call. */
+  eventPropertyAllowlist?: readonly string[];
+  redactEventProperties?: readonly string[];
+
+  /** Signed config uses the same Ed25519 public key as OTA updates. */
+  signingPublicKey?: string;
+  signingKeyId?: string;
+  requireConfigSignature?: boolean;
+  verifyConfigSignature?: (canonicalPayload: string, signature: ConfigSignature) => boolean | Promise<boolean>;
+
   /** Foreground poll interval for the config. 0 disables it; launch and resume still fetch. */
   pollIntervalMs?: number;
 
@@ -85,50 +114,201 @@ export interface InitPulseOptions {
 
 const DEVICE_ID_KEY = 'pulse.device-id';
 
+export interface PulseHealth {
+  appSlug: string;
+  deviceId: string;
+  config: ReturnType<typeof getConfigInfo>;
+  events: ReturnType<typeof getTrackingInfo>;
+  analyticsConsent: boolean;
+}
+
+export interface PulseClient {
+  deviceId: string;
+  configUrl: string;
+  trackUrl: string;
+  track: (event: string, props?: TrackedEventInput['props'], time?: Date) => void;
+  flush: () => Promise<number>;
+  setUser: (userId?: string, attributes?: Record<string, string>) => void;
+  clearUser: () => void;
+  setAnalyticsConsent: (granted: boolean) => void;
+  resetInstallId: () => string;
+  health: () => PulseHealth;
+  config: {
+    boolean: typeof getConfigBoolean;
+    number: typeof getConfigNumber;
+    string: typeof getConfigString;
+    json: typeof getConfigJson;
+    refresh: typeof fetchConfig;
+  };
+  dispose: () => Promise<void>;
+}
+
+export interface AsyncPulseStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+
+let activeClient: PulseClient | null = null;
+let stopActiveRefresh: (() => void) | null = null;
+
 /** Wires config and events, and returns the context the two share. */
-export function initPulse(opts: InitPulseOptions): { deviceId: string; configUrl: string; trackUrl: string } {
+export function initPulse(opts: InitPulseOptions): PulseClient {
+  // Reconfiguration is synchronous. Calling the old async dispose without awaiting
+  // it lets its eventual flush tear down the brand-new tracker — exactly the race a
+  // fast app switch or test setup triggers. Persist the old outbox, stop its refresh,
+  // then configure the new app in one uninterrupted turn.
+  stopActiveRefresh?.();
+  disposeTracking();
+  activeClient = null;
+  stopActiveRefresh = null;
   const base = opts.apiUrl.replace(/\/+$/, '');
   const slug = opts.appSlug.trim();
   const configUrl = `${base}/pulse/config/${slug}`;
   const trackUrl = `${base}/pulse/track/${slug}`;
 
-  const deviceId = opts.deviceId?.trim() || resolveDeviceId(opts.storage);
+  const deviceStorageKey = `pulse.${slug}.device-id`;
+  let deviceId = opts.deviceId?.trim() || resolveDeviceId(opts.storage, deviceStorageKey);
   const platform = detectPlatform();
   const osVersion = detectOsVersion();
+  const appVersion = opts.appVersion ?? detectAppVersion();
+  const language = opts.language ?? detectLanguage();
+  let userId: string | undefined;
+  let userAttributes: Record<string, string> | undefined;
+  let consentOverride: boolean | undefined = typeof opts.analyticsConsent === 'boolean'
+    ? opts.analyticsConsent
+    : undefined;
+
+  const hasConsent = (): boolean => consentOverride ??
+    (typeof opts.analyticsConsent === 'function' ? opts.analyticsConsent() : true);
 
   const getContext = (): ConfigContext => ({
     platform,
     osVersion,
-    appVersion: opts.appVersion,
+    appVersion,
+    language,
     deviceId,
-    userId: opts.getUserId?.(),
-    userAttributes: opts.getUserAttributes?.(),
+    userId: userId ?? opts.getUserId?.(),
+    userAttributes: userAttributes ?? opts.getUserAttributes?.(),
   });
 
   configureConfig({
     url: configUrl,
     defaults: opts.defaults,
     storage: opts.storage,
+    storageKey: `pulse.${slug}.config.v1`,
     getContext,
     pollIntervalMs: opts.pollIntervalMs,
     onError: opts.onError,
+    signingPublicKey: opts.signingPublicKey,
+    signingKeyId: opts.signingKeyId,
+    requireSignature: opts.requireConfigSignature,
+    verifySignature: opts.verifyConfigSignature ??
+      (opts.requireConfigSignature && !opts.signingPublicKey ? verifyWithNativeKey : undefined),
   });
 
   configureTracking({
     url: trackUrl,
     getContext,
     flushIntervalMs: opts.flushIntervalMs,
+    storage: opts.storage,
+    storageKey: `pulse.${slug}.events.v1`,
+    hasConsent,
+    propertyAllowlist: opts.eventPropertyAllowlist,
+    redactProperties: opts.redactEventProperties,
+    appState: opts.appState,
     onIgnored: opts.onIgnoredEvents,
     onError: opts.onError,
   });
 
+  // The two fields nothing can derive, said out loud when they are missing. Both
+  // fail silently and late: without a version, every rule and slice that names one
+  // simply does not match this install — which reads as "the rollout did nothing".
+  // Without storage the id is new on every launch, so the arm is re-dealt each time
+  // and no experiment can mean anything.
+  if (!appVersion) {
+    opts.onError?.(new Error(
+      'Pulse: no appVersion given — version targeting and version slices will not match this install'));
+  }
+  if (!opts.storage && !opts.deviceId) {
+    opts.onError?.(new Error(
+      'Pulse: no storage and no deviceId — this install gets a new id every launch, which re-deals its arm'));
+  }
+
   // Fetch now rather than on the first read: a launch that reads the config before
   // the first response is the launch that runs on defaults, and defaults are the
   // off position of every flag.
   void fetchConfig();
-  startConfigAutoRefresh(opts.appState);
+  const stopRefresh = startConfigAutoRefresh(opts.appState);
+
+  const client: PulseClient = {
+    get deviceId() { return deviceId; },
+    configUrl,
+    trackUrl,
+    track,
+    flush: flushEvents,
+    setUser: (nextUserId, attributes) => {
+      userId = nextUserId?.trim() || undefined;
+      userAttributes = sanitizeAttributes(attributes);
+    },
+    clearUser: () => {
+      userId = undefined;
+      userAttributes = undefined;
+    },
+    setAnalyticsConsent: (granted) => { consentOverride = granted; },
+    resetInstallId: () => {
+      deviceId = randomId();
+      try { opts.storage?.set(deviceStorageKey, deviceId); } catch { /* memory-only fallback */ }
+      return deviceId;
+    },
+    health: () => ({ appSlug: slug, deviceId, config: getConfigInfo(), events: getTrackingInfo(), analyticsConsent: hasConsent() }),
+    config: {
+      boolean: getConfigBoolean,
+      number: getConfigNumber,
+      string: getConfigString,
+      json: getConfigJson,
+      refresh: fetchConfig,
+    },
+    dispose: async () => {
+      stopRefresh();
+      if (activeClient !== client) return;
+      await flushEvents();
+      // Another init may have taken ownership while this network flush was pending.
+      if (activeClient === client) {
+        disposeTracking();
+        activeClient = null;
+        stopActiveRefresh = null;
+      }
+    },
+  };
+  activeClient = client;
+  stopActiveRefresh = stopRefresh;
+  return client;
+}
 
-  return { deviceId, configUrl, trackUrl };
+/**
+ * AsyncStorage-friendly one-call setup. It preloads only Pulse's three app-scoped
+ * records, then exposes the same synchronous hot-path API as initPulse.
+ */
+export async function initPulseAsync(
+  opts: Omit<InitPulseOptions, 'storage'> & { storage: AsyncPulseStorage },
+): Promise<PulseClient> {
+  const slug = opts.appSlug.trim();
+  const keys = [
+    `pulse.${slug}.device-id`,
+    `pulse.${slug}.config.v1`,
+    `pulse.${slug}.events.v1`,
+    DEVICE_ID_KEY,
+  ];
+  const loaded = await Promise.all(keys.map(async (key) => [key, await opts.storage.getItem(key)] as const));
+  const memory = new Map(loaded.filter((entry): entry is readonly [string, string] => entry[1] !== null));
+  const storage: ConfigStorage = {
+    getString: (key) => memory.get(key),
+    set: (key, value) => {
+      memory.set(key, value);
+      void opts.storage.setItem(key, value);
+    },
+  };
+  return initPulse({ ...opts, storage });
 }
 
 /**
@@ -138,20 +318,28 @@ export function initPulse(opts: InitPulseOptions): { deviceId: string; configUrl
  * arm is a hash of it, so every launch would be a fresh coin toss and no experiment
  * could mean anything. Said out loud through onError rather than hidden.
  */
-function resolveDeviceId(storage?: ConfigStorage): string {
+function resolveDeviceId(storage?: ConfigStorage, key = DEVICE_ID_KEY): string {
   if (!storage) return randomId();
 
   try {
-    const existing = storage.getString(DEVICE_ID_KEY);
+    const existing = storage.getString(key) ?? storage.getString(DEVICE_ID_KEY);
     if (existing) return existing;
     const minted = randomId();
-    storage.set(DEVICE_ID_KEY, minted);
+    storage.set(key, minted);
     return minted;
   } catch {
     return randomId();
   }
 }
 
+function sanitizeAttributes(attributes?: Record<string, string>): Record<string, string> | undefined {
+  if (!attributes) return undefined;
+  const clean = Object.fromEntries(Object.entries(attributes)
+    .filter(([key, value]) => key.trim() !== '' && typeof value === 'string')
+    .slice(0, 50));
+  return Object.keys(clean).length > 0 ? clean : undefined;
+}
+
 function randomId(): string {
   const bytes = new Uint8Array(16);
   const crypto = (globalThis as { crypto?: { getRandomValues?: (a: Uint8Array) => void } }).crypto;
@@ -194,3 +382,44 @@ function detectOsVersion(): string | undefined {
     return undefined;
   }
 }
+
+function detectAppVersion(): string | undefined {
+  try {
+    // Optional by design: most RN apps already carry this package, plain JS hosts do not.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const loaded = require('react-native-device-info') as { default?: { getVersion?: () => string }; getVersion?: () => string };
+    return loaded.default?.getVersion?.() ?? loaded.getVersion?.();
+  } catch {
+    return undefined;
+  }
+}
+
+async function verifyWithNativeKey(
+  canonicalPayload: string,
+  signature: ConfigSignature,
+): Promise<boolean> {
+  try {
+    // Kept lazy so init/config remain usable in Node, web and test hosts without RN.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const updates = require('./PulseUpdates') as {
+      verifyConfigSignatureAsync?: (payload: string, value: ConfigSignature) => Promise<boolean>;
+    };
+    return await updates.verifyConfigSignatureAsync?.(canonicalPayload, signature) ?? false;
+  } catch {
+    return false;
+  }
+}
+
+function detectLanguage(): string | undefined {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const localize = require('react-native-localize') as { getLocales?: () => Array<{ languageTag?: string }> };
+    return localize.getLocales?.()[0]?.languageTag;
+  } catch {
+    try {
+      return Intl.DateTimeFormat().resolvedOptions().locale;
+    } catch {
+      return undefined;
+    }
+  }
+}

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)}`;
+}