@eventra_dev/eventra-sdk 2.0.10 → 2.0.12
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 +24 -15
- package/dist/index.cjs +314 -106
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +8 -1
- package/dist/index.d.ts +8 -1
- package/dist/index.mjs +314 -106
- package/dist/index.mjs.map +1 -1
- package/package.json +10 -4
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-
|
|
11
|
+
<img alt="tests passing" src="https://img.shields.io/badge/tests-245%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
|
|
12
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">
|
|
@@ -122,7 +122,7 @@ Minimal:
|
|
|
122
122
|
tracker.track("app.loaded");
|
|
123
123
|
```
|
|
124
124
|
|
|
125
|
-
Event names are trimmed to 64 characters, `userId` to 120 (API limits). `track()` never throws: an empty name, or properties that exceed the depth/size limits, are dropped silently and reported via `onEventsDropped` instead.
|
|
125
|
+
Event names are trimmed, cut to 64 characters and trimmed again, `userId` is cut to 120 (API limits); a cut never leaves half of an emoji, so the name is the one the CLI catalog holds. A numeric `userId` is written out as text, and `null` or an object means no user id. `properties` are copied when you call `track()`, so changing the object afterwards does not change the event. `track()` never throws: an empty name, or properties that exceed the depth/size limits, are dropped silently and reported via `onEventsDropped` instead.
|
|
126
126
|
|
|
127
127
|
---
|
|
128
128
|
|
|
@@ -210,7 +210,9 @@ tracker.track("page.viewed");
|
|
|
210
210
|
- persistence (localStorage)
|
|
211
211
|
- flush on tab close (`fetch` with `keepalive`)
|
|
212
212
|
|
|
213
|
-
|
|
213
|
+
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.
|
|
214
|
+
|
|
215
|
+
Optional - single sender across tabs:
|
|
214
216
|
|
|
215
217
|
```ts
|
|
216
218
|
const tracker = new Eventra({
|
|
@@ -232,7 +234,7 @@ Writes to `localStorage` are coalesced: a burst of `track()` calls costs one wri
|
|
|
232
234
|
|
|
233
235
|
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
236
|
|
|
235
|
-
With `persistQueue: false`, nothing is written to `localStorage`; the queue lives in memory only and is lost if the page closes before delivery (
|
|
237
|
+
With `persistQueue: false`, nothing is written to `localStorage`; the queue lives in memory only and is lost if the page closes before delivery (sharing events between tabs via `BroadcastChannel` still works, since that's never written to disk).
|
|
236
238
|
|
|
237
239
|
---
|
|
238
240
|
|
|
@@ -256,11 +258,13 @@ tracker.track("invoice.created");
|
|
|
256
258
|
### Serverless (IMPORTANT)
|
|
257
259
|
|
|
258
260
|
```ts
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
261
|
+
// created once, outside the handler: the platform reuses it between invocations.
|
|
262
|
+
// A new Eventra per call keeps adding exit listeners and is never cleaned up.
|
|
263
|
+
const tracker = new Eventra({
|
|
264
|
+
apiKey: "...",
|
|
265
|
+
});
|
|
263
266
|
|
|
267
|
+
export default async function handler(req, res) {
|
|
264
268
|
tracker.track("function.called");
|
|
265
269
|
|
|
266
270
|
await tracker.flush();
|
|
@@ -295,7 +299,7 @@ const tracker = new Eventra({
|
|
|
295
299
|
});
|
|
296
300
|
```
|
|
297
301
|
|
|
298
|
-
`endpoint` is optional - omit it to use the production ingest URL. Use `https`: a plain `http` endpoint on a remote host logs a warning, since the API key would travel unencrypted (`localhost` is exempt). The SDK never follows a redirect when sending, so the key cannot be forwarded to another host.
|
|
302
|
+
`endpoint` is optional - omit it to use the production ingest URL. Use `https`: a plain `http` endpoint on a remote host logs a warning, since the API key would travel unencrypted (`localhost` is exempt). The SDK never follows a redirect when sending, so the key cannot be forwarded to another host. A redirect is not a server rejection, so `onDeliveryFailed` is not called for it: the events stay queued and are retried, and in Node (and other runtimes whose `fetch` names the redirect) the SDK logs one warning telling you to check the endpoint URL. A browser only reports a failed request, so there a redirect looks like any other network failure.
|
|
299
303
|
|
|
300
304
|
For self-hosted or local development:
|
|
301
305
|
|
|
@@ -321,16 +325,18 @@ const tracker = new Eventra({
|
|
|
321
325
|
| retryBaseDelayMs | Base delay for exponential backoff (ms) |
|
|
322
326
|
| maxPayloadBytes | Max serialized batch size (default: 60000) |
|
|
323
327
|
| fetchImpl | Custom `fetch` (Node without native fetch, tests) |
|
|
324
|
-
| autoFlushOnExit |
|
|
328
|
+
| autoFlushOnExit | Node / serverless, default `true`: flush what is queued when the script ends by itself (`beforeExit`, bounded by `shutdownTimeoutMs`) and on `SIGINT`/`SIGTERM`. `process.exit()` and a crash do not run it, so call `await tracker.shutdown()` first |
|
|
325
329
|
| disableTimer | Disable periodic flush timer |
|
|
326
|
-
| onEventsDropped | Called
|
|
327
|
-
| onDeliveryFailed | Callback on permanent ingest errors (4xx except 429) |
|
|
330
|
+
| onEventsDropped | Called when events are dropped (queue full, an invalid event, or a single event above `maxPayloadBytes`), normally once per dropped event, so the count is 1; when a saved queue is trimmed at load, the number removed |
|
|
331
|
+
| onDeliveryFailed | Callback on permanent ingest errors (4xx except 429). The whole rejected batch is dropped, including events that were valid, because the server does not say which one it refused. A single event above `maxPayloadBytes` is reported here too, with status `413`, besides `onEventsDropped` |
|
|
328
332
|
| multiTabMode | `"independent"` (default) or `"leader"` (browser only) |
|
|
329
333
|
| 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
334
|
| 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
335
|
| diagnostics | Report delivery problems (counts only) with the next successful batch, default `true`; `false` sends nothing extra. See [Delivery diagnostics](#delivery-diagnostics) |
|
|
332
336
|
| 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 |
|
|
333
337
|
|
|
338
|
+
An option with an invalid value (for example `maxBatchSize: 0` or `NaN`, an empty `endpoint`) is ignored with one console warning and the default is used. Callbacks such as `onEventsDropped` and `onDeliveryFailed` can throw or reject without affecting the SDK. Draining a large queue (hundreds of thousands of events) takes time in proportion to its size. Some values are refused at once instead: an `apiKey` with characters a header cannot carry, a `fetchImpl` that is not a function. `endpoint` that is not a URL, an unknown `multiTabMode`, a `diagnostics` that is not `true` or `false`, a fractional `maxBatchSize` or `maxQueueSize`, and a `maxRetries` above 20 are reported with a warning and replaced. A `userId` that is `NaN` or infinite is no user id.
|
|
339
|
+
|
|
334
340
|
---
|
|
335
341
|
|
|
336
342
|
## Manual Flush
|
|
@@ -339,6 +345,8 @@ const tracker = new Eventra({
|
|
|
339
345
|
await tracker.flush();
|
|
340
346
|
```
|
|
341
347
|
|
|
348
|
+
`flush()` also waits for a send that is already running (the timer, a full batch, or the per-call flush on serverless), so awaiting it in a serverless handler is enough. While the circuit breaker is open or a `Retry-After` wait is active it resolves without sending, and the events stay queued.
|
|
349
|
+
|
|
342
350
|
---
|
|
343
351
|
|
|
344
352
|
## Shutdown
|
|
@@ -351,7 +359,7 @@ await tracker.shutdown();
|
|
|
351
359
|
|
|
352
360
|
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
361
|
|
|
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
|
|
362
|
+
`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` (each time the loop drains, so later ones too, within the same budget); `process.exit()` or a crash skips that. `track()` after `shutdown()` is ignored without a callback. `shutdown()` waits for a flush that is already running before sending what is left.
|
|
355
363
|
|
|
356
364
|
For Node / serverless, prefer explicit shutdown over relying on process signals:
|
|
357
365
|
|
|
@@ -434,7 +442,7 @@ Eventra SDK includes:
|
|
|
434
442
|
|
|
435
443
|
**100% statement/branch/function/line coverage** (v8 provider, `pnpm test:coverage`).
|
|
436
444
|
|
|
437
|
-
|
|
445
|
+
245 vitest tests across 21 files (plus 7 Playwright tests in a real browser) cover the entire delivery pipeline:
|
|
438
446
|
|
|
439
447
|
- `track()` validation — name length, userId truncation, properties depth/size, idempotency keys
|
|
440
448
|
- Batching — auto-flush at `maxBatchSize`, periodic flush via timer, queue overflow drop
|
|
@@ -446,7 +454,8 @@ Eventra SDK includes:
|
|
|
446
454
|
- Runtime detection — Node, Edge (`EdgeRuntime`), Serverless (AWS Lambda), unknown fallback, Node process exit handling
|
|
447
455
|
- Browser mode — persistence, leader election (including multi-tab lease races), BroadcastChannel sync, `fetch` keepalive, `pagehide`
|
|
448
456
|
- Storage edge cases — corrupted/blocked localStorage, quota exceeded, queue trimming
|
|
449
|
-
- Internal fallbacks
|
|
457
|
+
- Internal fallbacks - `crypto.getRandomValues` (and a random id when there is no Web Crypto at all, as on Node 18), `Buffer`/string-length byte counting
|
|
458
|
+
- Regressions: `flush()` waiting for a flush already in flight, properties copied at `track()`, a corrupt stored queue
|
|
450
459
|
|
|
451
460
|
Run locally:
|
|
452
461
|
|