@traffical/node 0.9.0 → 0.10.0

package/README.md

@@ -44,12 +44,22 @@ await client.track('purchase', {
 ```typescript
 const client = new TrafficalClient({
   // Required
+  orgId: 'org_...',
+  projectId: 'proj_...',
+  env: 'production',
   apiKey: 'sk_...',
-  
+
   // Optional
-  apiBase: 'https://api.traffical.io', // Custom API endpoint
-  cacheTtl: 60_000, // Config cache TTL in ms (default: 60s)
-  timeout: 5_000, // Request timeout in ms (default: 5s)
+  baseUrl: 'https://sdk.traffical.io', // Custom edge endpoint
+  refreshIntervalMs: 60_000,   // Config refresh interval (default: 60000)
+  batchSize: 10,               // Events per batch (default: 10)
+                               //   (legacy alias: eventBatchSize)
+  flushIntervalMs: 30_000,     // Flush interval (default: 30000)
+                               //   (legacy alias: eventFlushIntervalMs)
+  configTimeoutMs: 10_000,     // Config-fetch timeout (default: 10000)
+  eventsTimeoutMs: 10_000,     // Event-delivery timeout (default: 10000)
+  resolveTimeoutMs: 5_000,     // Server-resolve timeout (default: 5000)
+                               //   (legacy fallback for all three: requestTimeoutMs)
 });
 ```
 
@@ -106,8 +116,8 @@ The Node SDK automatically batches events for efficiency:
 ```typescript
 const client = new TrafficalClient({
   apiKey: 'sk_...',
-  batchSize: 100,      // Events per batch (default: 100)
-  flushInterval: 5000, // Flush interval in ms (default: 5s)
+  batchSize: 10,          // Events per batch (default: 10)
+  flushIntervalMs: 30000, // Flush interval in ms (default: 30s)
 });
 
 // Events are queued and sent in batches

package/dist/assignment-logger.test.js

@@ -68,9 +68,18 @@ describe("Node TrafficalClient assignmentLogger", () => {
         expect(entry.type).toBe("decision");
         expect(entry.policyId).toBe("pol_1");
         expect(entry.allocationName).toBe("treatment");
-        expect(entry.decisionId).toBe("dec_server_1");
+        // Server mode now mints a FRESH decisionId per decide() (spec 0.7.0 S8) —
+        // it no longer reuses the resolve response's decisionId across decisions.
+        expect(entry.decisionId).toMatch(/^dec_/);
+        expect(entry.decisionId).not.toBe("dec_server_1");
         expect(entry.anonymousId).toBeUndefined();
         expect(entry.id).toMatch(/^asn_/);
+        // Warehouse-native passthrough fields from the layer resolution.
+        expect(entry.bucket).toBe(500);
+        expect(entry.configVersion).toBe(serverResolveResponse.stateVersion);
+        // The server response carries no propensity or contextual model version.
+        expect(entry.probability).toBeUndefined();
+        expect(entry.modelVersion).toBeUndefined();
         await client.destroy();
     });
     test("decide() then trackExposure() produce two distinct rows (decision + exposure)", async () => {

package/dist/assignment-logger.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"assignment-logger.test.js","sourceRoot":"","sources":["../src/assignment-logger.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"assignment-logger.test.js","sourceRoot":"","sources":["../src/assignment-logger.test.ts"],"names":[],"mappings":"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"}

package/dist/canonical-options.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=canonical-options.test.d.ts.map

package/dist/canonical-options.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-options.test.d.ts","sourceRoot":"","sources":["../src/canonical-options.test.ts"],"names":[],"mappings":""}

package/dist/canonical-options.test.js

@@ -0,0 +1,167 @@
+/**
+ * Canonical option-name aliases (spec 0.7.0 sdk-design-contract).
+ *
+ * The Node client accepts the canonical option names alongside the legacy
+ * ones, and a specific canonical option always wins when both are set:
+ *   - batchSize            (alias of eventBatchSize)
+ *   - flushIntervalMs      (alias of eventFlushIntervalMs)
+ *   - configTimeoutMs / eventsTimeoutMs / resolveTimeoutMs
+ *       (per-path split of the legacy single requestTimeoutMs)
+ */
+import { describe, test, expect, afterEach, mock } from "bun:test";
+import { TrafficalClient } from "./client.js";
+const originalFetch = globalThis.fetch;
+const originalWarn = console.warn;
+afterEach(() => {
+    globalThis.fetch = originalFetch;
+    console.warn = originalWarn;
+});
+const localConfig = {
+    version: "2024-06-01T00:00:00.000Z",
+    orgId: "org_1",
+    projectId: "proj_1",
+    env: "test",
+    hashing: { unitKey: "userId", bucketCount: 1000 },
+    parameters: [
+        { key: "ui.color", type: "string", default: "#000", layerId: "layer_ui", namespace: "ui" },
+    ],
+    layers: [],
+};
+function baseOpts() {
+    return {
+        orgId: "org_1",
+        projectId: "proj_1",
+        env: "test",
+        apiKey: "pk",
+        localConfig,
+        refreshIntervalMs: -1,
+        trackDecisions: false,
+        // Never auto-flush on a timer unless a test overrides it.
+        eventFlushIntervalMs: 999999,
+        flushIntervalMs: 999999,
+    };
+}
+/** Mock fetch that records the /v1/events/batch POST bodies (config routes 404). */
+function mockEventPosts(posted) {
+    globalThis.fetch = mock(async (url, init) => {
+        if (String(url).includes("/v1/events/batch")) {
+            const body = JSON.parse(String(init?.body ?? "{}"));
+            posted.push(body.events);
+            return new Response(JSON.stringify({ accepted: 1 }), { status: 200 });
+        }
+        return new Response("not found", { status: 404 });
+    });
+}
+const tick = () => new Promise((r) => setTimeout(r, 0));
+describe("batchSize alias", () => {
+    test("canonical batchSize triggers auto-flush at the threshold", async () => {
+        const posted = [];
+        mockEventPosts(posted);
+        const client = new TrafficalClient({ ...baseOpts(), batchSize: 1 });
+        await client.initialize();
+        client.track("purchase", { orderId: "o1" }, { unitKey: "user-1" });
+        await tick();
+        expect(posted.flat().length).toBeGreaterThan(0);
+        await client.close();
+    });
+    test("legacy eventBatchSize still triggers auto-flush at the threshold", async () => {
+        const posted = [];
+        mockEventPosts(posted);
+        const client = new TrafficalClient({ ...baseOpts(), eventBatchSize: 1 });
+        await client.initialize();
+        client.track("purchase", { orderId: "o1" }, { unitKey: "user-1" });
+        await tick();
+        expect(posted.flat().length).toBeGreaterThan(0);
+        await client.close();
+    });
+    test("canonical batchSize wins over legacy eventBatchSize", async () => {
+        const posted = [];
+        mockEventPosts(posted);
+        // Canonical=1 (flush after 1) beats legacy=1000 (would never flush here).
+        const client = new TrafficalClient({ ...baseOpts(), batchSize: 1, eventBatchSize: 1000 });
+        await client.initialize();
+        client.track("purchase", { orderId: "o1" }, { unitKey: "user-1" });
+        await tick();
+        expect(posted.flat().length).toBeGreaterThan(0);
+        await client.close();
+    });
+});
+describe("flushIntervalMs alias", () => {
+    test("canonical flushIntervalMs wins over legacy eventFlushIntervalMs", async () => {
+        const posted = [];
+        mockEventPosts(posted);
+        // Canonical=10ms flushes on the timer; legacy=999999 would not within the window.
+        const client = new TrafficalClient({
+            ...baseOpts(),
+            flushIntervalMs: 10,
+            eventFlushIntervalMs: 999999,
+            batchSize: 1000, // keep batch threshold high so only the timer can flush
+        });
+        await client.initialize();
+        client.track("purchase", { orderId: "o1" }, { unitKey: "user-1" });
+        await new Promise((r) => setTimeout(r, 60));
+        expect(posted.flat().length).toBeGreaterThan(0);
+        await client.close();
+    });
+});
+/** A fetch that hangs forever but rejects with AbortError when aborted. */
+function mockHungFetch(capture) {
+    globalThis.fetch = mock((url, init) => new Promise((_resolve, reject) => {
+        capture(String(url), init?.signal);
+        init?.signal?.addEventListener("abort", () => {
+            reject(new DOMException("The operation was aborted.", "AbortError"));
+        });
+    }));
+}
+describe("configTimeoutMs alias", () => {
+    test("canonical configTimeoutMs aborts a hung config fetch (canonical wins over legacy)", async () => {
+        const warnings = [];
+        console.warn = (...args) => warnings.push(args.map(String).join(" "));
+        let configSignal;
+        mockHungFetch((url, signal) => {
+            if (url.includes("/v1/config/"))
+                configSignal = signal;
+        });
+        const client = new TrafficalClient({
+            orgId: "org_1",
+            projectId: "proj_1",
+            env: "test",
+            apiKey: "pk",
+            trackDecisions: false,
+            refreshIntervalMs: -1,
+            disableCloudEvents: true,
+            // Canonical tiny timeout must win over the huge legacy value; otherwise
+            // initialize() would hang ~100s and this test would time out.
+            configTimeoutMs: 20,
+            requestTimeoutMs: 100000,
+        });
+        await client.initialize();
+        expect(warnings.some((w) => w.includes("Failed to fetch config"))).toBe(true);
+        expect(configSignal?.aborted).toBe(true);
+        await client.close();
+    });
+});
+describe("eventsTimeoutMs alias", () => {
+    test("canonical eventsTimeoutMs aborts a hung events POST (canonical wins over legacy)", async () => {
+        console.warn = () => { };
+        let eventsSignal;
+        mockHungFetch((url, signal) => {
+            if (url.includes("/v1/events/batch"))
+                eventsSignal = signal;
+        });
+        const client = new TrafficalClient({
+            ...baseOpts(),
+            batchSize: 1, // flush after one event
+            eventsTimeoutMs: 20, // canonical tiny value...
+            requestTimeoutMs: 100000, // ...must win over the huge legacy fallback
+        });
+        // localConfig is preloaded, so no config fetch is needed before tracking.
+        client.track("purchase", { orderId: "o1" }, { unitKey: "user-1" });
+        await new Promise((r) => setTimeout(r, 80));
+        expect(eventsSignal).toBeDefined();
+        expect(eventsSignal?.aborted).toBe(true);
+        // destroySync() avoids awaiting a final flush against the still-hung fetch.
+        client.destroySync();
+    });
+});
+//# sourceMappingURL=canonical-options.test.js.map

package/dist/canonical-options.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-options.test.js","sourceRoot":"","sources":["../src/canonical-options.test.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -11,7 +11,7 @@
  * - Batched event transport for efficiency
  * - Graceful degradation with local config and schema defaults
  */
-import { type Context, type DecisionResult, type ParameterValue, type TrafficalClientOptions as CoreClientOptions, type TrackOptions, type AssignmentLogger, type TrackableEventLogger, type TrackEventMap, type OnSchemaWarnings } from "@traffical/core";
+import { type Context, type DecisionResult, type ParameterValue, type TrafficalClientOptions as CoreClientOptions, type TrackOptions, type TrackEventOptions, type DecideOptions, type GetParamsOptions, type AssignmentLogger, type TrackableEventLogger, type TrackEventMap, type OnSchemaWarnings } from "@traffical/core";
 /**
  * Options for the Node.js Traffical client.
  * Extends the core options with Node-specific settings.
@@ -30,12 +30,23 @@ export interface TrafficalClientOptions extends CoreClientOptions {
     decisionDeduplicationTtlMs?: number;
     /**
      * Event batch size - number of events before auto-flush (default: 10).
+     * @deprecated Use the canonical `batchSize` instead. `eventBatchSize` still works.
      */
     eventBatchSize?: number;
     /**
      * Event flush interval in milliseconds (default: 30000).
+     * @deprecated Use the canonical `flushIntervalMs` instead. `eventFlushIntervalMs` still works.
      */
     eventFlushIntervalMs?: number;
+    /** Events per delivery batch (default: 10). Canonical alias of `eventBatchSize`. */
+    batchSize?: number;
+    /** Event flush cadence in milliseconds (default: 30000). Canonical alias of `eventFlushIntervalMs`. */
+    flushIntervalMs?: number;
+    /**
+     * Maximum number of events buffered in memory before the oldest is dropped
+     * (default: 1000). Bounds memory in long-lived server processes.
+     */
+    eventMaxQueueSize?: number;
     /**
      * Timeout in milliseconds for SDK network requests — the config bundle
      * fetch and event batch POSTs (default: 10000).
@@ -43,8 +54,27 @@ export interface TrafficalClientOptions extends CoreClientOptions {
      * On timeout the request is aborted and treated exactly like a network
      * failure: config fetches fall back to the cached/local config, and event
      * batches are re-queued for retry.
+     *
+     * @deprecated Use the per-path options `configTimeoutMs`, `eventsTimeoutMs`,
+     * and `resolveTimeoutMs` instead. `requestTimeoutMs` is still honored as the
+     * legacy fallback for all three when the specific option is not provided.
      */
     requestTimeoutMs?: number;
+    /**
+     * Timeout in milliseconds for the config-bundle fetch (default: 10000).
+     * Falls back to `requestTimeoutMs` when not set.
+     */
+    configTimeoutMs?: number;
+    /**
+     * Timeout in milliseconds for event-delivery POSTs (default: 10000).
+     * Falls back to `requestTimeoutMs` when not set.
+     */
+    eventsTimeoutMs?: number;
+    /**
+     * Timeout in milliseconds for server-resolve requests (POST /v1/resolve,
+     * default: 5000). Falls back to `requestTimeoutMs` when not set.
+     */
+    resolveTimeoutMs?: number;
     /**
      * Enable debug logging for events (default: false).
      */
@@ -70,6 +100,15 @@ export interface TrafficalClientOptions extends CoreClientOptions {
      * (same unit+policy+variant won't fire again within TTL). Default: true.
      */
     deduplicateAssignmentLogger?: boolean;
+    /**
+     * When true, exposure events are deduplicated per (unit, policy, allocation)
+     * within a session via in-memory LRU, mirroring the browser SDK. Default: true.
+     */
+    deduplicateExposures?: boolean;
+    /**
+     * Exposure deduplication session TTL in milliseconds (default: 30 minutes).
+     */
+    exposureSessionTtlMs?: number;
     /**
      * Optional callback for routing full events (exposure, track, decision)
      * to a customer-managed pipeline (e.g. Jitsu, Segment). Fires regardless
@@ -107,21 +146,44 @@ export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventM
     private readonly _disableCloudEvents;
     /** In-memory LRU for assignment logger deduplication: key → expiry timestamp */
     private readonly _assignmentLoggerDedup;
+    /** In-memory LRU for exposure-event deduplication: key → expiry timestamp */
+    private readonly _exposureDedup;
+    /** Session TTL for exposure deduplication (ms) */
+    private readonly _exposureSessionTtlMs;
     /** Cache of recent decisions for attribution lookup on rewards */
     private readonly _decisionCache;
+    /** Serialized context of the last server-mode resolve (per-call throttle). */
+    private _lastResolveContextKey;
+    /** Resolves once the first config load attempt completes (fail-open). */
+    private _readyResolve;
+    private readonly _readyPromise;
     constructor(options: TrafficalClientOptions);
     /**
      * Initializes the client by fetching the config bundle.
      * This is called automatically by createTrafficalClient.
      */
     initialize(): Promise<void>;
+    /**
+     * Resolves once the first usable config has loaded (or the SDK has failed
+     * open on an unavailable/malformed bundle). Never rejects.
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * Single teardown verb (spec 0.7.0 design contract). Stops background
+     * refresh and awaits a final event flush before returning.
+     */
+    close(): Promise<void>;
     /**
      * Stops background refresh and cleans up resources.
+     *
+     * @deprecated Use {@link close} instead — the canonical single teardown verb.
      */
     destroy(): Promise<void>;
     /**
      * Synchronous destroy for process exit handlers.
-     * Use destroy() when possible for proper cleanup.
+     *
+     * @deprecated Use {@link close} instead. This best-effort variant does not
+     * await the final flush; prefer `await close()` where you can.
      */
     destroySync(): void;
     /**
@@ -132,6 +194,17 @@ export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventM
      * Gets the current config bundle version.
      */
     getConfigVersion(): string | null;
+    /**
+     * Returns the context field the bundle buckets on (the project's unit key),
+     * or null before the bundle has loaded. Adapters (e.g. an OpenFeature
+     * provider) map their targeting key onto this field.
+     */
+    getUnitKeyField(): string | null;
+    /**
+     * Returns the id of the layer a parameter belongs to, or null if the
+     * parameter is unknown / the bundle is not yet loaded.
+     */
+    getParameterLayerId(key: string): string | null;
     /**
      * Flush pending events immediately.
      */
@@ -145,25 +218,29 @@ export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventM
      * 3. Local config (if remote unavailable)
      * 4. Caller defaults
      */
-    getParams<T extends Record<string, ParameterValue>>(options: {
-        context: Context;
-        defaults: T;
-    }): T;
+    getParams<T extends Record<string, ParameterValue>>(context: Context, defaults: T): T;
+    /** @deprecated Pass `(context, defaults)` positionally (spec 0.7.0 contract). */
+    getParams<T extends Record<string, ParameterValue>>(options: GetParamsOptions<T>): T;
     /**
      * Makes a decision with full metadata for tracking.
      *
      * When trackDecisions is enabled (default), automatically sends a DecisionEvent
      * to the backend for intent-to-treat analysis.
      */
-    decide<T extends Record<string, ParameterValue>>(options: {
-        context: Context;
-        defaults: T;
-    }): DecisionResult;
+    decide<T extends Record<string, ParameterValue>>(context: Context, defaults: T): DecisionResult;
+    /** @deprecated Pass `(context, defaults)` positionally (spec 0.7.0 contract). */
+    decide<T extends Record<string, ParameterValue>>(options: DecideOptions<T>): DecisionResult;
     /**
-     * Tracks an exposure event.
+     * Tracks an exposure event — the "user was actually shown this treatment"
+     * signal (treatment-on-the-treated).
      *
-     * If the decision includes filtered context (from policies with contextLogging),
-     * it will be included in the exposure event for contextual bandit training.
+     * Only layers the caller was actually exposed to are emitted: layers without
+     * a policy/allocation and `attributionOnly` layers (resolved for attribution
+     * but whose parameters weren't requested) are skipped, and each
+     * (unit, policy, allocation) is deduplicated per session so the same exposure
+     * isn't emitted twice. Mirrors the browser SDK. If the decision includes
+     * filtered context (from policies with contextLogging), it is included in the
+     * exposure event for contextual bandit training.
      */
     trackExposure(decision: DecisionResult): void;
     /**
@@ -179,10 +256,7 @@ export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventM
      * // Track with explicit decision attribution
      * client.track('checkout_complete', { value: 1 }, { decisionId: 'dec_xyz' });
      */
-    track<E extends Extract<keyof TEvents, string>>(event: E, properties?: TEvents[E], options?: {
-        decisionId?: string;
-        unitKey?: string;
-    }): void;
+    track<E extends Extract<keyof TEvents, string>>(event: E, properties?: TEvents[E], options?: TrackEventOptions): void;
     /**
      * @deprecated Use track() instead.
      * Tracks a reward event.
@@ -206,8 +280,18 @@ export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventM
     /**
      * Logs an offline warning (rate-limited).
      */
+    /**
+     * Server mode: threads the per-call context into a background /v1/resolve so
+     * the cached snapshot converges to the contexts actually being evaluated.
+     * Throttled by serialized context so repeated identical contexts (the common
+     * case) don't hammer the edge. Because decide()/getParams() are synchronous
+     * they cannot await this; the current call degrades to the last-good snapshot
+     * and subsequent calls pick up the refreshed resolution.
+     */
+    private _maybeResolveForContext;
     private _fetchServerResolve;
     private _logOfflineWarning;
+    private _logMalformedBundleWarning;
     /**
      * Routes a built event to the BYO event logger (if configured) and to the
      * Traffical edge batcher (unless cloud events are disabled).

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}