pulse-updates 1.3.7 → 1.3.8

package/lib/typescript/track.d.ts

@@ -45,7 +45,7 @@ export interface TrackOptions {
     flushIntervalMs?: number;
     /** 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. */
     storage?: ConfigStorage;
@@ -53,9 +53,12 @@ export interface TrackOptions {
     storageKey?: string;
     /** 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. */
     propertyAllowlist?: readonly string[];
@@ -84,12 +87,20 @@ export declare function configureTracking(opts: TrackOptions): void;
  * caller has to wrap.
  */
 export declare function track(event: string, props?: TrackedEventInput['props'], time?: Date): void;
+/**
+ * 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 declare function trackIdempotent(eventId: string, event: string, props?: TrackedEventInput['props'], time?: Date): boolean;
 /**
  * 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 declare function flushEvents(): Promise<number>;
 /** How many events are waiting — for a caller that wants to flush before backgrounding. */

package/lib/typescript/track.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"track.d.ts","sourceRoot":"","sources":["../../src/track.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,aAAa,CAAC;IAEjC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,wBAAwB,CAAC;IAEpD,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAE3B,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtC,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC,0EAA0E;IAC1E,QAAQ,CAAC,EAAE;QAAE,gBAAgB,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,KAAK;YAAE,MAAM,EAAE,MAAM,IAAI,CAAA;SAAE,CAAA;KAAE,CAAC;IAE9G,+DAA+D;IAC/D,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAEvC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,cAAc,GAAG,YAAY,KAAK,IAAI,CAAC;IAE1F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrE,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAoCD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAY1D;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CA2B1F;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAiEnD;AAED,2FAA2F;AAC3F,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,eAAe,IAAI;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAEA;AAED,qEAAqE;AACrE,wBAAgB,eAAe,IAAI,IAAI,CAStC;AAED,wBAAgB,YAAY,IAAI,IAAI,CAOnC"}
+{"version":3,"file":"track.d.ts","sourceRoot":"","sources":["../../src/track.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,aAAa,CAAC;IAEjC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,wBAAwB,CAAC;IAEpD,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,qHAAqH;IACrH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,qIAAqI;IACrI,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;IAE3B,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEtC,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC,0EAA0E;IAC1E,QAAQ,CAAC,EAAE;QAAE,gBAAgB,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,KAAK;YAAE,MAAM,EAAE,MAAM,IAAI,CAAA;SAAE,CAAA;KAAE,CAAC;IAE9G,+DAA+D;IAC/D,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAEvC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,cAAc,GAAG,YAAY,KAAK,IAAI,CAAC;IAE1F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrE,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAuCD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAY1D;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAE1F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAClC,IAAI,CAAC,EAAE,IAAI,GACV,OAAO,CAIT;AA2GD;;;;;;GAMG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAiEnD;AAED,2FAA2F;AAC3F,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,wBAAgB,eAAe,IAAI;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAEA;AAED,qEAAqE;AACrE,wBAAgB,eAAe,IAAI,IAAI,CAStC;AAED,wBAAgB,YAAY,IAAI,IAAI,CAOnC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-updates",
-  "version": "1.3.7",
+  "version": "1.3.8",
   "description": "Pulse app-experience SDK for React Native: updates, config, experiments, events, decisions and first-party links",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",

package/src/config.ts

@@ -50,6 +50,12 @@ export type ConfigSignatureStatus = 'not-configured' | 'verified' | 'cached-veri
 export interface ConfigStorage {
   getString(key: string): string | null | undefined;
   set(key: string, value: string): void;
+  /**
+   * False when `set` only mirrors a write and schedules asynchronous persistence. Durable
+   * acknowledgement APIs must fail closed because process death may still lose that write.
+   * Omitted means the historical synchronous-storage contract.
+   */
+  readonly supportsDurableSyncWrites?: boolean;
 }
 
 /**

package/src/init.ts

@@ -45,6 +45,7 @@ import {
   flushEvents,
   getTrackingInfo,
   track,
+  trackIdempotent,
   type TrackedEventInput,
 } from './track';
 
@@ -140,6 +141,12 @@ export interface PulseClient {
   configUrl: string;
   trackUrl: string;
   track: (event: string, props?: TrackedEventInput['props'], time?: Date) => void;
+  trackIdempotent: (
+    eventId: string,
+    event: string,
+    props?: TrackedEventInput['props'],
+    time?: Date,
+  ) => boolean;
   flush: () => Promise<number>;
   setUser: (userId?: string, attributes?: Record<string, string>) => void;
   clearUser: () => void;
@@ -261,6 +268,7 @@ export function initPulse(opts: InitPulseOptions): PulseClient {
     configUrl,
     trackUrl,
     track,
+    trackIdempotent,
     flush: flushEvents,
     setUser: (nextUserId, attributes) => {
       userId = nextUserId?.trim() || undefined;
@@ -328,10 +336,17 @@ export async function initPulseAsync(
   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 = {
+    supportsDurableSyncWrites: false,
     getString: (key) => memory.get(key),
     set: (key, value) => {
       memory.set(key, value);
-      void opts.storage.setItem(key, value);
+      try {
+        void Promise.resolve(opts.storage.setItem(key, value)).catch((error) => {
+          try { opts.onError?.(error); } catch { /* diagnostics never break persistence */ }
+        });
+      } catch (error) {
+        try { opts.onError?.(error); } catch { /* diagnostics never break persistence */ }
+      }
     },
   };
   return initPulse({ ...opts, storage });