@fluxtrace/node 0.0.0-stage → 3.9.1

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @fluxtrace/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Server-side tracking, identification, and feature flags for FluxTrace.
+Requires Node.js 20 or later. ESM only.
+
+## Install
+
+```bash
+npm install @fluxtrace/node
+```
+
+## 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 (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                                       |
+
+### `track(name, props?)`
+
+Sends a track event. Throws when `name` is missing. Payloads are validated
+against the FluxTrace collect schema before sending.
+
+### `identify(userId, traits?)`
+
+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`.
+
+### `isFeatureEnabled(key, userId?)`
+
+Convenience wrapper returning `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
+
+`CollectError extends Error` carries a numeric `status` (`400` for invalid
+payloads, the HTTP status otherwise).

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+declare class CollectError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+type FluxtraceClientOptions = {
+    /** Project tracking id sent as `projectId` on `POST /api/collect`. */
+    trackingId: string;
+    /**
+     * Absolute collect URL. Defaults to `/api/collect`, which Node cannot call
+     * until you pass an absolute URL such as `https://collector.example.com/api/collect`.
+     */
+    endpoint?: string;
+    /**
+     * Web origin for `GET /api/projects/:id/flags`. When set, flags use this
+     * origin and `subjectId`. When unset, flags stay on the collector origin
+     * and send the deprecated `userId` alias.
+     */
+    apiHost?: string;
+    /** Override for tests. Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+};
+/**
+ * Server-side collector client.
+ * `identify` sends `userId`, which the worker stores on `sessions.identified_user_id`.
+ * Later `track` calls on the same instance reuse that id.
+ */
+declare class FluxtraceClient {
+    readonly trackingId: string;
+    readonly endpoint: string;
+    private readonly apiHost;
+    private readonly fetchImpl;
+    private identifiedUserId;
+    constructor(options: FluxtraceClientOptions);
+    track(name: string, props?: Record<string, unknown>): Promise<void>;
+    identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
+    /** Evaluated flag map from `GET /api/projects/:id/flags`. Does not block `track`. */
+    getFlags(userId?: string): Promise<Record<string, boolean>>;
+    isFeatureEnabled(key: string, userId?: string): Promise<boolean>;
+    private flagsUrl;
+    private send;
+}
+
+export { CollectError, FluxtraceClient, type FluxtraceClientOptions };