@grainql/analytics-web 1.7.4 → 2.0.0

package/dist/cjs/react/index.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Grain Analytics React Hooks
+ *
+ * React integration for @grainql/analytics-web
+ *
+ * @example
+ * ```tsx
+ * import { GrainProvider, useConfig, useTrack } from '@grainql/analytics-web/react';
+ *
+ * // Pattern 1: Provider-managed client
+ * <GrainProvider config={{ tenantId: 'xxx' }}>
+ *   <App />
+ * </GrainProvider>
+ *
+ * // Pattern 2: External client
+ * const grain = new GrainAnalytics({ tenantId: 'xxx' });
+ * <GrainProvider client={grain}>
+ *   <App />
+ * </GrainProvider>
+ *
+ * // Use hooks in components
+ * function MyComponent() {
+ *   const { value } = useConfig('hero_variant');
+ *   const track = useTrack();
+ *
+ *   return <button onClick={() => track('clicked')}>Click</button>;
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTrack = exports.useAllConfigs = exports.useConfig = exports.useGrainAnalytics = exports.GrainProvider = void 0;
+// Provider
+var GrainProvider_1 = require("./GrainProvider");
+Object.defineProperty(exports, "GrainProvider", { enumerable: true, get: function () { return GrainProvider_1.GrainProvider; } });
+// Hooks
+var useGrainAnalytics_1 = require("./hooks/useGrainAnalytics");
+Object.defineProperty(exports, "useGrainAnalytics", { enumerable: true, get: function () { return useGrainAnalytics_1.useGrainAnalytics; } });
+var useConfig_1 = require("./hooks/useConfig");
+Object.defineProperty(exports, "useConfig", { enumerable: true, get: function () { return useConfig_1.useConfig; } });
+var useAllConfigs_1 = require("./hooks/useAllConfigs");
+Object.defineProperty(exports, "useAllConfigs", { enumerable: true, get: function () { return useAllConfigs_1.useAllConfigs; } });
+var useTrack_1 = require("./hooks/useTrack");
+Object.defineProperty(exports, "useTrack", { enumerable: true, get: function () { return useTrack_1.useTrack; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/index.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;;;AAEH,WAAW;AACX,iDAAgD;AAAvC,8GAAA,aAAa,OAAA;AAEtB,QAAQ;AACR,+DAA8D;AAArD,sHAAA,iBAAiB,OAAA;AAC1B,+CAA8C;AAArC,sGAAA,SAAS,OAAA;AAClB,uDAAsD;AAA7C,8GAAA,aAAa,OAAA;AACtB,6CAA4C;AAAnC,oGAAA,QAAQ,OAAA"}

package/dist/cjs/react/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * React-specific types for Grain Analytics
+ */
+import type { GrainAnalytics, GrainConfig, SendEventOptions } from '../index';
+export interface GrainProviderProps {
+    children: React.ReactNode;
+    client?: GrainAnalytics;
+    config?: GrainConfig;
+}
+export interface UseConfigOptions {
+    forceRefresh?: boolean;
+    immediateKeys?: string[];
+    properties?: Record<string, string>;
+}
+export interface UseConfigResult {
+    value: string | undefined;
+    isRefreshing: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+export interface UseAllConfigsOptions {
+    forceRefresh?: boolean;
+    immediateKeys?: string[];
+    properties?: Record<string, string>;
+}
+export interface UseAllConfigsResult {
+    configs: Record<string, string>;
+    isRefreshing: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+export type TrackFunction = (eventName: string, properties?: Record<string, unknown>, options?: SendEventOptions) => Promise<void>;
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/react/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/react/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,aAAa,GAAG,CAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,CAAC,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/cjs/react/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * React-specific types for Grain Analytics
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/react/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/react/types.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/dist/esm/react/GrainProvider.d.ts

@@ -0,0 +1,11 @@
+/**
+ * GrainProvider - Context provider for Grain Analytics
+ *
+ * Supports two patterns:
+ * 1. Provider-managed: Pass `config` prop, provider creates and manages client lifecycle
+ * 2. External client: Pass `client` prop, user manages lifecycle
+ */
+import * as React from 'react';
+import type { GrainProviderProps } from './types';
+export declare function GrainProvider({ children, client, config }: GrainProviderProps): React.JSX.Element;
+//# sourceMappingURL=GrainProvider.d.ts.map

package/dist/esm/react/GrainProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrainProvider.d.ts","sourceRoot":"","sources":["../../../src/react/GrainProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,kBAAkB,qBA8C7E"}

package/dist/esm/react/GrainProvider.js

@@ -0,0 +1,43 @@
+/**
+ * GrainProvider - Context provider for Grain Analytics
+ *
+ * Supports two patterns:
+ * 1. Provider-managed: Pass `config` prop, provider creates and manages client lifecycle
+ * 2. External client: Pass `client` prop, user manages lifecycle
+ */
+import * as React from 'react';
+import { GrainAnalytics } from '../index';
+import { GrainContext } from './context';
+export function GrainProvider({ children, client, config }) {
+    // Validate props
+    if (client && config) {
+        throw new Error('GrainProvider: Cannot provide both "client" and "config" props. ' +
+            'Use "client" for external management or "config" for provider-managed client.');
+    }
+    if (!client && !config) {
+        throw new Error('GrainProvider: Must provide either "client" or "config" prop. ' +
+            'Use "client" to pass an existing GrainAnalytics instance, or "config" to create one automatically.');
+    }
+    const isProviderManaged = Boolean(config);
+    const clientRef = React.useRef(null);
+    // Initialize client if config is provided
+    if (isProviderManaged && !clientRef.current && config) {
+        clientRef.current = new GrainAnalytics(config);
+    }
+    // Use external client if provided
+    const activeClient = client || clientRef.current;
+    if (!activeClient) {
+        throw new Error('GrainProvider: Failed to initialize client');
+    }
+    // Cleanup on unmount (only for provider-managed clients)
+    React.useEffect(() => {
+        return () => {
+            if (isProviderManaged && clientRef.current) {
+                clientRef.current.destroy();
+                clientRef.current = null;
+            }
+        };
+    }, [isProviderManaged]);
+    return (React.createElement(GrainContext.Provider, { value: { client: activeClient, isProviderManaged } }, children));
+}
+//# sourceMappingURL=GrainProvider.js.map

package/dist/esm/react/GrainProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrainProvider.js","sourceRoot":"","sources":["../../../src/react/GrainProvider.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGzC,MAAM,UAAU,aAAa,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAsB;IAC5E,iBAAiB;IACjB,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,kEAAkE;YAClE,+EAA+E,CAChF,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,gEAAgE;YAChE,oGAAoG,CACrG,CAAC;IACJ,CAAC;IAED,MAAM,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAwB,IAAI,CAAC,CAAC;IAE5D,0CAA0C;IAC1C,IAAI,iBAAiB,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,MAAM,EAAE,CAAC;QACtD,SAAS,CAAC,OAAO,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;IACjD,CAAC;IAED,kCAAkC;IAClC,MAAM,YAAY,GAAG,MAAM,IAAI,SAAS,CAAC,OAAO,CAAC;IAEjD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IAED,yDAAyD;IACzD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,OAAO,GAAG,EAAE;YACV,IAAI,iBAAiB,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;gBAC3C,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;gBAC5B,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;YAC3B,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAExB,OAAO,CACL,oBAAC,YAAY,CAAC,QAAQ,IAAC,KAAK,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,iBAAiB,EAAE,IACtE,QAAQ,CACa,CACzB,CAAC;AACJ,CAAC"}

package/dist/esm/react/context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * React context for Grain Analytics
+ */
+import * as React from 'react';
+import type { GrainAnalytics } from '../index';
+export interface GrainContextValue {
+    client: GrainAnalytics;
+    isProviderManaged: boolean;
+}
+export declare const GrainContext: React.Context<GrainContextValue | null>;
+//# sourceMappingURL=context.d.ts.map

package/dist/esm/react/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/react/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,cAAc,CAAC;IACvB,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,eAAO,MAAM,YAAY,yCAAsD,CAAC"}

package/dist/esm/react/context.js

@@ -0,0 +1,7 @@
+/**
+ * React context for Grain Analytics
+ */
+import * as React from 'react';
+export const GrainContext = React.createContext(null);
+GrainContext.displayName = 'GrainContext';
+//# sourceMappingURL=context.js.map

package/dist/esm/react/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/react/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAQ/B,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAA2B,IAAI,CAAC,CAAC;AAEhF,YAAY,CAAC,WAAW,GAAG,cAAc,CAAC"}

package/dist/esm/react/hooks/useAllConfigs.d.ts

@@ -0,0 +1,8 @@
+/**
+ * useAllConfigs - Get all configurations with automatic updates
+ *
+ * Returns all configs as a reactive object with cache-first strategy.
+ */
+import type { UseAllConfigsOptions, UseAllConfigsResult } from '../types';
+export declare function useAllConfigs(options?: UseAllConfigsOptions): UseAllConfigsResult;
+//# sourceMappingURL=useAllConfigs.d.ts.map

package/dist/esm/react/hooks/useAllConfigs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAllConfigs.d.ts","sourceRoot":"","sources":["../../../../src/react/hooks/useAllConfigs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE1E,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,mBAAmB,CA4ErF"}

package/dist/esm/react/hooks/useAllConfigs.js

@@ -0,0 +1,76 @@
+/**
+ * useAllConfigs - Get all configurations with automatic updates
+ *
+ * Returns all configs as a reactive object with cache-first strategy.
+ */
+import * as React from 'react';
+import { useGrainAnalytics } from './useGrainAnalytics';
+export function useAllConfigs(options = {}) {
+    const client = useGrainAnalytics();
+    // Get initial configs from cache/defaults (synchronous, instant)
+    const [configs, setConfigs] = React.useState(() => client.getAllConfigs());
+    const [isRefreshing, setIsRefreshing] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const isMountedRef = React.useRef(true);
+    // Fetch fresh configs from API
+    const fetchConfigs = React.useCallback(async () => {
+        if (!isMountedRef.current)
+            return;
+        setIsRefreshing(true);
+        setError(null);
+        try {
+            const response = await client.fetchConfig({
+                immediateKeys: options.immediateKeys || [],
+                properties: options.properties,
+                forceRefresh: options.forceRefresh,
+            });
+            if (isMountedRef.current && response) {
+                setConfigs(response.configurations);
+            }
+        }
+        catch (err) {
+            if (isMountedRef.current) {
+                setError(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        finally {
+            if (isMountedRef.current) {
+                setIsRefreshing(false);
+            }
+        }
+    }, [client, options.immediateKeys, options.properties, options.forceRefresh]);
+    // Manual refresh function
+    const refresh = React.useCallback(async () => {
+        await fetchConfigs();
+    }, [fetchConfigs]);
+    // Background fetch on mount and when options change
+    React.useEffect(() => {
+        fetchConfigs();
+    }, [fetchConfigs]);
+    // Subscribe to config changes
+    React.useEffect(() => {
+        const listener = (configurations) => {
+            if (isMountedRef.current) {
+                setConfigs(configurations);
+            }
+        };
+        client.addConfigChangeListener(listener);
+        return () => {
+            client.removeConfigChangeListener(listener);
+        };
+    }, [client]);
+    // Track mount state
+    React.useEffect(() => {
+        isMountedRef.current = true;
+        return () => {
+            isMountedRef.current = false;
+        };
+    }, []);
+    return {
+        configs,
+        isRefreshing,
+        error,
+        refresh,
+    };
+}
+//# sourceMappingURL=useAllConfigs.js.map

package/dist/esm/react/hooks/useAllConfigs.js.map

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

package/dist/esm/react/hooks/useConfig.d.ts

@@ -0,0 +1,9 @@
+/**
+ * useConfig - Cache-first config access with automatic background refresh
+ *
+ * Returns cached/default value immediately, fetches fresh data in background,
+ * and automatically updates when configuration changes.
+ */
+import type { UseConfigOptions, UseConfigResult } from '../types';
+export declare function useConfig(key: string, options?: UseConfigOptions): UseConfigResult;
+//# sourceMappingURL=useConfig.d.ts.map

package/dist/esm/react/hooks/useConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConfig.d.ts","sourceRoot":"","sources":["../../../../src/react/hooks/useConfig.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAElE,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA+EtF"}

package/dist/esm/react/hooks/useConfig.js

@@ -0,0 +1,80 @@
+/**
+ * useConfig - Cache-first config access with automatic background refresh
+ *
+ * Returns cached/default value immediately, fetches fresh data in background,
+ * and automatically updates when configuration changes.
+ */
+import * as React from 'react';
+import { useGrainAnalytics } from './useGrainAnalytics';
+export function useConfig(key, options = {}) {
+    const client = useGrainAnalytics();
+    // Get initial value from cache/defaults (synchronous, instant)
+    const [value, setValue] = React.useState(() => client.getConfig(key));
+    const [isRefreshing, setIsRefreshing] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const isMountedRef = React.useRef(true);
+    // Fetch fresh config from API
+    const fetchConfig = React.useCallback(async () => {
+        if (!isMountedRef.current)
+            return;
+        setIsRefreshing(true);
+        setError(null);
+        try {
+            const response = await client.fetchConfig({
+                immediateKeys: options.immediateKeys || [key],
+                properties: options.properties,
+                forceRefresh: options.forceRefresh,
+            });
+            if (isMountedRef.current && response) {
+                const newValue = response.configurations[key];
+                if (newValue !== undefined) {
+                    setValue(newValue);
+                }
+            }
+        }
+        catch (err) {
+            if (isMountedRef.current) {
+                setError(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        finally {
+            if (isMountedRef.current) {
+                setIsRefreshing(false);
+            }
+        }
+    }, [client, key, options.immediateKeys, options.properties, options.forceRefresh]);
+    // Manual refresh function
+    const refresh = React.useCallback(async () => {
+        await fetchConfig();
+    }, [fetchConfig]);
+    // Background fetch on mount and when key/options change
+    React.useEffect(() => {
+        fetchConfig();
+    }, [fetchConfig]);
+    // Subscribe to config changes
+    React.useEffect(() => {
+        const listener = (configurations) => {
+            if (isMountedRef.current && configurations[key] !== undefined) {
+                setValue(configurations[key]);
+            }
+        };
+        client.addConfigChangeListener(listener);
+        return () => {
+            client.removeConfigChangeListener(listener);
+        };
+    }, [client, key]);
+    // Track mount state
+    React.useEffect(() => {
+        isMountedRef.current = true;
+        return () => {
+            isMountedRef.current = false;
+        };
+    }, []);
+    return {
+        value,
+        isRefreshing,
+        error,
+        refresh,
+    };
+}
+//# sourceMappingURL=useConfig.js.map

package/dist/esm/react/hooks/useConfig.js.map

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

package/dist/esm/react/hooks/useGrainAnalytics.d.ts

@@ -0,0 +1,6 @@
+/**
+ * useGrainAnalytics - Access the GrainAnalytics client from context
+ */
+import type { GrainAnalytics } from '../../index';
+export declare function useGrainAnalytics(): GrainAnalytics;
+//# sourceMappingURL=useGrainAnalytics.d.ts.map

package/dist/esm/react/hooks/useGrainAnalytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGrainAnalytics.d.ts","sourceRoot":"","sources":["../../../../src/react/hooks/useGrainAnalytics.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,wBAAgB,iBAAiB,IAAI,cAAc,CAWlD"}

package/dist/esm/react/hooks/useGrainAnalytics.js

@@ -0,0 +1,14 @@
+/**
+ * useGrainAnalytics - Access the GrainAnalytics client from context
+ */
+import * as React from 'react';
+import { GrainContext } from '../context';
+export function useGrainAnalytics() {
+    const context = React.useContext(GrainContext);
+    if (!context) {
+        throw new Error('useGrainAnalytics must be used within a GrainProvider. ' +
+            'Wrap your component tree with <GrainProvider client={client}> or <GrainProvider config={{...}}>');
+    }
+    return context.client;
+}
+//# sourceMappingURL=useGrainAnalytics.js.map

package/dist/esm/react/hooks/useGrainAnalytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGrainAnalytics.js","sourceRoot":"","sources":["../../../../src/react/hooks/useGrainAnalytics.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,MAAM,UAAU,iBAAiB;IAC/B,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;IAE/C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,yDAAyD;YACzD,iGAAiG,CAClG,CAAC;IACJ,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,CAAC;AACxB,CAAC"}

package/dist/esm/react/hooks/useTrack.d.ts

@@ -0,0 +1,9 @@
+/**
+ * useTrack - Get a stable, memoized track function
+ *
+ * Returns a track function that doesn't cause re-renders when passed to child components.
+ * Prevents unnecessary re-renders compared to using useCallback.
+ */
+import type { TrackFunction } from '../types';
+export declare function useTrack(): TrackFunction;
+//# sourceMappingURL=useTrack.d.ts.map

package/dist/esm/react/hooks/useTrack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTrack.d.ts","sourceRoot":"","sources":["../../../../src/react/hooks/useTrack.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,wBAAgB,QAAQ,IAAI,aAAa,CAYxC"}

package/dist/esm/react/hooks/useTrack.js

@@ -0,0 +1,17 @@
+/**
+ * useTrack - Get a stable, memoized track function
+ *
+ * Returns a track function that doesn't cause re-renders when passed to child components.
+ * Prevents unnecessary re-renders compared to using useCallback.
+ */
+import * as React from 'react';
+import { useGrainAnalytics } from './useGrainAnalytics';
+export function useTrack() {
+    const client = useGrainAnalytics();
+    // Create stable track function that won't change across renders
+    const track = React.useCallback(async (eventName, properties, options) => {
+        await client.track(eventName, properties, options);
+    }, [client]);
+    return track;
+}
+//# sourceMappingURL=useTrack.js.map

package/dist/esm/react/hooks/useTrack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTrack.js","sourceRoot":"","sources":["../../../../src/react/hooks/useTrack.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGxD,MAAM,UAAU,QAAQ;IACtB,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IAEnC,gEAAgE;IAChE,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAC7B,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE;QACvC,MAAM,MAAM,CAAC,KAAK,CAAC,SAAS,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IACrD,CAAC,EACD,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/esm/react/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Grain Analytics React Hooks
+ *
+ * React integration for @grainql/analytics-web
+ *
+ * @example
+ * ```tsx
+ * import { GrainProvider, useConfig, useTrack } from '@grainql/analytics-web/react';
+ *
+ * // Pattern 1: Provider-managed client
+ * <GrainProvider config={{ tenantId: 'xxx' }}>
+ *   <App />
+ * </GrainProvider>
+ *
+ * // Pattern 2: External client
+ * const grain = new GrainAnalytics({ tenantId: 'xxx' });
+ * <GrainProvider client={grain}>
+ *   <App />
+ * </GrainProvider>
+ *
+ * // Use hooks in components
+ * function MyComponent() {
+ *   const { value } = useConfig('hero_variant');
+ *   const track = useTrack();
+ *
+ *   return <button onClick={() => track('clicked')}>Click</button>;
+ * }
+ * ```
+ */
+export { GrainProvider } from './GrainProvider';
+export { useGrainAnalytics } from './hooks/useGrainAnalytics';
+export { useConfig } from './hooks/useConfig';
+export { useAllConfigs } from './hooks/useAllConfigs';
+export { useTrack } from './hooks/useTrack';
+export type { GrainProviderProps, UseConfigOptions, UseConfigResult, UseAllConfigsOptions, UseAllConfigsResult, TrackFunction, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,GACd,MAAM,SAAS,CAAC"}

package/dist/esm/react/index.js

@@ -0,0 +1,37 @@
+/**
+ * Grain Analytics React Hooks
+ *
+ * React integration for @grainql/analytics-web
+ *
+ * @example
+ * ```tsx
+ * import { GrainProvider, useConfig, useTrack } from '@grainql/analytics-web/react';
+ *
+ * // Pattern 1: Provider-managed client
+ * <GrainProvider config={{ tenantId: 'xxx' }}>
+ *   <App />
+ * </GrainProvider>
+ *
+ * // Pattern 2: External client
+ * const grain = new GrainAnalytics({ tenantId: 'xxx' });
+ * <GrainProvider client={grain}>
+ *   <App />
+ * </GrainProvider>
+ *
+ * // Use hooks in components
+ * function MyComponent() {
+ *   const { value } = useConfig('hero_variant');
+ *   const track = useTrack();
+ *
+ *   return <button onClick={() => track('clicked')}>Click</button>;
+ * }
+ * ```
+ */
+// Provider
+export { GrainProvider } from './GrainProvider';
+// Hooks
+export { useGrainAnalytics } from './hooks/useGrainAnalytics';
+export { useConfig } from './hooks/useConfig';
+export { useAllConfigs } from './hooks/useAllConfigs';
+export { useTrack } from './hooks/useTrack';
+//# sourceMappingURL=index.js.map

package/dist/esm/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,QAAQ;AACR,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/esm/react/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * React-specific types for Grain Analytics
+ */
+import type { GrainAnalytics, GrainConfig, SendEventOptions } from '../index';
+export interface GrainProviderProps {
+    children: React.ReactNode;
+    client?: GrainAnalytics;
+    config?: GrainConfig;
+}
+export interface UseConfigOptions {
+    forceRefresh?: boolean;
+    immediateKeys?: string[];
+    properties?: Record<string, string>;
+}
+export interface UseConfigResult {
+    value: string | undefined;
+    isRefreshing: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+export interface UseAllConfigsOptions {
+    forceRefresh?: boolean;
+    immediateKeys?: string[];
+    properties?: Record<string, string>;
+}
+export interface UseAllConfigsResult {
+    configs: Record<string, string>;
+    isRefreshing: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+}
+export type TrackFunction = (eventName: string, properties?: Record<string, unknown>, options?: SendEventOptions) => Promise<void>;
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/react/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/react/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,MAAM,aAAa,GAAG,CAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,CAAC,EAAE,gBAAgB,KACvB,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/esm/react/types.js

@@ -0,0 +1,5 @@
+/**
+ * React-specific types for Grain Analytics
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/react/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/react/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/index.global.dev.js

@@ -1,4 +1,4 @@
-/* Grain Analytics Web SDK v1.7.4 | MIT License | Development Build */
+/* Grain Analytics Web SDK v2.0.0 | MIT License | Development Build */
 "use strict";
 var Grain = (() => {
   var __defProp = Object.defineProperty;