@fluxtrace/node 3.9.1 → 3.10.0

package/README.md

@@ -1,5 +1,7 @@
 # @fluxtrace/node
 
+[![npm version](https://img.shields.io/npm/v/@fluxtrace/node)](https://www.npmjs.com/package/@fluxtrace/node)
+
 Server-side tracking, identification, and feature flags for FluxTrace.
 Requires Node.js 20 or later. ESM only.
 
@@ -9,6 +11,9 @@ Requires Node.js 20 or later. ESM only.
 npm install @fluxtrace/node
 ```
 
+- Package: <https://www.npmjs.com/package/@fluxtrace/node>
+- Zero runtime dependencies. TypeScript types included.
+
 ## Usage
 
 ```ts
@@ -31,32 +36,56 @@ if (await client.isFeatureEnabled("new-checkout")) {
 
 ### `new FluxtraceClient(options)`
 
-| Option       | Required | Default         | Description                                              |
-| ------------ | -------- | --------------- | -------------------------------------------------------- |
-| `trackingId` | yes      | —               | Project tracking id sent as `projectId` on collect       |
-| `endpoint`   | no       | `/api/collect`  | Absolute collect URL (relative default can't be called from Node) |
-| `apiHost`    | no       | —               | Web origin for flag lookups; when set, flags use `subjectId`, otherwise the deprecated `userId` alias |
-| `fetch`      | no       | global `fetch`  | Override for tests                                       |
+| Option       | Required | Default        | Description                                              |
+| ------------ | -------- | -------------- | -------------------------------------------------------- |
+| `trackingId` | yes      | —              | Project tracking id sent as `projectId` on collect       |
+| `endpoint`   | no       | `/api/collect` | Absolute collect URL (the relative default can't be called from Node — always set this server-side) |
+| `apiHost`    | no       | —              | Web origin for flag lookups. When set, flags use `subjectId`; when unset they stay on the collector origin with the deprecated `userId` alias |
+| `fetch`      | no       | global `fetch` | Override for tests                                       |
 
 ### `track(name, props?)`
 
-Sends a track event. Throws when `name` is missing. Payloads are validated
-against the FluxTrace collect schema before sending.
+```ts
+await client.track("checkout_completed", {
+  amount: 4999,
+  currency: "USD",
+  coupon: null, // null/undefined values are allowed
+});
+```
+
+Throws when `name` is missing. Payloads are validated against the
+FluxTrace collect schema client-side before sending.
 
 ### `identify(userId, traits?)`
 
+```ts
+await client.identify("user-123", { plan: "pro", role: "admin" });
+```
+
 Sends an identify call and remembers `userId` on the instance, so later
 `track` calls are attributed to that user.
 
 ### `getFlags(userId?)`
 
-Returns the evaluated flag map (`Record<string, boolean>`) for the given
-user, defaulting to the identified user. Throws `CollectError` on HTTP
-failure. Flag fetching never blocks `track`.
+```ts
+// Flags for the identified user…
+const mine = await client.getFlags();
+// …or for someone else
+const theirs = await client.getFlags("user-456");
+```
+
+Returns the evaluated flag map (`Record<string, boolean>`). Throws
+`CollectError` on HTTP failure. Flag fetching never blocks `track`.
 
 ### `isFeatureEnabled(key, userId?)`
 
-Convenience wrapper returning `true` only when the flag is explicitly `true`.
+```ts
+if (await client.isFeatureEnabled("new-checkout", "user-456")) {
+  // serve the new experience
+}
+```
+
+Returns `true` only when the flag is explicitly `true`.
 
 ## Reliability
 
@@ -67,5 +96,43 @@ Convenience wrapper returning `true` only when the flag is explicitly `true`.
 
 ## Errors
 
+```ts
+import { CollectError, FluxtraceClient } from "@fluxtrace/node";
+
+try {
+  await client.track("purchase", { amount: 100 });
+} catch (err) {
+  if (err instanceof CollectError && err.status === 429) {
+    // rate limited — already retried 3× inside the client
+  }
+  throw err;
+}
+```
+
 `CollectError extends Error` carries a numeric `status` (`400` for invalid
 payloads, the HTTP status otherwise).
+
+## Testing
+
+Inject a stub `fetch` — no network needed:
+
+```ts
+const calls: unknown[] = [];
+const client = new FluxtraceClient({
+  trackingId: "test-project",
+  endpoint: "https://collector.test/api/collect",
+  fetch: (async (url: unknown, init?: { body?: string }) => {
+    calls.push(JSON.parse(init!.body!));
+    return new Response(null, { status: 204 });
+  }) as typeof fetch,
+});
+
+await client.track("signup");
+console.log(calls.length); // 1
+```
+
+## Changelog
+
+### 3.9.0
+
+- Initial public release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluxtrace/node",
-  "version": "3.9.1",
+  "version": "3.10.0",
   "private": false,
   "description": "Server-side track, identify, and feature flags for FluxTrace",
   "type": "module",