@traffical/js-client 0.14.0 → 0.16.0

package/dist/client.js

@@ -9,7 +9,7 @@
  * - Plugin system (P2)
  * - Auto stable ID for anonymous users
  */
-import { resolveParameters, decide as coreDecide, getUnitKeyValue, generateExposureId, generateTrackEventId, generateDecisionId, generateAssignmentId, } from "@traffical/core";
+import { resolveParameters, decide as coreDecide, getUnitKeyValue, getUnitKeyField as coreGetUnitKeyField, getParameterLayerId as coreGetParameterLayerId, generateExposureId, generateTrackEventId, generateDecisionId, generateAssignmentId, } from "@traffical/core";
 import { DecisionClient, createEdgeDecideRequest, } from "@traffical/core-io";
 import { ErrorBoundary } from "./error-boundary.js";
 import { EventLogger } from "./event-logger.js";
@@ -23,10 +23,59 @@ import { SDK_VERSION } from "./version.js";
 // Constants
 // =============================================================================
 const SDK_NAME = "js-client";
+/**
+ * Normalizes evaluation-method arguments so both the canonical positional form
+ * `decide(context, defaults)` and the legacy object-bag form
+ * `decide({ context, defaults })` work. Positional is detected by the presence
+ * of the second (`defaults`) argument; the bag form is soft-deprecated.
+ */
+function normalizeEvalArgs(contextOrOptions, maybeDefaults) {
+    if (maybeDefaults !== undefined) {
+        return { context: contextOrOptions, defaults: maybeDefaults };
+    }
+    const bag = contextOrOptions;
+    return { context: bag.context, defaults: bag.defaults };
+}
 const DEFAULT_BASE_URL = "https://sdk.traffical.io";
 const DEFAULT_REFRESH_INTERVAL_MS = 60000; // 1 minute
+const DEFAULT_REQUEST_TIMEOUT_MS = 10000; // 10 seconds
 const OFFLINE_WARNING_INTERVAL_MS = 300000; // 5 minutes
+const MALFORMED_BUNDLE_WARNING_INTERVAL_MS = 300000; // 5 minutes
 const DECISION_CACHE_MAX_SIZE = 100; // Max decisions to cache for attribution lookup
+/** +/-10% jitter on the background refresh interval to avoid thundering-herd sync. */
+const REFRESH_JITTER_RATIO = 0.1;
+/** Returns `intervalMs` perturbed by uniform +/-REFRESH_JITTER_RATIO jitter. */
+function jitteredInterval(intervalMs) {
+    const delta = intervalMs * REFRESH_JITTER_RATIO;
+    return intervalMs + (Math.random() * 2 - 1) * delta;
+}
+/**
+ * Structural guard for a fetched config bundle. A 200 response can still carry a
+ * malformed body (truncated CDN write, partial deploy); serving it would corrupt
+ * every bucket assignment. Requires the hashing config the resolver depends on
+ * (`unitKey` non-empty, `bucketCount` an integer >= 1) plus the top-level
+ * parameters/layers arrays.
+ */
+function isValidConfigBundle(bundle) {
+    if (!bundle || typeof bundle !== "object")
+        return false;
+    const b = bundle;
+    if (!Array.isArray(b.parameters))
+        return false;
+    if (!Array.isArray(b.layers))
+        return false;
+    const hashing = b.hashing;
+    if (!hashing || typeof hashing !== "object")
+        return false;
+    if (typeof hashing.unitKey !== "string" || hashing.unitKey.length === 0)
+        return false;
+    if (typeof hashing.bucketCount !== "number" ||
+        !Number.isInteger(hashing.bucketCount) ||
+        hashing.bucketCount < 1) {
+        return false;
+    }
+    return true;
+}
 // =============================================================================
 // TrafficalClient Class
 // =============================================================================
