@databuddy/sdk 2.2.0 → 2.2.11

package/dist/node/index.d.ts

@@ -5,57 +5,85 @@ interface Logger {
     debug(msg: string, data?: Record<string, unknown>): void;
 }
 
+/**
+ * Middleware function that can transform or filter events
+ * Return null to drop the event, or return a modified event
+ */
+type Middleware = (event: BatchEventInput) => BatchEventInput | null | Promise<BatchEventInput | null>;
 interface DatabuddyConfig {
+    /** Client ID from Databuddy dashboard */
     clientId: string;
+    /** Custom API endpoint (default: https://basket.databuddy.cc) */
     apiUrl?: string;
+    /** Enable debug logging */
     debug?: boolean;
+    /** Custom logger instance */
     logger?: Logger;
-    /**
-     * Enable automatic batching of events
-     * Default: true
-     */
+    /** Enable automatic batching (default: true) */
     enableBatching?: boolean;
-    /**
-     * Number of events to batch before auto-flushing
-     * Default: 10, Max: 100
-     */
+    /** Number of events to batch before flushing (default: 10, max: 100) */
     batchSize?: number;
-    /**
-     * Time in milliseconds before auto-flushing batched events
-     * Default: 2000ms (2 seconds)
-     */
+    /** Time in ms before auto-flushing batched events (default: 2000) */
     batchTimeout?: number;
-    /**
-     * Maximum number of events to queue before auto-flushing
-     * Default: 1000
-     */
+    /** Maximum number of events to queue (default: 1000) */
     maxQueueSize?: number;
+    /** Middleware functions to transform events */
+    middleware?: Middleware[];
+    /** Enable event deduplication based on eventId (default: true) */
+    enableDeduplication?: boolean;
+    /** Maximum deduplication cache size (default: 10000) */
+    maxDeduplicationCacheSize?: number;
 }
 interface CustomEventInput {
+    /** Event name (required) */
     name: string;
+    /** Unique event ID for deduplication */
     eventId?: string;
+    /** Anonymous user ID */
     anonymousId?: string | null;
+    /** Session ID */
     sessionId?: string | null;
+    /** Event timestamp in milliseconds */
     timestamp?: number | null;
+    /** Event properties/metadata */
     properties?: Record<string, unknown> | null;
 }
 interface EventResponse {
+    /** Whether the event was successfully sent */
     success: boolean;
+    /** Server-assigned event ID */
     eventId?: string;
+    /** Error message if failed */
     error?: string;
 }
 interface BatchEventInput {
-    type: 'custom';
+    /** Event type */
+    type: "custom";
+    /** Event name */
     name: string;
+    /** Unique event ID for deduplication */
     eventId?: string;
+    /** Anonymous user ID */
     anonymousId?: string | null;
+    /** Session ID */
     sessionId?: string | null;
+    /** Event timestamp in milliseconds */
     timestamp?: number | null;
+    /** Event properties/metadata */
     properties?: Record<string, unknown> | null;
 }
