@traffical/node 0.1.2

package/README.md

@@ -0,0 +1,154 @@
+# @traffical/node
+
+Traffical SDK for Node.js - server-side parameter resolution with caching and event tracking.
+
+## Installation
+
+```bash
+npm install @traffical/node
+# or
+bun add @traffical/node
+```
+
+## Quick Start
+
+```typescript
+import { TrafficalClient } from '@traffical/node';
+
+const client = new TrafficalClient({
+  apiKey: 'sk_...', // Server-side API key
+});
+
+// Get parameters for a user
+const decision = await client.decide({
+  userId: 'user-123',
+  country: 'US',
+});
+
+console.log(decision.params);
+// { 'button.color': '#007bff', 'pricing.discount': 0.1 }
+
+// Track an event
+await client.track('purchase', {
+  decisionId: decision.decisionId,
+  unitKey: 'user-123',
+  properties: {
+    amount: 99.99,
+    currency: 'USD',
+  },
+});
+```
+
+## Configuration
+
+```typescript
+const client = new TrafficalClient({
+  // Required
+  apiKey: 'sk_...',
+  
+  // Optional
+  apiBase: 'https://api.traffical.io', // Custom API endpoint
+  cacheTtl: 60_000, // Config cache TTL in ms (default: 60s)
+  timeout: 5_000, // Request timeout in ms (default: 5s)
+});
+```
+
+## API Reference
+
+### `decide(context)`
+
+Resolves parameters for a given context.
+
+```typescript
+const decision = await client.decide({
+  userId: 'user-123',     // Required: unit key for bucketing
+  country: 'US',          // Optional: targeting context
+  plan: 'premium',        // Optional: more context
+});
+
+// Returns:
+{
+  decisionId: 'dec_...',  // Unique ID for this decision
+  params: {               // Resolved parameters
+    'feature.enabled': true,
+    'ui.theme': 'dark',
+  },
+  exposures: [...]        // Which experiments the user is in
+}
+```
+
+### `track(event, options)`
+
+Tracks a user event for analytics.
+
+```typescript
+await client.track('purchase', {
+  decisionId: decision.decisionId,
+  unitKey: 'user-123',
+  properties: {
+    amount: 99.99,
+  },
+});
+```
+
+### `refresh()`
+
+Forces a refresh of the cached configuration.
+
+```typescript
+await client.refresh();
+```
+
+## Event Batching
+
+The Node SDK automatically batches events for efficiency:
+
+```typescript
+const client = new TrafficalClient({
+  apiKey: 'sk_...',
+  batchSize: 100,      // Events per batch (default: 100)
+  flushInterval: 5000, // Flush interval in ms (default: 5s)
+});
+
+// Events are queued and sent in batches
+client.track('page_view', { ... });
+client.track('click', { ... });
+
+// Force flush before shutdown
+await client.flush();
+```
+
+## Error Handling
+
+```typescript
+try {
+  const decision = await client.decide({ userId: 'user-123' });
+} catch (error) {
+  if (error.code === 'NETWORK_ERROR') {
+    // Handle network issues - use defaults
+  }
+  if (error.code === 'INVALID_API_KEY') {
+    // Handle auth issues
+  }
+}
+```
+
+## TypeScript
+
+Full TypeScript support with type inference:
+
+```typescript
+import type { Context, DecisionResult } from '@traffical/node';
+
+const context: Context = {
+  userId: 'user-123',
+  plan: 'premium',
+};
+
+const decision: DecisionResult = await client.decide(context);
+```
+
+## License
+
+MIT
+

