@fluxtrace/node 3.9.0 → 3.10.0

package/README.md

@@ -0,0 +1,138 @@
+# @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.
+
+## Install
+
+```bash
+npm install @fluxtrace/node
+```
+
+- Package: <https://www.npmjs.com/package/@fluxtrace/node>
+- Zero runtime dependencies. TypeScript types included.
+
+## Usage
+
+```ts
+import { FluxtraceClient } from "@fluxtrace/node";
+
+const client = new FluxtraceClient({
+  trackingId: "YOUR_TRACKING_ID",
+  endpoint: "https://collector.example.com/api/collect",
+});
+
+await client.identify("user-123", { plan: "pro" });
+await client.track("checkout_completed", { amount: 4999 });
+
+if (await client.isFeatureEnabled("new-checkout")) {
+  // ...
+}
+```
+
+## API
+
+### `new FluxtraceClient(options)`
+
+| 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?)`
+
+```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?)`
+
+```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?)`
+
+```ts
+if (await client.isFeatureEnabled("new-checkout", "user-456")) {
+  // serve the new experience
+}
+```
+
+Returns `true` only when the flag is explicitly `true`.
+
+## Reliability
+
+- Up to 3 delivery attempts per call with linear backoff.
+- HTTP `429` responses are retried; other non-2xx responses throw
+  `CollectError` with the response `status`.
+- Network failures are retried; anything else is thrown immediately.
+
+## 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.0",
+  "version": "3.10.0",
   "private": false,
   "description": "Server-side track, identify, and feature flags for FluxTrace",
   "type": "module",