@traffical/core 0.1.2

package/src/dedup/decision-dedup.ts

@@ -0,0 +1,175 @@
+/**
+ * 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";
+
+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 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 class DecisionDeduplicator {
+  private _seen = new Map<string, number>(); // key -> timestamp
+  private readonly _ttlMs: number;
+  private readonly _maxEntries: number;
+  private _lastCleanup = Date.now();
+
+  constructor(options: DecisionDeduplicatorOptions = {}) {
+    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: Record<string, ParameterValue>): string {
+    // Sort keys for deterministic ordering
+    const sortedKeys = Object.keys(assignments).sort();
+    const parts: string[] = [];
+
+    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: string, assignmentHash: string): string {
+    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: string, assignmentHash: string): boolean {
+    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: string, assignmentHash: string): boolean {
+    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(): void {
+    this._seen.clear();
+  }
+
+  /**
+   * Get the number of entries in the deduplication cache.
+   */
+  get size(): number {
+    return this._seen.size;
+  }
+
+  /**
+   * Perform cleanup of expired entries.
+   * Called periodically based on CLEANUP_THRESHOLD.
+   */
+  private _maybeCleanup(now: number): void {
+    // 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.
+   */
+  private _cleanup(now: number): void {
+    const expiredKeys: string[] = [];
+
+    // 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);
+      }
+    }
+  }
+}
+

package/src/dedup/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Deduplication utilities for event tracking.
+ */
+
+export { DecisionDeduplicator, type DecisionDeduplicatorOptions } from "./decision-dedup.js";
+

package/src/edge/client.ts

@@ -0,0 +1,256 @@
+/**
+ * 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";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * 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;
+}
+
+// =============================================================================
+// Edge Client
+// =============================================================================
+
+/**
+ * EdgeClient - makes per-entity decisions via the edge worker API.
+ */
+export class EdgeClient {
+  private config: EdgeClientConfig;
+  private defaultTimeout: number;
+
+  constructor(config: EdgeClientConfig) {
+    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: EdgeDecideRequest,
+    timeoutMs?: number
+  ): Promise<EdgeDecideResponse | null> {
+    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()) as EdgeDecideResponse;
+    } 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: EdgeDecideRequest[],
+    timeoutMs?: number
+  ): Promise<(EdgeDecideResponse | null)[]> {
+    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()) as EdgeBatchDecideResponse;
+      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: Id,
+  entityKeys: string[],
+  context: Context,
+  unitKeyValue: string,
+  allocationCount?: number
+): EdgeDecideRequest | null {
+  // Build entity ID from context
+  const parts: string[] = [];
+  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,
+  };
+}
+

package/src/edge/index.ts

