@metarouter/react-native-sdk 1.5.0 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +59 -10
  2. package/android/build.gradle +41 -0
  3. package/android/src/main/AndroidManifest.xml +4 -0
  4. package/android/src/main/java/com/metarouter/reactnative/MetaRouterNetworkMonitorModule.kt +119 -0
  5. package/android/src/main/java/com/metarouter/reactnative/MetaRouterPackage.kt +23 -0
  6. package/android/src/main/java/com/metarouter/reactnative/MetaRouterQueueStorageModule.kt +124 -0
  7. package/ios/MetaRouterNetworkMonitor.m +76 -0
  8. package/ios/MetaRouterQueueStorage.m +127 -0
  9. package/lib/analytics/MetaRouterAnalyticsClient.d.ts +23 -4
  10. package/lib/analytics/MetaRouterAnalyticsClient.d.ts.map +1 -1
  11. package/lib/analytics/MetaRouterAnalyticsClient.js +178 -89
  12. package/lib/analytics/dispatcher.d.ts +61 -4
  13. package/lib/analytics/dispatcher.d.ts.map +1 -1
  14. package/lib/analytics/dispatcher.js +248 -45
  15. package/lib/analytics/init.d.ts +1 -1
  16. package/lib/analytics/init.d.ts.map +1 -1
  17. package/lib/analytics/init.js +12 -2
  18. package/lib/analytics/persistence/NativeQueueStorage.d.ts +5 -0
  19. package/lib/analytics/persistence/NativeQueueStorage.d.ts.map +1 -0
  20. package/lib/analytics/persistence/NativeQueueStorage.js +59 -0
  21. package/lib/analytics/persistence/PersistentEventQueue.d.ts +96 -0
  22. package/lib/analytics/persistence/PersistentEventQueue.d.ts.map +1 -0
  23. package/lib/analytics/persistence/PersistentEventQueue.js +401 -0
  24. package/lib/analytics/persistence/types.d.ts +20 -0
  25. package/lib/analytics/persistence/types.d.ts.map +1 -0
  26. package/lib/analytics/persistence/types.js +10 -0
  27. package/lib/analytics/proxy/proxyClient.d.ts +1 -1
  28. package/lib/analytics/proxy/proxyClient.d.ts.map +1 -1
  29. package/lib/analytics/proxy/proxyClient.js +23 -29
  30. package/lib/analytics/types.d.ts +12 -4
  31. package/lib/analytics/types.d.ts.map +1 -1
  32. package/lib/analytics/utils/circuitBreaker.d.ts +4 -1
  33. package/lib/analytics/utils/circuitBreaker.d.ts.map +1 -1
  34. package/lib/analytics/utils/circuitBreaker.js +23 -14
  35. package/lib/analytics/utils/contextInfo.d.ts +1 -1
  36. package/lib/analytics/utils/contextInfo.d.ts.map +1 -1
  37. package/lib/analytics/utils/contextInfo.js +28 -24
  38. package/lib/analytics/utils/debouncedNetworkMonitor.d.ts +25 -0
  39. package/lib/analytics/utils/debouncedNetworkMonitor.d.ts.map +1 -0
  40. package/lib/analytics/utils/debouncedNetworkMonitor.js +68 -0
  41. package/lib/analytics/utils/networkMonitor.d.ts +30 -0
  42. package/lib/analytics/utils/networkMonitor.d.ts.map +1 -0
  43. package/lib/analytics/utils/networkMonitor.js +90 -0
  44. package/lib/analytics/utils/responseCategory.d.ts +14 -0
  45. package/lib/analytics/utils/responseCategory.d.ts.map +1 -0
  46. package/lib/analytics/utils/responseCategory.js +26 -0
  47. package/metarouter-react-native-sdk.podspec +19 -0
  48. package/package.json +27 -10
  49. package/react-native.config.js +15 -0
