@eventra_dev/eventra-sdk 2.0.13 → 2.0.14

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.
package/README.md CHANGED
@@ -8,7 +8,7 @@
8
8
  <a href="https://www.npmjs.com/package/@eventra_dev/eventra-sdk"><img alt="npm version" src="https://img.shields.io/npm/v/@eventra_dev/eventra-sdk.svg?style=flat-square&color=blue"></a>
9
9
  <a href="https://www.npmjs.com/package/@eventra_dev/eventra-sdk"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@eventra_dev/eventra-sdk.svg?style=flat-square&color=blue"></a>
10
10
  <a href="https://github.com/and-1991/eventra-sdk/actions/workflows/test.yml"><img alt="tests" src="https://img.shields.io/github/actions/workflow/status/and-1991/eventra-sdk/test.yml?branch=main&label=tests&style=flat-square&logo=vitest&logoColor=white"></a>
11
- <img alt="tests passing" src="https://img.shields.io/badge/tests-266%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
11
+ <img alt="tests passing" src="https://img.shields.io/badge/tests-280%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
12
12
  <img alt="test suites" src="https://img.shields.io/badge/suites-22-brightgreen?style=flat-square">
13
13
  <img alt="coverage" src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&logo=vitest&logoColor=white">
14
14
  <img alt="node" src="https://img.shields.io/node/v/@eventra_dev/eventra-sdk?style=flat-square&color=darkgreen&logo=node.js&logoColor=white">
@@ -212,7 +212,7 @@ tracker.track("page.viewed");
212
212
  - persistence (localStorage)
213
213
  - flush on tab close (`fetch` with `keepalive`)
214
214
 
215
- By default (`multiTabMode: "independent"`) every open tab shares its pending events with the others and each tab may deliver them. An event keeps the same idempotency key in every tab, so it is counted once, but the number of requests grows with the number of open tabs. Use `"leader"` to have one tab send for all of them.
215
+ By default (`multiTabMode: "independent"`) every open tab shares its pending events with the others, so the events of a tab that closes are not lost. An event another open tab just announced is left to that tab for 15 seconds (it sends within its flush interval and tells the others); only after that does another tab send it, for example when the first tab was closed. Events read back from storage (an earlier page, a closed tab) are sent at once. An event keeps the same idempotency key in every tab, so it is counted once even if two tabs send it. Use `"leader"` to have one tab send for all of them.
216
216
 
217
217
  Optional - single sender across tabs:
218
218
 
@@ -391,7 +391,7 @@ await tracker.flush();
391
391
  await tracker.shutdown();