@@ -37,6 +86,7 @@ export class TrafficalClient {
             etag: null,
             lastFetchTime: 0,
             lastOfflineWarning: 0,
+            lastMalformedWarning: 0,
             refreshTimer: null,
             isInitialized: false,
             serverResponse: null,
@@ -55,6 +105,11 @@ export class TrafficalClient {
         this._identityListeners = [];
         this._overrideListeners = [];
         this._overrides = {};
+        /** Serialized context of the last server-mode resolve (per-call throttle). */
+        this._lastResolveContextKey = null;
+        this._readyPromise = new Promise((resolve) => {
+            this._readyResolve = resolve;
+        });
         const evaluationMode = options.evaluationMode ?? "bundle";
         this._options = {
             orgId: options.orgId,
@@ -67,6 +122,9 @@ export class TrafficalClient {
             attributionMode: options.attributionMode ?? "cumulative",
             evaluationMode,
         };
+        // Config-fetch timeout: canonical configTimeoutMs wins, else legacy requestTimeoutMs.
+        this._requestTimeoutMs =
+            options.configTimeoutMs ?? options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
         // Create DecisionClient when needed (server mode, or bundle mode may use for edge policies)
         const decisionClientConfig = {
             baseUrl: this._options.baseUrl,
@@ -74,6 +132,9 @@ export class TrafficalClient {
             projectId: this._options.projectId,
             env: this._options.env,
             apiKey: this._options.apiKey,
+            // Server-resolve timeout: canonical resolveTimeoutMs wins, else legacy
+            // requestTimeoutMs; undefined lets DecisionClient apply its own 5s default.
+            defaultTimeoutMs: options.resolveTimeoutMs ?? options.requestTimeoutMs,
         };
         this._decisionClient = new DecisionClient(decisionClientConfig);
         // Initialize components
@@ -102,8 +163,12 @@ export class TrafficalClient {
             apiKey: options.apiKey,
             storage: this._storage,
             lifecycleProvider: this._lifecycleProvider,
-            batchSize: options.eventBatchSize,
-            flushIntervalMs: options.eventFlushIntervalMs,
+            // Canonical batchSize/flushIntervalMs win over legacy event* names.
+            batchSize: options.batchSize ?? options.eventBatchSize,
+            flushIntervalMs: options.flushIntervalMs ?? options.eventFlushIntervalMs,
+            maxQueueSize: options.eventMaxQueueSize,
+            // Event-delivery timeout: canonical eventsTimeoutMs wins, else legacy requestTimeoutMs.
+            requestTimeoutMs: options.eventsTimeoutMs ?? options.requestTimeoutMs,
             onError: (error) => {
                 console.warn("[Traffical] Event logging error:", error.message);
             },
@@ -133,6 +198,7 @@ export class TrafficalClient {
                     projectId: this._options.projectId,
                     env: this._options.env,
                     log: (event) => this._dispatchEvent(event),
+                    getConfigVersion: () => this.getConfigVersion(),
                 }),
                 priority: 100, // High priority so it runs before user plugins
             });
@@ -175,6 +241,8 @@ export class TrafficalClient {
             // Run plugin onInitialize hooks (pass client reference for autonomous plugins)
             await this._plugins.runInitialize(this);
         }, undefined);
+        // Fail-open: resolve readiness even if the config load errored/degraded.
+        this._readyResolve();
     }
     /**
      * Check if the client is initialized.
@@ -182,8 +250,51 @@ export class TrafficalClient {
     get isInitialized() {
         return this._state.isInitialized;
     }
+    /**
+     * Resolves once the first usable config has loaded (or the SDK has failed
+     * open on an unavailable/malformed bundle). Never rejects.
+     */
+    async waitForReady() {
+        return this._readyPromise;
+    }
+    /**
+     * Single teardown verb (spec 0.7.0 design contract). Awaits a final event
+     * flush before returning; on page unload it falls back to sendBeacon so the
+     * final batch still ships. Prefer this over destroy()/destroySync().
+     */
+    async close() {
+        if (this._state.refreshTimer) {
+            clearInterval(this._state.refreshTimer);
+            this._state.refreshTimer = null;
+        }
+        // Await the final flush in the normal path; fall back to a beacon on unload
+        // (a normal async flush can't complete as the page tears down).
+        if (this._lifecycleProvider.isUnloading()) {
+            this._eventLogger.flushBeacon();
+        }
+        else {
+            await this._eventLogger.flush().catch(() => { });
+        }
+        this._eventLogger.destroy();
+        this._plugins.runDestroy();
+        this._identityListeners = [];
+        this._overrideListeners = [];
+        this._overrides = {};
+        if (typeof window !== "undefined") {
+            const w = window;
+            const instances = w.__TRAFFICAL_INSTANCES__;
+            if (instances) {
+                const idx = instances.indexOf(this);
+                if (idx !== -1)
+                    instances.splice(idx, 1);
+            }
+        }
+    }
     /**
      * Stops background refresh and cleans up resources.
+     *
+     * @deprecated Use {@link close} instead — the canonical single teardown verb
+     * that awaits the final flush.
      */
     destroy() {
         if (this._state.refreshTimer) {
@@ -236,17 +347,28 @@ export class TrafficalClient {
     getConfigVersion() {
         return this._state.serverResponse?.stateVersion ?? this._state.bundle?.version ?? null;
     }
-    // ===========================================================================
-    // Parameter Resolution
-    // ===========================================================================
     /**
-     * Resolves parameters with defaults as fallback.
+     * 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() {
+        return coreGetUnitKeyField(this._getEffectiveBundle());
+    }
+    /**
+     * Returns the id of the layer a parameter belongs to, or null if the
+     * parameter is unknown / the bundle is not yet loaded.
      */
-    getParams(options) {
+    getParameterLayerId(key) {
+        return coreGetParameterLayerId(this._getEffectiveBundle(), key);
+    }
+    getParams(contextOrOptions, maybeDefaults) {
+        const { context: rawContext, defaults } = normalizeEvalArgs(contextOrOptions, maybeDefaults);
         return this._errorBoundary.capture("getParams", () => {
             // Server mode: return from cached server response
             if (this._options.evaluationMode === "server" && this._state.serverResponse) {
-                const result = { ...options.defaults };
+                this._maybeResolveForContext(rawContext);
+                const result = { ...defaults };
                 for (const [key, value] of Object.entries(this._state.serverResponse.assignments)) {
                     if (key in result) {
                         result[key] = value;
@@ -257,33 +379,37 @@ export class TrafficalClient {
                 return result;
             }
             const bundle = this._getEffectiveBundle();
-            const context = this._enrichContext(options.context);
-            const params = resolveParameters(bundle, context, options.defaults);
+            const context = this._enrichContext(rawContext);
+            const params = resolveParameters(bundle, context, defaults);
             // Run plugin onResolve hooks (e.g., DOM binding plugin)
             this._plugins.runResolve(params);
             // Apply parameter overrides (post-resolution, post-plugin)
             this._applyOverridesToResult(params);
             return params;
-        }, options.defaults);
+        }, defaults);
     }
-    /**
-     * Makes a decision with full metadata for tracking.
-     */
-    decide(options) {
+    decide(contextOrOptions, maybeDefaults) {
+        const { context: rawContext, defaults } = normalizeEvalArgs(contextOrOptions, maybeDefaults);
         return this._errorBoundary.capture("decide", () => {
             // Server mode: return from cached server response
             if (this._options.evaluationMode === "server" && this._state.serverResponse) {
+                this._maybeResolveForContext(rawContext);
                 const resp = this._state.serverResponse;
-                const assignments = { ...options.defaults };
+                const assignments = { ...defaults };
                 for (const [key, value] of Object.entries(resp.assignments)) {
                     if (key in assignments) {
                         assignments[key] = value;
                     }
                 }
                 const decision = {
-                    decisionId: resp.decisionId,
+                    // Fresh decisionId per call — never reuse the resolve response's
+                    // decisionId across decisions (spec 0.7.0 S8).
+                    decisionId: generateDecisionId(),
                     assignments,
-                    metadata: resp.metadata,
+                    // Snapshot the resolve stateVersion at decision time so events
+                    // built later stamp the version this decision was evaluated
+                    // against (not whatever response is cached at event-build time).
+                    metadata: { ...resp.metadata, configVersion: resp.stateVersion },
                 };
                 this._cacheDecision(decision);
                 this._updateCumulativeAttribution(decision);
@@ -294,11 +420,11 @@ export class TrafficalClient {
             }
             const bundle = this._getEffectiveBundle();
             // Run plugin onBeforeDecision hooks
-            let context = this._enrichContext(options.context);
+            let context = this._enrichContext(rawContext);
             context = this._plugins.runBeforeDecision(context);
             // Pass cached edge results (from bundle mode pre-fetch) if available
             const edgeOpts = this._state.cachedEdgeResults ?? undefined;
-            const decision = coreDecide(bundle, context, options.defaults, edgeOpts);
+            const decision = coreDecide(bundle, context, defaults, edgeOpts);
             // Cache decision for attribution lookup when track() is called
             this._cacheDecision(decision);
             // Accumulate attribution entries (survives decision cache eviction)
@@ -311,7 +437,7 @@ export class TrafficalClient {
             return decision;
         }, {
             decisionId: generateDecisionId(),
-            assignments: options.defaults,
+            assignments: defaults,
             metadata: {
                 timestamp: new Date().toISOString(),
                 unitKeyValue: "",
@@ -337,39 +463,51 @@ export class TrafficalClient {
                 return;
             // Emit to assignment logger (separate from cloud events)
             this._emitAssignmentLogEntries(decision, "exposure");
-            // Check each layer for deduplication
+            // Config bundle version the SDK evaluated against — from the
+            // decision-time snapshot. The current version is only a fallback for
+            // decisions that predate the snapshot field.
+            const configVersion = decision.metadata.configVersion ?? this.getConfigVersion() ?? undefined;
+            // S4 canonical shape: ONE exposure event per trackExposure() carrying
+            // only newly-exposed, non-attributionOnly layers. Skip layers without
+            // a policy/allocation, skip attribution-only layers (parameters not
+            // requested by this decision), and dedup per (unit, policy, allocation)
+            // for the session (dedup on by default). Mirrors the Node SDK — no
+            // longer one event per layer with the full unfiltered layers array.
+            const exposedLayers = [];
             for (const layer of decision.metadata.layers) {
                 if (!layer.policyId || !layer.allocationName)
                     continue;
-                // Skip attribution-only layers — the user wasn't exposed to
-                // parameters from this layer, so no exposure event should fire.
                 if (layer.attributionOnly)
                     continue;
-                // Deduplicate
                 const isNew = this._exposureDedup.checkAndMark(unitKey, layer.policyId, layer.allocationName);
                 if (!isNew)
                     continue;
-                const event = {
-                    type: "exposure",
-                    id: generateExposureId(), // Unique exposure ID (not same as decision)
-                    decisionId: decision.decisionId,
-                    orgId: this._options.orgId,
-                    projectId: this._options.projectId,
-                    env: this._options.env,
-                    unitKey,
-                    timestamp: new Date().toISOString(),
-                    assignments: decision.assignments,
-                    layers: decision.metadata.layers,
-                    context: decision.metadata.filteredContext,
-                    sdkName: SDK_NAME,
-                    sdkVersion: SDK_VERSION,
-                };
-                // Run plugin onExposure hooks
-                if (!this._plugins.runExposure(event)) {
-                    continue;
-                }
-                this._dispatchEvent(event);
+                exposedLayers.push(layer);
             }
+            // Nothing new to expose (all attribution-only or already seen this
+            // session) — emit NO event (never an empty-layers event).
+            if (exposedLayers.length === 0)
+                return;
+            const event = {
+                type: "exposure",
+                id: generateExposureId(), // Unique exposure ID (not same as decision)
+                decisionId: decision.decisionId,
+                orgId: this._options.orgId,
+                projectId: this._options.projectId,
+                env: this._options.env,
+                unitKey,
+                timestamp: new Date().toISOString(),
+                assignments: decision.assignments,
+                layers: exposedLayers,
+                context: decision.metadata.filteredContext,
+                configVersion,
+                sdkName: SDK_NAME,
+                sdkVersion: SDK_VERSION,
+            };
+            // Run plugin onExposure hooks
+            if (!this._plugins.runExposure(event))
+                return;
+            this._dispatchEvent(event);
         }, undefined);
     }
     /**
@@ -392,7 +530,12 @@ export class TrafficalClient {
     track(eventName, properties, options) {
         this._errorBoundary.capture("track", () => {
             const unitKey = options?.unitKey ?? this._stableId.getId();
-            const value = typeof properties?.value === 'number' ? properties.value : undefined;
+            // Single numeric value: explicit options.value wins, else properties.value.
+            const value = typeof options?.value === "number"
+                ? options.value
+                : typeof properties?.value === "number"
+                    ? properties.value
+                    : undefined;
             // Auto-populate attribution from cached decisions
             const attribution = this._buildAttribution(unitKey, options?.decisionId);
             const decisionId = options?.decisionId;
@@ -406,9 +549,11 @@ export class TrafficalClient {
                 timestamp: new Date().toISOString(),
                 event: eventName,
                 value,
+                values: options?.values,
                 properties,
                 decisionId,
                 attribution,
+                eventTimestamp: options?.eventTimestamp,
                 sdkName: SDK_NAME,
                 sdkVersion: SDK_VERSION,
             };
@@ -584,6 +729,9 @@ export class TrafficalClient {
         const unitKey = decision.metadata.unitKeyValue;
         if (!unitKey)
             return;
+        // Config bundle version the SDK evaluated against — from the
+        // decision-time snapshot, falling back to the current version.
+        const configVersion = decision.metadata.configVersion ?? this.getConfigVersion() ?? undefined;
         for (const layer of decision.metadata.layers) {
             if (!layer.policyId || !layer.allocationName)
                 continue;
@@ -612,6 +760,10 @@ export class TrafficalClient {
                 decisionId: decision.decisionId,
                 anonymousId: this._stableId.getId(),
                 id: generateAssignmentId(),
+                bucket: layer.bucket >= 0 ? layer.bucket : undefined,
+                probability: layer.probability,
+                modelVersion: layer.modelVersion,
+                configVersion,
             });
         }
     }
@@ -641,7 +793,9 @@ export class TrafficalClient {
         return context;
     }
     async _fetchConfig() {
-        const url = `${this._options.baseUrl}/v1/config/${this._options.projectId}?env=${this._options.env}`;
+        // URL-encode path/query components so an env or projectId containing
+        // reserved characters (spaces, &, ?, /) can't corrupt the request URL.
+        const url = `${this._options.baseUrl}/v1/config/${encodeURIComponent(this._options.projectId)}?env=${encodeURIComponent(this._options.env)}`;
         const headers = {
             "Content-Type": "application/json",
             Authorization: `Bearer ${this._options.apiKey}`,
@@ -649,8 +803,16 @@ export class TrafficalClient {
         if (this._state.etag) {
             headers["If-None-Match"] = this._state.etag;
         }
+        // Abort the request if the edge hangs (slow TCP, not a 5xx) so the
+        // promise settles and we fall back to cached/local config.
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this._requestTimeoutMs);
         try {
-            const response = await fetch(url, { method: "GET", headers });
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: controller.signal,
+            });
             if (response.status === 304) {
                 this._state.lastFetchTime = Date.now();
                 return;
@@ -660,6 +822,13 @@ export class TrafficalClient {
             }
             const bundle = (await response.json());
             const etag = response.headers.get("ETag");
+            // A 200 can still carry a malformed body. Discard it and keep the
+            // previous last-good bundle rather than corrupting bucket assignments or
+            // falling through to defaults when we already have a valid config.
+            if (!isValidConfigBundle(bundle)) {
+                this._logMalformedBundleWarning();
+                return;
+            }
             this._state.bundle = bundle;
             this._state.etag = etag;
             this._state.lastFetchTime = Date.now();
@@ -677,6 +846,9 @@ export class TrafficalClient {
         catch (error) {
             this._logOfflineWarning(error);
         }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
     _startBackgroundRefresh() {
         const interval = this._options.evaluationMode === "server"
@@ -684,20 +856,50 @@ export class TrafficalClient {
             : this._options.refreshIntervalMs;
         if (interval <= 0)
             return;
-        this._state.refreshTimer = setInterval(() => {
-            if (this._options.evaluationMode === "server") {
-                this._fetchServerResolve().catch(() => { });
-            }
-            else {
-                this._fetchConfig().catch(() => { });
-            }
-        }, interval);
+        // Reschedule via setTimeout with fresh +/-10% jitter each tick (instead of a
+        // fixed setInterval) so fleets of clients don't converge on the same refresh
+        // instant and stampede the edge.
+        const scheduleNext = () => {
+            this._state.refreshTimer = setTimeout(() => {
+                // Schedule the next tick before firing so cadence stays independent of
+                // fetch latency (matching the previous fire-and-forget setInterval).
+                scheduleNext();
+                if (this._options.evaluationMode === "server") {
+                    this._fetchServerResolve().catch(() => { });
+                }
+                else {
+                    this._fetchConfig().catch(() => { });
+                }
+            }, jitteredInterval(interval));
+        };
+        scheduleNext();
     }
-    async _fetchServerResolve() {
+    /**
+     * 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 don't hammer
+     * the edge. decide()/getParams() are synchronous and cannot await this; the
+     * current call degrades to the last-good snapshot.
+     */
+    _maybeResolveForContext(context) {
+        const enriched = this._enrichContext(context);
+        let key;
+        try {
+            key = JSON.stringify(enriched);
+        }
+        catch {
+            key = "";
+        }
+        if (key === this._lastResolveContextKey)
+            return;
+        this._lastResolveContextKey = key;
+        void this._fetchServerResolve(enriched);
+    }
+    async _fetchServerResolve(contextOverride) {
         if (!this._decisionClient)
             return;
         try {
-            const context = this._enrichContext({});
+            const context = contextOverride ?? this._enrichContext({});
             const response = await this._decisionClient.resolve({ context });
             if (response) {
                 this._state.serverResponse = response;
@@ -775,6 +977,13 @@ export class TrafficalClient {
             this._state.lastOfflineWarning = now;
         }
     }
+    _logMalformedBundleWarning() {
+        const now = Date.now();
+        if (now - this._state.lastMalformedWarning > MALFORMED_BUNDLE_WARNING_INTERVAL_MS) {
+            console.warn(`[Traffical] Discarded malformed config bundle (invalid hashing/shape). Using ${this._state.bundle ? "cached" : "local"} config.`);
+            this._state.lastMalformedWarning = now;
+        }
+    }
     /**
      * Caches a decision for attribution lookup when track() is called.
      * Maintains a bounded cache to prevent memory leaks.