@grainql/analytics-web 1.7.4 → 2.1.0

package/dist/react/react/components/ConsentBanner.mjs

@@ -0,0 +1,75 @@
+/**
+ * ConsentBanner - Glassmorphic consent popup for GDPR compliance
+ * Follows Grain Design System specifications
+ */
+import * as React from 'react';
+import { useGrainAnalytics } from '../hooks/useGrainAnalytics';
+export function ConsentBanner({ position = 'bottom', theme = 'glass', customText, onAccept, onDecline, showPreferences = false, privacyPolicyUrl, }) {
+    const client = useGrainAnalytics();
+    const [visible, setVisible] = React.useState(false);
+    const [showPreferencesModal, setShowPreferencesModal] = React.useState(false);
+    React.useEffect(() => {
+        if (!client)
+            return;
+        // Check if user has already made a consent decision
+        const consentState = client.getConsentState();
+        if (!consentState) {
+            setVisible(true);
+        }
+    }, [client]);
+    const handleAccept = () => {
+        if (client) {
+            client.grantConsent(['necessary', 'analytics', 'functional']);
+        }
+        setVisible(false);
+        onAccept?.();
+    };
+    const handleDecline = () => {
+        if (client) {
+            client.revokeConsent();
+        }
+        setVisible(false);
+        onDecline?.();
+    };
+    const handleEscape = (e) => {
+        if (e.key === 'Escape') {
+            handleDecline();
+        }
+    };
+    if (!visible)
+        return null;
+    const defaultText = customText ||
+        "We use cookies and similar technologies to improve your experience. By accepting, you consent to our use of analytics and functional cookies.";
+    // Position styles
+    const positionStyles = {
+        top: 'top-4 left-4 right-4',
+        bottom: 'bottom-4 left-4 right-4',
+        center: 'top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2',
+    };
+    // Theme styles (glassmorphic by default)
+    const themeStyles = {
+        light: 'bg-white/95 border-gray-200 text-gray-900',
+        dark: 'bg-zinc-900/95 border-zinc-800 text-zinc-100',
+        glass: 'bg-zinc-950/40 backdrop-blur-xl border-zinc-800/40 text-zinc-100',
+    };
+    const buttonAcceptStyles = {
+        light: 'bg-blue-600 hover:bg-blue-700 text-white',
+        dark: 'bg-emerald-600 hover:bg-emerald-700 text-white',
+        glass: 'bg-emerald-600 hover:bg-emerald-700 text-white',
+    };
+    const buttonDeclineStyles = {
+        light: 'bg-gray-200 hover:bg-gray-300 text-gray-800',
+        dark: 'bg-zinc-800 hover:bg-zinc-700 text-zinc-200',
+        glass: 'bg-zinc-900/60 hover:bg-zinc-800/60 text-zinc-300 border border-zinc-800/60',
+    };
+    return (React.createElement("div", { className: `fixed z-50 max-w-2xl ${positionStyles[position]}`, onKeyDown: handleEscape, role: "dialog", "aria-labelledby": "consent-title", "aria-describedby": "consent-description" },
+        React.createElement("div", { className: `rounded-lg shadow-2xl border p-6 transition-all ${themeStyles[theme]}` },
+            React.createElement("h2", { id: "consent-title", className: "text-lg font-semibold mb-2" }, "Cookie Consent"),
+            React.createElement("p", { id: "consent-description", className: "text-sm opacity-80 mb-4" }, defaultText),
+            privacyPolicyUrl && (React.createElement("a", { href: privacyPolicyUrl, target: "_blank", rel: "noopener noreferrer", className: "text-sm underline opacity-70 hover:opacity-100 transition-opacity block mb-4" }, "Read our Privacy Policy")),
+            React.createElement("div", { className: "flex flex-wrap gap-2" },
+                React.createElement("button", { onClick: handleAccept, className: `px-4 py-2 rounded-lg font-medium transition-all ${buttonAcceptStyles[theme]}`, "aria-label": "Accept cookies" }, "Accept All"),
+                React.createElement("button", { onClick: handleDecline, className: `px-4 py-2 rounded-lg font-medium transition-all ${buttonDeclineStyles[theme]}`, "aria-label": "Decline cookies" }, "Decline"),
+                showPreferences && (React.createElement("button", { onClick: () => setShowPreferencesModal(true), className: `px-4 py-2 rounded-lg font-medium transition-all ${buttonDeclineStyles[theme]}`, "aria-label": "Manage preferences" }, "Manage Preferences")),
+                React.createElement("kbd", { className: "ml-auto px-2 py-1 bg-zinc-900/50 border border-zinc-800 rounded text-[10px] font-mono self-center" }, "ESC")))));
+}

