@traffical/js-client 0.16.2 → 0.18.0

package/README.md

@@ -29,7 +29,7 @@ const traffical = await createTrafficalClient({
   orgId: 'org_xxx',
   projectId: 'proj_xxx',
   env: 'production',
-  apiKey: 'pk_xxx',
+  apiKey: 'traffical_pk_…',
 });
 
 // Get parameters
@@ -67,7 +67,7 @@ traffical.track('checkout_complete', { value: 1 }, { decisionId: decision.decisi
     orgId: 'org_xxx',
     projectId: 'proj_xxx',
     env: 'production',
-    apiKey: 'pk_xxx',
+    apiKey: 'traffical_pk_…',
   }).then(function(traffical) {
     var params = traffical.getParams({
       context: { userId: 'user_123' },
@@ -167,7 +167,7 @@ The Traffical DevTools debug plugin uses these methods to let developers force p
 ## Features
 
 - **Error Boundary** - SDK errors never crash your app
-- **Exposure Deduplication** - Same user/variant = 1 exposure per session
+- **Exposure Deduplication** - Same user/allocation = 1 exposure event per session
 - **Smart Batching** - Events batched and flushed efficiently
 - **Beacon on Unload** - Events sent reliably on page close
 - **Auto Stable ID** - Anonymous user identification via localStorage/cookie
@@ -187,7 +187,7 @@ const traffical = await createTrafficalClient({
   orgId: 'org_xxx',
   projectId: 'proj_xxx',
   env: 'production',
-  apiKey: 'pk_xxx',
+  apiKey: 'traffical_pk_…',
   plugins: [
     createDOMBindingPlugin({
       observeMutations: true,  // Watch for DOM changes (SPA support)
@@ -218,7 +218,7 @@ The plugin:
 
 ### Redirect Plugin
 
-Run URL split tests (redirect experiments) where visitors are redirected to different landing page variants. The redirect plugin automatically triggers a decision on init, performs the redirect, and sets an attribution cookie. The attribution plugin ensures conversions on the variant page are attributed back to the experiment.
+Run URL split tests (redirect policies) where visitors are redirected to different landing page allocations. The redirect plugin automatically triggers a decision on init, performs the redirect, and sets an attribution cookie. The attribution plugin ensures conversions on the destination page are attributed back to the policy.
 
 ```typescript
 import {
@@ -231,7 +231,7 @@ const traffical = await createTrafficalClient({
   orgId: 'org_xxx',
   projectId: 'proj_xxx',
   env: 'production',
-  apiKey: 'pk_xxx',
+  apiKey: 'traffical_pk_…',
   plugins: [
     createRedirectPlugin(),
     createRedirectAttributionPlugin(),
@@ -242,7 +242,7 @@ const traffical = await createTrafficalClient({
 // On entry pages, it redirects. On other pages, it's a no-op.
 
 // Track goals as usual — the attribution plugin injects
-// redirect experiment metadata into every track() call.
+// redirect policy metadata into every track() call.
 traffical.track('add_to_cart', { value: 29.99 });
 ```
 
@@ -281,9 +281,9 @@ Track goal events from a separate GTM tag (e.g., triggered on "Add to Cart" clic
 
 1. **Init** — The redirect plugin's `onInitialize` hook receives the client and calls `decide()` automatically.
 
-2. **Entry page** — `onBeforeDecision` injects `url.pathname` into the context. The policy condition (e.g., `url.pathname startsWith /products/pillow`) matches, `redirect.url` resolves to the variant URL. `onDecision` writes an attribution cookie (`traffical_rdr`) and calls `window.location.replace()`.
+2. **Entry page** — `onBeforeDecision` injects `url.pathname` into the context. The policy condition (e.g., `url.pathname startsWith /products/pillow`) matches, `redirect.url` resolves to the allocation's URL. `onDecision` writes an attribution cookie (`traffical_rdr`) and calls `window.location.replace()`.
 
-3. **Variant page** — The SDK loads again, `decide()` runs, but the policy condition doesn't match the new URL, so `redirect.url` stays empty and no redirect happens. The redirect-attribution plugin reads the `traffical_rdr` cookie and injects the experiment metadata into every `track()` call.
+3. **Destination page** — The SDK loads again, `decide()` runs, but the policy condition doesn't match the new URL, so `redirect.url` stays empty and no redirect happens. The redirect-attribution plugin reads the `traffical_rdr` cookie and injects the policy metadata into every `track()` call.
 
 #### Configuration
 

package/dist/client.d.ts

@@ -9,12 +9,26 @@
  * - Plugin system (P2)
  * - Auto stable ID for anonymous users
  */
-import { type ConfigBundle, type Context, type DecisionResult, type ParameterValue, type DecideOptions, type GetParamsOptions, type TrackEventOptions, type AssignmentLogger, type TrackableEventLogger, type TrackEventMap, type OnSchemaWarnings } from "@traffical/core";
+import { type ConfigBundle, type Context, type DecisionResult, type ParameterValue, type DecideOptions, type GetParamsOptions, type TrackEventOptions, type AssignmentLogger, type TrackableEventLogger, type TrackEventMap, type OnSchemaWarnings, type OnResolutionError, type SdkDiagnostics } from "@traffical/core";
 import { type ErrorBoundaryOptions } from "./error-boundary.js";
 import { type StorageProvider } from "./storage.js";
 import { type TrafficalPlugin } from "./plugins/index.js";
 import { type LifecycleProvider } from "./lifecycle.js";
 export interface TrafficalClientOptions {
+    /**
+     * What a resolution failure does (default: `"default"` — return the caller's
+     * defaults and stamp `metadata.reason: "error"`). `"throw"` rethrows, which
+     * is useful in CI and staging.
+     *
+     * Governs **resolution only**: `assignmentLogger`, `eventLogger`, and
+     * `onError` are always contained in either mode.
+     */
+    onResolutionError?: OnResolutionError;
+    /**
+     * Called for every contained error, deduplicated per `tag:name:message`.
+     * Errors it throws are swallowed.
+     */
+    onError?: (tag: string, error: Error) => void;
     /** Organization ID */
     orgId: string;
     /** Project ID */
@@ -58,6 +72,10 @@ export interface TrafficalClientOptions {
      */
     resolveTimeoutMs?: number;
     /** Error boundary options */
+    /**
+     * @deprecated Use the top-level `onError` (and `onResolutionError`) instead.
+     * `errorBoundary.onError` is still honored.
+     */
     errorBoundary?: ErrorBoundaryOptions;
     /** Event batching options */
     /**
@@ -133,7 +151,7 @@ export interface TrafficalClientOptions {
     disableCloudEvents?: boolean;
     /**
      * When true, assignment logger calls are deduplicated per session
-     * (same unit+policy+variant won't fire again). Default: true.
+     * (same unit+policy+allocation won't fire again). Default: true.
      */
     deduplicateAssignmentLogger?: boolean;
     /**
@@ -160,7 +178,7 @@ export interface TrafficalClientOptions {
 export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventMap> {
     private readonly _options;
     private _state;
-    private readonly _errorBoundary;
+    private readonly _errorPolicy;
     private readonly _storage;
     private readonly _eventLogger;
     private readonly _exposureDedup;
@@ -237,6 +255,12 @@ export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventM
      * parameter is unknown / the bundle is not yet loaded.
      */
     getParameterLayerId(key: string): string | null;
+    /**
+     * Counters for degradation that is otherwise invisible: contained resolution
+     * errors, dropped assignment/event log rows, rejected bundles, and the most
+     * recent contained error. Monotonic for the life of the client.
+     */
+    getDiagnostics(): SdkDiagnostics;
     /**
      * Resolves parameters with defaults as fallback.
      */
@@ -251,7 +275,7 @@ export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventM
     decide<T extends Record<string, ParameterValue>>(options: DecideOptions<T>): DecisionResult;
     /**
      * Tracks an exposure event.
-     * Automatically deduplicates exposures for the same user/variant.
+     * Automatically deduplicates exposure events for the same user/allocation.
      *
      * Skips layers marked `attributionOnly` — those were resolved for
      * attribution/assignment purposes only (no parameters were requested
@@ -342,6 +366,16 @@ export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventM
      * Traffical edge batcher (unless cloud events are disabled).
      */
     private _dispatchEvent;
+    /**
+     * Emits assignment rows to the customer's sink.
+     *
+     * MUST be called OUTSIDE the resolution boundary, and each invocation of the
+     * customer callback is guarded individually. Calling it inside `resolve()`
+     * made a throwing sink discard the *decision*: the unit was bucketed into
+     * treatment and the caller received control, with `getParams()` — which
+     * emits nothing — still returning treatment for the same unit. Because a
+     * bounded queue throws when full, that biased assignment with traffic load.
+     */
     private _emitAssignmentLogEntries;
     private _applyOverridesToResult;
     private _getEffectiveBundle;
@@ -385,7 +419,7 @@ export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventM
      * - "cumulative": Collects layers from ALL cached decisions for this unit,
      *   deduplicated by layerId:policyId (last-write-wins). This ensures cross-page
      *   funnels (e.g., catalog -> PDP -> checkout) attribute correctly to all
-     *   experiments the user is exposed to. For per-entity dynamic allocation
+     *   policies the user is exposed to. For per-entity dynamic allocation
      *   policies, only the most recent allocation is kept to avoid attributing
      *   rewards to allocations from other entities (e.g., different products).
      *

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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"}

package/dist/client.js

@@ -9,9 +9,8 @@
  * - Plugin system (P2)
  * - Auto stable ID for anonymous users
  */
-import { resolveParameters, decide as coreDecide, getUnitKeyValue, getUnitKeyField as coreGetUnitKeyField, getParameterLayerId as coreGetParameterLayerId, generateExposureId, generateTrackEventId, generateDecisionId, generateAssignmentId, } from "@traffical/core";
+import { ErrorPolicy, validateConfigBundle, 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";
 import { ExposureDeduplicator } from "./exposure-dedup.js";
 import { StableIdProvider } from "./stable-id.js";
@@ -49,33 +48,6 @@ 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
 // =============================================================================
@@ -138,7 +110,11 @@ export class TrafficalClient {
         };
         this._decisionClient = new DecisionClient(decisionClientConfig);
         // Initialize components
-        this._errorBoundary = new ErrorBoundary(options.errorBoundary);
+        this._errorPolicy = new ErrorPolicy({
+            onResolutionError: options.onResolutionError,
+            // `errorBoundary.onError` remains supported as the legacy spelling.
+            onError: options.onError ?? options.errorBoundary?.onError,
+        });
         this._storage = options.storage ?? createStorageProvider();
         this._lifecycleProvider = options.lifecycleProvider ?? createBrowserLifecycleProvider();
         // Default dev-mode schema warnings handler
@@ -209,11 +185,20 @@ export class TrafficalClient {
                 this._plugins.register(plugin);
             }
         }
-        // Initialize with local config if provided
+        // Initialize with local config if provided.
+        // Validated on exactly the same terms as a fetched bundle: a hand-edited
+        // local bundle is no more trustworthy than one off the wire.
         if (this._options.localConfig) {
-            this._state.bundle = this._options.localConfig;
-            // Notify plugins about the local config
-            this._plugins.runConfigUpdate(this._options.localConfig);
+            const validation = validateConfigBundle(this._options.localConfig);
+            if (validation.ok) {
+                this._state.bundle = this._options.localConfig;
+                // Notify plugins about the local config
+                this._plugins.runConfigUpdate(this._options.localConfig);
+            }
+            else {
+                this._errorPolicy.recordRejectedBundle("localConfig", validation.path, validation.reason);
+                this._options.localConfig = undefined;
+            }
         }
         // Register on global instance list so DevTools can discover ES-module SDKs
         if (typeof window !== "undefined") {
@@ -229,7 +214,14 @@ export class TrafficalClient {
      * Initializes the client by fetching the config bundle.
      */
     async initialize() {
-        await this._errorBoundary.captureAsync("initialize", async () => {
+        // Initialization is contained unconditionally, NOT under
+        // onResolutionError. `_readyResolve()` below must always run: rethrowing
+        // here would leave `waitForReady()` pending forever, and it would do so
+        // only in strict mode — the mode people enable in CI. Initialization
+        // strictness is a separate phase decision (cf. Eppo's
+        // `throwOnFailedInitialization`, also defaulting to false); resolution
+        // strictness still applies to decide()/getParams().
+        await this._errorPolicy.sideEffectAsync("initialize", "other", async () => {
             if (this._options.evaluationMode === "server") {
                 await this._fetchServerResolve();
             }
@@ -240,7 +232,7 @@ export class TrafficalClient {
             this._state.isInitialized = true;
             // 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();
     }
@@ -332,7 +324,7 @@ export class TrafficalClient {
      * Manually refreshes the config bundle.
      */
     async refreshConfig() {
-        await this._errorBoundary.swallow("refreshConfig", async () => {
+        await this._errorPolicy.sideEffectAsync("refreshConfig", "other", async () => {
             if (this._options.evaluationMode === "server") {
                 await this._fetchServerResolve();
             }
@@ -362,9 +354,20 @@ export class TrafficalClient {
     getParameterLayerId(key) {
         return coreGetParameterLayerId(this._getEffectiveBundle(), key);
     }
+    // ===========================================================================
+    // Parameter Resolution
+    // ===========================================================================
+    /**
+     * Counters for degradation that is otherwise invisible: contained resolution
+     * errors, dropped assignment/event log rows, rejected bundles, and the most
+     * recent contained error. Monotonic for the life of the client.
+     */
+    getDiagnostics() {
+        return this._errorPolicy.getDiagnostics();
+    }
     getParams(contextOrOptions, maybeDefaults) {
         const { context: rawContext, defaults } = normalizeEvalArgs(contextOrOptions, maybeDefaults);
-        return this._errorBoundary.capture("getParams", () => {
+        return this._errorPolicy.resolve("getParams", () => {
             // Server mode: return from cached server response
             if (this._options.evaluationMode === "server" && this._state.serverResponse) {
                 this._maybeResolveForContext(rawContext);
@@ -386,11 +389,11 @@ export class TrafficalClient {
             // Apply parameter overrides (post-resolution, post-plugin)
             this._applyOverridesToResult(params);
             return params;
-        }, defaults);
+        }, () => ({ ...defaults }));
     }
     decide(contextOrOptions, maybeDefaults) {
         const { context: rawContext, defaults } = normalizeEvalArgs(contextOrOptions, maybeDefaults);
-        return this._errorBoundary.capture("decide", () => {
+        const decision = this._errorPolicy.resolve("decide", () => {
             // Server mode: return from cached server response
             if (this._options.evaluationMode === "server" && this._state.serverResponse) {
                 this._maybeResolveForContext(rawContext);
@@ -415,7 +418,9 @@ export class TrafficalClient {
                 this._updateCumulativeAttribution(decision);
                 this._plugins.runDecision(decision);
                 this._applyOverridesToResult(decision.assignments);
-                this._emitAssignmentLogEntries(decision, "decision");
+                decision.metadata.reason = resp.metadata.layers?.some((l) => l.policyId)
+                    ? "resolved"
+                    : "default";
                 return decision;
             }
             const bundle = this._getEffectiveBundle();
@@ -433,36 +438,45 @@ export class TrafficalClient {
             this._plugins.runDecision(decision);
             // Apply parameter overrides (post-resolution, post-plugin)
             this._applyOverridesToResult(decision.assignments);
-            this._emitAssignmentLogEntries(decision, "decision");
+            decision.metadata.reason = !bundle
+                ? "no-bundle"
+                : decision.metadata.layers.some((l) => l.policyId)
+                    ? "resolved"
+                    : "default";
             return decision;
-        }, {
+        }, () => ({
             decisionId: generateDecisionId(),
-            assignments: defaults,
+            assignments: { ...defaults },
             metadata: {
                 timestamp: new Date().toISOString(),
                 unitKeyValue: "",
                 layers: [],
+                reason: "error",
             },
-        });
+        }));
+        // Assignment rows are emitted OUTSIDE the boundary. A throwing sink must
+        // cost a log row, never the decision the caller just received.
+        this._emitAssignmentLogEntries(decision, "decision");
+        return decision;
     }
     // ===========================================================================
     // Event Tracking
     // ===========================================================================
     /**
      * Tracks an exposure event.
-     * Automatically deduplicates exposures for the same user/variant.
+     * Automatically deduplicates exposure events for the same user/allocation.
      *
      * Skips layers marked `attributionOnly` — those were resolved for
      * attribution/assignment purposes only (no parameters were requested
      * from that layer) and should not count as exposures.
      */
     trackExposure(decision) {
-        this._errorBoundary.capture("trackExposure", () => {
+        // Outside the boundary, for the same reason as decide().
+        this._emitAssignmentLogEntries(decision, "exposure");
+        this._errorPolicy.resolve("trackExposure", () => {
             const unitKey = decision.metadata.unitKeyValue;
             if (!unitKey)
                 return;
-            // Emit to assignment logger (separate from cloud events)
-            this._emitAssignmentLogEntries(decision, "exposure");
             // 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.
@@ -508,7 +522,7 @@ export class TrafficalClient {
             if (!this._plugins.runExposure(event))
                 return;
             this._dispatchEvent(event);
-        }, undefined);
+        }, () => undefined);
     }
     /**
      * Tracks a user event.
@@ -528,7 +542,7 @@ export class TrafficalClient {
      * client.track('checkout_complete', { value: 1 }, { decisionId: decision.decisionId });
      */
     track(eventName, properties, options) {
-        this._errorBoundary.capture("track", () => {
+        this._errorPolicy.resolve("track", () => {
             const unitKey = options?.unitKey ?? this._stableId.getId();
             // Single numeric value: explicit options.value wins, else properties.value.
             const value = typeof options?.value === "number"
@@ -562,13 +576,13 @@ export class TrafficalClient {
                 return;
             }
             this._dispatchEvent(event);
-        }, undefined);
+        }, () => undefined);
     }
     /**
      * Flush pending events immediately.
      */
     async flushEvents() {
-        await this._errorBoundary.swallow("flushEvents", async () => {
+        await this._errorPolicy.sideEffectAsync("flushEvents", "other", async () => {
             await this._eventLogger.flush();
         });
     }
@@ -723,6 +737,16 @@ export class TrafficalClient {
             this._eventLogger.log(event);
         }
     }
+    /**
+     * Emits assignment rows to the customer's sink.
+     *
+     * MUST be called OUTSIDE the resolution boundary, and each invocation of the
+     * customer callback is guarded individually. Calling it inside `resolve()`
+     * made a throwing sink discard the *decision*: the unit was bucketed into
+     * treatment and the caller received control, with `getParams()` — which
+     * emits nothing — still returning treatment for the same unit. Because a
+     * bounded queue throws when full, that biased assignment with traffic load.
+     */
     _emitAssignmentLogEntries(decision, type) {
         if (!this._assignmentLogger)
             return;
@@ -741,11 +765,16 @@ export class TrafficalClient {
                 if (!isNew)
                     continue;
             }
-            this._assignmentLogger({
+            // Tier 1: the customer's sink must never change a caller's answer.
+            // Guarded HERE, narrowly, rather than relying on the surrounding
+            // resolution boundary — see the note on _emitAssignmentLogEntries.
+            const policyId = layer.policyId;
+            const allocationName = layer.allocationName;
+            this._errorPolicy.sideEffect("assignmentLogger", "assignmentLog", () => this._assignmentLogger({
                 unitKey,
-                policyId: layer.policyId,
+                policyId,
                 policyKey: layer.policyKey,
-                allocationName: layer.allocationName,
+                allocationName,
                 allocationKey: layer.allocationKey,
                 timestamp: decision.metadata.timestamp,
                 layerId: layer.layerId,
@@ -764,7 +793,7 @@ export class TrafficalClient {
                 probability: layer.probability,
                 modelVersion: layer.modelVersion,
                 configVersion,
-            });
+            }));
         }
     }
     _applyOverridesToResult(target) {
@@ -825,7 +854,9 @@ export class TrafficalClient {
             // 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)) {
+            const validation = validateConfigBundle(bundle);
+            if (!validation.ok) {
+                this._errorPolicy.recordRejectedBundle("fetchConfig", validation.path, validation.reason);
                 this._logMalformedBundleWarning();
                 return;
             }
@@ -1034,7 +1065,7 @@ export class TrafficalClient {
      * - "cumulative": Collects layers from ALL cached decisions for this unit,
      *   deduplicated by layerId:policyId (last-write-wins). This ensures cross-page
      *   funnels (e.g., catalog -> PDP -> checkout) attribute correctly to all
-     *   experiments the user is exposed to. For per-entity dynamic allocation
+     *   policies the user is exposed to. For per-entity dynamic allocation
      *   policies, only the most recent allocation is kept to avoid attributing
      *   rewards to allocations from other entities (e.g., different products).
      *