392
392
  ```
393
393
 
394
- `destroy()` stops timers and listeners immediately without flushing.
394
+ `destroy()` stops timers and listeners immediately without flushing, and a retry that is waiting does not run. In a browser the queue stays in `localStorage` for the next page; where it cannot be kept (Node, `persistQueue: false`, blocked storage) the events still queued are reported to `onEventsDropped` (a batch already in flight is not counted).
395
395
 
396
396
  ---
397
397
 
@@ -465,7 +465,7 @@ Eventra SDK includes:
465
465
 
466
466
  **100% statement/branch/function/line coverage** (v8 provider, `pnpm test:coverage`).
467
467
 
468
- 266 vitest tests across 22 files (plus 7 Playwright tests in a real browser) cover the entire delivery pipeline:
468
+ 280 vitest tests across 24 files (plus 7 Playwright tests in a real browser) cover the entire delivery pipeline:
469
469
 
470
470
  - `track()` validation — name length, userId truncation, properties depth/size, idempotency keys
471
471
  - Batching — auto-flush at `maxBatchSize`, periodic flush via timer, queue overflow drop
package/dist/index.cjs CHANGED
@@ -193,7 +193,7 @@ var Diagnostics = class {
193
193
  // src/client.ts
194
194
  var SDK_NAME = "@eventra_dev/eventra-sdk";
195
195
  var DEFAULT_ENDPOINT = "https://api.eventra.dev/api/v1/ingest/batch";
196
- var SDK_VERSION = "2.0.13";
196
+ var SDK_VERSION = "2.0.14";
197
197
  var LEADER_KEY = "__eventra_leader__";
198
198
  var LEADER_TTL_MS = 4e3;
199
199
  var QUEUE_KEY = "__eventra_q__";
@@ -216,6 +216,8 @@ var DEFAULT_SHUTDOWN_TIMEOUT_MS = 1e4;
216
216
  var PERSISTED_QUEUE_MAX_CHARS = 1e6;
217
217
  var KEEPALIVE_MAX_BYTES = 6e4;
218
218
  var DELIVERED_KEYS_MAX = 1e4;
219
+ var LIVE_TAB_GRACE_MS = 15e3;
220
+ var LIVE_TAB_KEYS_MAX = 1e4;
219
221
  var activeInstances = 0;
220
222
  function detectRuntime() {
221
223
  const g = globalThis;
@@ -480,6 +482,12 @@ var RetryableDeliveryError = class extends Error {
480
482
  this.name = "RetryableDeliveryError";
481
483
  }
482
484
  };
485
+ var DeliveryStopped = class extends Error {
486
+ constructor() {
487
+ super("delivery stopped by destroy()");
488
+ this.name = "DeliveryStopped";
489
+ }
490
+ };
483
491
  var Storage = class {
484
492
  constructor() {
485
493
  this.enabled = false;
@@ -492,6 +500,10 @@ var Storage = class {
492
500
  } catch {
493
501
  }
494
502
  }
503
+ // localStorage works here (not in Node, a blocked or private-mode browser)
504
+ get isEnabled() {
505
+ return this.enabled;
506
+ }
495
507
  get(key) {
496
508
  if (!this.enabled) return null;
497
509
  try {
@@ -663,6 +675,8 @@ var Eventra = class {
663
675
  constructor(options) {
664
676
  this.queue = [];
665
677
  this.sending = null;
678
+ // events other open tabs announced on the channel, by key, and until when they are theirs to send
679
+ this.liveTabEvents = /* @__PURE__ */ new Map();
666
680
  this.inFlight = false;
667
681
  this.destroyed = false;
668
682
  this.shuttingDown = false;
@@ -951,6 +965,12 @@ var Eventra = class {
951
965
  activeInstances = Math.max(0, activeInstances - 1);
952
966
  if (this.timer) clearInterval(this.timer);
953
967
  this.persistNow();
968
+ const kept = this.runtime === "browser" && this.persistQueue && this.storage.isEnabled;
969
+ if (!kept) {
970
+ const inFlight = new Set(this.sending ?? []);
971
+ const lost = this.queue.filter((event) => !inFlight.has(event)).length;
972
+ if (lost > 0) callSafely(this.options.onEventsDropped, lost);
973
+ }
954
974
  this.leader?.destroy();
955
975
  if (this.channel) {
956
976
  try {
@@ -981,6 +1001,10 @@ var Eventra = class {
981
1001
  let index = 0;
982
1002
  while (index < this.queue.length && events.length < this.maxBatch) {
983
1003
  const event = this.queue[index];
1004
+ if (this.leftToItsTab(event)) {
1005
+ index++;
1006
+ continue;
1007
+ }
984
1008
  let eventJson;
985
1009
  try {
986
1010
  eventJson = JSON.stringify(event);
@@ -1120,6 +1144,7 @@ var Eventra = class {
1120
1144
  throw err instanceof RetryableDeliveryError ? err : new RetryableDeliveryError("retryable delivery error", void 0, "network");
1121
1145
  }
1122
1146
  await sleep(wait);
1147
+ if (this.destroyed) throw new DeliveryStopped();
1123
1148
  } finally {
1124
1149
  clearTimeout(timeout);
1125
1150
  }
@@ -1207,11 +1232,34 @@ var Eventra = class {
1207
1232
  }
1208
1233
  trimQueue(queue = this.queue) {
1209
1234
  if (queue.length <= this.maxQueue) return queue;
1210
- const dropped = queue.length - this.maxQueue;
1211
- this.recordDiagnostic("queue_full", dropped);
1212
- callSafely(this.options.onEventsDropped, dropped);
1235
+ const removed = queue.slice(0, queue.length - this.maxQueue);
1236
+ const dropped = removed.filter((e) => !this.liveTabEvents.has(e?.idempotencyKey)).length;
1237
+ if (dropped > 0) {
1238
+ this.recordDiagnostic("queue_full", dropped);
1239
+ callSafely(this.options.onEventsDropped, dropped);
1240
+ }
1213
1241
  return queue.slice(-this.maxQueue);
1214
1242
  }
1243
+ // events another open tab just announced on the channel, with the time until which that tab sends them
1244
+ rememberLiveTabEvents(events) {
1245
+ const until = Date.now() + LIVE_TAB_GRACE_MS;
1246
+ for (const event of events) {
1247
+ const key = event?.idempotencyKey;
1248
+ if (typeof key === "string" && !this.liveTabEvents.has(key)) this.liveTabEvents.set(key, until);
1249
+ }
1250
+ for (const key of this.liveTabEvents.keys()) {
1251
+ if (this.liveTabEvents.size <= LIVE_TAB_KEYS_MAX) break;
1252
+ this.liveTabEvents.delete(key);
1253
+ }
1254
+ }
1255
+ // In `independent` mode, an event another open tab announced less than LIVE_TAB_GRACE_MS ago is that
1256
+ // tab's to send. After that (the tab was closed, or it cannot reach the server either) anyone sends it.
1257
+ // The leader in `leader` mode sends everything, so it never waits.
1258
+ leftToItsTab(event) {
1259
+ if (this.leader) return false;
1260
+ const until = this.liveTabEvents.get(event?.idempotencyKey);
1261
+ return until !== void 0 && Date.now() < until;
1262
+ }
1215
1263
  // Sends only what changed (a new event, or the keys just delivered) instead
1216
1264
  // of structured-cloning the whole queue on every call.
1217
1265
  broadcast(message) {
@@ -1234,13 +1282,16 @@ var Eventra = class {
1234
1282
  if (data?.type === "delivered" && Array.isArray(data.keys)) {
1235
1283
  const keys = new Set(data.keys);
1236
1284
  this.rememberDelivered(keys);
1285
+ for (const key of keys) this.liveTabEvents.delete(key);
1237
1286
  this.queue = this.queue.filter((ev) => !keys.has(ev.idempotencyKey));
1238
1287
  return;
1239
1288
  }
1240
1289
  if (data?.type !== "queue-add" && data?.type !== "queue-sync" || !Array.isArray(data.events)) {
1241
1290
  return;
1242
1291
  }
1243
- this.queue = mergeQueues(this.queue, this.withoutDelivered(data.events));
1292
+ const announced = this.withoutDelivered(data.events);
1293
+ this.rememberLiveTabEvents(announced);
1294
+ this.queue = mergeQueues(this.queue, announced);
1244
1295
  this.queue = this.trimQueue();
1245
1296
  };
1246
1297
  }