@@ -0,0 +1,96 @@
1
+ import type { EventPayload } from '../types';
2
+ import type Dispatcher from '../dispatcher';
3
+ /**
4
+ * Memory + disk coordination for the event queue.
5
+ *
6
+ * Single disk file (queue.v1.json) backs both crash-safety (background flush)
7
+ * and offline overflow. All native file mutations run through one serialized
8
+ * lane so append, drain, and delete operations cannot interleave.
9
+ *
10
+ * On boot, {@link checkForPersistedEvents} does a cheap existence check and
11
+ * sets {@link hasDiskData}. The in-memory queue starts empty; when online,
12
+ * the dispatcher drains disk events directly to the network via
13
+ * {@link drainDiskToNetwork} instead of rehydrating into memory.
14
+ */
15
+ export declare class PersistentEventQueue {
16
+ private readonly dispatcher;
17
+ private readonly maxDiskEvents;
18
+ private _hasDiskData;
19
+ /** Serializes every native file mutation: append, drain rewrite/delete, reset delete. */
20
+ private diskMutation;
21
+ /**
22
+ * Capacity overflow happens from a synchronous enqueue path. These events
23
+ * are owned here until a native write succeeds, so a failed write does not
24
+ * silently discard them from JS memory.
25
+ */
26
+ private pendingDiskEvents;
27
+ private pendingFlushInFlight;
28
+ /** Guards drainDiskToNetwork (read-then-delete semantics). */
29
+ private drainInFlight;
30
+ constructor(dispatcher: Dispatcher, opts?: {
31
+ maxDiskEvents?: number;
32
+ });
33
+ private enqueueDiskMutation;
34
+ private waitForDiskIdle;
35
+ /** True when a disk snapshot existed at boot or was written since. */
36
+ get hasDiskData(): boolean;
37
+ /**
38
+ * Boot-time cheap existence check.
39
+ * Sets {@link hasDiskData} without reading or parsing the snapshot file,
40
+ * so we can decide whether to trigger a drain without paying the cost of
41
+ * loading a potentially-large snapshot into memory.
42
+ */
43
+ checkForPersistedEvents(): Promise<boolean>;
44
+ /**
45
+ * Flush the in-memory queue to disk (append + cap).
46
+ * Called on app background and when the flush-to-disk threshold is hit.
47
+ * Serialized against other disk writes.
48
+ *
49
+ * No-op when persistence is disabled (maxDiskEvents === 0). Memory queue
50
+ * is left intact so a subsequent foreground flush can still try to send
51
+ * those events; on app kill they are lost (documented tradeoff).
52
+ */
53
+ flushToDisk(): Promise<void>;
54
+ /**
55
+ * Append explicit events to the disk store (read-merge-cap-write).
56
+ * Called by lifecycle/offline paths that can await disk durability.
57
+ * Serialized against every other disk mutation.
58
+ *
59
+ * No-op when persistence is disabled (maxDiskEvents === 0).
60
+ */
61
+ flushEventsToDisk(events: EventPayload[]): Promise<void>;
62
+ /**
63
+ * Own events from synchronous overflow paths until they are durable.
64
+ * The write is started immediately but errors are retained in the pending
65
+ * buffer for a later retry instead of being dropped.
66
+ */
67
+ bufferEventsForDisk(events: EventPayload[]): void;
68
+ flushPendingDiskWrites(): Promise<void>;
69
+ private _flushPendingDiskWrites;
70
+ private appendPendingDiskEvents;
71
+ private _doFlushEventsToDisk;
72
+ /**
73
+ * Check if the queue has crossed a flush-to-disk threshold.
74
+ */
75
+ shouldFlushToDisk(): boolean;
76
+ /**
77
+ * Drain disk events directly to network in batches. Does NOT load events
78
+ * into the memory queue. Called on offline→online transition and after
79
+ * successful online flushes.
80
+ *
81
+ * Response handling:
82
+ * - 2xx: advances and deletes sent events; restores batch size after 413
83
+ * - 413: halves batch size, retries. Drops at batchSize=1
84
+ * - 5xx/408/429: stops, writes remainder back, retries on next online transition
85
+ * - 401/403/404: fatal, deletes disk store
86
+ * - Other 4xx: drops batch, continues
87
+ */
88
+ drainDiskToNetwork(dispatcher: Dispatcher): Promise<void>;
89
+ private _doDrainDiskToNetwork;
90
+ /**
91
+ * Delete the disk store (used during reset).
92
+ */
93
+ deleteSnapshot(): Promise<void>;
94
+ private _readExistingEvents;
95
+ }
96
+ //# sourceMappingURL=PersistentEventQueue.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"PersistentEventQueue.d.ts","sourceRoot":"","sources":["../../../src/analytics/persistence/PersistentEventQueue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,UAAU,MAAM,eAAe,CAAC;AA2B5C;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,YAAY,CAAkB;IAEtC,yFAAyF;IACzF,OAAO,CAAC,YAAY,CAAoC;IACxD;;;;OAIG;IACH,OAAO,CAAC,iBAAiB,CAAsB;IAC/C,OAAO,CAAC,oBAAoB,CAA8B;IAC1D,8DAA8D;IAC9D,OAAO,CAAC,aAAa,CAA8B;gBAEvC,UAAU,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE;IAKrE,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,eAAe;IAIvB,sEAAsE;IACtE,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;;OAKG;IACG,uBAAuB,IAAI,OAAO,CAAC,OAAO,CAAC;IAcjD;;;;;;;;OAQG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAclC;;;;;;OAMG;IACG,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9D;;;;OAIG;IACH,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI;IAQ3C,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;YAa/B,uBAAuB;IAarC,OAAO,CAAC,uBAAuB;YAWjB,oBAAoB;IAgClC;;OAEG;IACH,iBAAiB,IAAI,OAAO;IAO5B;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;YAkBjD,qBAAqB;IAuKnC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;YAgBvB,mBAAmB;CAiBlC"}
@@ -0,0 +1,401 @@
1
+ import { exists as nativeExists, readSnapshot, writeSnapshot, deleteSnapshot as nativeDeleteSnapshot, } from './NativeQueueStorage';
2
+ import { SNAPSHOT_VERSION, FLUSH_THRESHOLD_BYTES, FLUSH_THRESHOLD_COUNT, DEFAULT_EVENT_TTL_MS, DEFAULT_MAX_DISK_EVENTS, } from './types';
3
+ import { ResponseCategory, categorizeResponse, } from '../utils/responseCategory';
4
+ import { log, warn } from '../utils/logger';
5
+ /**
6
+ * Default batch size for draining disk events to network.
7
+ * May be halved on 413 responses.
8
+ */
9
+ const DRAIN_BATCH_SIZE = 100;
10
+ /**
11
+ * Memory + disk coordination for the event queue.
12
+ *
13
+ * Single disk file (queue.v1.json) backs both crash-safety (background flush)
14
+ * and offline overflow. All native file mutations run through one serialized
15
+ * lane so append, drain, and delete operations cannot interleave.
16
+ *
17
+ * On boot, {@link checkForPersistedEvents} does a cheap existence check and
18
+ * sets {@link hasDiskData}. The in-memory queue starts empty; when online,
19
+ * the dispatcher drains disk events directly to the network via
20
+ * {@link drainDiskToNetwork} instead of rehydrating into memory.
21
+ */
22
+ export class PersistentEventQueue {
23
+ constructor(dispatcher, opts) {
24
+ var _a;
25
+ this._hasDiskData = false;
26
+ /** Serializes every native file mutation: append, drain rewrite/delete, reset delete. */
27
+ this.diskMutation = Promise.resolve();
28
+ /**
29
+ * Capacity overflow happens from a synchronous enqueue path. These events
30
+ * are owned here until a native write succeeds, so a failed write does not
31
+ * silently discard them from JS memory.
32
+ */
33
+ this.pendingDiskEvents = [];
34
+ this.pendingFlushInFlight = null;
35
+ /** Guards drainDiskToNetwork (read-then-delete semantics). */
36
+ this.drainInFlight = null;
37
+ this.dispatcher = dispatcher;
38
+ this.maxDiskEvents = (_a = opts === null || opts === void 0 ? void 0 : opts.maxDiskEvents) !== null && _a !== void 0 ? _a : DEFAULT_MAX_DISK_EVENTS;
39
+ }
40
+ enqueueDiskMutation(fn) {
41
+ const run = this.diskMutation.then(fn, fn);
42
+ this.diskMutation = run.then(() => undefined, () => undefined);
43
+ return run;
44
+ }
45
+ waitForDiskIdle() {
46
+ return this.diskMutation;
47
+ }
48
+ /** True when a disk snapshot existed at boot or was written since. */
49
+ get hasDiskData() {
50
+ return this._hasDiskData;
51
+ }
52
+ /**
53
+ * Boot-time cheap existence check.
54
+ * Sets {@link hasDiskData} without reading or parsing the snapshot file,
55
+ * so we can decide whether to trigger a drain without paying the cost of
56
+ * loading a potentially-large snapshot into memory.
57
+ */
58
+ async checkForPersistedEvents() {
59
+ try {
60
+ this._hasDiskData = await nativeExists();
61
+ if (this._hasDiskData) {
62
+ log('Persisted events detected on disk — drain pending');
63
+ }
64
+ return this._hasDiskData;
65
+ }
66
+ catch (err) {
67
+ warn('Failed to check for persisted events:', err);
68
+ this._hasDiskData = false;
69
+ return false;
70
+ }
71
+ }
72
+ /**
73
+ * Flush the in-memory queue to disk (append + cap).
74
+ * Called on app background and when the flush-to-disk threshold is hit.
75
+ * Serialized against other disk writes.
76
+ *
77
+ * No-op when persistence is disabled (maxDiskEvents === 0). Memory queue
78
+ * is left intact so a subsequent foreground flush can still try to send
79
+ * those events; on app kill they are lost (documented tradeoff).
80
+ */
81
+ async flushToDisk() {
82
+ if (this.maxDiskEvents === 0)
83
+ return;
84
+ const queue = this.dispatcher.getQueueRef();
85
+ if (queue.length === 0)
86
+ return;
87
+ const events = this.dispatcher.drainQueue();
88
+ try {
89
+ await this.flushEventsToDisk(events);
90
+ }
91
+ catch (err) {
92
+ this.dispatcher.restoreQueueFront(events);
93
+ warn('Failed to flush queue to disk — restored events to memory:', err);
94
+ throw err;
95
+ }
96
+ }
97
+ /**
98
+ * Append explicit events to the disk store (read-merge-cap-write).
99
+ * Called by lifecycle/offline paths that can await disk durability.
100
+ * Serialized against every other disk mutation.
101
+ *
102
+ * No-op when persistence is disabled (maxDiskEvents === 0).
103
+ */
104
+ async flushEventsToDisk(events) {
105
+ if (events.length === 0)
106
+ return;
107
+ if (this.maxDiskEvents === 0)
108
+ return;
109
+ await this.flushPendingDiskWrites();
110
+ return this.enqueueDiskMutation(() => this._doFlushEventsToDisk(events));
111
+ }
112
+ /**
113
+ * Own events from synchronous overflow paths until they are durable.
114
+ * The write is started immediately but errors are retained in the pending
115
+ * buffer for a later retry instead of being dropped.
116
+ */
117
+ bufferEventsForDisk(events) {
118
+ if (events.length === 0 || this.maxDiskEvents === 0)
119
+ return;
120
+ this.appendPendingDiskEvents(events);
121
+ void this.flushPendingDiskWrites().catch((err) => {
122
+ warn('Failed to flush pending disk events:', err);
123
+ });
124
+ }
125
+ async flushPendingDiskWrites() {
126
+ if (this.maxDiskEvents === 0) {
127
+ this.pendingDiskEvents = [];
128
+ return;
129
+ }
130
+ if (this.pendingFlushInFlight)
131
+ return this.pendingFlushInFlight;
132
+ this.pendingFlushInFlight = this._flushPendingDiskWrites().finally(() => {
133
+ this.pendingFlushInFlight = null;
134
+ });
135
+ return this.pendingFlushInFlight;
136
+ }
137
+ async _flushPendingDiskWrites() {
138
+ while (this.pendingDiskEvents.length > 0) {
139
+ const events = this.pendingDiskEvents;
140
+ this.pendingDiskEvents = [];
141
+ try {
142
+ await this.enqueueDiskMutation(() => this._doFlushEventsToDisk(events));
143
+ }
144
+ catch (err) {
145
+ this.pendingDiskEvents = events.concat(this.pendingDiskEvents);
146
+ throw err;
147
+ }
148
+ }
149
+ }
150
+ appendPendingDiskEvents(events) {
151
+ this.pendingDiskEvents.push(...events);
152
+ if (this.pendingDiskEvents.length > this.maxDiskEvents) {
153
+ const dropCount = this.pendingDiskEvents.length - this.maxDiskEvents;
154
+ this.pendingDiskEvents = this.pendingDiskEvents.slice(dropCount);
155
+ warn(`Pending disk buffer cap reached — dropped ${dropCount} oldest events`);
156
+ }
157
+ }
158
+ async _doFlushEventsToDisk(events) {
159
+ try {
160
+ const existing = await this._readExistingEvents();
161
+ let combined = existing.concat(events);
162
+ if (combined.length > this.maxDiskEvents) {
163
+ const dropCount = combined.length - this.maxDiskEvents;
164
+ combined = combined.slice(dropCount);
165
+ warn(`Disk store cap reached — dropped ${dropCount} oldest events`);
166
+ }
167
+ if (combined.length === 0) {
168
+ await nativeDeleteSnapshot();
169
+ this._hasDiskData = false;
170
+ return;
171
+ }
172
+ const snapshot = {
173
+ version: SNAPSHOT_VERSION,
174
+ events: combined,
175
+ };
176
+ await writeSnapshot(JSON.stringify(snapshot));
177
+ this._hasDiskData = true;
178
+ log(`Memory queue flushed to disk: ${events.length} events, ${combined.length} total on disk`);
179
+ }
180
+ catch (err) {
181
+ warn('Failed to flush events to disk:', err);
182
+ throw err;
183
+ }
184
+ }
185
+ /**
186
+ * Check if the queue has crossed a flush-to-disk threshold.
187
+ */
188
+ shouldFlushToDisk() {
189
+ return (this.dispatcher.getQueueRef().length >= FLUSH_THRESHOLD_COUNT ||
190
+ this.dispatcher.getQueueSizeBytes() >= FLUSH_THRESHOLD_BYTES);
191
+ }
192
+ /**
193
+ * Drain disk events directly to network in batches. Does NOT load events
194
+ * into the memory queue. Called on offline→online transition and after
195
+ * successful online flushes.
196
+ *
197
+ * Response handling:
198
+ * - 2xx: advances and deletes sent events; restores batch size after 413
199
+ * - 413: halves batch size, retries. Drops at batchSize=1
200
+ * - 5xx/408/429: stops, writes remainder back, retries on next online transition
201
+ * - 401/403/404: fatal, deletes disk store
202
+ * - Other 4xx: drops batch, continues
203
+ */
204
+ async drainDiskToNetwork(dispatcher) {
205
+ if (this.drainInFlight)
206
+ return this.drainInFlight;
207
+ this.drainInFlight = (async () => {
208
+ try {
209
+ await this.flushPendingDiskWrites();
210
+ }
211
+ catch (err) {
212
+ warn('Disk drain continuing after pending write failure:', err);
213
+ }
214
+ await this.enqueueDiskMutation(() => this._doDrainDiskToNetwork(dispatcher));
215
+ })().finally(() => {
216
+ this.drainInFlight = null;
217
+ });
218
+ return this.drainInFlight;
219
+ }
220
+ async _doDrainDiskToNetwork(dispatcher) {
221
+ let batchSize = DRAIN_BATCH_SIZE;
222
+ try {
223
+ while (true) {
224
+ const raw = await readSnapshot();
225
+ if (!raw) {
226
+ this._hasDiskData = false;
227
+ return;
228
+ }
229
+ let snapshot;
230
+ try {
231
+ snapshot = JSON.parse(raw);
232
+ }
233
+ catch {
234
+ warn('Queue snapshot is corrupt during drain — deleting');
235
+ await nativeDeleteSnapshot();
236
+ this._hasDiskData = false;
237
+ return;
238
+ }
239
+ if (!Array.isArray(snapshot.events) || snapshot.events.length === 0) {
240
+ await nativeDeleteSnapshot();
241
+ this._hasDiskData = false;
242
+ return;
243
+ }
244
+ const events = filterExpired(snapshot.events);
245
+ const droppedExpired = snapshot.events.length - events.length;
246
+ if (droppedExpired > 0) {
247
+ log(`Drain TTL filter dropped ${droppedExpired} event(s) older than 7 days`);
248
+ }
249
+ if (events.length === 0) {
250
+ log('All disk events expired — deleting');
251
+ await nativeDeleteSnapshot();
252
+ this._hasDiskData = false;
253
+ return;
254
+ }
255
+ const n = Math.min(batchSize, events.length);
256
+ const batch = events.slice(0, n);
257
+ const remaining = events.slice(n);
258
+ const response = await dispatcher.sendBatchDirect(batch);
259
+ if (!response) {
260
+ log(`Disk drain paused — network error, ${events.length} event(s) remain on disk`);
261
+ if (droppedExpired > 0) {
262
+ await writeSnapshot(JSON.stringify({ version: SNAPSHOT_VERSION, events }));
263
+ }
264
+ return;
265
+ }
266
+ const category = categorizeResponse(response.statusCode);
267
+ switch (category) {
268
+ case ResponseCategory.SUCCESS: {
269
+ if (batchSize < DRAIN_BATCH_SIZE) {
270
+ batchSize = Math.min(batchSize * 2, DRAIN_BATCH_SIZE);
271
+ }
272
+ if (remaining.length === 0) {
273
+ await nativeDeleteSnapshot();
274
+ this._hasDiskData = false;
275
+ log('Disk store drain complete');
276
+ }
277
+ else {
278
+ await writeSnapshot(JSON.stringify({
279
+ version: SNAPSHOT_VERSION,
280
+ events: remaining,
281
+ }));
282
+ log(`Disk drain batch sent (${batch.length}), ${remaining.length} remaining on disk`);
283
+ }
284
+ break;
285
+ }
286
+ case ResponseCategory.PAYLOAD_TOO_LARGE: {
287
+ if (batchSize > 1) {
288
+ batchSize = Math.max(1, Math.floor(batchSize / 2));
289
+ warn(`Disk drain: 413 — halving batch size to ${batchSize}`);
290
+ if (droppedExpired > 0) {
291
+ await writeSnapshot(JSON.stringify({ version: SNAPSHOT_VERSION, events }));
292
+ }
293
+ }
294
+ else {
295
+ const ids = batch
296
+ .map((e) => e.messageId)
297
+ .join(',');
298
+ warn(`Disk drain: dropping oversize event(s) at batchSize=1; messageIds=${ids}`);
299
+ if (remaining.length === 0) {
300
+ await nativeDeleteSnapshot();
301
+ this._hasDiskData = false;
302
+ }
303
+ else {
304
+ await writeSnapshot(JSON.stringify({
305
+ version: SNAPSHOT_VERSION,
306
+ events: remaining,
307
+ }));
308
+ }
309
+ }
310
+ break;
311
+ }
312
+ case ResponseCategory.SERVER_ERROR:
313
+ case ResponseCategory.RATE_LIMITED: {
314
+ warn(`Disk drain paused — ${response.statusCode}, ${events.length} event(s) remain on disk`);
315
+ if (droppedExpired > 0) {
316
+ await writeSnapshot(JSON.stringify({ version: SNAPSHOT_VERSION, events }));
317
+ }
318
+ return;
319
+ }
320
+ case ResponseCategory.FATAL_CONFIG: {
321
+ warn(`Disk drain: fatal config error ${response.statusCode} — deleting disk store`);
322
+ await nativeDeleteSnapshot();
323
+ this._hasDiskData = false;
324
+ // Coordinate shutdown with the main dispatcher. Previously the
325
+ // drain path silently swallowed 401/403/404 while the main flush
326
+ // path disabled the client — inconsistent behavior.
327
+ dispatcher.handleFatalConfig(response.statusCode);
328
+ return;
329
+ }
330
+ case ResponseCategory.CLIENT_ERROR: {
331
+ warn(`Disk drain: dropping batch due to client error ${response.statusCode}`);
332
+ if (remaining.length === 0) {
333
+ await nativeDeleteSnapshot();
334
+ this._hasDiskData = false;
335
+ }
336
+ else {
337
+ await writeSnapshot(JSON.stringify({
338
+ version: SNAPSHOT_VERSION,
339
+ events: remaining,
340
+ }));
341
+ }
342
+ break;
343
+ }
344
+ }
345
+ }
346
+ }
347
+ catch (err) {
348
+ warn('Failed to drain disk to network:', err);
349
+ }
350
+ }
351
+ /**
352
+ * Delete the disk store (used during reset).
353
+ */
354
+ async deleteSnapshot() {
355
+ if (this.pendingFlushInFlight) {
356
+ try {
357
+ await this.pendingFlushInFlight;
358
+ }
359
+ catch (err) {
360
+ warn('Reset continuing after pending disk write failure:', err);
361
+ }
362
+ }
363
+ await this.waitForDiskIdle();
364
+ this.pendingDiskEvents = [];
365
+ await this.enqueueDiskMutation(async () => {
366
+ await nativeDeleteSnapshot();
367
+ this._hasDiskData = false;
368
+ });
369
+ }
370
+ async _readExistingEvents() {
371
+ const raw = await readSnapshot();
372
+ if (!raw)
373
+ return [];
374
+ try {
375
+ const snapshot = JSON.parse(raw);
376
+ if (snapshot.version === SNAPSHOT_VERSION &&
377
+ Array.isArray(snapshot.events)) {
378
+ return snapshot.events;
379
+ }
380
+ return [];
381
+ }
382
+ catch {
383
+ warn('Existing disk snapshot is corrupt JSON — overwriting');
384
+ return [];
385
+ }
386
+ }
387
+ }
388
+ function filterExpired(events) {
389
+ const cutoff = Date.now() - DEFAULT_EVENT_TTL_MS;
390
+ return events.filter((e) => {
391
+ const ts = e.timestamp;
392
+ if (!ts)
393
+ return true;
394
+ const eventTime = new Date(ts).getTime();
395
+ // Unparseable timestamp — keep it. Conservative: better to send than to
396
+ // silently drop an event whose age we can't verify.
397
+ if (isNaN(eventTime))
398
+ return true;
399
+ return eventTime > cutoff;
400
+ });
401
+ }
@@ -0,0 +1,20 @@
1
+ import type { EventPayload } from '../types';
2
+ /**
3
+ * On-disk snapshot envelope for the event queue.
4
+ * version is used for forward-compatible deserialization.
5
+ */
6
+ export interface QueueSnapshot {
7
+ version: number;
8
+ events: EventPayload[];
9
+ }
10
+ /** Current snapshot schema version */
11
+ export declare const SNAPSHOT_VERSION = 1;
12
+ /** Default TTL for rehydrated events: 7 days in milliseconds */
13
+ export declare const DEFAULT_EVENT_TTL_MS: number;
14
+ /** Flush-to-disk threshold: approximate serialized size in bytes (~2MB) */
15
+ export declare const FLUSH_THRESHOLD_BYTES: number;
16
+ /** Flush-to-disk threshold: event count */
17
+ export declare const FLUSH_THRESHOLD_COUNT = 500;
18
+ /** Default max events stored on disk (crash safety + extended offline overflow) */
19
+ export declare const DEFAULT_MAX_DISK_EVENTS = 10000;
20
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/analytics/persistence/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,sCAAsC;AACtC,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,gEAAgE;AAChE,eAAO,MAAM,oBAAoB,QAA0B,CAAC;AAE5D,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,QAAkB,CAAC;AAErD,2CAA2C;AAC3C,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,QAAS,CAAC"}
@@ -0,0 +1,10 @@
1
+ /** Current snapshot schema version */
2
+ export const SNAPSHOT_VERSION = 1;
3
+ /** Default TTL for rehydrated events: 7 days in milliseconds */
4
+ export const DEFAULT_EVENT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
5
+ /** Flush-to-disk threshold: approximate serialized size in bytes (~2MB) */
6
+ export const FLUSH_THRESHOLD_BYTES = 2 * 1024 * 1024;
7
+ /** Flush-to-disk threshold: event count */
8
+ export const FLUSH_THRESHOLD_COUNT = 500;
9
+ /** Default max events stored on disk (crash safety + extended offline overflow) */
10
+ export const DEFAULT_MAX_DISK_EVENTS = 10000;
@@ -1,4 +1,4 @@
1
- import type { AnalyticsInterface } from "../types";
1
+ import type { AnalyticsInterface } from '../types';
2
2
  export declare const proxyClient: AnalyticsInterface;
