@traffical/core 0.1.2

package/dist/dedup/decision-dedup.d.ts

@@ -0,0 +1,74 @@
+/**
+ * DecisionDeduplicator - Pure decision deduplication logic.
+ *
+ * Tracks which user+assignment combinations have been seen to avoid
+ * sending duplicate decision events. This enables efficient decision
+ * tracking without overwhelming the event pipeline.
+ *
+ * Key differences from ExposureDeduplicator:
+ * - Pure in-memory (no I/O, no storage dependency)
+ * - Deduplicates on unitKey + assignment hash (not policy/variant)
+ * - Suitable for use in any JavaScript environment
+ */
+import type { ParameterValue } from "../types/index.js";
+export interface DecisionDeduplicatorOptions {
+    /**
+     * Time-to-live for deduplication entries in milliseconds.
+     * After this time, the same decision can be tracked again.
+     * Default: 1 hour (3600000 ms)
+     */
+    ttlMs?: number;
+    /**
+     * Maximum number of entries to store.
+     * When exceeded, oldest entries are removed.
+     * Default: 10000
+     */
+    maxEntries?: number;
+}
+export declare class DecisionDeduplicator {
+    private _seen;
+    private readonly _ttlMs;
+    private readonly _maxEntries;
+    private _lastCleanup;
+    constructor(options?: DecisionDeduplicatorOptions);
+    /**
+     * Generate a stable hash for assignment values.
+     * Used to create a deduplication key from assignments.
+     */
+    static hashAssignments(assignments: Record<string, ParameterValue>): string;
+    /**
+     * Create a deduplication key from unitKey and assignment hash.
+     */
+    static createKey(unitKey: string, assignmentHash: string): string;
+    /**
+     * Check if this decision is new (not seen before within TTL).
+     * If new, marks it as seen.
+     *
+     * @param unitKey - The unit key (user identifier)
+     * @param assignmentHash - Hash of the assignments (from hashAssignments)
+     * @returns true if this is a new decision, false if duplicate
+     */
+    checkAndMark(unitKey: string, assignmentHash: string): boolean;
+    /**
+     * Check if a decision would be considered new (without marking it).
+     */
+    wouldBeNew(unitKey: string, assignmentHash: string): boolean;
+    /**
+     * Clear all seen decisions.
+     */
+    clear(): void;
+    /**
+     * Get the number of entries in the deduplication cache.
+     */
+    get size(): number;
+    /**
+     * Perform cleanup of expired entries.
+     * Called periodically based on CLEANUP_THRESHOLD.
+     */
+    private _maybeCleanup;
+    /**
+     * Remove expired entries and enforce max size.
+     */
+    private _cleanup;
+}
+//# sourceMappingURL=decision-dedup.d.ts.map

package/dist/dedup/decision-dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-dedup.d.ts","sourceRoot":"","sources":["../../src/dedup/decision-dedup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMxD,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,YAAY,CAAc;gBAEtB,OAAO,GAAE,2BAAgC;IAKrD;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,MAAM;IAe3E;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM;IAIjE;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO;IAmB9D;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO;IAY5D;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,OAAO,CAAC,aAAa;IAcrB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAyBjB"}

package/dist/dedup/decision-dedup.js