package/dist/react/react/components/CookieNotice.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CookieNotice - Simple cookie notification banner
+ */
+import * as React from 'react';
+export interface CookieNoticeProps {
+    message?: string;
+    privacyPolicyUrl?: string;
+    onDismiss?: () => void;
+    position?: 'top' | 'bottom';
+}
+export declare function CookieNotice({ message, privacyPolicyUrl, onDismiss, position, }: CookieNoticeProps): React.JSX.Element;
+//# sourceMappingURL=CookieNotice.d.ts.map

package/dist/react/react/components/CookieNotice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CookieNotice.d.ts","sourceRoot":"","sources":["../../../../src/react/components/CookieNotice.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;CAC7B;AAED,wBAAgB,YAAY,CAAC,EAC3B,OAAO,EACP,gBAAgB,EAChB,SAAS,EACT,QAAmB,GACpB,EAAE,iBAAiB,qBA6CnB"}

package/dist/react/react/components/CookieNotice.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * CookieNotice - Simple cookie notification banner
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CookieNotice = CookieNotice;
+const React = require("react");
+function CookieNotice({ message, privacyPolicyUrl, onDismiss, position = 'bottom', }) {
+    const [visible, setVisible] = React.useState(true);
+    const defaultMessage = message ||
+        "This website uses cookies to enhance your experience.";
+    const handleDismiss = () => {
+        setVisible(false);
+        onDismiss?.();
+    };
+    if (!visible)
+        return null;
+    const positionStyles = position === 'top' ? 'top-0' : 'bottom-0';
+    return (React.createElement("div", { className: `fixed ${positionStyles} left-0 right-0 z-40` },
+        React.createElement("div", { className: "bg-zinc-950/90 backdrop-blur-sm border-t border-zinc-800/40 px-4 py-3" },
+            React.createElement("div", { className: "max-w-7xl mx-auto flex items-center justify-between gap-4" },
+                React.createElement("p", { className: "text-sm text-zinc-300" },
+                    defaultMessage,
+                    privacyPolicyUrl && (React.createElement(React.Fragment, null,
+                        ' ',
+                        React.createElement("a", { href: privacyPolicyUrl, target: "_blank", rel: "noopener noreferrer", className: "underline opacity-70 hover:opacity-100 transition-opacity" }, "Learn more")))),
+                React.createElement("button", { onClick: handleDismiss, className: "px-3 py-1 bg-zinc-800/60 hover:bg-zinc-700/60 text-zinc-300 rounded text-sm font-medium transition-all flex-shrink-0" }, "Dismiss")))));
+}

package/dist/react/react/components/CookieNotice.mjs

@@ -0,0 +1,25 @@
+/**
+ * CookieNotice - Simple cookie notification banner
+ */
+import * as React from 'react';
+export function CookieNotice({ message, privacyPolicyUrl, onDismiss, position = 'bottom', }) {
+    const [visible, setVisible] = React.useState(true);
+    const defaultMessage = message ||
+        "This website uses cookies to enhance your experience.";
+    const handleDismiss = () => {
+        setVisible(false);
+        onDismiss?.();
+    };
+    if (!visible)
+        return null;
+    const positionStyles = position === 'top' ? 'top-0' : 'bottom-0';
+    return (React.createElement("div", { className: `fixed ${positionStyles} left-0 right-0 z-40` },
+        React.createElement("div", { className: "bg-zinc-950/90 backdrop-blur-sm border-t border-zinc-800/40 px-4 py-3" },
+            React.createElement("div", { className: "max-w-7xl mx-auto flex items-center justify-between gap-4" },
+                React.createElement("p", { className: "text-sm text-zinc-300" },
+                    defaultMessage,
+                    privacyPolicyUrl && (React.createElement(React.Fragment, null,
+                        ' ',
+                        React.createElement("a", { href: privacyPolicyUrl, target: "_blank", rel: "noopener noreferrer", className: "underline opacity-70 hover:opacity-100 transition-opacity" }, "Learn more")))),
+                React.createElement("button", { onClick: handleDismiss, className: "px-3 py-1 bg-zinc-800/60 hover:bg-zinc-700/60 text-zinc-300 rounded text-sm font-medium transition-all flex-shrink-0" }, "Dismiss")))));
+}