3
3
  /**
4
4
  * Binds or unbinds the real analytics client to the proxy and manages queued calls.
@@ -1 +1 @@
1
- {"version":3,"file":"proxyClient.d.ts","sourceRoot":"","sources":["../../../src/analytics/proxy/proxyClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AA8InD,eAAO,MAAM,WAAW,EAAE,kBAezB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,GAAG,IAAI,EACjC,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,QAqBjC"}
1
+ {"version":3,"file":"proxyClient.d.ts","sourceRoot":"","sources":["../../../src/analytics/proxy/proxyClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AA2InD,eAAO,MAAM,WAAW,EAAE,kBAkBzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,GAAG,IAAI,EACjC,IAAI,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,QAqBjC"}
@@ -4,6 +4,7 @@ let realClient = null;
4
4
  const ASYNC_METHODS = {
5
5
  flush: true,
6
6
  getDebugInfo: true,
7
+ getAnonymousId: true,
7
8
  setAdvertisingId: true,
8
9
  clearAdvertisingId: true,
9
10
  };
@@ -21,11 +22,10 @@ let flushInFlight = null;
21
22
  *
22
23
  * - **Pre-bind:**
23
24
  * - Queues the call in `pendingCalls` for replay after binding.
24
- * - For async methods (`flush`, `reset`, `getDebugInfo`), returns a Promise
25
- * that resolves/rejects after replay. Keeps a `reject` handle so
25
+ * - For async methods (`flush`, `getDebugInfo`, `setAdvertisingId`, `clearAdvertisingId`),
26
+ * returns a Promise that resolves/rejects after replay. Keeps a `reject` handle so
26
27
  * `dropPending` can fail them immediately.
27
28
  * - For sync "fire-and-forget" methods, returns `void` immediately.
28
- * - For `getDebugInfo`, returns an immediate proxy snapshot without queuing.
29
29
  * - For `reset`, returns an immediate resolved Promise (no-op).
30
30
  * - If the queue exceeds `MAX_PENDING_CALLS`, drops the oldest call
31
31
  * (rejecting it if async) and logs a warning.
@@ -38,7 +38,7 @@ function handleMethodCall(methodName, ...args) {
38
38
  var _a;
39
39
  // Real client bound
40
40
  if (realClient) {
41
- if (methodName === "flush") {
41
+ if (methodName === 'flush') {
42
42
  if (flushInFlight)
43
43
  return flushInFlight;
44
44
  const p = Promise.resolve(realClient.flush(...args)).then(() => undefined);
@@ -56,14 +56,7 @@ function handleMethodCall(methodName, ...args) {
56
56
  console.warn(`[MetaRouter] Oldest call dropped (queue cap ${MAX_PENDING_CALLS})`);
57
57
  }
58
58
  // Special-cases while unbound:
59
- if (methodName === "getDebugInfo") {
60
- // Return immediate proxy snapshot instead of queueing
61
- return Promise.resolve({
62
- proxy: true,
63
- pendingCalls: pendingCalls.length,
64
- });
65
- }
66
- if (methodName === "reset") {
59
+ if (methodName === 'reset') {
67
60
  // Nothing to reset pre-bind; resolve immediately
68
61
  return Promise.resolve();
69
62
  }
@@ -75,9 +68,9 @@ function handleMethodCall(methodName, ...args) {
75
68
  fn: async () => {
76
69
  try {
77
70
  if (!realClient) {
78
- return reject(new Error("Proxy detached before real client was bound"));
71
+ return reject(new Error('Proxy detached before real client was bound'));
79
72
  }
80
- if (methodName === "flush") {
73
+ if (methodName === 'flush') {
81
74
  if (!flushInFlight) {
82
75
  const p = Promise.resolve(realClient.flush(...args)).then(() => undefined);
83
76
  flushInFlight = p.finally(() => {
@@ -107,19 +100,20 @@ function handleMethodCall(methodName, ...args) {
107
100
  return undefined;
108
101
  }
109
102
  export const proxyClient = {
110
- track: (event, props) => handleMethodCall("track", event, props),
111
- identify: (userId, traits) => handleMethodCall("identify", userId, traits),
112
- group: (groupId, traits) => handleMethodCall("group", groupId, traits),
113
- screen: (name, props) => handleMethodCall("screen", name, props),
114
- page: (name, props) => handleMethodCall("page", name, props),
115
- alias: (newUserId) => handleMethodCall("alias", newUserId),
116
- setAdvertisingId: (advertisingId) => handleMethodCall("setAdvertisingId", advertisingId),
117
- clearAdvertisingId: () => handleMethodCall("clearAdvertisingId"),
118
- setTracing: (enabled) => handleMethodCall("setTracing", enabled),
119
- flush: () => handleMethodCall("flush"),
120
- reset: () => handleMethodCall("reset"),
121
- enableDebugLogging: () => handleMethodCall("enableDebugLogging"),
122
- getDebugInfo: () => handleMethodCall("getDebugInfo"),
103
+ track: (event, props) => handleMethodCall('track', event, props),
104
+ identify: (userId, traits) => handleMethodCall('identify', userId, traits),
105
+ group: (groupId, traits) => handleMethodCall('group', groupId, traits),
106
+ screen: (name, props) => handleMethodCall('screen', name, props),
107
+ page: (name, props) => handleMethodCall('page', name, props),
108
+ alias: (newUserId) => handleMethodCall('alias', newUserId),
109
+ setAdvertisingId: (advertisingId) => handleMethodCall('setAdvertisingId', advertisingId),
110
+ clearAdvertisingId: () => handleMethodCall('clearAdvertisingId'),
111
+ setTracing: (enabled) => handleMethodCall('setTracing', enabled),
112
+ flush: () => handleMethodCall('flush'),
113
+ reset: () => handleMethodCall('reset'),
114
+ enableDebugLogging: () => handleMethodCall('enableDebugLogging'),
115
+ getDebugInfo: () => handleMethodCall('getDebugInfo'),
116
+ getAnonymousId: () => handleMethodCall('getAnonymousId'),
123
117
  };
124
118
  /**
125
119
  * Binds or unbinds the real analytics client to the proxy and manages queued calls.
@@ -158,14 +152,14 @@ export function setRealClient(client, opts) {
158
152
  Promise.resolve(fn()).catch(() => { });
159
153
  }
160
154
  catch (err) {
161
- console.warn("[MetaRouter] replay error:", err);
155
+ console.warn('[MetaRouter] replay error:', err);
162
156
  }
163
157
  }
164
158
  }
165
159
  else {
166
160
  if (opts === null || opts === void 0 ? void 0 : opts.dropPending) {
167
161
  for (const it of pendingCalls)
168
- (_a = it.reject) === null || _a === void 0 ? void 0 : _a.call(it, new Error("[MetaRouter] Proxy dropped before bind"));
162
+ (_a = it.reject) === null || _a === void 0 ? void 0 : _a.call(it, new Error('[MetaRouter] Proxy dropped before bind'));
169
163
  pendingCalls.length = 0;
170
164
  }
171
165
  flushInFlight = null; // reset coalescer