+/**
+ * Global properties that will be attached to all events
+ */
+interface GlobalProperties {
+    [key: string]: unknown;
+}
 interface BatchEventResponse {
+    /** Whether the batch was successfully sent */
     success: boolean;
+    /** Number of events processed */
     processed?: number;
+    /** Results for each event in the batch */
     results?: Array<{
         status: string;
         type?: string;
@@ -63,11 +91,12 @@ interface BatchEventResponse {
         message?: string;
         error?: string;
     }>;
+    /** Error message if batch failed */
     error?: string;
 }
 
 declare class Databuddy {
-    private clientId;
+    private readonly clientId;
     private apiUrl;
     private logger;
     private enableBatching;
@@ -75,20 +104,21 @@ declare class Databuddy {
     private batchTimeout;
     private queue;
     private flushTimer;
+    private globalProperties;
+    private middleware;
+    private enableDeduplication;
+    private deduplicationCache;
+    private maxDeduplicationCacheSize;
     constructor(config: DatabuddyConfig);
     /**
      * Track a custom event
-     * If batching is enabled, queues the event and auto-flushes when batch size is reached or timeout expires
-     * If batching is disabled, sends the event immediately
-     *
-     * @param event - Custom event data
-     * @returns Response indicating success or failure
-     *
+     * @param event - Event data to track
+     * @returns Promise with success/error response
      * @example
      * ```typescript
      * await client.track({
      *   name: 'user_signup',
-     *   properties: { plan: 'pro' }
+     *   properties: { plan: 'pro', source: 'web' }
      * });
      * ```
      */
@@ -97,26 +127,19 @@ declare class Databuddy {
     private scheduleFlush;
     /**
      * Manually flush all queued events
-     * Important for serverless/stateless environments where you need to ensure events are sent before the process exits
-     *
-     * @returns Response with batch results
-     *
+     * Useful in serverless environments to ensure events are sent before process exits
+     * @returns Promise with batch results
      * @example
      * ```typescript
-     * // In serverless function
      * await client.track({ name: 'api_call' });
-     * await client.flush(); // Ensure events are sent before function exits
+     * await client.flush(); // Ensure events are sent
      * ```
      */
     flush(): Promise<BatchEventResponse>;
     /**
-     * Send multiple custom events in a single batch request
-     * Max 100 events per batch
-     * Note: Usually you don't need to call this directly - use track() with batching enabled instead
-     *
-     * @param events - Array of custom events
-     * @returns Response with results for each event
-     *
+     * Send multiple events in a single batch request
+     * @param events - Array of events to batch (max 100)
+     * @returns Promise with batch results
      * @example
      * ```typescript
      * await client.batch([
@@ -126,7 +149,89 @@ declare class Databuddy {
      * ```
      */
     batch(events: BatchEventInput[]): Promise<BatchEventResponse>;
+    /**
+     * Set global properties attached to all events
+     * Properties are merged with existing globals; event properties override globals
+     * @param properties - Properties to merge with existing globals
+     * @example
+     * ```typescript
+     * client.setGlobalProperties({ environment: 'production', version: '1.0.0' });
+     * // All subsequent events will include these properties
+     * ```
+     */
+    setGlobalProperties(properties: GlobalProperties): void;
+    /**
+     * Get current global properties
+     * @returns Copy of current global properties
+     * @example
+     * ```typescript
+     * const globals = client.getGlobalProperties();
+     * console.log(globals); // { environment: 'production', version: '1.0.0' }
+     * ```
+     */
+    getGlobalProperties(): GlobalProperties;
+    /**
+     * Clear all global properties
+     * @example
+     * ```typescript
+     * client.clearGlobalProperties();
+     * // No more global properties will be attached to events
+     * ```
+     */
+    clearGlobalProperties(): void;
+    /**
+     * Add middleware to transform events
+     * Middleware runs before deduplication and is executed in order
+     * Return null to drop the event, or return a modified event
+     * @param middleware - Middleware function
+     * @example
+     * ```typescript
+     * client.addMiddleware((event) => {
+     *   // Add custom field
+     *   event.properties = { ...event.properties, processed: true };
+     *   return event;
+     * });
+     *
+     * // Drop events matching a condition
+     * client.addMiddleware((event) => {
+     *   if (event.name === 'unwanted_event') return null;
+     *   return event;
+     * });
+     * ```
+     */
+    addMiddleware(middleware: Middleware): void;
+    /**
+     * Remove all middleware functions
+     * @example
+     * ```typescript
+     * client.clearMiddleware();
+     * // All middleware transformations removed
+     * ```
+     */
+    clearMiddleware(): void;
+    /**
+     * Get current deduplication cache size
+     * @returns Number of event IDs in cache
+     * @example
+     * ```typescript
+     * const size = client.getDeduplicationCacheSize();
+     * console.log(`Cache size: ${size}`);
+     * ```
+     */
+    getDeduplicationCacheSize(): number;
+    /**
+     * Clear the deduplication cache
+     * Useful for testing or resetting duplicate detection
+     * @example
+     * ```typescript
+     * client.clearDeduplicationCache();
+     * // All cached event IDs cleared
+     * ```
+     */
+    clearDeduplicationCache(): void;
+    private applyMiddleware;
+    private addToDeduplicationCache;
 }
 
 export { Databuddy, Databuddy as db };
-export type { BatchEventInput, BatchEventResponse, CustomEventInput, DatabuddyConfig, EventResponse, Logger };
+export type { BatchEventInput, BatchEventResponse, CustomEventInput, DatabuddyConfig, EventResponse, GlobalProperties, Logger, Middleware };

package/dist/node/index.mjs

@@ -20,10 +20,7 @@ function createConsoleLogger(debug) {
     },
     error(msg, data) {
       if (debug) {
-        console.error(
-          `[Databuddy] ${msg}`,
-          data ? JSON.stringify(data) : ""
-        );
+        console.error(`[Databuddy] ${msg}`, data ? JSON.stringify(data) : "");
       }
     },
     warn(msg, data) {
@@ -32,10 +29,7 @@ function createConsoleLogger(debug) {
       }
     },
     debug: debug ? (msg, data) => {
-      console.debug(
-        `[Databuddy] ${msg}`,
-        data ? JSON.stringify(data) : ""
-      );
+      console.debug(`[Databuddy] ${msg}`, data ? JSON.stringify(data) : "");
     } : noop
   };
 }
@@ -78,6 +72,7 @@ const DEFAULT_API_URL = "https://basket.databuddy.cc";
 const DEFAULT_BATCH_SIZE = 10;
 const DEFAULT_BATCH_TIMEOUT = 2e3;
 const DEFAULT_MAX_QUEUE_SIZE = 1e3;
+const DEFAULT_MAX_DEDUPLICATION_CACHE_SIZE = 1e4;
 class Databuddy {
   clientId;
   apiUrl;
@@ -87,6 +82,11 @@ class Databuddy {
   batchTimeout;
   queue;
   flushTimer = null;
+  globalProperties = {};
+  middleware = [];
+  enableDeduplication;
+  deduplicationCache = /* @__PURE__ */ new Set();
+  maxDeduplicationCacheSize;
   constructor(config) {
     if (!config.clientId || typeof config.clientId !== "string") {
       throw new Error("clientId is required and must be a string");
@@ -97,6 +97,9 @@ class Databuddy {
     this.batchSize = Math.min(config.batchSize || DEFAULT_BATCH_SIZE, 100);
     this.batchTimeout = config.batchTimeout || DEFAULT_BATCH_TIMEOUT;
     this.queue = new EventQueue(config.maxQueueSize || DEFAULT_MAX_QUEUE_SIZE);
+    this.middleware = config.middleware || [];
+    this.enableDeduplication = config.enableDeduplication !== false;
+    this.maxDeduplicationCacheSize = config.maxDeduplicationCacheSize || DEFAULT_MAX_DEDUPLICATION_CACHE_SIZE;
     if (config.logger) {
       this.logger = config.logger;
     } else if (config.debug) {
@@ -109,22 +112,20 @@ class Databuddy {
       apiUrl: this.apiUrl,
       enableBatching: this.enableBatching,
       batchSize: this.batchSize,
-      batchTimeout: this.batchTimeout
+      batchTimeout: this.batchTimeout,
+      middlewareCount: this.middleware.length,
+      enableDeduplication: this.enableDeduplication
     });
   }
   /**
    * Track a custom event
-   * If batching is enabled, queues the event and auto-flushes when batch size is reached or timeout expires
-   * If batching is disabled, sends the event immediately
-   *
-   * @param event - Custom event data
-   * @returns Response indicating success or failure
-   *
+   * @param event - Event data to track
+   * @returns Promise with success/error response
    * @example
    * ```typescript
    * await client.track({
    *   name: 'user_signup',
-   *   properties: { plan: 'pro' }
+   *   properties: { plan: 'pro', source: 'web' }
    * });
    * ```
    */
@@ -142,12 +143,29 @@ class Databuddy {
       anonymousId: event.anonymousId,
       sessionId: event.sessionId,
       timestamp: event.timestamp,
-      properties: event.properties || null
+      properties: {
+        ...this.globalProperties,
+        ...event.properties || {}
+      }
     };
+    const processedEvent = await this.applyMiddleware(batchEvent);
+    if (!processedEvent) {
+      this.logger.debug("Event dropped by middleware", { name: event.name });
+      return { success: true };
+    }
+    if (this.enableDeduplication && processedEvent.eventId) {
+      if (this.deduplicationCache.has(processedEvent.eventId)) {
+        this.logger.debug("Event deduplicated", {
+          eventId: processedEvent.eventId
+        });
+        return { success: true };
+      }
+      this.addToDeduplicationCache(processedEvent.eventId);
+    }
     if (!this.enableBatching) {
-      return this.send(batchEvent);
+      return this.send(processedEvent);
     }
-    const shouldFlush = this.queue.add(batchEvent);
+    const shouldFlush = this.queue.add(processedEvent);
     this.logger.debug("Event queued", { queueSize: this.queue.size() });
     this.scheduleFlush();
     if (shouldFlush || this.queue.size() >= this.batchSize) {
@@ -218,15 +236,12 @@ class Databuddy {
   }
   /**
    * Manually flush all queued events
-   * Important for serverless/stateless environments where you need to ensure events are sent before the process exits
-   *
-   * @returns Response with batch results
-   *
+   * Useful in serverless environments to ensure events are sent before process exits
+   * @returns Promise with batch results
    * @example
    * ```typescript
-   * // In serverless function
    * await client.track({ name: 'api_call' });
-   * await client.flush(); // Ensure events are sent before function exits
+   * await client.flush(); // Ensure events are sent
    * ```
    */
   async flush() {
@@ -247,13 +262,9 @@ class Databuddy {
     return this.batch(events);
   }
   /**
-   * Send multiple custom events in a single batch request
-   * Max 100 events per batch
-   * Note: Usually you don't need to call this directly - use track() with batching enabled instead
-   *
-   * @param events - Array of custom events
-   * @returns Response with results for each event
-   *
+   * Send multiple events in a single batch request
+   * @param events - Array of events to batch (max 100)
+   * @returns Promise with batch results
    * @example
    * ```typescript
    * await client.batch([
@@ -289,20 +300,57 @@ class Databuddy {
         };
       }
     }
+    const enrichedEvents = events.map((event) => ({
+      ...event,
+      properties: {
+        ...this.globalProperties,
+        ...event.properties || {}
+      }
+    }));
+    const processedEvents = [];
+    for (const event of enrichedEvents) {
+      const processedEvent = await this.applyMiddleware(event);
+      if (!processedEvent) {
+        continue;
+      }
+      if (this.enableDeduplication && processedEvent.eventId) {
+        if (this.deduplicationCache.has(processedEvent.eventId)) {
+          this.logger.debug("Event deduplicated in batch", {
+            eventId: processedEvent.eventId
+          });
+          continue;
+        }
+        this.addToDeduplicationCache(processedEvent.eventId);
+      }
+      processedEvents.push(processedEvent);
+    }
+    if (processedEvents.length === 0) {
+      return {
+        success: true,
+        processed: 0,
+        results: []
+      };
+    }
     try {
       const url = `${this.apiUrl}/batch?client_id=${encodeURIComponent(this.clientId)}`;
       this.logger.info("\u{1F4E6} SENDING BATCH EVENTS:", {
-        count: events.length,
-        firstEventName: events[0]?.name,
-        firstEventProperties: JSON.stringify(events[0]?.properties, null, 2),
-        firstEventPropertiesCount: Object.keys(events[0]?.properties || {}).length
+        count: processedEvents.length,
+        firstEventName: processedEvents[0]?.name,
+        firstEventProperties: JSON.stringify(
+          processedEvents[0]?.properties,
+          null,
+          2
+        ),
+        firstEventPropertiesCount: Object.keys(
+          processedEvents[0]?.properties || {}
+        ).length
       });
       const response = await fetch(url, {
         method: "POST",
         headers: {
           "Content-Type": "application/json"
         },
-        body: JSON.stringify(events)
+        body: JSON.stringify(processedEvents)
       });
       if (!response.ok) {
         const errorText = await response.text().catch(() => "Unknown error");
@@ -321,7 +369,7 @@ class Databuddy {
       if (data.status === "success") {
         return {
           success: true,
-          processed: data.processed,
+          processed: data.processed || processedEvents.length,
           results: data.results
         };
       }
@@ -339,6 +387,132 @@ class Databuddy {
       };
     }
   }
+  /**
+   * Set global properties attached to all events
+   * Properties are merged with existing globals; event properties override globals
+   * @param properties - Properties to merge with existing globals
+   * @example
+   * ```typescript
+   * client.setGlobalProperties({ environment: 'production', version: '1.0.0' });
+   * // All subsequent events will include these properties
+   * ```
+   */
+  setGlobalProperties(properties) {
+    this.globalProperties = { ...this.globalProperties, ...properties };
+    this.logger.debug("Global properties updated", { properties });
+  }
+  /**
+   * Get current global properties
+   * @returns Copy of current global properties
+   * @example
+   * ```typescript
+   * const globals = client.getGlobalProperties();
+   * console.log(globals); // { environment: 'production', version: '1.0.0' }
+   * ```
+   */
+  getGlobalProperties() {
+    return { ...this.globalProperties };
+  }
+  /**
+   * Clear all global properties
+   * @example
+   * ```typescript
+   * client.clearGlobalProperties();
+   * // No more global properties will be attached to events
+   * ```
+   */
+  clearGlobalProperties() {
+    this.globalProperties = {};
+    this.logger.debug("Global properties cleared");
+  }
+  /**
+   * Add middleware to transform events
+   * Middleware runs before deduplication and is executed in order
+   * Return null to drop the event, or return a modified event
+   * @param middleware - Middleware function
+   * @example
+   * ```typescript
+   * client.addMiddleware((event) => {
+   *   // Add custom field
+   *   event.properties = { ...event.properties, processed: true };
+   *   return event;
+   * });
+   *
+   * // Drop events matching a condition
+   * client.addMiddleware((event) => {
+   *   if (event.name === 'unwanted_event') return null;
+   *   return event;
+   * });
+   * ```
+   */
+  addMiddleware(middleware) {
+    this.middleware.push(middleware);
+    this.logger.debug("Middleware added", {
+      totalMiddleware: this.middleware.length
+    });
+  }
+  /**
+   * Remove all middleware functions
+   * @example
+   * ```typescript
+   * client.clearMiddleware();
+   * // All middleware transformations removed
+   * ```
+   */
+  clearMiddleware() {
+    this.middleware = [];
+    this.logger.debug("Middleware cleared");
+  }
+  /**
+   * Get current deduplication cache size
+   * @returns Number of event IDs in cache
+   * @example
+   * ```typescript
+   * const size = client.getDeduplicationCacheSize();
+   * console.log(`Cache size: ${size}`);
+   * ```
+   */
+  getDeduplicationCacheSize() {
+    return this.deduplicationCache.size;
+  }
+  /**
+   * Clear the deduplication cache
+   * Useful for testing or resetting duplicate detection
+   * @example
+   * ```typescript
+   * client.clearDeduplicationCache();
+   * // All cached event IDs cleared
+   * ```
+   */
+  clearDeduplicationCache() {
+    this.deduplicationCache.clear();
+    this.logger.debug("Deduplication cache cleared");
+  }
+  async applyMiddleware(event) {
+    let processedEvent = event;
+    for (const middleware of this.middleware) {
+      if (!processedEvent) {
+        break;
+      }
+      try {
+        processedEvent = await middleware(processedEvent);
+      } catch (error) {
+        this.logger.error("Middleware error", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    return processedEvent;
+  }
+  addToDeduplicationCache(eventId) {
+    if (this.deduplicationCache.size >= this.maxDeduplicationCacheSize) {
+      const oldest = this.deduplicationCache.values().next().value;
+      if (oldest) {
+        this.deduplicationCache.delete(oldest);
+      }
+    }
+    this.deduplicationCache.add(eventId);
+  }
 }
 
 export { Databuddy, Databuddy as db };

package/dist/react/index.d.mts

@@ -1,12 +1,25 @@
-export { b as Databuddy } from '../shared/@databuddy/sdk.C8T93n5r.mjs';
+import { D as DatabuddyConfig } from '../shared/@databuddy/sdk.B1NyVg8b.mjs';
+import * as react from 'react';
 import { ReactNode } from 'react';
-import { d as FlagsConfig, c as FlagState } from '../shared/@databuddy/sdk.YfiY9DoZ.mjs';
-export { b as FlagResult, e as FlagsContext } from '../shared/@databuddy/sdk.YfiY9DoZ.mjs';
+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';
+
+/**
+ * <Databuddy /> component for Next.js/React apps
+ * Injects the databuddy.js script with all config as data attributes
+ * Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
+ * Or simply: <Databuddy /> (auto-detects clientId from environment variables)
+ */
+declare function Databuddy(props: DatabuddyConfig): null;
 
 interface FlagsProviderProps extends FlagsConfig {
     children: ReactNode;
 }
-declare function FlagsProvider({ children, ...config }: FlagsProviderProps): any;
+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;
@@ -14,4 +27,4 @@ declare function useFlags(): {
     refresh: (forceClear?: boolean) => void;
 };
 
-export { FlagState, FlagsConfig, FlagsProvider, useFlags };
+export { Databuddy, FlagState, FlagsConfig, FlagsProvider, useFlags };

package/dist/react/index.d.ts

@@ -1,12 +1,25 @@
-export { b as Databuddy } from '../shared/@databuddy/sdk.C8T93n5r.js';
+import { D as DatabuddyConfig } from '../shared/@databuddy/sdk.B1NyVg8b.js';
+import * as react from 'react';
 import { ReactNode } from 'react';
-import { d as FlagsConfig, c as FlagState } from '../shared/@databuddy/sdk.YfiY9DoZ.js';
-export { b as FlagResult, e as FlagsContext } from '../shared/@databuddy/sdk.YfiY9DoZ.js';
+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';
+
+/**
+ * <Databuddy /> component for Next.js/React apps
+ * Injects the databuddy.js script with all config as data attributes
+ * Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
+ * Or simply: <Databuddy /> (auto-detects clientId from environment variables)
+ */
+declare function Databuddy(props: DatabuddyConfig): null;
 
 interface FlagsProviderProps extends FlagsConfig {
     children: ReactNode;
 }
-declare function FlagsProvider({ children, ...config }: FlagsProviderProps): any;
+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;
@@ -14,4 +27,4 @@ declare function useFlags(): {
     refresh: (forceClear?: boolean) => void;
 };
 
-export { FlagState, FlagsConfig, FlagsProvider, useFlags };
+export { Databuddy, FlagState, FlagsConfig, FlagsProvider, useFlags };