@traffical/react 0.1.1

package/dist/context.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Traffical React Context
+ *
+ * Provides the Traffical client instance to React components.
+ * Uses the browser-optimized JS Client for full feature support.
+ */
+import type { TrafficalClient, TrafficalPlugin } from "@traffical/js-client";
+import type { ConfigBundle, Context } from "@traffical/core";
+/**
+ * Configuration for the Traffical provider.
+ */
+export interface TrafficalProviderConfig {
+    /** 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 control plane API (optional) */
+    baseUrl?: string;
+    /** Local config bundle for offline fallback */
+    localConfig?: ConfigBundle;
+    /** Refresh interval in milliseconds (default: 60000) */
+    refreshIntervalMs?: number;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Exposure deduplication session TTL in milliseconds (default: 30 minutes).
+     * Same user seeing same variant won't trigger multiple exposure events.
+     */
+    exposureSessionTtlMs?: number;
+    /**
+     * Plugins to register with the client.
+     * The DecisionTrackingPlugin is included by default unless trackDecisions is false.
+     */
+    plugins?: TrafficalPlugin[];
+    /** Max events before auto-flush (default: 10) */
+    eventBatchSize?: number;
+    /** Auto-flush interval in ms (default: 30000) */
+    eventFlushIntervalMs?: number;
+    /** 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 declare const TrafficalContext: import("react").Context<TrafficalContextValue | null>;
+/**
+ * Hook to access the Traffical context.
+ * Throws if used outside of TrafficalProvider.
+ */
+export declare function useTrafficalContext(): TrafficalContextValue;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,uBAAuB;IAKtC,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IAMf,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAM3B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IACzB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAM1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,0BAA0B,CAAC,EAAE,MAAM,CAAC;IAMpC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAM9B;;;OAGG;IACH,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAM5B,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAM9B,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oCAAoC;IACpC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/B,kDAAkD;IAClD,KAAK,EAAE,OAAO,CAAC;IACf,+BAA+B;IAC/B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,mCAAmC;IACnC,UAAU,EAAE,MAAM,MAAM,CAAC;IACzB,uCAAuC;IACvC,UAAU,EAAE,MAAM,OAAO,CAAC;IAC1B,8BAA8B;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,2EAA2E;IAC3E,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,uDAE5B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,qBAAqB,CAQ3D"}

package/dist/context.js

@@ -0,0 +1,23 @@
+/**
+ * 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";
+/**
+ * React context for Traffical.
+ */
+export const TrafficalContext = createContext(null);
+/**
+ * Hook to access the Traffical context.
+ * Throws if used outside of TrafficalProvider.
+ */
+export function useTrafficalContext() {
+    const context = useContext(TrafficalContext);
+    if (!context) {
+        throw new Error("useTrafficalContext must be used within a TrafficalProvider");
+    }
+    return context;
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAqHlD;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAC3C,IAAI,CACL,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,OAAO,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC7C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,6DAA6D,CAC9D,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/hooks.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Traffical React Hooks
+ *
+ * React hooks for parameter resolution and decision tracking.
+ * Uses the browser-optimized JS Client for full feature support.
+ */
+import type { ParameterValue, DecisionResult, Context } from "@traffical/core";
+import type { TrafficalPlugin } from "@traffical/js-client";
+/**
+ * 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 declare function useTraffical<T extends Record<string, ParameterValue>>(options: UseTrafficalOptions<T>): UseTrafficalResult<T>;
+/**
+ * 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 declare function useTrafficalParams<T extends Record<string, ParameterValue>>(options: UseTrafficalParamsOptions<T>): UseTrafficalParamsResult<T>;
+/**
+ * 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 declare function useTrafficalDecision<T extends Record<string, ParameterValue>>(options: UseTrafficalDecisionOptions<T>): UseTrafficalDecisionResult<T>;
+/**
+ * Hook to track user events.
+ *
+ * @example
+ * ```tsx
+ * const track = useTrafficalTrack();
+ *
+ * const handlePurchase = (amount: number) => {
+ *   track('purchase', { value: amount, orderId: 'ord_123' });
+ * };
+ * ```
+ */
+export declare function useTrafficalTrack(): (event: string, properties?: Record<string, unknown>, options?: {
+    decisionId?: string;
+}) => void;
+/**
+ * @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 declare function useTrafficalReward(): (options: {
+    decisionId: string;
+    reward: number;
+    rewardType?: string;
+    rewards?: Record<string, number>;
+}) => void;
+/**
+ * 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 declare function useTrafficalPlugin<T extends TrafficalPlugin = TrafficalPlugin>(name: string): 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 declare function useTrafficalClient(): {
+    client: import("@traffical/js-client").TrafficalClient | null;
+    ready: boolean;
+    error: Error | null;
+};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

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