@traffical/react 0.1.2 → 0.1.4

package/package.json

@@ -1,32 +1,30 @@
 {
   "name": "@traffical/react",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Traffical SDK for React - Provider and hooks for parameter resolution",
   "type": "module",
-  "main": "./src/index.ts",
-  "module": "./src/index.ts",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "bun": "./src/index.ts",
-      "import": "./src/index.ts"
+      "default": "./dist/index.js"
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
     "test": "echo 'No tests yet'",
-    "typecheck": "tsc --noEmit",
-    "release": "bun scripts/release.ts"
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@traffical/core": "workspace:^",
-    "@traffical/js-client": "workspace:^"
+    "@traffical/core": "^0.1.4",
+    "@traffical/js-client": "^0.1.4"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/context.ts

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

package/src/hooks.ts

@@ -1,656 +0,0 @@
-/**
- * Traffical React Hooks
- *
- * React hooks for parameter resolution and decision tracking.
- * Uses the browser-optimized JS Client for full feature support.
- */
-
-import { useState, useEffect, useCallback, useRef } from "react";
-import type {
-  ParameterValue,
-  DecisionResult,
-  Context,
-} from "@traffical/core";
-import { resolveParameters } from "@traffical/core";
-import type { TrafficalPlugin } from "@traffical/js-client";
-import { useTrafficalContext } from "./context.js";
-
-// =============================================================================
-// Internal Utilities
-// =============================================================================
-
-/**
- * Creates a stable string key from an object for use in dependency arrays.
- * This prevents infinite re-renders when users pass inline objects to hooks.
- *
- * Uses JSON.stringify with sorted keys to ensure consistent ordering.
- */
-function createStableKey(obj: unknown): string {
-  if (obj === null || obj === undefined) {
-    return String(obj);
-  }
-  if (typeof obj !== "object") {
-    return String(obj);
-  }
-  // Sort keys for consistent ordering
-  return JSON.stringify(obj, Object.keys(obj as object).sort());
-}
-
-/**
- * Custom hook that returns a stable reference to an object.
- * Only updates the reference when the object's serialized value changes.
- *
- * This allows users to pass inline objects without causing infinite re-renders:
- * ```tsx
- * // This now works without memoization!
- * const { params } = useTraffical({
- *   defaults: { 'ui.color': '#000' }, // inline object is fine
- * });
- * ```
- */
-function useStableObject<T>(obj: T): T {
-  const stableKey = createStableKey(obj);
-  const ref = useRef(obj);
-
-  // Only update the ref when the serialized value actually changes
-  // This is safe because we're comparing by value, not reference
-  if (createStableKey(ref.current) !== stableKey) {
-    ref.current = obj;
-  }
-
-  return ref.current;
-}
-
-// =============================================================================
-// useTraffical - Primary Hook
-// =============================================================================
-
-/**
- * Options for the useTraffical hook.
- */
-export interface UseTrafficalOptions<T> {
-  /** Default parameter values */
-  defaults: T;
-
-  /** Additional context (optional) */
-  context?: Context;
-
-  /**
-   * Tracking mode (default: "full")
-   * - "full": Track decision + exposure (default, recommended for UI)
-   * - "decision": Track decision only, manual exposure control
-   * - "none": No tracking (SSR, internal logic, tests)
-   */
-  tracking?: "full" | "decision" | "none";
-}
-
-/**
- * Options for the bound track function returned by useTraffical.
- */
-export interface BoundTrackOptions {
-  /** Additional event properties */
-  properties?: Record<string, unknown>;
-}
-
-/**
- * @deprecated Use BoundTrackOptions instead.
- */
-export interface BoundTrackRewardOptions {
-  /** The reward value (e.g., revenue amount, conversion count) */
-  reward: number;
-  /** Type of reward (e.g., "revenue", "conversion", "engagement") */
-  rewardType?: string;
-  /** Multiple reward values keyed by type */
-  rewards?: Record<string, number>;
-}
-
-/**
- * Return value from the useTraffical hook.
- */
-export interface UseTrafficalResult<T> {
-  /** Resolved parameter values */
-  params: T;
-  /** The full decision result (null when tracking="none") */
-  decision: DecisionResult | null;
-  /** Whether the client is ready (config loaded) */
-  ready: boolean;
-  /** Any error that occurred */
-  error: Error | null;
-  /** Function to manually track exposure (no-op when tracking="none") */
-  trackExposure: () => void;
-  /**
-   * Track a user event. The decisionId is automatically bound.
-   * No-op if tracking="none" or no decision is available.
-   *
-   * @example
-   * track('purchase', { value: 99.99, orderId: 'ord_123' });
-   * track('add_to_cart', { itemId: 'sku_456' });
-   */
-  track: (event: string, properties?: Record<string, unknown>) => void;
-  /**
-   * @deprecated Use track() instead.
-   * Track a reward for this decision. The decisionId is automatically bound.
-   * No-op if tracking="none" or no decision is available.
-   */
-  trackReward: (options: BoundTrackRewardOptions) => void;
-}
-
-/**
- * Primary hook for Traffical parameter resolution and decision tracking.
- *
- * On first render, returns defaults immediately (no blocking).
- * When the config bundle loads, recomputes and returns resolved values.
- *
- * @example
- * ```tsx
- * // Full tracking (default) - decision + exposure events
- * const { params, decision, ready } = useTraffical({
- *   defaults: { "checkout.ctaText": "Buy Now" },
- * });
- *
- * // Decision tracking only - manual exposure control
- * const { params, decision, trackExposure } = useTraffical({
- *   defaults: { "checkout.ctaText": "Buy Now" },
- *   tracking: "decision",
- * });
- *
- * // No tracking - for SSR, tests, or internal logic
- * const { params, ready } = useTraffical({
- *   defaults: { "ui.hero.title": "Welcome" },
- *   tracking: "none",
- * });
- * ```
- */
-export function useTraffical<T extends Record<string, ParameterValue>>(
-  options: UseTrafficalOptions<T>
-): UseTrafficalResult<T> {
-  const { client, ready, error, getContext, getUnitKey, initialParams, localConfig } =
-    useTrafficalContext();
-
-  const trackingMode = options.tracking ?? "full";
-  const shouldTrackDecision = trackingMode !== "none";
-  const shouldAutoTrackExposure = trackingMode === "full";
-
-  // Create stable references for objects to prevent infinite re-renders
-  // when users pass inline objects like: useTraffical({ defaults: { ... } })
-  const stableDefaults = useStableObject(options.defaults);
-  const stableContext = useStableObject(options.context);
-
-  // Track if we resolved synchronously (to avoid duplicate resolution in useEffect)
-  const resolvedSyncRef = useRef(false);
-  const syncDecisionRef = useRef<DecisionResult | null>(null);
-
-  // State - resolve synchronously if possible to prevent flicker
-  const [params, setParams] = useState<T>(() => {
-    // If client is already ready (e.g., subsequent page navigation), resolve synchronously
-    // This prevents the default -> resolved flicker (classic A/B testing problem)
-    if (client && ready) {
-      resolvedSyncRef.current = true;
-
-      const context: Context = {
-        ...getContext(),
-        ...(options.context ?? {}),
-      };
-
-      if (shouldTrackDecision) {
-        // Use decide() for tracked decisions
-        const result = client.decide({
-          context,
-          defaults: options.defaults,
-        });
-        syncDecisionRef.current = result;
-        return result.assignments as T;
-      } else {
-        // Use getParams() for untracked
-        return client.getParams({
-          context,
-          defaults: options.defaults,
-        }) as T;
-      }
-    }
-
-    // NEW: If we have localConfig bundle, resolve synchronously even before client is ready
-    // This is the key to flicker-free SSR: server and client both resolve from the same bundle
-    if (localConfig) {
-      try {
-        const context = getContext();
-        // Only resolve if we have a userId (set by server via cookie/header)
-        if (context.userId) {
-          resolvedSyncRef.current = true;
-          const fullContext: Context = {
-            ...context,
-            ...(options.context ?? {}),
-          };
-          // Use pure resolution function from core - no tracking on initial render
-          const resolved = resolveParameters(localConfig, fullContext, options.defaults);
-          return resolved as T;
-        }
-      } catch {
-        // Context function not ready, fall through to defaults
-      }
-    }
-
-    // Fallback to defaults (no localConfig or no userId)
-    if (initialParams) {
-      return { ...stableDefaults, ...initialParams } as T;
-    }
-    return stableDefaults;
-  });
-
-  const [decision, setDecision] = useState<DecisionResult | null>(
-    () => syncDecisionRef.current
-  );
-  const [hasTrackedExposure, setHasTrackedExposure] = useState(false);
-
-  // Manual exposure tracking (synchronous - batched internally)
-  const trackExposure = useCallback(() => {
-    // No-op when tracking is "none"
-    if (trackingMode === "none") {
-      return;
-    }
-    if (!client || !decision || hasTrackedExposure) {
-      return;
-    }
-    client.trackExposure(decision);
-    setHasTrackedExposure(true);
-  }, [client, decision, hasTrackedExposure, trackingMode]);
-
-  // Resolve params or make decision when client is ready
-  useEffect(() => {
-    if (!client || !ready) {
-      return;
-    }
-
-    // Build context using stable references
-    const context: Context = {
-      ...getContext(),
-      ...stableContext,
-    };
-
-    if (shouldTrackDecision) {
-      // Use decide() - tracks decision event via DecisionTrackingPlugin
-      const result = client.decide({
-        context,
-        defaults: stableDefaults,
-      });
-
-      // Only update state if we didn't already resolve synchronously
-      // This prevents the params from flickering (default -> resolved)
-      // But we ALWAYS call decide() to ensure tracking happens
-      if (!resolvedSyncRef.current) {
-        setParams(result.assignments as T);
-      }
-      setDecision(result);
-      setHasTrackedExposure(false);
-    } else {
-      // Use getParams() - no tracking
-      if (!resolvedSyncRef.current) {
-        const resolved = client.getParams({
-          context,
-          defaults: stableDefaults,
-        });
-        setParams(resolved as T);
-      }
-      setDecision(null);
-    }
-
-    // Clear the sync flag after first effect run
-    resolvedSyncRef.current = false;
-  }, [client, ready, getContext, stableContext, stableDefaults, shouldTrackDecision]);
-
-  // Auto-track exposure when tracking is "full"
-  useEffect(() => {
-    if (shouldAutoTrackExposure && decision && !hasTrackedExposure) {
-      trackExposure();
-    }
-  }, [shouldAutoTrackExposure, decision, hasTrackedExposure, trackExposure]);
-
-  // Ref to store current decision for stable track function reference
-  const decisionRef = useRef<DecisionResult | null>(null);
-  decisionRef.current = decision;
-
-  // Buffer for track events that arrive before decision is ready
-  // This prevents race conditions where track() is called in a useEffect
-  // that runs before the decision has been set
-  const pendingTracksRef = useRef<Array<{ event: string; properties?: Record<string, unknown> }>>([]);
-
-  // Flush pending track events when decision becomes available
-  useEffect(() => {
-    if (decision && client && pendingTracksRef.current.length > 0) {
-      const pending = pendingTracksRef.current;
-      pendingTracksRef.current = [];
-      
-      for (const { event, properties } of pending) {
-        client.track(event, properties, {
-          decisionId: decision.decisionId,
-          unitKey: getUnitKey(),
-        });
-      }
-    }
-  }, [decision, client, getUnitKey]);
-
-  // Track user events - decisionId is automatically included
-  // If decision isn't ready yet, events are queued and flushed when it becomes available
-  const track = useCallback(
-    (event: string, properties?: Record<string, unknown>) => {
-      if (!client) {
-        console.warn("[Traffical] Client not initialized, cannot track event");
-        return;
-      }
-      
-      const currentDecision = decisionRef.current;
-      if (!currentDecision) {
-        // Queue the event instead of dropping it - will be flushed when decision is ready
-        // This handles the race condition where track() is called before decision is set
-        if (trackingMode === "none") {
-          console.warn(
-            "[Traffical] Cannot track event with tracking: 'none'. Use tracking: 'full' or 'decision'."
-          );
-          return;
-        }
-        pendingTracksRef.current.push({ event, properties });
-        return;
-      }
-      
-      client.track(event, properties, {
-        decisionId: currentDecision.decisionId,
-        unitKey: getUnitKey(),
-      });
-    },
-    [client, getUnitKey, trackingMode]
-  );
-
-  // Deprecated: Bound reward tracking - decisionId is automatically included
-  const trackReward = useCallback(
-    (options: BoundTrackRewardOptions) => {
-      if (!client) {
-        console.warn("[Traffical] Client not initialized, cannot track reward");
-        return;
-      }
-      const currentDecision = decisionRef.current;
-      if (!currentDecision) {
-        console.warn(
-          "[Traffical] No decision available, cannot track reward. Did you use tracking: 'none'?"
-        );
-        return;
-      }
-      // Map old API to new track() API
-      track(options.rewardType || "reward", {
-        value: options.reward,
-        ...(options.rewards ? { rewards: options.rewards } : {}),
-      });
-    },
-    [client, track]
-  );
-
-  return { params, decision, ready, error, trackExposure, track, trackReward };
-}
-
-// =============================================================================
-// Deprecated Hooks (for backward compatibility)
-// =============================================================================
-
-/**
- * Options for useTrafficalParams hook.
- * @deprecated Use UseTrafficalOptions instead.
- */
-export interface UseTrafficalParamsOptions<T extends Record<string, ParameterValue>> {
-  /** Default values for parameters */
-  defaults: T;
-  /** Additional context to merge (optional) */
-  context?: Context;
-}
-
-/**
- * Return value from useTrafficalParams hook.
- * @deprecated Use UseTrafficalResult instead.
- */
-export interface UseTrafficalParamsResult<T> {
-  /** Resolved parameter values */
-  params: T;
-  /** Whether the client is ready (config loaded) */
-  ready: boolean;
-  /** Any error that occurred */
-  error: Error | null;
-}
-
-/**
- * Hook to get resolved parameter values.
- *
- * @deprecated Use `useTraffical({ tracking: "none" })` instead.
- *
- * @example
- * ```tsx
- * // Old way (deprecated)
- * const { params, ready } = useTrafficalParams({ defaults: { ... } });
- *
- * // New way
- * const { params, ready } = useTraffical({ defaults: { ... }, tracking: "none" });
- * ```
- */
-export function useTrafficalParams<T extends Record<string, ParameterValue>>(
-  options: UseTrafficalParamsOptions<T>
-): UseTrafficalParamsResult<T> {
-  // Show deprecation warning in development only
-  useEffect(() => {
-    if (process.env.NODE_ENV === "development") {
-      console.warn(
-        '[Traffical] useTrafficalParams is deprecated. Use useTraffical({ tracking: "none" }) instead.'
-      );
-    }
-  }, []);
-
-  const result = useTraffical({ ...options, tracking: "none" });
-  return { params: result.params, ready: result.ready, error: result.error };
-}
-
-/**
- * Options for useTrafficalDecision hook.
- * @deprecated Use UseTrafficalOptions instead.
- */
-export interface UseTrafficalDecisionOptions<T extends Record<string, ParameterValue>> {
-  /** Default values for parameters */
-  defaults: T;
-  /** Additional context to merge (optional) */
-  context?: Context;
-  /**
-   * Whether to automatically track exposure (default: true).
-   * Set to false if you want to manually control when exposure is tracked
-   * (e.g., when an element scrolls into view).
-   *
-   * Note: Decision tracking happens automatically via DecisionTrackingPlugin
-   * and is separate from exposure tracking.
-   */
-  trackExposure?: boolean;
-}
-
-/**
- * Return value from useTrafficalDecision hook.
- * @deprecated Use UseTrafficalResult instead.
- */
-export interface UseTrafficalDecisionResult<T> {
-  /** Resolved parameter values */
-  params: T;
-  /** The full decision result (for tracking) */
-  decision: DecisionResult | null;
-  /** Whether the client is ready (config loaded) */
-  ready: boolean;
-  /** Any error that occurred */
-  error: Error | null;
-  /**
-   * Function to manually track exposure.
-   * Note: This is synchronous - events are batched internally.
-   */
-  trackExposure: () => void;
-}
-
-/**
- * Hook to get a decision with full metadata for tracking.
- *
- * @deprecated Use `useTraffical()` instead.
- *
- * @example
- * ```tsx
- * // Old way (deprecated)
- * const { params, decision } = useTrafficalDecision({ defaults: { ... } });
- *
- * // New way
- * const { params, decision } = useTraffical({ defaults: { ... } });
- *
- * // Old way with manual exposure (deprecated)
- * const { params, trackExposure } = useTrafficalDecision({ defaults: { ... }, trackExposure: false });
- *
- * // New way with manual exposure
- * const { params, trackExposure } = useTraffical({ defaults: { ... }, tracking: "decision" });
- * ```
- */
-export function useTrafficalDecision<T extends Record<string, ParameterValue>>(
-  options: UseTrafficalDecisionOptions<T>
-): UseTrafficalDecisionResult<T> {
-  // Show deprecation warning in development only
-  useEffect(() => {
-    if (process.env.NODE_ENV === "development") {
-      console.warn(
-        "[Traffical] useTrafficalDecision is deprecated. Use useTraffical() instead."
-      );
-    }
-  }, []);
-
-  // Map old trackExposure option to new tracking mode
-  const tracking = options.trackExposure === false ? "decision" : "full";
-  return useTraffical({ defaults: options.defaults, context: options.context, tracking });
-}
-
-/**
- * Hook to track user events.
- *
- * @example
- * ```tsx
- * const track = useTrafficalTrack();
- *
- * const handlePurchase = (amount: number) => {
- *   track('purchase', { value: amount, orderId: 'ord_123' });
- * };
- * ```
- */
-export function useTrafficalTrack() {
-  const { client, getUnitKey } = useTrafficalContext();
-
-  const track = useCallback(
-    (
-      event: string,
-      properties?: Record<string, unknown>,
-      options?: { decisionId?: string }
-    ) => {
-      if (!client) {
-        console.warn("[Traffical] Client not initialized, cannot track event");
-        return;
-      }
-
-      client.track(event, properties, {
-        decisionId: options?.decisionId,
-        unitKey: getUnitKey(),
-      });
-    },
-    [client, getUnitKey]
-  );
-
-  return track;
-}
-
-/**
- * @deprecated Use useTrafficalTrack() instead.
- *
- * Hook to track a reward.
- *
- * @example
- * ```tsx
- * const trackReward = useTrafficalReward();
- *
- * const handlePurchase = (amount: number) => {
- *   trackReward({
- *     decisionId: decision.decisionId,
- *     reward: amount,
- *     rewardType: "revenue",
- *   });
- * };
- * ```
- */
-export function useTrafficalReward() {
-  const { client, getUnitKey, getContext } = useTrafficalContext();
-
-  const trackReward = useCallback(
-    (options: {
-      decisionId: string;
-      reward: number;
-      rewardType?: string;
-      rewards?: Record<string, number>;
-    }) => {
-      if (!client) {
-        console.warn("[Traffical] Client not initialized, cannot track reward");
-        return;
-      }
-
-      // Map old API to new track() API
-      client.track(options.rewardType || "reward", {
-        value: options.reward,
-        ...(options.rewards ? { rewards: options.rewards } : {}),
-      }, {
-        decisionId: options.decisionId,
-        unitKey: getUnitKey(),
-      });
-    },
-    [client, getUnitKey, getContext]
-  );
-
-  return trackReward;
-}
-
-/**
- * Hook to access a registered plugin by name.
- *
- * @example
- * ```tsx
- * import { createDOMBindingPlugin, DOMBindingPlugin } from '@traffical/js-client';
- *
- * // In your provider config:
- * plugins: [createDOMBindingPlugin()]
- *
- * // In a component:
- * const domPlugin = useTrafficalPlugin<DOMBindingPlugin>('dom-binding');
- *
- * // Re-apply bindings after dynamic content changes
- * useEffect(() => {
- *   domPlugin?.applyBindings();
- * }, [contentLoaded, domPlugin]);
- * ```
- */
-export function useTrafficalPlugin<T extends TrafficalPlugin = TrafficalPlugin>(
-  name: string
-): T | undefined {
-  const { client, ready } = useTrafficalContext();
-
-  if (!client || !ready) {
-    return undefined;
-  }
-
-  return client.getPlugin(name) as T | undefined;
-}
-
-/**
- * Hook to access the Traffical client directly.
- *
- * @example
- * ```tsx
- * const { client, ready } = useTrafficalClient();
- *
- * if (ready && client) {
- *   const version = client.getConfigVersion();
- *   const stableId = client.getStableId();
- * }
- * ```
- */
-export function useTrafficalClient() {
-  const { client, ready, error } = useTrafficalContext();
-  return { client, ready, error };
-}

package/src/index.ts

@@ -1,93 +0,0 @@
-/**
- * @traffical/react
- *
- * Traffical SDK for React applications.
- * Provides Provider and hooks for parameter resolution and decision tracking.
- *
- * Features:
- * - Browser-optimized with sendBeacon, localStorage persistence
- * - Automatic stable ID for anonymous users
- * - Plugin system support (DecisionTrackingPlugin enabled by default)
- * - Decision and exposure deduplication
- *
- * @example
- * ```tsx
- * import { TrafficalProvider, useTraffical } from '@traffical/react';
- *
- * function App() {
- *   return (
- *     <TrafficalProvider
- *       config={{
- *         orgId: 'org_123',
- *         projectId: 'proj_456',
- *         env: 'production',
- *         apiKey: 'pk_...',
- *       }}
- *     >
- *       <MyComponent />
- *     </TrafficalProvider>
- *   );
- * }
- *
- * function MyComponent() {
- *   const { params, ready } = useTraffical({
- *     defaults: { 'ui.hero.title': 'Welcome' },
- *   });
- *
- *   if (!ready) return <div>Loading...</div>;
- *   return <h1>{params['ui.hero.title']}</h1>;
- * }
- * ```
- */
-
-// Re-export everything from core
-export * from "@traffical/core";
-
-// Re-export client and utilities from JS Client
-export {
-  TrafficalClient,
-  createTrafficalClient,
-  createTrafficalClientSync,
-  type TrafficalClientOptions,
-} from "@traffical/js-client";
-
-// Re-export plugin utilities from JS Client
-export {
-  type TrafficalPlugin,
-  type PluginOptions,
-  createDOMBindingPlugin,
-  type DOMBindingPlugin,
-  type DOMBindingPluginOptions,
-} from "@traffical/js-client";
-
-// Export React-specific components and hooks
-export { TrafficalProvider, type TrafficalProviderProps } from "./provider.js";
-
-export {
-  TrafficalContext,
-  useTrafficalContext,
-  type TrafficalProviderConfig,
-  type TrafficalContextValue,
-} from "./context.js";
-
-export {
-  // Primary hook
-  useTraffical,
-  type UseTrafficalOptions,
-  type UseTrafficalResult,
-  type BoundTrackOptions,
-  // Track hook
-  useTrafficalTrack,
-  // Other hooks
-  useTrafficalPlugin,
-  useTrafficalClient,
-  // Deprecated (kept for backward compatibility)
-  type BoundTrackRewardOptions,
-  useTrafficalReward,
-  useTrafficalParams,
-  useTrafficalDecision,
-  type UseTrafficalParamsOptions,
-  type UseTrafficalParamsResult,
-  type UseTrafficalDecisionOptions,
-  type UseTrafficalDecisionResult,
-} from "./hooks.js";

package/src/provider.tsx

@@ -1,194 +0,0 @@
-/**
- * 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 React, {
-  useEffect,
-  useState,
-  useCallback,
-  useMemo,
-  useRef,
-  type ReactNode,
-} from "react";
-import {
-  TrafficalClient,
-  createTrafficalClientSync,
-} from "@traffical/js-client";
-import type { Context } from "@traffical/core";
-import {
-  TrafficalContext,
-  type TrafficalProviderConfig,
-  type TrafficalContextValue,
-} from "./context.js";
-
-/**
- * Props for the TrafficalProvider component.
- */
-export interface TrafficalProviderProps {
-  /** Configuration for the Traffical client */
-  config: TrafficalProviderConfig;
-  /** Child components */
-  children: ReactNode;
-}
-
-/**
- * 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,
-}: TrafficalProviderProps): React.ReactElement {
-  const [client, setClient] = useState<TrafficalClient | null>(null);
-  const [ready, setReady] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  // Keep a ref to the client for cleanup
-  const clientRef = useRef<TrafficalClient | null>(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((): Context => {
-    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<TrafficalContextValue>(
-    () => ({
-      client,
-      ready,
-      error,
-      getUnitKey,
-      getContext,
-      initialParams: config.initialParams,
-      localConfig: config.localConfig,
-    }),
-    [client, ready, error, getUnitKey, getContext, config.initialParams, config.localConfig]
-  );
-
-  return (
-    <TrafficalContext.Provider value={contextValue}>
-      {children}
-    </TrafficalContext.Provider>
-  );
-}