@eventra_dev/eventra-sdk 2.0.4 → 2.0.6
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/LICENSE +14 -2
- package/README.md +66 -8
- package/dist/index.cjs +468 -86
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +47 -3
- package/dist/index.d.ts +47 -3
- package/dist/index.mjs +471 -89
- package/dist/index.mjs.map +1 -1
- package/package.json +7 -2
package/LICENSE
CHANGED
|
@@ -1,9 +1,21 @@
|
|
|
1
1
|
MIT License
|
|
2
2
|
|
|
3
|
-
Copyright (c) 2026
|
|
3
|
+
Copyright (c) 2026 and-1991
|
|
4
4
|
|
|
5
5
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
6
|
of this software and associated documentation files (the "Software"), to deal
|
|
7
7
|
in the Software without restriction, including without limitation the rights
|
|
8
8
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -8,8 +8,8 @@
|
|
|
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-
|
|
12
|
-
<img alt="test suites" src="https://img.shields.io/badge/suites-
|
|
11
|
+
<img alt="tests passing" src="https://img.shields.io/badge/tests-162%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
|
|
12
|
+
<img alt="test suites" src="https://img.shields.io/badge/suites-17-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">
|
|
15
15
|
<a href="https://www.typescriptlang.org/"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-ready-blue?style=flat-square&logo=typescript&logoColor=white"></a>
|
|
@@ -228,6 +228,10 @@ const tracker = new Eventra({
|
|
|
228
228
|
});
|
|
229
229
|
```
|
|
230
230
|
|
|
231
|
+
Writes to `localStorage` are coalesced: a burst of `track()` calls costs one write about 50 ms later, not one write per call, and the queue is written immediately on `pagehide`, when the tab becomes hidden, and on `shutdown()`/`destroy()`. Closing or navigating away never loses events; only a hard crash of the tab in that ~50 ms window can.
|
|
232
|
+
|
|
233
|
+
Events kept in `localStorage` have a maximum age of 14 days: when the queue is loaded again (page load, another tab writing it), events older than that are dropped. The server only remembers idempotency keys for 30 days, so an event that was already delivered while the page was closing (whose response is never seen) must not be re-sent by a visitor who comes back months later and be counted twice.
|
|
234
|
+
|
|
231
235
|
With `persistQueue: false`, nothing is written to `localStorage`; the queue lives in memory only and is lost if the page closes before delivery (live cross-tab dedup via `BroadcastChannel` still works, since that's never written to disk).
|
|
232
236
|
|
|
233
237
|
---
|
|
@@ -322,6 +326,9 @@ const tracker = new Eventra({
|
|
|
322
326
|
| onEventsDropped | Callback when queue is full |
|
|
323
327
|
| onDeliveryFailed | Callback on permanent ingest errors (4xx except 429) |
|
|
324
328
|
| multiTabMode | `"independent"` (default) or `"leader"` (browser only) |
|
|
329
|
+
| exitOnSignal | Node only. On `SIGINT`/`SIGTERM` the SDK flushes and does nothing else (default `false`); `true` re-raises the signal after the flush when no other listener exists. See [Shutdown](#shutdown) |
|
|
330
|
+
| shutdownTimeoutMs | Total time `shutdown()` may spend flushing (default: 10000). It gives up after this, so a dead or rate-limited server cannot hold a `SIGTERM` shutdown past your grace period |
|
|
331
|
+
| diagnostics | Report delivery problems (counts only) with the next successful batch, default `true`; `false` sends nothing extra. See [Delivery diagnostics](#delivery-diagnostics) |
|
|
325
332
|
| persistQueue | Persist the queue to `localStorage` in the browser (browser only, default: `true`) — `false` keeps it in-memory only, avoiding writing `userId`/`properties` to disk |
|
|
326
333
|
|
|
327
334
|
---
|
|
@@ -342,6 +349,10 @@ Graceful shutdown — flush first, then cleanup:
|
|
|
342
349
|
await tracker.shutdown();
|
|
343
350
|
```
|
|
344
351
|
|
|
352
|
+
On `SIGINT`/`SIGTERM` the SDK flushes its queue and does nothing else, so it never interrupts your own graceful shutdown (an app that uses `process.once` or framework shutdown hooks has already removed its listener by the time the SDK finishes, and killing the process then would cut that shutdown off). Be aware that registering any signal handler cancels Node's default "exit on SIGINT/SIGTERM": **if the SDK is the only signal handler in your process, your app must exit itself** (for example `process.exit()` after your cleanup), or you can set `exitOnSignal: true`, which makes the SDK re-raise the signal after the flush when no other listener exists.
|
|
353
|
+
|
|
354
|
+
`shutdown()` has a total time budget (`shutdownTimeoutMs`, default 10 s). While it runs, retries and `Retry-After` waits that do not fit in what is left are skipped and requests are cut at the deadline, so a server that is down or rate limiting cannot hold the process past a typical termination grace period; events that could not be sent stay in the persisted queue (browser) or are lost with the process (Node). The flush timer never keeps a Node process alive on its own, and events still queued when a script ends are sent on `beforeExit`. `shutdown()` waits for a flush that is already running before sending what is left.
|
|
355
|
+
|
|
345
356
|
For Node / serverless, prefer explicit shutdown over relying on process signals:
|
|
346
357
|
|
|
347
358
|
```ts
|
|
@@ -353,13 +364,58 @@ await tracker.shutdown();
|
|
|
353
364
|
|
|
354
365
|
---
|
|
355
366
|
|
|
367
|
+
## Delivery diagnostics
|
|
368
|
+
|
|
369
|
+
The SDK counts what it could not deliver and tells Eventra with the next batch that gets through, so the dashboard can show how many events never arrived and why. It is on by default and switched off with `diagnostics: false`.
|
|
370
|
+
|
|
371
|
+
What is counted (numbers only, never event names, user ids or properties):
|
|
372
|
+
|
|
373
|
+
| group | reason | meaning |
|
|
374
|
+
|-------|--------|---------|
|
|
375
|
+
| dropped (events) | `queue_full` | the queue overflowed |
|
|
376
|
+
| | `invalid_event` | empty name, or properties over the depth/size limits |
|
|
377
|
+
| | `too_large` | a single event above `maxPayloadBytes` |
|
|
378
|
+
| | `rejected` | the server answered 4xx (not 429) |
|
|
379
|
+
| failed (send attempts) | `network` | blocked, offline, DNS or timeout, after the retries |
|
|
380
|
+
| | `server_error` | 5xx after the retries |
|
|
381
|
+
| | `rate_limited` | 429 after the retries |
|
|
382
|
+
| (detail) | `circuit_open` | the circuit breaker opened; listed by reason only, not added to `failedTotal` |
|
|
383
|
+
|
|
384
|
+
A failed batch is not lost: its events stay queued. `failedTotal` counts failed send attempts (a batch that could not be delivered after all its retries counts once, whatever the number of events or HTTP requests in it), `droppedTotal` counts events that are gone. The two are different units and are not added together.
|
|
385
|
+
|
|
386
|
+
How it is sent: as optional metadata in the batch envelope, never as an event, so it is not billed and an event count never includes it.
|
|
387
|
+
|
|
388
|
+
```json
|
|
389
|
+
{
|
|
390
|
+
"sentAt": "2026-03-12T10:00:00Z",
|
|
391
|
+
"sdk": { "name": "@eventra_dev/eventra-sdk", "version": "<sdk-version>", "runtime": "browser" },
|
|
392
|
+
"diagnostics": {
|
|
393
|
+
"reportId": "0b6f3c52-3a2a-4a3e-8f0e-1b2f6f2d9b11",
|
|
394
|
+
"since": "2026-03-12T09:41:00.000Z",
|
|
395
|
+
"droppedTotal": 3,
|
|
396
|
+
"failedTotal": 2,
|
|
397
|
+
"byReason": { "queue_full": 3, "network": 2 },
|
|
398
|
+
"queued": 12,
|
|
399
|
+
"sdkVersion": "<sdk-version>"
|
|
400
|
+
},
|
|
401
|
+
"events": []
|
|
402
|
+
}
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
- A report is built from the counters since the last acknowledged one, and is removed only after the server answers 2xx for the batch that carried it. If that batch fails, the same report (same `reportId`) is sent again, and the server counts a `reportId` once, so a retry never double counts.
|
|
406
|
+
- In the browser the counters are kept with the queue (`localStorage`, same debounce) and survive a reload; with `persistQueue: false` they stay in memory.
|
|
407
|
+
- A server that does not know the field and rejects the batch with 400/422 gets the same batch again without it (no event is lost), and the SDK stops sending the field.
|
|
408
|
+
- **Limit:** a client that is fully blocked (an ad blocker, a firewall) cannot report anything: the report travels with a successful batch, so it only arrives once a later batch gets through. To reduce blocking, send events through a first-party endpoint on your own domain (a reverse proxy that forwards `/eventra/ingest` to Eventra's ingest URL, with the `x-api-key` header passed through) and set `endpoint` to it.
|
|
409
|
+
|
|
410
|
+
---
|
|
411
|
+
|
|
356
412
|
## Reliability Features
|
|
357
413
|
|
|
358
414
|
Eventra SDK includes:
|
|
359
415
|
|
|
360
416
|
- Idempotency (UUID v4 per event, stable across retries)
|
|
361
|
-
- Retry with exponential backoff + jitter (capped)
|
|
362
|
-
- Circuit breaker with half-open recovery
|
|
417
|
+
- Retry with exponential backoff + jitter (capped); `Retry-After` on 429/5xx is honoured (up to 30 s), also for the next scheduled flush after the last attempt
|
|
418
|
+
- Circuit breaker with half-open recovery: one probe request, cooldown doubles after each failed probe (5 s up to 60 s)
|
|
363
419
|
- Queue-based delivery (all runtimes)
|
|
364
420
|
- Safe dequeue (events removed only after successful ingest)
|
|
365
421
|
- Queue persistence (browser) with merge + cross-tab sync — opt out via `persistQueue: false` if `localStorage` isn't acceptable for your data
|
|
@@ -370,6 +426,7 @@ Eventra SDK includes:
|
|
|
370
426
|
- Payload byte limits per batch
|
|
371
427
|
- Permanent error handling via `onDeliveryFailed` (401, 422, etc.)
|
|
372
428
|
- Automatic requeue on network errors and 429 / 5xx
|
|
429
|
+
- Delivery diagnostics: counts of dropped / failed events sent with the next successful batch (opt out with `diagnostics: false`)
|
|
373
430
|
|
|
374
431
|
---
|
|
375
432
|
|
|
@@ -377,14 +434,15 @@ Eventra SDK includes:
|
|
|
377
434
|
|
|
378
435
|
**100% statement/branch/function/line coverage** (v8 provider, `pnpm test:coverage`).
|
|
379
436
|
|
|
380
|
-
|
|
437
|
+
162 vitest tests across 17 files (plus 7 Playwright tests in a real browser) cover the entire delivery pipeline:
|
|
381
438
|
|
|
382
439
|
- `track()` validation — name length, userId truncation, properties depth/size, idempotency keys
|
|
383
440
|
- Batching — auto-flush at `maxBatchSize`, periodic flush via timer, queue overflow drop
|
|
384
441
|
- Retry & backoff — 429, 5xx, network errors, no-retry on 4xx, fetch timeout/abort
|
|
385
442
|
- Circuit breaker — opens after 5 consecutive failures, cools down, resets on success
|
|
386
443
|
- Payload guards — multi-batch splitting, oversize event dropped via `onDeliveryFailed(413)`
|
|
387
|
-
- Shutdown & destroy
|
|
444
|
+
- Shutdown & destroy - flush ordering, timer teardown, idempotent shutdown, the `shutdownTimeoutMs` budget, signal handling (flush only by default, `exitOnSignal`)
|
|
445
|
+
- Persisted queue - coalesced writes, 14-day maximum age, delivered-key filtering, cross-tab merge
|
|
388
446
|
- Runtime detection — Node, Edge (`EdgeRuntime`), Serverless (AWS Lambda), unknown fallback, Node process exit handling
|
|
389
447
|
- Browser mode — persistence, leader election (including multi-tab lease races), BroadcastChannel sync, `fetch` keepalive, `pagehide`
|
|
390
448
|
- Storage edge cases — corrupted/blocked localStorage, quota exceeded, queue trimming
|
|
@@ -435,7 +493,7 @@ Limits enforced by the SDK at `track()` time:
|
|
|
435
493
|
| Property nesting depth | ≤ 8 |
|
|
436
494
|
| Batch payload | ≤ `maxPayloadBytes` (default 60,000) |
|
|
437
495
|
| Fetch timeout | 5,000 ms |
|
|
438
|
-
| Circuit breaker | opens after 5 consecutive failures, cools down 5,000 ms |
|
|
496
|
+
| Circuit breaker | opens after 5 consecutive failures, cools down 5,000 ms, doubling after each failed probe up to 60,000 ms |
|
|
439
497
|
|
|
440
498
|
---
|
|
441
499
|
|
|
@@ -447,4 +505,4 @@ https://eventra.dev/docs
|
|
|
447
505
|
|
|
448
506
|
## License
|
|
449
507
|
|
|
450
|
-
MIT
|
|
508
|
+
MIT, copyright (c) 2026 [and-1991](https://github.com/and-1991). See [LICENSE](LICENSE).
|