@fluxtrace/node 3.9.0 → 3.9.1
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 +71 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# @fluxtrace/node
|
|
2
|
+
|
|
3
|
+
Server-side tracking, identification, and feature flags for FluxTrace.
|
|
4
|
+
Requires Node.js 20 or later. ESM only.
|
|
5
|
+
|
|
6
|
+
## Install
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
npm install @fluxtrace/node
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Usage
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
import { FluxtraceClient } from "@fluxtrace/node";
|
|
16
|
+
|
|
17
|
+
const client = new FluxtraceClient({
|
|
18
|
+
trackingId: "YOUR_TRACKING_ID",
|
|
19
|
+
endpoint: "https://collector.example.com/api/collect",
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
await client.identify("user-123", { plan: "pro" });
|
|
23
|
+
await client.track("checkout_completed", { amount: 4999 });
|
|
24
|
+
|
|
25
|
+
if (await client.isFeatureEnabled("new-checkout")) {
|
|
26
|
+
// ...
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## API
|
|
31
|
+
|
|
32
|
+
### `new FluxtraceClient(options)`
|
|
33
|
+
|
|
34
|
+
| Option | Required | Default | Description |
|
|
35
|
+
| ------------ | -------- | --------------- | -------------------------------------------------------- |
|
|
36
|
+
| `trackingId` | yes | — | Project tracking id sent as `projectId` on collect |
|
|
37
|
+
| `endpoint` | no | `/api/collect` | Absolute collect URL (relative default can't be called from Node) |
|
|
38
|
+
| `apiHost` | no | — | Web origin for flag lookups; when set, flags use `subjectId`, otherwise the deprecated `userId` alias |
|
|
39
|
+
| `fetch` | no | global `fetch` | Override for tests |
|
|
40
|
+
|
|
41
|
+
### `track(name, props?)`
|
|
42
|
+
|
|
43
|
+
Sends a track event. Throws when `name` is missing. Payloads are validated
|
|
44
|
+
against the FluxTrace collect schema before sending.
|
|
45
|
+
|
|
46
|
+
### `identify(userId, traits?)`
|
|
47
|
+
|
|
48
|
+
Sends an identify call and remembers `userId` on the instance, so later
|
|
49
|
+
`track` calls are attributed to that user.
|
|
50
|
+
|
|
51
|
+
### `getFlags(userId?)`
|
|
52
|
+
|
|
53
|
+
Returns the evaluated flag map (`Record<string, boolean>`) for the given
|
|
54
|
+
user, defaulting to the identified user. Throws `CollectError` on HTTP
|
|
55
|
+
failure. Flag fetching never blocks `track`.
|
|
56
|
+
|
|
57
|
+
### `isFeatureEnabled(key, userId?)`
|
|
58
|
+
|
|
59
|
+
Convenience wrapper returning `true` only when the flag is explicitly `true`.
|
|
60
|
+
|
|
61
|
+
## Reliability
|
|
62
|
+
|
|
63
|
+
- Up to 3 delivery attempts per call with linear backoff.
|
|
64
|
+
- HTTP `429` responses are retried; other non-2xx responses throw
|
|
65
|
+
`CollectError` with the response `status`.
|
|
66
|
+
- Network failures are retried; anything else is thrown immediately.
|
|
67
|
+
|
|
68
|
+
## Errors
|
|
69
|
+
|
|
70
|
+
`CollectError extends Error` carries a numeric `status` (`400` for invalid
|
|
71
|
+
payloads, the HTTP status otherwise).
|