@traffical/js-client 0.1.2

package/README.md

@@ -0,0 +1,209 @@
+# @traffical/js-client
+
+JavaScript SDK for browser environments with error boundaries, exposure deduplication, and smart event batching.
+
+## Installation
+
+### NPM
+
+```bash
+npm install @traffical/js-client
+# or
+bun add @traffical/js-client
+```
+
+### CDN
+
+```html
+<script src="https://cdn.traffical.io/js-client/v1/traffical.min.js"></script>
+```
+
+## Usage
+
+### NPM / ES Modules
+
+```typescript
+import { createTrafficalClient } from '@traffical/js-client';
+
+const traffical = await createTrafficalClient({
+  orgId: 'org_xxx',
+  projectId: 'proj_xxx',
+  env: 'production',
+  apiKey: 'pk_xxx',
+});
+
+// Get parameters
+const params = traffical.getParams({
+  context: { userId: 'user_123' },
+  defaults: {
+    'ui.hero.title': 'Welcome',
+    'ui.hero.color': '#000',
+  },
+});
+
+// Make decision with tracking metadata
+const decision = traffical.decide({
+  context: { userId: 'user_123' },
+  defaults: { 'ui.hero.title': 'Welcome' },
+});
+
+// Track exposure (automatically deduplicated)
+traffical.trackExposure(decision);
+
+// Track user events
+traffical.track('purchase', { value: 99.99, orderId: 'ord_123' });
+traffical.track('add_to_cart', { itemId: 'sku_456' });
+
+// Track with explicit decision attribution
+traffical.track('checkout_complete', { value: 1 }, { decisionId: decision.decisionId });
+```
+
+### CDN / Script Tag
+
+```html
+<script src="https://cdn.traffical.io/js-client/v1/traffical.min.js"></script>
+<script>
+  Traffical.init({
+    orgId: 'org_xxx',
+    projectId: 'proj_xxx',
+    env: 'production',
+    apiKey: 'pk_xxx',
+  }).then(function(traffical) {
+    var params = traffical.getParams({
+      context: { userId: 'user_123' },
+      defaults: { 'ui.hero.title': 'Welcome' },
+    });
+    console.log(params);
+  });
+</script>
+```
+
+### Google Tag Manager
+
+```html
+<script>
+  (function() {
+    var s = document.createElement('script');
+    s.src = 'https://cdn.traffical.io/js-client/v1/traffical.min.js';
+    s.onload = function() {
+      Traffical.init({
+        orgId: '{{Traffical Org ID}}',
+        projectId: '{{Traffical Project ID}}',
+        env: '{{Traffical Environment}}',
+        apiKey: '{{Traffical API Key}}',
+      });
+    };
+    document.head.appendChild(s);
+  })();
+</script>
+```
+
+## Configuration Options
+
+```typescript
+createTrafficalClient({
+  // Required
+  orgId: string,
+  projectId: string,
+  env: string,
+  apiKey: string,
+  
+  // Optional
+  baseUrl?: string,                // Default: https://sdk.traffical.io
+  refreshIntervalMs?: number,      // Config refresh interval (default: 60000)
+  localConfig?: ConfigBundle,      // Offline fallback config
+  eventBatchSize?: number,         // Events per batch (default: 10)
+  eventFlushIntervalMs?: number,   // Flush interval (default: 30000)
+  exposureSessionTtlMs?: number,   // Dedup session TTL (default: 1800000)
+  plugins?: TrafficalPlugin[],     // Plugins to register
+});
+```
+
+## Features
+
+- **Error Boundary** - SDK errors never crash your app
+- **Exposure Deduplication** - Same user/variant = 1 exposure 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
+- **Plugin System** - Extensible via plugins
+- **DOM Binding Plugin** - Auto-apply parameters to DOM elements
+
+## Plugins
+
+### DOM Binding Plugin
+
+Automatically applies parameter values to DOM elements based on bindings configured via the Traffical Visual Editor.
+
+```typescript
+import { createTrafficalClient, createDOMBindingPlugin } from '@traffical/js-client';
+
+const traffical = await createTrafficalClient({
+  orgId: 'org_xxx',
+  projectId: 'proj_xxx',
+  env: 'production',
+  apiKey: 'pk_xxx',
+  plugins: [
+    createDOMBindingPlugin({
+      observeMutations: true,  // Watch for DOM changes (SPA support)
+      debounceMs: 100,         // Debounce reapplication
+    }),
+  ],
+});
+
+// Parameters are automatically applied to DOM elements
+// when getParams() or decide() is called
+const params = traffical.getParams({
+  context: { userId: 'user_123' },
+  defaults: { 'hero.headline': 'Welcome' },
+});
+
+// Access the plugin for manual control
+const bindingPlugin = traffical.getPlugin('dom-binding');
+bindingPlugin?.applyBindings();  // Re-apply bindings
+bindingPlugin?.getBindings();    // Get current bindings
+```
+
+The plugin:
+- Receives bindings from the config bundle via `onConfigUpdate`
+- Applies parameter values to DOM elements via `onResolve` and `onDecision`
+- Supports URL pattern matching (regex) for page-specific bindings
+- Uses MutationObserver for SPA support
+- Supports multiple property types: `innerHTML`, `textContent`, `src`, `href`, `style.*`
+
+## Development
+
+### Build
+
+```bash
+# Install dependencies (from sdk/ root)
+cd ../
+bun install
+
+# Build ESM + IIFE
+cd js-client
+bun run build
+
+# Type check only
+bun run typecheck
+```
+
+### Output
+
+| File | Format | Use Case |
+|------|--------|----------|
+| `dist/index.js` | ESM | npm / bundlers |
+| `dist/traffical.min.js` | IIFE | CDN / script tag |
+
+### Release to CDN
+
+```bash
+# Requires wrangler CLI with R2 access configured
+./scripts/release-cdn.sh
+```
+
+This uploads to:
+- `cdn.traffical.io/js-client/v{VERSION}/` - Immutable, 1 year cache
+- `cdn.traffical.io/js-client/v{MAJOR}/` - Latest major, 1 hour cache
+- `cdn.traffical.io/js-client/latest/` - Latest, 5 minute cache
+