package/dist/react/react/components/PrivacyPreferenceCenter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * PrivacyPreferenceCenter - Detailed preference management modal
+ * Follows Grain Design System specifications
+ */
+import * as React from 'react';
+export interface PrivacyPreferenceCenterProps {
+    isOpen: boolean;
+    onClose: () => void;
+    onSave?: (categories: string[]) => void;
+}
+export declare function PrivacyPreferenceCenter({ isOpen, onClose, onSave, }: PrivacyPreferenceCenterProps): React.JSX.Element;
+//# sourceMappingURL=PrivacyPreferenceCenter.d.ts.map

package/dist/react/react/components/PrivacyPreferenceCenter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrivacyPreferenceCenter.d.ts","sourceRoot":"","sources":["../../../../src/react/components/PrivacyPreferenceCenter.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACzC;AA8BD,wBAAgB,uBAAuB,CAAC,EACtC,MAAM,EACN,OAAO,EACP,MAAM,GACP,EAAE,4BAA4B,qBAkH9B"}

package/dist/react/react/components/PrivacyPreferenceCenter.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * PrivacyPreferenceCenter - Detailed preference management modal
+ * Follows Grain Design System specifications
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrivacyPreferenceCenter = PrivacyPreferenceCenter;
+const React = require("react");
+const useGrainAnalytics_1 = require("../hooks/useGrainAnalytics");
+const CATEGORIES = [
+    {
+        id: 'necessary',
+        name: 'Necessary',
+        description: 'Essential for the website to function properly. Cannot be disabled.',
+        required: true,
+    },
+    {
+        id: 'analytics',
+        name: 'Analytics',
+        description: 'Help us understand how visitors interact with our website.',
+        required: false,
+    },
+    {
+        id: 'functional',
+        name: 'Functional',
+        description: 'Enable enhanced functionality and personalization.',
+        required: false,
+    },
+];
+function PrivacyPreferenceCenter({ isOpen, onClose, onSave, }) {
+    const client = (0, useGrainAnalytics_1.useGrainAnalytics)();
+    const [selectedCategories, setSelectedCategories] = React.useState(['necessary']);
+    React.useEffect(() => {
+        if (!client)
+            return;
+        const consentState = client.getConsentState();
+        if (consentState) {
+            setSelectedCategories(consentState.categories);
+        }
+    }, [client, isOpen]);
+    const handleToggle = (categoryId, required) => {
+        if (required)
+            return; // Cannot toggle required categories
+        setSelectedCategories((prev) => prev.includes(categoryId)
+            ? prev.filter((id) => id !== categoryId)
+            : [...prev, categoryId]);
+    };
+    const handleSave = () => {
+        if (client) {
+            if (selectedCategories.length > 0) {
+                client.grantConsent(selectedCategories);
+            }
+            else {
+                client.revokeConsent();
+            }
+        }
+        onSave?.(selectedCategories);
+        onClose();
+    };
+    const handleEscape = (e) => {
+        if (e.key === 'Escape') {
+            onClose();
+        }
+    };
+    if (!isOpen)
+        return null;
+    return (React.createElement("div", { className: "fixed inset-0 z-50 flex items-center justify-center", onKeyDown: handleEscape, role: "dialog", "aria-labelledby": "preferences-title", "aria-modal": "true" },
+        React.createElement("div", { className: "fixed inset-0 bg-zinc-950/80 backdrop-blur-sm", onClick: onClose }),
+        React.createElement("div", { className: "relative bg-zinc-950/95 border border-zinc-800/60 backdrop-blur-xl rounded-lg shadow-2xl max-w-2xl w-full mx-4 p-6" },
+            React.createElement("h2", { id: "preferences-title", className: "text-xl font-semibold text-zinc-100 mb-4" }, "Privacy Preferences"),
+            React.createElement("div", { className: "space-y-4 mb-6" }, CATEGORIES.map((category) => (React.createElement("div", { key: category.id, className: "p-4 bg-zinc-900/40 border border-zinc-800/40 rounded-lg" },
+                React.createElement("div", { className: "flex items-start justify-between" },
+                    React.createElement("div", { className: "flex-1" },
+                        React.createElement("h3", { className: "font-medium text-zinc-200 mb-1" },
+                            category.name,
+                            category.required && (React.createElement("span", { className: "ml-2 text-xs text-emerald-500" }, "(Required)"))),
+                        React.createElement("p", { className: "text-sm text-zinc-400" }, category.description)),
+                    React.createElement("label", { className: "relative inline-flex items-center cursor-pointer" },
+                        React.createElement("input", { type: "checkbox", checked: selectedCategories.includes(category.id), onChange: () => handleToggle(category.id, category.required), disabled: category.required, className: "sr-only peer" }),
+                        React.createElement("div", { className: "w-11 h-6 bg-zinc-700 peer-focus:outline-none rounded-full peer peer-checked:after:translate-x-full peer-checked:after:border-white after:content-[''] after:absolute after:top-[2px] after:left-[2px] after:bg-white after:rounded-full after:h-5 after:w-5 after:transition-all peer-checked:bg-emerald-600" }))))))),
+            React.createElement("div", { className: "flex justify-end gap-2" },
+                React.createElement("button", { onClick: onClose, className: "px-4 py-2 bg-zinc-900/60 hover:bg-zinc-800/60 text-zinc-300 border border-zinc-800/60 rounded-lg font-medium transition-all" },
+                    "Cancel",
+                    React.createElement("kbd", { className: "ml-2 px-2 py-0.5 bg-zinc-900/50 border border-zinc-800 rounded text-[10px] font-mono" }, "ESC")),
+                React.createElement("button", { onClick: handleSave, className: "px-4 py-2 bg-emerald-600 hover:bg-emerald-700 text-white rounded-lg font-medium transition-all" }, "Save Preferences")))));
+}

