@databuddy/sdk 2.3.1 → 2.3.2

package/dist/core/index.mjs

@@ -1,5 +1,5 @@
 export { d as detectClientId } from '../shared/@databuddy/sdk.BUsPV0LH.mjs';
-export { B as BrowserFlagStorage, C as CoreFlagsManager, c as createScript, i as isScriptInjected } from '../shared/@databuddy/sdk.ByNF_UxE.mjs';
+export { c as createScript, i as isScriptInjected } from '../shared/@databuddy/sdk.F8Xt1uF7.mjs';
 
 function isTrackerAvailable() {
   return typeof window !== "undefined" && (!!window.databuddy || !!window.db);

package/dist/node/index.d.mts

@@ -1,3 +1,5 @@
+import { e as FlagsManager, f as FlagsManagerOptions, U as UserContext, d as FlagResult, b as FlagState, F as FlagsConfig } from '../shared/@databuddy/sdk.B6nwxnPC.mjs';
+
 interface Logger {
     info(msg: string, data?: Record<string, unknown>): void;
     error(msg: string, data?: Record<string, unknown>): void;
@@ -95,20 +97,129 @@ interface BatchEventResponse {
     error?: string;
 }
 
+/**
+ * Server-side flags manager
+ * Optimized for server environments with:
+ * - Request-level deduplication
+ * - Request batching
+ * - Stale-while-revalidate caching
+ * - No persistent storage (stateless)
+ */
+declare class ServerFlagsManager implements FlagsManager {
+    private config;
+    private readonly onFlagsUpdate?;
+    private readonly onConfigUpdate?;
+    /** In-memory cache with stale tracking */
+    private readonly cache;
+    /** In-flight requests for deduplication */
+    private readonly inFlight;
+    /** Request batcher */
+    private batcher;
+    /** Ready state */
+    private ready;
+    /** Init promise for awaiting */
+    private readonly initPromise;
+    constructor(options: FlagsManagerOptions);
+    private withDefaults;
+    private initialize;
+    /**
+     * Wait for initialization to complete
+     */
+    waitForInit(): Promise<void>;
+    private getFromCache;
+    private getBatcher;
+    /**
+     * Get a flag with deduplication, batching, and SWR caching
+     */
+    getFlag(key: string, user?: UserContext): Promise<FlagResult>;
+    private revalidateFlag;
+    /**
+     * Fetch all flags for a user
+     */
+    fetchAllFlags(user?: UserContext): Promise<void>;
+    /**
+     * Check if flag is enabled (synchronous)
+     */
+    isEnabled(key: string): FlagState;
+    /**
+     * Get flag value (synchronous)
+     */
+    getValue<T = boolean | string | number>(key: string, defaultValue?: T): T;
+    /**
+     * Update user context
+     */
+    updateUser(user: UserContext): void;
+    /**
+     * Refresh flags
+     */
+    refresh(forceClear?: boolean): Promise<void>;
+    /**
+     * Update config
+     */
+    updateConfig(config: FlagsConfig): void;
+    /**
+     * Get all cached flags
+     */
+    getMemoryFlags(): Record<string, FlagResult>;
+    /**
+     * Check if ready
+     */
+    isReady(): boolean;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}
+
+/**
+ * Create a ServerFlagsManager with in-memory caching
+ *
+ * @example
+ * ```typescript
+ * import { createServerFlagsManager } from '@databuddy/sdk/node';
+ *
+ * const manager = createServerFlagsManager({
+ *   clientId: process.env.DATABUDDY_CLIENT_ID!,
+ * });
+ *
+ * await manager.waitForInit();
+ * const flag = await manager.getFlag('my-feature');
+ * ```
+ */
+declare function createServerFlagsManager(config: FlagsConfig): ServerFlagsManager;
+/**
+ * Alias for createServerFlagsManager (for backwards compatibility)
+ *
+ * @example
+ * ```typescript
+ * import { createServerFlagsManagerInMemory } from '@databuddy/sdk/node';
+ *
+ * const manager = createServerFlagsManagerInMemory({
+ *   clientId: process.env.DATABUDDY_CLIENT_ID!,
+ * });
+ *
+ * await manager.waitForInit();
+ * const flag = await manager.getFlag('my-feature');
+ * ```
+ */
+declare function createServerFlagsManagerInMemory(config: FlagsConfig): ServerFlagsManager;
+
+/** biome-ignore-all lint/performance/noBarrelFile: im a big fan of barrels */
+
 declare class Databuddy {
     private readonly clientId;
-    private apiUrl;
-    private logger;
-    private enableBatching;
-    private batchSize;
-    private batchTimeout;
-    private queue;
+    private readonly apiUrl;
+    private readonly logger;
+    private readonly enableBatching;
+    private readonly batchSize;
+    private readonly batchTimeout;
+    private readonly queue;
     private flushTimer;
     private globalProperties;
     private middleware;
-    private enableDeduplication;
-    private deduplicationCache;
-    private maxDeduplicationCacheSize;
+    private readonly enableDeduplication;
+    private readonly deduplicationCache;
+    private readonly maxDeduplicationCacheSize;
     constructor(config: DatabuddyConfig);
     /**
      * Track a custom event
@@ -233,5 +344,5 @@ declare class Databuddy {
     private addToDeduplicationCache;
 }
 
-export { Databuddy, Databuddy as db };
+export { Databuddy, ServerFlagsManager, createServerFlagsManager, createServerFlagsManagerInMemory, Databuddy as db };
 export type { BatchEventInput, BatchEventResponse, CustomEventInput, DatabuddyConfig, EventResponse, GlobalProperties, Logger, Middleware };

package/dist/node/index.d.ts

@@ -1,3 +1,5 @@
+import { e as FlagsManager, f as FlagsManagerOptions, U as UserContext, d as FlagResult, b as FlagState, F as FlagsConfig } from '../shared/@databuddy/sdk.B6nwxnPC.js';
+
 interface Logger {
     info(msg: string, data?: Record<string, unknown>): void;
     error(msg: string, data?: Record<string, unknown>): void;
@@ -95,20 +97,129 @@ interface BatchEventResponse {
     error?: string;
 }
 
+/**
+ * Server-side flags manager
+ * Optimized for server environments with:
+ * - Request-level deduplication
+ * - Request batching
+ * - Stale-while-revalidate caching
+ * - No persistent storage (stateless)
+ */
+declare class ServerFlagsManager implements FlagsManager {
+    private config;
+    private readonly onFlagsUpdate?;
+    private readonly onConfigUpdate?;
+    /** In-memory cache with stale tracking */
+    private readonly cache;
+    /** In-flight requests for deduplication */
+    private readonly inFlight;
+    /** Request batcher */
+    private batcher;
+    /** Ready state */
+    private ready;
+    /** Init promise for awaiting */
+    private readonly initPromise;
+    constructor(options: FlagsManagerOptions);
+    private withDefaults;
+    private initialize;
+    /**
+     * Wait for initialization to complete
+     */
+    waitForInit(): Promise<void>;
+    private getFromCache;
+    private getBatcher;
+    /**
+     * Get a flag with deduplication, batching, and SWR caching
+     */
+    getFlag(key: string, user?: UserContext): Promise<FlagResult>;
+    private revalidateFlag;
+    /**
+     * Fetch all flags for a user
+     */
+    fetchAllFlags(user?: UserContext): Promise<void>;
+    /**
+     * Check if flag is enabled (synchronous)
+     */
+    isEnabled(key: string): FlagState;
+    /**
+     * Get flag value (synchronous)
+     */
+    getValue<T = boolean | string | number>(key: string, defaultValue?: T): T;
+    /**
+     * Update user context
+     */
+    updateUser(user: UserContext): void;
+    /**
+     * Refresh flags
+     */
+    refresh(forceClear?: boolean): Promise<void>;
+    /**
+     * Update config
+     */
+    updateConfig(config: FlagsConfig): void;
+    /**
+     * Get all cached flags
+     */
+    getMemoryFlags(): Record<string, FlagResult>;
+    /**
+     * Check if ready
+     */
+    isReady(): boolean;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}
+
+/**
+ * Create a ServerFlagsManager with in-memory caching
+ *
+ * @example
+ * ```typescript
+ * import { createServerFlagsManager } from '@databuddy/sdk/node';
+ *
+ * const manager = createServerFlagsManager({
+ *   clientId: process.env.DATABUDDY_CLIENT_ID!,
+ * });
+ *
+ * await manager.waitForInit();
+ * const flag = await manager.getFlag('my-feature');
+ * ```
+ */
+declare function createServerFlagsManager(config: FlagsConfig): ServerFlagsManager;
+/**
+ * Alias for createServerFlagsManager (for backwards compatibility)
+ *
+ * @example
+ * ```typescript
+ * import { createServerFlagsManagerInMemory } from '@databuddy/sdk/node';
+ *
+ * const manager = createServerFlagsManagerInMemory({
+ *   clientId: process.env.DATABUDDY_CLIENT_ID!,
+ * });
+ *
+ * await manager.waitForInit();
+ * const flag = await manager.getFlag('my-feature');
+ * ```
+ */
+declare function createServerFlagsManagerInMemory(config: FlagsConfig): ServerFlagsManager;
+
+/** biome-ignore-all lint/performance/noBarrelFile: im a big fan of barrels */
+
 declare class Databuddy {
     private readonly clientId;
-    private apiUrl;
-    private logger;
-    private enableBatching;
-    private batchSize;
-    private batchTimeout;
-    private queue;
+    private readonly apiUrl;
+    private readonly logger;
+    private readonly enableBatching;
+    private readonly batchSize;
+    private readonly batchTimeout;
+    private readonly queue;
     private flushTimer;
     private globalProperties;
     private middleware;
-    private enableDeduplication;
-    private deduplicationCache;
-    private maxDeduplicationCacheSize;
+    private readonly enableDeduplication;
+    private readonly deduplicationCache;
+    private readonly maxDeduplicationCacheSize;
     constructor(config: DatabuddyConfig);
     /**
      * Track a custom event
@@ -233,5 +344,5 @@ declare class Databuddy {
     private addToDeduplicationCache;
 }
 
-export { Databuddy, Databuddy as db };
+export { Databuddy, ServerFlagsManager, createServerFlagsManager, createServerFlagsManagerInMemory, Databuddy as db };
 export type { BatchEventInput, BatchEventResponse, CustomEventInput, DatabuddyConfig, EventResponse, GlobalProperties, Logger, Middleware };

package/dist/node/index.mjs

@@ -1,3 +1,5 @@
+import { l as logger, i as isCacheValid, b as buildQueryParams, R as RequestBatcher, D as DEFAULT_RESULT, g as getCacheKey, a as isCacheStale, c as createCacheEntry, f as fetchAllFlags } from '../shared/@databuddy/sdk.3kaCzyfu.mjs';
+
 function createLogger(debug = false) {
   return createConsoleLogger(debug);
 }
@@ -60,6 +62,258 @@ class EventQueue {
   }
 }
 
+class ServerFlagsManager {
+  config;
+  onFlagsUpdate;
+  onConfigUpdate;
+  /** In-memory cache with stale tracking */
+  cache = /* @__PURE__ */ new Map();
+  /** In-flight requests for deduplication */
+  inFlight = /* @__PURE__ */ new Map();
+  /** Request batcher */
+  batcher = null;
+  /** Ready state */
+  ready = false;
+  /** Init promise for awaiting */
+  initPromise;
+  constructor(options) {
+    this.config = this.withDefaults(options.config);
+    this.onFlagsUpdate = options.onFlagsUpdate;
+    this.onConfigUpdate = options.onConfigUpdate;
+    logger.setDebug(this.config.debug ?? false);
+    logger.debug("ServerFlagsManager initialized", {
+      clientId: this.config.clientId,
+      hasUser: Boolean(this.config.user)
+    });
+    this.initPromise = this.initialize();
+  }
+  withDefaults(config) {
+    return {
+      clientId: config.clientId,
+      apiUrl: config.apiUrl ?? "https://api.databuddy.cc",
+      user: config.user,
+      disabled: config.disabled ?? false,
+      debug: config.debug ?? false,
+      skipStorage: true,
+      // Always skip storage on server
+      isPending: config.isPending,
+      autoFetch: config.autoFetch ?? false,
+      environment: config.environment,
+      cacheTtl: config.cacheTtl ?? 6e4,
+      // 1 minute
+      staleTime: config.staleTime ?? 3e4
+      // 30 seconds
+    };
+  }
+  async initialize() {
+    if (this.config.autoFetch && !this.config.isPending) {
+      await this.fetchAllFlags();
+    }
+    this.ready = true;
+  }
+  /**
+   * Wait for initialization to complete
+   */
+  async waitForInit() {
+    await this.initPromise;
+  }
+  getFromCache(key) {
+    const cached = this.cache.get(key);
+    if (isCacheValid(cached)) {
+      return cached;
+    }
+    if (cached) {
+      this.cache.delete(key);
+    }
+    return null;
+  }
+  getBatcher() {
+    if (!this.batcher) {
+      const apiUrl = this.config.apiUrl ?? "https://api.databuddy.cc";
+      const params = buildQueryParams(this.config);
+      this.batcher = new RequestBatcher(apiUrl, params, 5);
+    }
+    return this.batcher;
+  }
+  /**
+   * Get a flag with deduplication, batching, and SWR caching
+   */
+  async getFlag(key, user) {
+    if (this.config.disabled) {
+      return DEFAULT_RESULT;
+    }
+    if (this.config.isPending) {
+      return { ...DEFAULT_RESULT, reason: "SESSION_PENDING" };
+    }
+    const cacheKey = getCacheKey(key, user ?? this.config.user);
+    const cached = this.getFromCache(cacheKey);
+    if (cached) {
+      if (isCacheStale(cached)) {
+        this.revalidateFlag(key, cacheKey);
+      }
+      return cached.result;
+    }
+    const existing = this.inFlight.get(cacheKey);
+    if (existing) {
+      logger.debug(`Deduplicating request: ${key}`);
+      return existing;
+    }
+    const promise = this.getBatcher().request(key);
+    this.inFlight.set(cacheKey, promise);
+    try {
+      const result = await promise;
+      const ttl = this.config.cacheTtl ?? 6e4;
+      const staleTime = this.config.staleTime ?? ttl / 2;
+      this.cache.set(cacheKey, createCacheEntry(result, ttl, staleTime));
+      return result;
+    } finally {
+      this.inFlight.delete(cacheKey);
+    }
+  }
+  async revalidateFlag(key, cacheKey) {
+    if (this.inFlight.has(cacheKey)) {
+      return;
+    }
+    const promise = this.getBatcher().request(key);
+    this.inFlight.set(cacheKey, promise);
+    try {
+      const result = await promise;
+      const ttl = this.config.cacheTtl ?? 6e4;
+      const staleTime = this.config.staleTime ?? ttl / 2;
+      this.cache.set(cacheKey, createCacheEntry(result, ttl, staleTime));
+      logger.debug(`Revalidated flag: ${key}`);
+    } catch (err) {
+      logger.error(`Revalidation error: ${key}`, err);
+    } finally {
+      this.inFlight.delete(cacheKey);
+    }
+  }
+  /**
+   * Fetch all flags for a user
+   */
+  async fetchAllFlags(user) {
+    if (this.config.disabled || this.config.isPending) {
+      return;
+    }
+    const apiUrl = this.config.apiUrl ?? "https://api.databuddy.cc";
+    const params = buildQueryParams(this.config, user);
+    try {
+      const flags = await fetchAllFlags(apiUrl, params);
+      const ttl = this.config.cacheTtl ?? 6e4;
+      const staleTime = this.config.staleTime ?? ttl / 2;
+      for (const [key, result] of Object.entries(flags)) {
+        const cacheKey = getCacheKey(key, user ?? this.config.user);
+        this.cache.set(cacheKey, createCacheEntry(result, ttl, staleTime));
+      }
+      this.ready = true;
+      this.onFlagsUpdate?.(flags);
+      logger.debug(`Fetched ${Object.keys(flags).length} flags`);
+    } catch (err) {
+      logger.error("Bulk fetch error:", err);
+    }
+  }
+  /**
+   * Check if flag is enabled (synchronous)
+   */
+  isEnabled(key) {
+    const cacheKey = getCacheKey(key, this.config.user);
+    const cached = this.getFromCache(cacheKey);
+    if (cached) {
+      return {
+        on: cached.result.enabled,
+        enabled: cached.result.enabled,
+        status: cached.result.reason === "ERROR" ? "error" : "ready",
+        loading: false,
+        isLoading: false,
+        isReady: true,
+        value: cached.result.value,
+        variant: cached.result.variant
+      };
+    }
+    const loading = this.inFlight.has(cacheKey);
+    return {
+      on: false,
+      enabled: false,
+      status: "loading",
+      loading,
+      isLoading: loading,
+      isReady: false
+    };
+  }
+  /**
+   * Get flag value (synchronous)
+   */
+  getValue(key, defaultValue) {
+    const cacheKey = getCacheKey(key, this.config.user);
+    const cached = this.getFromCache(cacheKey);
+    if (cached) {
+      return cached.result.value;
+    }
+    return defaultValue ?? false;
+  }
+  /**
+   * Update user context
+   */
+  updateUser(user) {
+    this.config = { ...this.config, user };
+    this.batcher?.destroy();
+    this.batcher = null;
+    this.onConfigUpdate?.(this.config);
+  }
+  /**
+   * Refresh flags
+   */
+  async refresh(forceClear = false) {
+    if (forceClear) {
+      this.cache.clear();
+    }
+    await this.fetchAllFlags();
+  }
+  /**
+   * Update config
+   */
+  updateConfig(config) {
+    this.config = this.withDefaults(config);
+    this.batcher?.destroy();
+    this.batcher = null;
+    this.onConfigUpdate?.(this.config);
+  }
+  /**
+   * Get all cached flags
+   */
+  getMemoryFlags() {
+    const flags = {};
+    for (const [key, entry] of this.cache) {
+      const flagKey = key.split(":")[0];
+      flags[flagKey] = entry.result;
+    }
+    return flags;
+  }
+  /**
+   * Check if ready
+   */
+  isReady() {
+    return this.ready;
+  }
+  /**
+   * Cleanup resources
+   */
+  destroy() {
+    this.batcher?.destroy();
+    this.cache.clear();
+    this.inFlight.clear();
+  }
+}
+
+function createServerFlagsManager(config) {
+  return new ServerFlagsManager({
+    config
+  });
+}
+function createServerFlagsManagerInMemory(config) {
+  return createServerFlagsManager(config);
+}
+
 const DEFAULT_API_URL = "https://basket.databuddy.cc";
 const DEFAULT_BATCH_SIZE = 10;
 const DEFAULT_BATCH_TIMEOUT = 2e3;
@@ -251,7 +505,7 @@ class Databuddy {
     const events = this.queue.getAll();
     this.queue.clear();
     this.logger.info("Flushing events", { count: events.length });
-    return this.batch(events);
+    return await this.batch(events);
   }
   /**
    * Send multiple events in a single batch request
@@ -507,4 +761,4 @@ class Databuddy {
   }
 }
 
-export { Databuddy, Databuddy as db };
+export { Databuddy, ServerFlagsManager, createServerFlagsManager, createServerFlagsManagerInMemory, Databuddy as db };

package/dist/react/index.d.mts

@@ -1,9 +1,6 @@
-import { D as DatabuddyConfig } from '../shared/@databuddy/sdk.CeYE_kaj.mjs';
-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.mjs';
-export { b as FlagResult, e as FlagsContext } from '../shared/@databuddy/sdk.OK9Nbqlf.mjs';
+import { D as DatabuddyConfig } from '../shared/@databuddy/sdk.C9b3SVYK.mjs';
+import React, { ReactNode } from 'react';
+import { F as FlagsConfig, a as FeatureState, b as FlagState, c as FlagsContext } from '../shared/@databuddy/sdk.B6nwxnPC.mjs';
 
 /**
  * React/Next.js component that injects the Databuddy tracking script.
@@ -56,18 +53,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 };