package/dist/client.d.ts

@@ -0,0 +1,167 @@
+/**
+ * TrafficalClient - JavaScript SDK for browser environments.
+ *
+ * Features:
+ * - Same API as Node SDK: getParams(), decide(), trackExposure(), track()
+ * - Error boundary wrapping (P0)
+ * - Exposure deduplication (P0)
+ * - Smart event batching with beacon on unload (P1)
+ * - Plugin system (P2)
+ * - Auto stable ID for anonymous users
+ */
+import { type ConfigBundle, type Context, type DecisionResult, type ParameterValue } from "@traffical/core";
+import { type ErrorBoundaryOptions } from "./error-boundary.js";
+import { type StorageProvider } from "./storage.js";
+import { type TrafficalPlugin } from "./plugins/index.js";
+export interface TrafficalClientOptions {
+    /** Organization ID */
+    orgId: string;
+    /** Project ID */
+    projectId: string;
+    /** Environment (e.g., "production", "staging") */
+    env: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for the SDK API (edge worker) */
+    baseUrl?: string;
+    /** Local config bundle for offline fallback */
+    localConfig?: ConfigBundle;
+    /** Refresh interval in milliseconds (default: 60000) */
+    refreshIntervalMs?: number;
+    /** Error boundary options */
+    errorBoundary?: ErrorBoundaryOptions;
+    /** Event batching options */
+    eventBatchSize?: number;
+    eventFlushIntervalMs?: number;
+    /** Exposure deduplication session TTL */
+    exposureSessionTtlMs?: number;
+    /**
+     * 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;
+    /** Plugins to register on init */
+    plugins?: TrafficalPlugin[];
+    /** Custom storage provider (default: localStorage) */
+    storage?: StorageProvider;
+    /** Disable automatic stable ID generation */
+    disableAutoStableId?: boolean;
+}
+export declare class TrafficalClient {
+    private readonly _options;
+    private _state;
+    private readonly _errorBoundary;
+    private readonly _storage;
+    private readonly _eventLogger;
+    private readonly _exposureDedup;
+    private readonly _stableId;
+    private readonly _plugins;
+    /** Cache of recent decisions for attribution lookup when track() is called */
+    private readonly _decisionCache;
+    constructor(options: TrafficalClientOptions);
+    /**
+     * Initializes the client by fetching the config bundle.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if the client is initialized.
+     */
+    get isInitialized(): boolean;
+    /**
+     * Stops background refresh and cleans up resources.
+     */
+    destroy(): void;
+    /**
+     * Manually refreshes the config bundle.
+     */
+    refreshConfig(): Promise<void>;
+    /**
+     * Gets the current config bundle version.
+     */
+    getConfigVersion(): string | null;
+    /**
+     * Resolves parameters with defaults as fallback.
+     */
+    getParams<T extends Record<string, ParameterValue>>(options: {
+        context: Context;
+        defaults: T;
+    }): T;
+    /**
+     * Makes a decision with full metadata for tracking.
+     */
+    decide<T extends Record<string, ParameterValue>>(options: {
+        context: Context;
+        defaults: T;
+    }): DecisionResult;
+    /**
+     * Tracks an exposure event.
+     * Automatically deduplicates exposures for the same user/variant.
+     */
+    trackExposure(decision: DecisionResult): void;
+    /**
+     * Tracks a user event.
+     *
+     * @param eventName - The event name (e.g., 'purchase', 'add_to_cart')
+     * @param properties - Optional event properties (including value for optimization)
+     * @param options - Optional tracking options (decisionId, unitKey)
+     *
+     * @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: decision.decisionId });
+     */
+    track(eventName: string, properties?: Record<string, unknown>, options?: {
+        decisionId?: string;
+        unitKey?: string;
+    }): void;
+    /**
+     * Flush pending events immediately.
+     */
+    flushEvents(): Promise<void>;
+    /**
+     * Register a plugin.
+     */
+    use(plugin: TrafficalPlugin): this;
+    /**
+     * Get a registered plugin by name.
+     */
+    getPlugin(name: string): TrafficalPlugin | undefined;
+    /**
+     * Get the stable ID for the current user.
+     */
+    getStableId(): string;
+    /**
+     * Set a custom stable ID (e.g., when user logs in).
+     */
+    setStableId(id: string): void;
+    private _getEffectiveBundle;
+    private _enrichContext;
+    private _fetchConfig;
+    private _startBackgroundRefresh;
+    private _logOfflineWarning;
+    /**
+     * Caches a decision for attribution lookup when track() is called.
+     * Maintains a bounded cache to prevent memory leaks.
+     */
+    private _cacheDecision;
+}
+/**
+ * Creates and initializes a Traffical client.
+ */
+export declare function createTrafficalClient(options: TrafficalClientOptions): Promise<TrafficalClient>;
+/**
+ * Creates a Traffical client without initializing (synchronous).
+ */
+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":"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"}