@traffical/react 0.1.1

package/dist/provider.js

@@ -0,0 +1,144 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Traffical React Provider
+ *
+ * Initializes the Traffical client (browser-optimized) and provides it to child components.
+ * Supports plugins, automatic stable ID, and decision tracking out of the box.
+ */
+import { useEffect, useState, useCallback, useMemo, useRef, } from "react";
+import { createTrafficalClientSync, } from "@traffical/js-client";
+import { TrafficalContext, } from "./context.js";
+/**
+ * TrafficalProvider - initializes and provides the Traffical client to React components.
+ *
+ * Features:
+ * - Browser-optimized with sendBeacon, localStorage persistence
+ * - Automatic stable ID for anonymous users (unless unitKeyFn provided)
+ * - Plugin system support (DecisionTrackingPlugin enabled by default)
+ * - Decision and exposure deduplication
+ *
+ * @example
+ * ```tsx
+ * <TrafficalProvider
+ *   config={{
+ *     orgId: "org_123",
+ *     projectId: "proj_456",
+ *     env: "production",
+ *     apiKey: "pk_...",
+ *     // Optional: provide unitKeyFn for logged-in users
+ *     unitKeyFn: () => getUserId(),
+ *     // Optional: add context
+ *     contextFn: () => ({ locale: "en-US" }),
+ *     // Optional: add custom plugins
+ *     plugins: [createDOMBindingPlugin()],
+ *   }}
+ * >
+ *   <App />
+ * </TrafficalProvider>
+ * ```
+ */
+export function TrafficalProvider({ config, children, }) {
+    const [client, setClient] = useState(null);
+    const [ready, setReady] = useState(false);
+    const [error, setError] = useState(null);
+    // Keep a ref to the client for cleanup
+    const clientRef = useRef(null);
+    // Memoize the unit key function
+    // If no unitKeyFn is provided, use the client's stable ID
+    const getUnitKey = useCallback(() => {
+        if (config.unitKeyFn) {
+            return config.unitKeyFn();
+        }
+        // Fall back to the client's auto-generated stable ID
+        return clientRef.current?.getStableId() ?? "";
+    }, [config.unitKeyFn]);
+    const getContext = useCallback(() => {
+        const unitKey = getUnitKey();
+        const additionalContext = config.contextFn?.() ?? {};
+        // The unit key field name comes from the bundle's hashing config
+        // For now, we use common conventions and let the SDK handle it
+        return {
+            ...additionalContext,
+            // Include common unit key field names
+            userId: unitKey,
+            deviceId: unitKey,
+            anonymousId: unitKey,
+        };
+    }, [getUnitKey, config.contextFn]);
+    // Initialize client on mount
+    useEffect(() => {
+        let mounted = true;
+        const initClient = async () => {
+            try {
+                // Create client synchronously so it's available immediately
+                const newClient = createTrafficalClientSync({
+                    orgId: config.orgId,
+                    projectId: config.projectId,
+                    env: config.env,
+                    apiKey: config.apiKey,
+                    baseUrl: config.baseUrl,
+                    localConfig: config.localConfig,
+                    refreshIntervalMs: config.refreshIntervalMs,
+                    trackDecisions: config.trackDecisions,
+                    decisionDeduplicationTtlMs: config.decisionDeduplicationTtlMs,
+                    exposureSessionTtlMs: config.exposureSessionTtlMs,
+                    eventBatchSize: config.eventBatchSize,
+                    eventFlushIntervalMs: config.eventFlushIntervalMs,
+                    plugins: config.plugins,
+                });
+                clientRef.current = newClient;
+                if (mounted) {
+                    setClient(newClient);
+                    // If localConfig was provided, mark as ready immediately
+                    if (config.localConfig) {
+                        setReady(true);
+                    }
+                }
+                // Initialize asynchronously (fetches/refreshes config bundle)
+                await newClient.initialize();
+                if (mounted) {
+                    setReady(true);
+                }
+            }
+            catch (err) {
+                if (mounted) {
+                    setError(err instanceof Error ? err : new Error(String(err)));
+                    // Still mark as ready - we'll use defaults
+                    setReady(true);
+                }
+            }
+        };
+        initClient();
+        return () => {
+            mounted = false;
+            clientRef.current?.destroy();
+            clientRef.current = null;
+        };
+    }, [
+        config.orgId,
+        config.projectId,
+        config.env,
+        config.apiKey,
+        config.baseUrl,
+        config.localConfig,
+        config.refreshIntervalMs,
+        config.trackDecisions,
+        config.decisionDeduplicationTtlMs,
+        config.exposureSessionTtlMs,
+        config.eventBatchSize,
+        config.eventFlushIntervalMs,
+        config.plugins,
+    ]);
+    // Memoize context value
+    const contextValue = useMemo(() => ({
+        client,
+        ready,
+        error,
+        getUnitKey,
+        getContext,
+        initialParams: config.initialParams,
+        localConfig: config.localConfig,
+    }), [client, ready, error, getUnitKey, getContext, config.initialParams, config.localConfig]);
+    return (_jsx(TrafficalContext.Provider, { value: contextValue, children: children }));
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@traffical/react",
+  "version": "0.1.1",
+  "description": "Traffical SDK for React - Provider and hooks for parameter resolution",
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "release": "bun scripts/release.ts"
+  },
+  "dependencies": {
+    "@traffical/core": "workspace:^",
+    "@traffical/js-client": "workspace:^"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^18.2.0",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "keywords": [
+    "traffical",
+    "feature-flags",
+    "experimentation",
+    "a/b-testing",
+    "react",
+    "hooks"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/traffical/js-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/context.ts

@@ -0,0 +1,144 @@
+/**
+ * Traffical React Context
+ *
+ * Provides the Traffical client instance to React components.
+ * Uses the browser-optimized JS Client for full feature support.
+ */
+
+import { createContext, useContext } from "react";
+import type { TrafficalClient, TrafficalPlugin } from "@traffical/js-client";
+import type { ConfigBundle, Context } from "@traffical/core";
+
+/**
+ * Configuration for the Traffical provider.
+ */
+export interface TrafficalProviderConfig {
+  // ==========================================================================
+  // Required
+  // ==========================================================================
+
+  /** Organization ID */
+  orgId: string;
+  /** Project ID */
+  projectId: string;
+  /** Environment (e.g., "production", "staging") */
+  env: string;
+  /** API key for authentication */
+  apiKey: string;
+
+  // ==========================================================================
+  // Optional - Connection
+  // ==========================================================================
+
+  /** Base URL for the control plane API (optional) */
+  baseUrl?: string;
+  /** Local config bundle for offline fallback */
+  localConfig?: ConfigBundle;
+  /** Refresh interval in milliseconds (default: 60000) */
+  refreshIntervalMs?: number;
+
+  // ==========================================================================
+  // Optional - Identity
+  // ==========================================================================
+
+  /**
+   * Function to get the unit key value.
+   * If not provided, the SDK will use automatic stable ID generation.
+   */
+  unitKeyFn?: () => string;
+  /** Function to get additional context (optional) */
+  contextFn?: () => Context;
+
+  // ==========================================================================
+  // Optional - Decision Tracking
+  // ==========================================================================
+
+  /**
+   * Whether to automatically track decision events (default: true).
+   * When enabled, every call to decide() automatically sends a DecisionEvent
+   * to the control plane, 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;
+
+  // ==========================================================================
+  // Optional - Exposure Tracking
+  // ==========================================================================
+
+  /**
+   * Exposure deduplication session TTL in milliseconds (default: 30 minutes).
+   * Same user seeing same variant won't trigger multiple exposure events.
+   */
+  exposureSessionTtlMs?: number;
+
+  // ==========================================================================
+  // Optional - Plugins
+  // ==========================================================================
+
+  /**
+   * Plugins to register with the client.
+   * The DecisionTrackingPlugin is included by default unless trackDecisions is false.
+   */
+  plugins?: TrafficalPlugin[];
+
+  // ==========================================================================
+  // Optional - Event Batching
+  // ==========================================================================
+
+  /** Max events before auto-flush (default: 10) */
+  eventBatchSize?: number;
+  /** Auto-flush interval in ms (default: 30000) */
+  eventFlushIntervalMs?: number;
+
+  // ==========================================================================
+  // Optional - SSR
+  // ==========================================================================
+
+  /** Initial params from SSR (optional) */
+  initialParams?: Record<string, unknown>;
+}
+
+/**
+ * Internal context value.
+ */
+export interface TrafficalContextValue {
+  /** The Traffical client instance */
+  client: TrafficalClient | null;
+  /** Whether the client is ready (config loaded) */
+  ready: boolean;
+  /** Any initialization error */
+  error: Error | null;
+  /** Function to get the unit key */
+  getUnitKey: () => string;
+  /** Function to get the full context */
+  getContext: () => Context;
+  /** Initial params from SSR */
+  initialParams?: Record<string, unknown>;
+  /** Local config bundle for synchronous resolution during initial render */
+  localConfig?: ConfigBundle;
+}
+
+/**
+ * React context for Traffical.
+ */
+export const TrafficalContext = createContext<TrafficalContextValue | null>(
+  null
+);
+
+/**
+ * Hook to access the Traffical context.
+ * Throws if used outside of TrafficalProvider.
+ */
+export function useTrafficalContext(): TrafficalContextValue {
+  const context = useContext(TrafficalContext);
+  if (!context) {
+    throw new Error(
+      "useTrafficalContext must be used within a TrafficalProvider"
+    );
+  }
+  return context;
+}