@databuddy/sdk 2.3.1 → 2.3.21

package/dist/react/index.d.ts

@@ -1,9 +1,7 @@
-import { D as DatabuddyConfig } from '../shared/@databuddy/sdk.CeYE_kaj.js';
-import * as react from 'react';
-import { ReactNode } from 'react';
-import * as jotai_vanilla_internals from 'jotai/vanilla/internals';
-import { d as FlagsConfig, c as FlagState } from '../shared/@databuddy/sdk.OK9Nbqlf.js';
-export { b as FlagResult, e as FlagsContext } from '../shared/@databuddy/sdk.OK9Nbqlf.js';
+import { D as DatabuddyConfig } from '../shared/@databuddy/sdk.BsF1xr6_.js';
+export { c as clear, f as flush, d as getAnonymousId, e as getSessionId, g as getTracker, h as getTrackingIds, j as getTrackingParams, i as isTrackerAvailable, t as track, b as trackError } from '../shared/@databuddy/sdk.BsF1xr6_.js';
+import React, { ReactNode } from 'react';
+import { F as FlagsConfig, a as FeatureState, b as FlagState, c as FlagsContext } from '../shared/@databuddy/sdk.B6nwxnPC.js';
 
 /**
  * React/Next.js component that injects the Databuddy tracking script.
@@ -56,18 +54,61 @@ export { b as FlagResult, e as FlagsContext } from '../shared/@databuddy/sdk.OK9
  */
 declare function Databuddy(props: DatabuddyConfig): null;
 
+/** biome-ignore-all lint/correctness/noUnusedImports: we need to import React to use the createContext function */
+
 interface FlagsProviderProps extends FlagsConfig {
     children: ReactNode;
 }
-declare function FlagsProvider({ children, ...config }: FlagsProviderProps): react.FunctionComponentElement<{
-    children?: ReactNode;
-    store?: jotai_vanilla_internals.INTERNAL_Store;
-}>;
-declare function useFlags(): {
-    isEnabled: (key: string) => FlagState;
-    fetchAllFlags: () => Promise<void> | undefined;
-    updateUser: (user: FlagsConfig["user"]) => void;
-    refresh: (forceClear?: boolean) => void;
-};
+/**
+ * Flags provider component
+ * Creates a manager instance and provides flag methods to children
+ */
+declare function FlagsProvider({ children, ...config }: FlagsProviderProps): React.JSX.Element;
+/**
+ * Access the full flags context
+ * @example
+ * const { isOn, getFlag, refresh } = useFlags();
+ */
+declare function useFlags(): FlagsContext;
+/**
+ * Get a flag's full state with loading/error handling
+ * @example
+ * const flag = useFlag("my-feature");
+ * if (flag.loading) return <Skeleton />;
+ * return flag.on ? <NewFeature /> : <OldFeature />;
+ */
+declare function useFlag(key: string): FlagState;
+/**
+ * Simple feature check - returns { on, loading, value, variant }
+ * @example
+ * const { on, loading } = useFeature("dark-mode");
+ * if (loading) return <Skeleton />;
+ * return on ? <DarkTheme /> : <LightTheme />;
+ */
+declare function useFeature(key: string): FeatureState;
+/**
+ * Boolean-only feature check with default value
+ * Useful for SSR-safe rendering where you need a boolean immediately
+ * @example
+ * const isDarkMode = useFeatureOn("dark-mode", false);
+ * return isDarkMode ? <DarkTheme /> : <LightTheme />;
+ */
+declare function useFeatureOn(key: string, defaultValue?: boolean): boolean;
+/**
+ * Get a flag's typed value
+ * @example
+ * const maxItems = useFlagValue("max-items", 10);
+ * const theme = useFlagValue<"light" | "dark">("theme", "light");
+ */
+declare function useFlagValue<T extends boolean | string | number = boolean>(key: string, defaultValue?: T): T;
+/**
+ * Get variant for A/B testing
+ * @example
+ * const variant = useVariant("checkout-experiment");
+ * if (variant === "control") return <OldCheckout />;
+ * if (variant === "treatment-a") return <NewCheckoutA />;
+ * return <NewCheckoutB />;
+ */
+declare function useVariant(key: string): string | undefined;
 