package/dist/client.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Traffical Node.js SDK Client
+ *
+ * HTTP client with caching, background refresh, and graceful degradation.
+ * Wraps the pure core-ts resolution engine.
+ *
+ * Features:
+ * - ETag-based caching for efficient config fetches
+ * - Background refresh for keeping config up-to-date
+ * - Automatic decision tracking for intent-to-treat analysis
+ * - Batched event transport for efficiency
+ * - Graceful degradation with local config and schema defaults
+ */
+import { type Context, type DecisionResult, type ParameterValue, type TrafficalClientOptions as CoreClientOptions, type TrackOptions } from "@traffical/core";
+/**
+ * Options for the Node.js Traffical client.
+ * Extends the core options with Node-specific settings.
+ */
+export interface TrafficalClientOptions extends CoreClientOptions {
+    /**
+     * Whether to automatically track decision events (default: true).
+     * When enabled, every call to decide() automatically sends a DecisionEvent
+     * to the backend, enabling intent-to-treat analysis.
+     */
+    trackDecisions?: boolean;
+    /**
+     * Decision deduplication TTL in milliseconds (default: 1 hour).
+     * Same user+assignment combination won't be tracked again within this window.
+     */
+    decisionDeduplicationTtlMs?: number;
+    /**
+     * Event batch size - number of events before auto-flush (default: 10).
+     */
+    eventBatchSize?: number;
+    /**
+     * Event flush interval in milliseconds (default: 30000).
+     */
+    eventFlushIntervalMs?: number;
+    /**
+     * Enable debug logging for events (default: false).
+     */
+    debugEvents?: boolean;
+}
+/**
+ * TrafficalClient - the main SDK client for Node.js environments.
+ *
+ * Features:
+ * - ETag-based caching for efficient config fetches
+ * - Background refresh for keeping config up-to-date
+ * - Automatic decision tracking for intent-to-treat analysis
+ * - Batched event transport for efficiency
+ * - Graceful degradation with local config and schema defaults
+ * - Rate-limited offline warnings
+ */
+export declare class TrafficalClient {
+    private readonly _options;
+    private _state;
+    private readonly _eventBatcher;
+    private readonly _decisionDedup;
+    /** Cache of recent decisions for attribution lookup on rewards */
+    private readonly _decisionCache;
+    constructor(options: TrafficalClientOptions);
+    /**
+     * Initializes the client by fetching the config bundle.
+     * This is called automatically by createTrafficalClient.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Stops background refresh and cleans up resources.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Synchronous destroy for process exit handlers.
+     * Use destroy() when possible for proper cleanup.
+     */
+    destroySync(): void;
+    /**
+     * Manually refreshes the config bundle.
+     */
+    refreshConfig(): Promise<void>;
+    /**
+     * Gets the current config bundle version.
+     */
+    getConfigVersion(): string | null;
+    /**
+     * Flush pending events immediately.
+     */
+    flushEvents(): Promise<void>;
+    /**
+     * Resolves parameters with defaults as fallback.
+     *
+     * Resolution priority (highest wins):
+     * 1. Policy overrides (from remote bundle)
+     * 2. Parameter defaults (from remote bundle)
+     * 3. Local config (if remote unavailable)
+     * 4. Caller defaults
+     */
+    getParams<T extends Record<string, ParameterValue>>(options: {
+        context: Context;
+        defaults: T;
+    }): T;
+    /**
+     * Makes a decision with full metadata for tracking.
+     *
+     * When trackDecisions is enabled (default), automatically sends a DecisionEvent
+     * to the backend for intent-to-treat analysis.
+     */
+    decide<T extends Record<string, ParameterValue>>(options: {
+        context: Context;
+        defaults: T;
+    }): DecisionResult;
+    /**
+     * Tracks an exposure event.
+     *
+     * If the decision includes filtered context (from policies with contextLogging),
+     * it will be included in the exposure event for contextual bandit training.
+     */
+    trackExposure(decision: DecisionResult): void;
+    /**
+     * Tracks a user event.
+     *
+     * @example
+     * // Track a purchase with revenue
+     * client.track('purchase', { value: 99.99, orderId: 'ord_123' });
+     *
+     * // Track a simple event
+     * client.track('add_to_cart', { itemId: 'sku_456' });
+     *
+     * // Track with explicit decision attribution
+     * client.track('checkout_complete', { value: 1 }, { decisionId: 'dec_xyz' });
+     */
+    track(event: string, properties?: Record<string, unknown>, options?: {
+        decisionId?: string;
+        unitKey?: string;
+    }): void;
+    /**
+     * @deprecated Use track() instead.
+     * Tracks a reward event.
+     * If decisionId is provided and the decision is cached, attribution is auto-populated.
+     */
+    trackReward(options: TrackOptions): void;
+    /**
+     * Gets the effective bundle: remote > local > null
+     */
+    private _getEffectiveBundle;
+    /**
+     * Fetches the config bundle from the edge worker.
+     * Uses ETag for efficient caching.
+     */
+    private _fetchConfig;
+    /**
+     * Starts background refresh timer.
+     */
+    private _startBackgroundRefresh;
+    /**
+     * Logs an offline warning (rate-limited).
+     */
+    private _logOfflineWarning;
+    /**
+     * Tracks a decision event (internal).
+     * Called automatically when trackDecisions is enabled.
+     */
+    private _trackDecision;
+    /**
+     * Caches a decision for attribution lookup when trackReward is called.
+     * Maintains a bounded cache to prevent memory leaks.
+     */
+    private _cacheDecision;
+    /**
+     * Gets attribution info from cached decision if available.
+     */
+    private _getAttributionFromCache;
+}
+/**
+ * Creates and initializes a Traffical client.
+ *
+ * @example
+ * ```typescript
+ * const traffical = await createTrafficalClient({
+ *   orgId: "org_123",
+ *   projectId: "proj_456",
+ *   env: "production",
+ *   apiKey: "sk_...",
+ * });
+ *
+ * const params = traffical.getParams({
+   *   context: { userId: "user_789" },
+   *   defaults: {
+   *     "ui.button.color": "#000",
+   *   },
+   * });
+ * ```
+ */
+export declare function createTrafficalClient(options: TrafficalClientOptions): Promise<TrafficalClient>;
+/**
+ * Creates a Traffical client without initializing (synchronous).
+ * Useful when you want to control initialization timing.
+ */
+export declare function createTrafficalClientSync(options: TrafficalClientOptions): TrafficalClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,sBAAsB,IAAI,iBAAiB,EAChD,KAAK,YAAY,EAUlB,MAAM,iBAAiB,CAAC;AAoBzB;;;GAGG;AACH,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAmBD;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAQvB;IAEF,OAAO,CAAC,MAAM,CAOZ;IAEF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;IACtD,kEAAkE;IAClE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0C;gBAE7D,OAAO,EAAE,sBAAsB;IAoC3C;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B;;;OAGG;IACH,WAAW,IAAI,IAAI;IASnB;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC;;OAEG;IACH,gBAAgB,IAAI,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlC;;;;;;;;OAQG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,CAAC,CAAA;KAAE,GAAG,CAAC;IAKlG;;;;;OAKG;IACH,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,CAAC,CAAA;KAAE,GAAG,cAAc;IAiB5G;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IA2B7C;;;;;;;;;;;;OAYG;IACH,KAAK,CACH,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAClD,IAAI;IA0BP;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAWxC;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAI3B;;;OAGG;YACW,YAAY;IAqC1B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAyCtB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAYtB;;OAEG;IACH,OAAO,CAAC,wBAAwB;CAoBjC;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC,CAI1B;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,sBAAsB,GAC9B,eAAe,CAEjB"}