@@ -0,0 +1,16 @@
+/**
+ * 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";
+

package/src/hashing/bucket.ts

@@ -0,0 +1,115 @@
+/**
+ * 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
+ */
+
+import { fnv1a } from "./fnv1a.js";
+
+/**
+ * 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 function computeBucket(
+  unitKeyValue: string,
+  layerId: string,
+  bucketCount: number
+): number {
+  // Concatenate unit key and layer ID with separator
+  const input = `${unitKeyValue}:${layerId}`;
+
+  // Use FNV-1a for consistent hashing
+  const hash = fnv1a(input);
+
+  // Map to bucket range
+  return hash % bucketCount;
+}
+
+/**
+ * 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 function isInBucketRange(
+  bucket: number,
+  range: [number, number]
+): boolean {
+  return bucket >= range[0] && bucket <= range[1];
+}
+
+/**
+ * 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 function findMatchingAllocation<
+  T extends { bucketRange: [number, number] }
+>(bucket: number, allocations: T[]): T | null {
+  for (const allocation of allocations) {
+    if (isInBucketRange(bucket, allocation.bucketRange)) {
+      return allocation;
+    }
+  }
+  return 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 function percentageToBucketRange(
+  percentage: number,
+  bucketCount: number,
+  startBucket = 0
+): [number, number] {
+  const bucketsNeeded = Math.floor((percentage / 100) * bucketCount);
+  const endBucket = Math.min(startBucket + bucketsNeeded - 1, bucketCount - 1);
+  return [startBucket, endBucket];
+}
+
+/**
+ * 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 function createBucketRanges(
+  percentages: number[],
+  bucketCount: number
+): [number, number][] {
+  const ranges: [number, number][] = [];
+  let currentBucket = 0;
+
+  for (const percentage of percentages) {
+    if (percentage <= 0) continue;
+
+    const bucketsNeeded = Math.floor((percentage / 100) * bucketCount);
+    if (bucketsNeeded > 0) {
+      const endBucket = currentBucket + bucketsNeeded - 1;
+      ranges.push([currentBucket, endBucket]);
+      currentBucket = endBucket + 1;
+    }
+  }
+
+  return ranges;
+}
+

package/src/hashing/fnv1a.test.ts

@@ -0,0 +1,87 @@
+/**
+ * FNV-1a Hash Tests
+ *
+ * Validates that the hash function produces consistent results.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { fnv1a } from "./fnv1a.js";
+import { computeBucket } from "./bucket.js";
+
+describe("fnv1a", () => {
+  test("produces consistent hash for empty string", () => {
+    expect(fnv1a("")).toBe(2166136261);
+  });
+
+  test("produces consistent hash for simple strings", () => {
+    // These values are the canonical FNV-1a outputs
+    expect(fnv1a("a")).toBe(3826002220);
+    expect(fnv1a("test")).toBe(2949673445);
+    expect(fnv1a("hello")).toBe(1335831723);
+  });
+
+  test("produces different hashes for different inputs", () => {
+    const hash1 = fnv1a("user-abc");
+    const hash2 = fnv1a("user-xyz");
+    expect(hash1).not.toBe(hash2);
+  });
+});
+
+describe("computeBucket", () => {
+  test("produces consistent buckets for test vectors", () => {
+    // Test case: user-abc:layer_ui
+    const bucket1 = computeBucket("user-abc", "layer_ui", 1000);
+    expect(bucket1).toBe(551);
+
+    // Test case: user-abc:layer_pricing
+    const bucket2 = computeBucket("user-abc", "layer_pricing", 1000);
+    expect(bucket2).toBe(913);
+
+    // Test case: user-xyz:layer_ui
+    const bucket3 = computeBucket("user-xyz", "layer_ui", 1000);
+    expect(bucket3).toBe(214);
+
+    // Test case: user-xyz:layer_pricing
+    const bucket4 = computeBucket("user-xyz", "layer_pricing", 1000);
+    expect(bucket4).toBe(42);
+
+    // Test case: user-123:layer_ui
+    const bucket5 = computeBucket("user-123", "layer_ui", 1000);
+    expect(bucket5).toBe(871);
+
+    // Test case: user-123:layer_pricing
+    const bucket6 = computeBucket("user-123", "layer_pricing", 1000);
+    expect(bucket6).toBe(177);
+  });
+
+  test("bucket is always in valid range", () => {
+    const bucketCount = 1000;
+    const testInputs = [
+      "user-1",
+      "user-2",
+      "user-abc",
+      "user-xyz",
+      "test-user-with-long-id-12345",
+    ];
+
+    for (const userId of testInputs) {
+      const bucket = computeBucket(userId, "test_layer", bucketCount);
+      expect(bucket).toBeGreaterThanOrEqual(0);
+      expect(bucket).toBeLessThan(bucketCount);
+    }
+  });
+
+  test("same input produces same bucket", () => {
+    const bucket1 = computeBucket("user-abc", "layer_1", 1000);
+    const bucket2 = computeBucket("user-abc", "layer_1", 1000);
+    expect(bucket1).toBe(bucket2);
+  });
+
+  test("different layers produce different buckets (orthogonality)", () => {
+    const bucket1 = computeBucket("user-abc", "layer_1", 1000);
+    const bucket2 = computeBucket("user-abc", "layer_2", 1000);
+    // While not guaranteed to be different, they should be independent
+    // This test just ensures the layer ID is included in the hash
+    expect(fnv1a("user-abc:layer_1")).not.toBe(fnv1a("user-abc:layer_2"));
+  });
+});

package/src/hashing/fnv1a.ts

@@ -0,0 +1,31 @@
+/**
+ * FNV-1a Hash Function
+ *
+ * A simple, fast hash function with good distribution properties.
+ * Used by Google's experimentation system for bucket assignment.
+ *
+ * This implementation produces consistent results across all platforms
+ * and is the canonical hash for Traffical SDKs.
+ */
+
+const FNV_OFFSET_BASIS = 2166136261;
+const FNV_PRIME = 16777619;
+
+/**
+ * Computes the FNV-1a hash of a string.
+ *
+ * @param input - The string to hash
+ * @returns Unsigned 32-bit integer hash
+ */
+export function fnv1a(input: string): number {
+  let hash = FNV_OFFSET_BASIS;
+
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+
+  // Convert to unsigned 32-bit integer
+  return hash >>> 0;
+}
+

package/src/hashing/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Hashing Module
+ *
+ * Exports all hashing-related functions for deterministic bucket assignment.
+ */
+
+export { fnv1a } from "./fnv1a.js";
+export {
+  computeBucket,
+  isInBucketRange,
+  findMatchingAllocation,
+  percentageToBucketRange,
+  createBucketRanges,
+} from "./bucket.js";
+