-export { Databuddy, FlagState, FlagsConfig, FlagsProvider, useFlags };
+export { Databuddy, FlagsProvider, useFeature, useFeatureOn, useFlag, useFlagValue, useFlags, useVariant };

package/dist/react/index.mjs

@@ -1,9 +1,11 @@
 'use client';
 
-import { i as isScriptInjected, c as createScript, B as BrowserFlagStorage, C as CoreFlagsManager, l as logger } from '../shared/@databuddy/sdk.ByNF_UxE.mjs';
-import { d as detectClientId } from '../shared/@databuddy/sdk.BUsPV0LH.mjs';
-import { createStore, atom, Provider, useAtom } from 'jotai';
-import { useRef, useEffect, createElement } from 'react';
+import { detectClientId } from '../core/index.mjs';
+export { clear, flush, getAnonymousId, getSessionId, getTracker, getTrackingIds, getTrackingParams, isTrackerAvailable, track, trackError } from '../core/index.mjs';
+import { i as isScriptInjected, c as createScript } from '../shared/@databuddy/sdk.C8vEu9Y4.mjs';
+import React, { useRef, useMemo, useEffect, useSyncExternalStore, createContext, useContext } from 'react';
+import { B as BrowserFlagStorage, C as CoreFlagsManager } from '../shared/@databuddy/sdk.D0dyEsAb.mjs';
+import { l as logger } from '../shared/@databuddy/sdk.DCKr2Zpd.mjs';
 
 function Databuddy(props) {
   const clientId = detectClientId(props.clientId);
@@ -22,101 +24,192 @@ function Databuddy(props) {
   return null;
 }
 
-const flagsStore = createStore();
-const managerAtom = atom(null);
-const memoryFlagsAtom = atom({});
+const FlagsReactContext = createContext(null);
+function createFlagState(result, isLoading, isPending) {
+  if (isPending) {
+    return {
+      on: false,
+      enabled: false,
+      status: "pending",
+      loading: true,
+      isLoading: true,
+      isReady: false
+    };
+  }
+  if (isLoading || !result) {
+    return {
+      on: false,
+      enabled: false,
+      status: "loading",
+      loading: true,
+      isLoading: true,
+      isReady: false
+    };
+  }
+  const status = result.reason === "ERROR" ? "error" : "ready";
+  return {
+    on: result.enabled,
+    enabled: result.enabled,
+    status,
+    loading: false,
+    isLoading: false,
+    isReady: true,
+    value: result.value,
+    variant: result.variant
+  };
+}
 function FlagsProvider({ children, ...config }) {
-  const managerRef = useRef(null);
-  useEffect(() => {
+  const storeRef = useRef({ flags: {}, isReady: false });
+  const listenersRef = useRef(/* @__PURE__ */ new Set());
+  const manager = useMemo(() => {
     const storage = config.skipStorage ? void 0 : new BrowserFlagStorage();
-    const manager = new CoreFlagsManager({
+    return new CoreFlagsManager({
       config,
       storage,
       onFlagsUpdate: (flags) => {
-        flagsStore.set(memoryFlagsAtom, flags);
+        storeRef.current = { ...storeRef.current, flags };
+        for (const listener of listenersRef.current) {
+          listener();
+        }
+      },
+      onReady: () => {
+        storeRef.current = { ...storeRef.current, isReady: true };
+        for (const listener of listenersRef.current) {
+          listener();
+        }
       }
     });
-    managerRef.current = manager;
-    flagsStore.set(managerAtom, manager);
-    return () => {
-      managerRef.current = null;
-      flagsStore.set(managerAtom, null);
-    };
-  }, [
-    config.clientId,
-    config.apiUrl,
-    config.user?.userId,
-    config.user?.email,
-    config.disabled,
-    config.debug,
-    config.skipStorage,
-    config.isPending,
-    config.autoFetch
-  ]);
+  }, [config.clientId]);
+  const prevConfigRef = useRef(config);
   useEffect(() => {
-    if (managerRef.current) {
-      managerRef.current.updateConfig(config);
+    const prevConfig = prevConfigRef.current;
+    const configChanged = prevConfig.apiUrl !== config.apiUrl || prevConfig.isPending !== config.isPending || prevConfig.user?.userId !== config.user?.userId || prevConfig.user?.email !== config.user?.email || prevConfig.environment !== config.environment || prevConfig.disabled !== config.disabled || prevConfig.autoFetch !== config.autoFetch || prevConfig.cacheTtl !== config.cacheTtl || prevConfig.staleTime !== config.staleTime;
+    if (configChanged) {
+      prevConfigRef.current = config;
+      manager.updateConfig(config);
     }
-  }, [
-    config.clientId,
-    config.apiUrl,
-    config.user?.userId,
-    config.user?.email,
-    config.disabled,
-    config.debug,
-    config.skipStorage,
-    config.isPending,
-    config.autoFetch
-  ]);
-  return createElement(Provider, { store: flagsStore }, children);
+  }, [manager, config]);
+  useEffect(() => {
+    return () => {
+      manager.destroy();
+    };
+  }, [manager]);
+  const subscribe = useMemo(
+    () => (callback) => {
+      listenersRef.current.add(callback);
+      return () => {
+        listenersRef.current.delete(callback);
+      };
+    },
+    []
+  );
+  const getSnapshot = useMemo(() => () => storeRef.current, []);
+  const store = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const contextValue = useMemo(
+    () => ({
+      // Cleaner API: getFlag returns FlagState
+      getFlag: (key) => {
+        const result = store.flags[key];
+        const managerState = manager.isEnabled(key);
+        return createFlagState(
+          result,
+          managerState.isLoading,
+          config.isPending ?? false
+        );
+      },
+      // Simple boolean check
+      isOn: (key) => {
+        const result = store.flags[key];
+        if (result) {
+          return result.enabled;
+        }
+        const state = manager.isEnabled(key);
+        return state.enabled;
+      },
+      // Get typed value
+      getValue: (key, defaultValue) => {
+        const result = store.flags[key];
+        if (result) {
+          return result.value;
+        }
+        return manager.getValue(key, defaultValue);
+      },
+      // Async fetch
+      fetchFlag: (key) => manager.getFlag(key),
+      fetchAllFlags: () => manager.fetchAllFlags(),
+      updateUser: (user) => manager.updateUser(user),
+      refresh: (forceClear = false) => manager.refresh(forceClear),
+      isReady: store.isReady,
+      // Deprecated: kept for backwards compatibility
+      isEnabled: (key) => {
+        const result = store.flags[key];
+        const managerState = manager.isEnabled(key);
+        return createFlagState(
+          result,
+          managerState.isLoading,
+          config.isPending ?? false
+        );
+      }
+    }),
+    [manager, store, config.isPending]
+  );
+  return /* @__PURE__ */ React.createElement(FlagsReactContext.Provider, { value: contextValue }, children);
 }
 function useFlags() {
-  const [manager] = useAtom(managerAtom, { store: flagsStore });
-  const [memoryFlags] = useAtom(memoryFlagsAtom, {
-    store: flagsStore
-  });
-  logger.debug("useFlags called with manager:", {
-    hasManager: !!manager,
-    memoryFlagsCount: Object.keys(memoryFlags).length,
-    memoryFlags: Object.keys(memoryFlags)
-  });
-  const isEnabled = (key) => {
-    if (!manager) {
-      return {
+  const context = useContext(FlagsReactContext);
+  if (!context) {
+    logger.warn("useFlags called outside FlagsProvider");
+    return {
+      isEnabled: () => createFlagState(void 0, false, false),
+      getFlag: () => createFlagState(void 0, false, false),
+      isOn: () => false,
+      getValue: (_key, defaultValue) => defaultValue ?? false,
+      fetchFlag: async () => ({
         enabled: false,
-        isLoading: false,
-        isReady: false
-      };
-    }
-    return manager.isEnabled(key);
-  };
-  const fetchAllFlags = () => {
-    if (!manager) {
-      logger.warn("No manager for bulk fetch");
-      return;
-    }
-    return manager.fetchAllFlags();
-  };
-  const updateUser = (user) => {
-    if (!manager) {
-      logger.warn("No manager for user update");
-      return;
-    }
-    manager.updateUser(user);
-  };
-  const refresh = (forceClear = false) => {
-    if (!manager) {
-      logger.warn("No manager for refresh");
-      return;
-    }
-    manager.refresh(forceClear);
-  };
+        value: false,
+        payload: null,
+        reason: "NO_PROVIDER"
+      }),
+      fetchAllFlags: async () => {
+      },
+      updateUser: () => {
+      },
+      refresh: async () => {
+      },
+      isReady: false
+    };
+  }
+  return context;
+}
+function useFlag(key) {
+  const { getFlag } = useFlags();
+  return getFlag(key);
+}
+function useFeature(key) {
+  const flag = useFlag(key);
   return {
-    isEnabled,
-    fetchAllFlags,
-    updateUser,
-    refresh
+    on: flag.on,
+    loading: flag.loading,
+    status: flag.status,
+    value: flag.value,
+    variant: flag.variant
   };
 }
+function useFeatureOn(key, defaultValue = false) {
+  const { isOn, isReady } = useFlags();
+  const flag = useFlag(key);
+  if (flag.loading || !isReady) {
+    return defaultValue;
+  }
+  return isOn(key);
+}
+function useFlagValue(key, defaultValue) {
+  const { getValue } = useFlags();
+  return getValue(key, defaultValue);
+}
+function useVariant(key) {
+  const flag = useFlag(key);
+  return flag.variant;
+}
 
-export { Databuddy, FlagsProvider, useFlags };
+export { Databuddy, FlagsProvider, useFeature, useFeatureOn, useFlag, useFlagValue, useFlags, useVariant };

package/dist/shared/@databuddy/sdk.B6nwxnPC.d.mts

@@ -0,0 +1,128 @@
+/** Flag evaluation result from API */
+interface FlagResult {
+    enabled: boolean;
+    value: boolean | string | number;
+    payload: Record<string, unknown> | null;
+    reason: string;
+    variant?: string;
+}
+/** User context for flag evaluation */
+interface UserContext {
+    userId?: string;
+    email?: string;
+    properties?: Record<string, unknown>;
+}
+/** SDK configuration */
+interface FlagsConfig {
+    /** Client ID (website or organization ID) */
+    clientId: string;
+    /** API URL (default: https://api.databuddy.cc) */
+    apiUrl?: string;
+    /** User context for evaluation */
+    user?: UserContext;
+    /** Disable flag evaluation entirely */
+    disabled?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Skip persistent storage (browser only) */
+    skipStorage?: boolean;
+    /** Session is loading - defer evaluation */
+    isPending?: boolean;
+    /** Auto-fetch all flags on init (default: true) */
+    autoFetch?: boolean;
+    /** Environment name */
+    environment?: string;
+    /** Cache TTL in ms - after this, cache is invalid (default: 60000) */
+    cacheTtl?: number;
+    /** Stale time in ms - after this, revalidate in background (default: cacheTtl/2) */
+    staleTime?: number;
+}
+/** Flag status for clear state management */
+type FlagStatus = "loading" | "ready" | "error" | "pending";
+/** Synchronous flag state for React hooks */
+interface FlagState {
+    /** Whether the flag is enabled (true/false) */
+    on: boolean;
+    /** @deprecated Use `on` instead */
+    enabled: boolean;
+    /**  Current status: loading, ready, error, or pending  */
+    status: FlagStatus;
+    /** Whether the flag is still loading */
+    loading: boolean;
+    /** @deprecated Use `status === 'ready'` instead */
+    isLoading: boolean;
+    /** @deprecated Use `status === 'ready'` instead */
+    isReady: boolean;
+    /** The flag's value (boolean, string, or number) */
+    value?: boolean | string | number;
+    /** Variant name for multivariate flags */
+    variant?: string;
+}
+/** Feature state returned by useFeature hook */
+interface FeatureState {
+    /** Whether the feature is enabled */
+    on: boolean;
+    /** Whether the flag is loading */
+    loading: boolean;
+    /** Current status */
+    status: FlagStatus;
+    /** The flag's value */
+    value?: boolean | string | number;
+    /** Variant for A/B tests */
+    variant?: string;
+}
+/** Context returned by useFlags hook */
+interface FlagsContext {
+    /** @deprecated Use getFlag instead - confusing name */
+    isEnabled: (key: string) => FlagState;
+    /** Get a flag's full state */
+    getFlag: (key: string) => FlagState;
+    /** Get a flag's value with type safety */
+    getValue: <T extends boolean | string | number = boolean>(key: string, defaultValue?: T) => T;
+    /** Check if a flag is on (simple boolean) */
+    isOn: (key: string) => boolean;
+    /** Async fetch a specific flag */
+    fetchFlag: (key: string) => Promise<FlagResult>;
+    /** Fetch all flags */
+    fetchAllFlags: () => Promise<void>;
+    /** Update user context */
+    updateUser: (user: UserContext) => void;
+    /** Refresh all flags */
+    refresh: (forceClear?: boolean) => Promise<void>;
+    /** Whether the SDK is ready */
+    isReady: boolean;
+}
+/** Storage interface for persistence */
+interface StorageInterface {
+    get(key: string): FlagResult | null;
+    set(key: string, value: FlagResult): void;
+    getAll(): Record<string, FlagResult>;
+    setAll(flags: Record<string, FlagResult>): void;
+    delete?(key: string): void;
+    deleteMultiple?(keys: string[]): void;
+    clear(): void;
+    cleanupExpired(): void;
+}
+/** Manager constructor options */
+interface FlagsManagerOptions {
+    config: FlagsConfig;
+    storage?: StorageInterface;
+    onFlagsUpdate?: (flags: Record<string, FlagResult>) => void;
+    onConfigUpdate?: (config: FlagsConfig) => void;
+    onReady?: () => void;
+}
+/** Flags manager interface */
+interface FlagsManager {
+    getFlag: (key: string, user?: UserContext) => Promise<FlagResult>;
+    isEnabled: (key: string) => FlagState;
+    getValue: <T = boolean | string | number>(key: string, defaultValue?: T) => T;
+    fetchAllFlags: (user?: UserContext) => Promise<void>;
+    updateUser: (user: UserContext) => void;
+    refresh: (forceClear?: boolean) => Promise<void>;
+    updateConfig: (config: FlagsConfig) => void;
+    getMemoryFlags: () => Record<string, FlagResult>;
+    isReady: () => boolean;
+    destroy?: () => void;
+}
+
+export type { FlagsConfig as F, UserContext as U, FeatureState as a, FlagState as b, FlagsContext as c, FlagResult as d, FlagsManager as e, FlagsManagerOptions as f };

package/dist/shared/@databuddy/sdk.B6nwxnPC.d.ts

@@ -0,0 +1,128 @@
+/** Flag evaluation result from API */
+interface FlagResult {
+    enabled: boolean;
+    value: boolean | string | number;
+    payload: Record<string, unknown> | null;
+    reason: string;
+    variant?: string;
+}
+/** User context for flag evaluation */
+interface UserContext {
+    userId?: string;
+    email?: string;
+    properties?: Record<string, unknown>;
+}
+/** SDK configuration */
+interface FlagsConfig {
+    /** Client ID (website or organization ID) */
+    clientId: string;
+    /** API URL (default: https://api.databuddy.cc) */
+    apiUrl?: string;
+    /** User context for evaluation */
+    user?: UserContext;
+    /** Disable flag evaluation entirely */
+    disabled?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Skip persistent storage (browser only) */
+    skipStorage?: boolean;
+    /** Session is loading - defer evaluation */
+    isPending?: boolean;
+    /** Auto-fetch all flags on init (default: true) */
+    autoFetch?: boolean;
+    /** Environment name */
+    environment?: string;
+    /** Cache TTL in ms - after this, cache is invalid (default: 60000) */
+    cacheTtl?: number;
+    /** Stale time in ms - after this, revalidate in background (default: cacheTtl/2) */
+    staleTime?: number;
+}
+/** Flag status for clear state management */
+type FlagStatus = "loading" | "ready" | "error" | "pending";
+/** Synchronous flag state for React hooks */
+interface FlagState {
+    /** Whether the flag is enabled (true/false) */
+    on: boolean;
+    /** @deprecated Use `on` instead */
+    enabled: boolean;
+    /**  Current status: loading, ready, error, or pending  */
+    status: FlagStatus;
+    /** Whether the flag is still loading */
+    loading: boolean;
+    /** @deprecated Use `status === 'ready'` instead */
+    isLoading: boolean;
+    /** @deprecated Use `status === 'ready'` instead */
+    isReady: boolean;
+    /** The flag's value (boolean, string, or number) */
+    value?: boolean | string | number;
+    /** Variant name for multivariate flags */
+    variant?: string;
+}
+/** Feature state returned by useFeature hook */
+interface FeatureState {
+    /** Whether the feature is enabled */
+    on: boolean;
+    /** Whether the flag is loading */
+    loading: boolean;
+    /** Current status */
+    status: FlagStatus;
+    /** The flag's value */
+    value?: boolean | string | number;
+    /** Variant for A/B tests */
+    variant?: string;
+}
+/** Context returned by useFlags hook */
+interface FlagsContext {
+    /** @deprecated Use getFlag instead - confusing name */
+    isEnabled: (key: string) => FlagState;
+    /** Get a flag's full state */
+    getFlag: (key: string) => FlagState;
+    /** Get a flag's value with type safety */
+    getValue: <T extends boolean | string | number = boolean>(key: string, defaultValue?: T) => T;
+    /** Check if a flag is on (simple boolean) */
+    isOn: (key: string) => boolean;
+    /** Async fetch a specific flag */
+    fetchFlag: (key: string) => Promise<FlagResult>;
+    /** Fetch all flags */
+    fetchAllFlags: () => Promise<void>;
+    /** Update user context */
+    updateUser: (user: UserContext) => void;
+    /** Refresh all flags */
+    refresh: (forceClear?: boolean) => Promise<void>;
+    /** Whether the SDK is ready */
+    isReady: boolean;
+}
+/** Storage interface for persistence */
+interface StorageInterface {
+    get(key: string): FlagResult | null;
+    set(key: string, value: FlagResult): void;
+    getAll(): Record<string, FlagResult>;
+    setAll(flags: Record<string, FlagResult>): void;
+    delete?(key: string): void;
+    deleteMultiple?(keys: string[]): void;
+    clear(): void;
+    cleanupExpired(): void;
+}
+/** Manager constructor options */
+interface FlagsManagerOptions {
+    config: FlagsConfig;
+    storage?: StorageInterface;
+    onFlagsUpdate?: (flags: Record<string, FlagResult>) => void;
+    onConfigUpdate?: (config: FlagsConfig) => void;
+    onReady?: () => void;
+}
+/** Flags manager interface */
+interface FlagsManager {
+    getFlag: (key: string, user?: UserContext) => Promise<FlagResult>;
+    isEnabled: (key: string) => FlagState;
+    getValue: <T = boolean | string | number>(key: string, defaultValue?: T) => T;
+    fetchAllFlags: (user?: UserContext) => Promise<void>;
+    updateUser: (user: UserContext) => void;
+    refresh: (forceClear?: boolean) => Promise<void>;
+    updateConfig: (config: FlagsConfig) => void;
+    getMemoryFlags: () => Record<string, FlagResult>;
+    isReady: () => boolean;
+    destroy?: () => void;
+}
+
+export type { FlagsConfig as F, UserContext as U, FeatureState as a, FlagState as b, FlagsContext as c, FlagResult as d, FlagsManager as e, FlagsManagerOptions as f };