@@ -0,0 +1,132 @@
+/**
+ * DecisionDeduplicator - Pure decision deduplication logic.
+ *
+ * Tracks which user+assignment combinations have been seen to avoid
+ * sending duplicate decision events. This enables efficient decision
+ * tracking without overwhelming the event pipeline.
+ *
+ * Key differences from ExposureDeduplicator:
+ * - Pure in-memory (no I/O, no storage dependency)
+ * - Deduplicates on unitKey + assignment hash (not policy/variant)
+ * - Suitable for use in any JavaScript environment
+ */
+const DEFAULT_TTL_MS = 3600_000; // 1 hour
+const DEFAULT_MAX_ENTRIES = 10_000;
+const CLEANUP_THRESHOLD = 0.2; // Clean when 20% of entries are expired
+export class DecisionDeduplicator {
+    _seen = new Map(); // key -> timestamp
+    _ttlMs;
+    _maxEntries;
+    _lastCleanup = Date.now();
+    constructor(options = {}) {
+        this._ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+        this._maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    }
+    /**
+     * Generate a stable hash for assignment values.
+     * Used to create a deduplication key from assignments.
+     */
+    static hashAssignments(assignments) {
+        // Sort keys for deterministic ordering
+        const sortedKeys = Object.keys(assignments).sort();
+        const parts = [];
+        for (const key of sortedKeys) {
+            const value = assignments[key];
+            // Simple string representation that's stable
+            const valueStr = typeof value === "object" ? JSON.stringify(value) : String(value);
+            parts.push(`${key}=${valueStr}`);
+        }
+        return parts.join("|");
+    }
+    /**
+     * Create a deduplication key from unitKey and assignment hash.
+     */
+    static createKey(unitKey, assignmentHash) {
+        return `${unitKey}:${assignmentHash}`;
+    }
+    /**
+     * Check if this decision is new (not seen before within TTL).
+     * If new, marks it as seen.
+     *
+     * @param unitKey - The unit key (user identifier)
+     * @param assignmentHash - Hash of the assignments (from hashAssignments)
+     * @returns true if this is a new decision, false if duplicate
+     */
+    checkAndMark(unitKey, assignmentHash) {
+        const key = DecisionDeduplicator.createKey(unitKey, assignmentHash);
+        const now = Date.now();
+        const lastSeen = this._seen.get(key);
+        // Check if we've seen this within TTL
+        if (lastSeen !== undefined && now - lastSeen < this._ttlMs) {
+            return false; // Duplicate
+        }
+        // Mark as seen
+        this._seen.set(key, now);
+        // Periodic cleanup
+        this._maybeCleanup(now);
+        return true; // New decision
+    }
+    /**
+     * Check if a decision would be considered new (without marking it).
+     */
+    wouldBeNew(unitKey, assignmentHash) {
+        const key = DecisionDeduplicator.createKey(unitKey, assignmentHash);
+        const now = Date.now();
+        const lastSeen = this._seen.get(key);
+        if (lastSeen === undefined) {
+            return true;
+        }
+        return now - lastSeen >= this._ttlMs;
+    }
+    /**
+     * Clear all seen decisions.
+     */
+    clear() {
+        this._seen.clear();
+    }
+    /**
+     * Get the number of entries in the deduplication cache.
+     */
+    get size() {
+        return this._seen.size;
+    }
+    /**
+     * Perform cleanup of expired entries.
+     * Called periodically based on CLEANUP_THRESHOLD.
+     */
+    _maybeCleanup(now) {
+        // Only cleanup periodically, not on every call
+        const timeSinceCleanup = now - this._lastCleanup;
+        const shouldCleanup = timeSinceCleanup > this._ttlMs * CLEANUP_THRESHOLD || this._seen.size > this._maxEntries;
+        if (!shouldCleanup) {
+            return;
+        }
+        this._lastCleanup = now;
+        this._cleanup(now);
+    }
+    /**
+     * Remove expired entries and enforce max size.
+     */
+    _cleanup(now) {
+        const expiredKeys = [];
+        // Find expired entries
+        for (const [key, timestamp] of this._seen.entries()) {
+            if (now - timestamp >= this._ttlMs) {
+                expiredKeys.push(key);
+            }
+        }
+        // Remove expired entries
+        for (const key of expiredKeys) {
+            this._seen.delete(key);
+        }
+        // If still over max, remove oldest entries
+        if (this._seen.size > this._maxEntries) {
+            const entries = Array.from(this._seen.entries()).sort((a, b) => a[1] - b[1]); // Sort by timestamp
+            const toRemove = entries.slice(0, this._seen.size - this._maxEntries);
+            for (const [key] of toRemove) {
+                this._seen.delete(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=decision-dedup.js.map

package/dist/dedup/decision-dedup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-dedup.js","sourceRoot":"","sources":["../../src/dedup/decision-dedup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,cAAc,GAAG,QAAQ,CAAC,CAAC,SAAS;AAC1C,MAAM,mBAAmB,GAAG,MAAM,CAAC;AACnC,MAAM,iBAAiB,GAAG,GAAG,CAAC,CAAC,wCAAwC;AAiBvE,MAAM,OAAO,oBAAoB;IACvB,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC,CAAC,mBAAmB;IAC7C,MAAM,CAAS;IACf,WAAW,CAAS;IAC7B,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAElC,YAAY,UAAuC,EAAE;QACnD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC;QAC9C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;IAC/D,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,eAAe,CAAC,WAA2C;QAChE,uCAAuC;QACvC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,CAAC;QACnD,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;YAC/B,6CAA6C;YAC7C,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnF,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,QAAQ,EAAE,CAAC,CAAC;QACnC,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,OAAe,EAAE,cAAsB;QACtD,OAAO,GAAG,OAAO,IAAI,cAAc,EAAE,CAAC;IACxC,CAAC;IAED;;;;;;;OAOG;IACH,YAAY,CAAC,OAAe,EAAE,cAAsB;QAClD,MAAM,GAAG,GAAG,oBAAoB,CAAC,SAAS,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QACpE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAErC,sCAAsC;QACtC,IAAI,QAAQ,KAAK,SAAS,IAAI,GAAG,GAAG,QAAQ,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAC3D,OAAO,KAAK,CAAC,CAAC,YAAY;QAC5B,CAAC;QAED,eAAe;QACf,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAEzB,mBAAmB;QACnB,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;QAExB,OAAO,IAAI,CAAC,CAAC,eAAe;IAC9B,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,OAAe,EAAE,cAAsB;QAChD,MAAM,GAAG,GAAG,oBAAoB,CAAC,SAAS,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QACpE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAErC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,GAAG,GAAG,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;;OAGG;IACK,aAAa,CAAC,GAAW;QAC/B,+CAA+C;QAC/C,MAAM,gBAAgB,GAAG,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC;QACjD,MAAM,aAAa,GACjB,gBAAgB,GAAG,IAAI,CAAC,MAAM,GAAG,iBAAiB,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC;QAE3F,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC;QACxB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAED;;OAEG;IACK,QAAQ,CAAC,GAAW;QAC1B,MAAM,WAAW,GAAa,EAAE,CAAC;QAEjC,uBAAuB;QACvB,KAAK,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YACpD,IAAI,GAAG,GAAG,SAAS,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBACnC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QAED,yBAAyB;QACzB,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC9B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;QAED,2CAA2C;QAC3C,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YACvC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,oBAAoB;YAElG,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC;YACtE,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,QAAQ,EAAE,CAAC;gBAC7B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/dedup/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Deduplication utilities for event tracking.
+ */
+export { DecisionDeduplicator, type DecisionDeduplicatorOptions } from "./decision-dedup.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/dedup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dedup/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/dedup/index.js

@@ -0,0 +1,5 @@
+/**
+ * Deduplication utilities for event tracking.
+ */
+export { DecisionDeduplicator } from "./decision-dedup.js";
+//# sourceMappingURL=index.js.map

package/dist/dedup/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/dedup/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,oBAAoB,EAAoC,MAAM,qBAAqB,CAAC"}

package/dist/edge/client.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Edge Client
+ *
+ * Client for making per-entity decisions via the edge worker API.
+ * Used when policies have entityConfig.resolutionMode = "edge".
+ *
+ * The edge client provides:
+ * - Real-time entity state resolution (vs batched bundle updates)
+ * - Timeout handling with fallback to bundle
+ * - Request batching for multiple entities
+ */
+import type { Id, Context } from "../types/index.js";
+/**
+ * Request to the edge /decide endpoint.
+ */
+export interface EdgeDecideRequest {
+    /** Policy ID */
+    policyId: Id;
+    /** Entity ID (composite from entityKeys) */
+    entityId: string;
+    /** Unit key value for deterministic selection */
+    unitKeyValue: string;
+    /** Number of allocations (for dynamic allocations) */
+    allocationCount?: number;
+    /** Full context (for logging/debugging) */
+    context?: Context;
+}
+/**
+ * Response from the edge /decide endpoint.
+ */
+export interface EdgeDecideResponse {
+    /** Selected allocation index */
+    allocationIndex: number;
+    /** Selected allocation name */
+    allocationName: string;
+    /** Weights used for selection */
+    weights: number[];
+    /** Whether this was a cold start (no entity state) */
+    coldStart: boolean;
+    /** Entity state version */
+    stateVersion?: string;
+}
+/**
+ * Batch request for multiple entity decisions.
+ */
+export interface EdgeBatchDecideRequest {
+    /** Array of individual decide requests */
+    requests: EdgeDecideRequest[];
+}
+/**
+ * Batch response for multiple entity decisions.
+ */
+export interface EdgeBatchDecideResponse {
+    /** Array of individual decide responses (same order as requests) */
+    responses: EdgeDecideResponse[];
+}
+/**
+ * Edge client configuration.
+ */
+export interface EdgeClientConfig {
+    /** Base URL for the edge worker (e.g., "https://edge.traffical.io") */
+    baseUrl: string;
+    /** Organization ID */
+    orgId: Id;
+    /** Project ID */
+    projectId: Id;
+    /** Environment */
+    env: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Default timeout in milliseconds */
+    defaultTimeoutMs?: number;
+}
+/**
+ * EdgeClient - makes per-entity decisions via the edge worker API.
+ */
+export declare class EdgeClient {
+    private config;
+    private defaultTimeout;
+    constructor(config: EdgeClientConfig);
+    /**
+     * Makes a single entity decision via the edge API.
+     *
+     * @param request - The decide request
+     * @param timeoutMs - Optional timeout override
+     * @returns The decide response, or null if request failed/timed out
+     */
+    decide(request: EdgeDecideRequest, timeoutMs?: number): Promise<EdgeDecideResponse | null>;
+    /**
+     * Makes multiple entity decisions in a single batch request.
+     *
+     * @param requests - Array of decide requests
+     * @param timeoutMs - Optional timeout override
+     * @returns Array of responses (null for failed requests)
+     */
+    decideBatch(requests: EdgeDecideRequest[], timeoutMs?: number): Promise<(EdgeDecideResponse | null)[]>;
+}
+/**
+ * Creates an edge decide request from policy and context.
+ *
+ * @param policyId - The policy ID
+ * @param entityKeys - Array of context keys that identify the entity
+ * @param context - The evaluation context
+ * @param unitKeyValue - The unit key value
+ * @param allocationCount - Number of allocations (for dynamic)
+ * @returns The decide request, or null if entity ID cannot be built
+ */
+export declare function createEdgeDecideRequest(policyId: Id, entityKeys: string[], context: Context, unitKeyValue: string, allocationCount?: number): EdgeDecideRequest | null;
+//# sourceMappingURL=client.d.ts.map

package/dist/edge/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/edge/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAMrD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB;IAChB,QAAQ,EAAE,EAAE,CAAC;IACb,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,+BAA+B;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sDAAsD;IACtD,SAAS,EAAE,OAAO,CAAC;IACnB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0CAA0C;IAC1C,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,SAAS,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,KAAK,EAAE,EAAE,CAAC;IACV,iBAAiB;IACjB,SAAS,EAAE,EAAE,CAAC;IACd,kBAAkB;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,EAAE,gBAAgB;IAKpC;;;;;;OAMG;IACG,MAAM,CACV,OAAO,EAAE,iBAAiB,EAC1B,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IA8CrC;;;;;;OAMG;IACG,WAAW,CACf,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,kBAAkB,GAAG,IAAI,CAAC,EAAE,CAAC;CA+C1C;AAMD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,EAAE,EACZ,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,EACpB,eAAe,CAAC,EAAE,MAAM,GACvB,iBAAiB,GAAG,IAAI,CAmB1B"}

package/dist/edge/client.js

@@ -0,0 +1,154 @@
+/**
+ * Edge Client
+ *
+ * Client for making per-entity decisions via the edge worker API.
+ * Used when policies have entityConfig.resolutionMode = "edge".
+ *
+ * The edge client provides:
+ * - Real-time entity state resolution (vs batched bundle updates)
+ * - Timeout handling with fallback to bundle
+ * - Request batching for multiple entities
+ */
+// =============================================================================
+// Edge Client
+// =============================================================================
+/**
+ * EdgeClient - makes per-entity decisions via the edge worker API.
+ */
+export class EdgeClient {
+    config;
+    defaultTimeout;
+    constructor(config) {
+        this.config = config;
+        this.defaultTimeout = config.defaultTimeoutMs ?? 100;
+    }
+    /**
+     * Makes a single entity decision via the edge API.
+     *
+     * @param request - The decide request
+     * @param timeoutMs - Optional timeout override
+     * @returns The decide response, or null if request failed/timed out
+     */
+    async decide(request, timeoutMs) {
+        const timeout = timeoutMs ?? this.defaultTimeout;
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            const url = `${this.config.baseUrl}/v1/decide/${request.policyId}`;
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                    "X-Org-Id": this.config.orgId,
+                    "X-Project-Id": this.config.projectId,
+                    "X-Env": this.config.env,
+                },
+                body: JSON.stringify({
+                    entityId: request.entityId,
+                    unitKeyValue: request.unitKeyValue,
+                    allocationCount: request.allocationCount,
+                    context: request.context,
+                }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                console.warn(`[Traffical] Edge decide failed: ${response.status} ${response.statusText}`);
+                return null;
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                console.warn(`[Traffical] Edge decide timed out after ${timeout}ms`);
+            }
+            else {
+                console.warn(`[Traffical] Edge decide error:`, error);
+            }
+            return null;
+        }
+    }
+    /**
+     * Makes multiple entity decisions in a single batch request.
+     *
+     * @param requests - Array of decide requests
+     * @param timeoutMs - Optional timeout override
+     * @returns Array of responses (null for failed requests)
+     */
+    async decideBatch(requests, timeoutMs) {
+        if (requests.length === 0)
+            return [];
+        if (requests.length === 1) {
+            const result = await this.decide(requests[0], timeoutMs);
+            return [result];
+        }
+        const timeout = timeoutMs ?? this.defaultTimeout;
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            const url = `${this.config.baseUrl}/v1/decide/batch`;
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                    "X-Org-Id": this.config.orgId,
+                    "X-Project-Id": this.config.projectId,
+                    "X-Env": this.config.env,
+                },
+                body: JSON.stringify({ requests }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                console.warn(`[Traffical] Edge batch decide failed: ${response.status} ${response.statusText}`);
+                return requests.map(() => null);
+            }
+            const data = (await response.json());
+            return data.responses;
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                console.warn(`[Traffical] Edge batch decide timed out after ${timeout}ms`);
+            }
+            else {
+                console.warn(`[Traffical] Edge batch decide error:`, error);
+            }
+            return requests.map(() => null);
+        }
+    }
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Creates an edge decide request from policy and context.
+ *
+ * @param policyId - The policy ID
+ * @param entityKeys - Array of context keys that identify the entity
+ * @param context - The evaluation context
+ * @param unitKeyValue - The unit key value
+ * @param allocationCount - Number of allocations (for dynamic)
+ * @returns The decide request, or null if entity ID cannot be built
+ */
+export function createEdgeDecideRequest(policyId, entityKeys, context, unitKeyValue, allocationCount) {
+    // Build entity ID from context
+    const parts = [];
+    for (const key of entityKeys) {
+        const value = context[key];
+        if (value === undefined || value === null) {
+            return null;
+        }
+        parts.push(String(value));
+    }
+    const entityId = parts.join("_");
+    return {
+        policyId,
+        entityId,
+        unitKeyValue,
+        allocationCount,
+        context,
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/edge/client.js.map

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

package/dist/edge/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Edge Client Module
+ *
+ * Exports for making per-entity decisions via the edge worker API.
+ */
+export { EdgeClient, createEdgeDecideRequest, type EdgeClientConfig, type EdgeDecideRequest, type EdgeDecideResponse, type EdgeBatchDecideRequest, type EdgeBatchDecideResponse, } from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/edge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/edge/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,UAAU,EACV,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC"}

package/dist/edge/index.js

@@ -0,0 +1,7 @@
+/**
+ * Edge Client Module
+ *
+ * Exports for making per-entity decisions via the edge worker API.
+ */
+export { EdgeClient, createEdgeDecideRequest, } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/edge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/edge/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,UAAU,EACV,uBAAuB,GAMxB,MAAM,aAAa,CAAC"}

package/dist/hashing/bucket.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Bucket Computation
+ *
+ * Deterministic bucket assignment for traffic splitting.
+ * The bucket is computed as: hash(unitKeyValue + ":" + layerId) % bucketCount
+ *
+ * This ensures:
+ * - Same user always gets same bucket for a given layer
+ * - Different layers can have independent bucketing (orthogonality)
+ * - Deterministic results across SDK and server
+ */
+/**
+ * Computes the bucket for a given unit and layer.
+ *
+ * @param unitKeyValue - The value of the unit key (e.g., userId value)
+ * @param layerId - The layer ID for orthogonal bucketing
+ * @param bucketCount - Total number of buckets (e.g., 1000)
+ * @returns Bucket number in range [0, bucketCount - 1]
+ */
+export declare function computeBucket(unitKeyValue: string, layerId: string, bucketCount: number): number;
+/**
+ * Checks if a bucket falls within a range.
+ *
+ * @param bucket - The computed bucket
+ * @param range - [start, end] inclusive range
+ * @returns True if bucket is in range
+ */
+export declare function isInBucketRange(bucket: number, range: [number, number]): boolean;
+/**
+ * Finds which allocation matches a given bucket.
+ *
+ * @param bucket - The computed bucket
+ * @param allocations - Array of allocations with bucket ranges
+ * @returns The matching allocation, or null if none match
+ */
+export declare function findMatchingAllocation<T extends {
+    bucketRange: [number, number];
+}>(bucket: number, allocations: T[]): T | null;
+/**
+ * Converts a percentage to a bucket range.
+ *
+ * @param percentage - Traffic percentage (0-100)
+ * @param bucketCount - Total buckets
+ * @param startBucket - Starting bucket (default 0)
+ * @returns [start, end] bucket range
+ */
+export declare function percentageToBucketRange(percentage: number, bucketCount: number, startBucket?: number): [number, number];
+/**
+ * Creates non-overlapping bucket ranges for multiple variants.
+ *
+ * @param percentages - Array of percentages that should sum to <= 100
+ * @param bucketCount - Total buckets
+ * @returns Array of [start, end] bucket ranges
+ */
+export declare function createBucketRanges(percentages: number[], bucketCount: number): [number, number][];
+//# sourceMappingURL=bucket.d.ts.map

package/dist/hashing/bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket.d.ts","sourceRoot":"","sources":["../../src/hashing/bucket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,MAAM,CASR;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,SAAS;IAAE,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EAC3C,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,IAAI,CAO5C;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,SAAI,GACd,CAAC,MAAM,EAAE,MAAM,CAAC,CAIlB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EAAE,EACrB,WAAW,EAAE,MAAM,GAClB,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAgBpB"}