package/dist/react/react/components/PrivacyPreferenceCenter.mjs

@@ -0,0 +1,83 @@
+/**
+ * PrivacyPreferenceCenter - Detailed preference management modal
+ * Follows Grain Design System specifications
+ */
+import * as React from 'react';
+import { useGrainAnalytics } from '../hooks/useGrainAnalytics';
+const CATEGORIES = [
+    {
+        id: 'necessary',
+        name: 'Necessary',
+        description: 'Essential for the website to function properly. Cannot be disabled.',
+        required: true,
+    },
+    {
+        id: 'analytics',
+        name: 'Analytics',
+        description: 'Help us understand how visitors interact with our website.',
+        required: false,
+    },
+    {
+        id: 'functional',
+        name: 'Functional',
+        description: 'Enable enhanced functionality and personalization.',
+        required: false,
+    },
+];
+export function PrivacyPreferenceCenter({ isOpen, onClose, onSave, }) {
+    const client = useGrainAnalytics();
+    const [selectedCategories, setSelectedCategories] = React.useState(['necessary']);
+    React.useEffect(() => {
+        if (!client)
+            return;
+        const consentState = client.getConsentState();
+        if (consentState) {
+            setSelectedCategories(consentState.categories);
+        }
+    }, [client, isOpen]);
+    const handleToggle = (categoryId, required) => {
+        if (required)
+            return; // Cannot toggle required categories
+        setSelectedCategories((prev) => prev.includes(categoryId)
+            ? prev.filter((id) => id !== categoryId)
+            : [...prev, categoryId]);
+    };
+    const handleSave = () => {
+        if (client) {
+            if (selectedCategories.length > 0) {
+                client.grantConsent(selectedCategories);
+            }
+            else {
+                client.revokeConsent();
+            }
+        }
+        onSave?.(selectedCategories);
+        onClose();
+    };
+    const handleEscape = (e) => {
+        if (e.key === 'Escape') {
+            onClose();
+        }
+    };
+    if (!isOpen)
+        return null;
+    return (React.createElement("div", { className: "fixed inset-0 z-50 flex items-center justify-center", onKeyDown: handleEscape, role: "dialog", "aria-labelledby": "preferences-title", "aria-modal": "true" },
+        React.createElement("div", { className: "fixed inset-0 bg-zinc-950/80 backdrop-blur-sm", onClick: onClose }),
+        React.createElement("div", { className: "relative bg-zinc-950/95 border border-zinc-800/60 backdrop-blur-xl rounded-lg shadow-2xl max-w-2xl w-full mx-4 p-6" },
+            React.createElement("h2", { id: "preferences-title", className: "text-xl font-semibold text-zinc-100 mb-4" }, "Privacy Preferences"),
+            React.createElement("div", { className: "space-y-4 mb-6" }, CATEGORIES.map((category) => (React.createElement("div", { key: category.id, className: "p-4 bg-zinc-900/40 border border-zinc-800/40 rounded-lg" },
+                React.createElement("div", { className: "flex items-start justify-between" },
+                    React.createElement("div", { className: "flex-1" },
+                        React.createElement("h3", { className: "font-medium text-zinc-200 mb-1" },
+                            category.name,
+                            category.required && (React.createElement("span", { className: "ml-2 text-xs text-emerald-500" }, "(Required)"))),
+                        React.createElement("p", { className: "text-sm text-zinc-400" }, category.description)),
+                    React.createElement("label", { className: "relative inline-flex items-center cursor-pointer" },
+                        React.createElement("input", { type: "checkbox", checked: selectedCategories.includes(category.id), onChange: () => handleToggle(category.id, category.required), disabled: category.required, className: "sr-only peer" }),
+                        React.createElement("div", { className: "w-11 h-6 bg-zinc-700 peer-focus:outline-none rounded-full peer peer-checked:after:translate-x-full peer-checked:after:border-white after:content-[''] after:absolute after:top-[2px] after:left-[2px] after:bg-white after:rounded-full after:h-5 after:w-5 after:transition-all peer-checked:bg-emerald-600" }))))))),
+            React.createElement("div", { className: "flex justify-end gap-2" },
+                React.createElement("button", { onClick: onClose, className: "px-4 py-2 bg-zinc-900/60 hover:bg-zinc-800/60 text-zinc-300 border border-zinc-800/60 rounded-lg font-medium transition-all" },
+                    "Cancel",
+                    React.createElement("kbd", { className: "ml-2 px-2 py-0.5 bg-zinc-900/50 border border-zinc-800 rounded text-[10px] font-mono" }, "ESC")),
+                React.createElement("button", { onClick: handleSave, className: "px-4 py-2 bg-emerald-600 hover:bg-emerald-700 text-white rounded-lg font-medium transition-all" }, "Save Preferences")))));
+}

package/dist/react/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>;
+//# sourceMappingURL=context.d.ts.map

package/dist/react/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,kCAAsD,CAAC"}

package/dist/react/react/context.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * React context for Grain Analytics
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrainContext = void 0;
+const React = require("react");
+exports.GrainContext = React.createContext(null);
+exports.GrainContext.displayName = 'GrainContext';

package/dist/react/react/context.mjs

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

package/dist/react/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/react/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/react/react/hooks/useAllConfigs.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * useAllConfigs - Get all configurations with automatic updates
+ *
+ * Returns all configs as a reactive object with cache-first strategy.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAllConfigs = useAllConfigs;
+const React = require("react");
+const useGrainAnalytics_1 = require("./useGrainAnalytics");
+function useAllConfigs(options = {}) {
+    const client = (0, useGrainAnalytics_1.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,
+    };
+}

package/dist/react/react/hooks/useAllConfigs.mjs

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

package/dist/react/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/react/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/react/react/hooks/useConfig.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useConfig = useConfig;
+const React = require("react");
+const useGrainAnalytics_1 = require("./useGrainAnalytics");
+function useConfig(key, options = {}) {
+    const client = (0, useGrainAnalytics_1.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,
+    };
+}