@databuddy/sdk 2.1.78 → 2.2.1

package/dist/node/index.d.ts

@@ -0,0 +1,237 @@
+interface Logger {
+    info(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    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 (default: true) */
+    enableBatching?: boolean;
+    /** Number of events to batch before flushing (default: 10, max: 100) */
+    batchSize?: number;
+    /** Time in ms before auto-flushing batched events (default: 2000) */
+    batchTimeout?: number;
+    /** 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 {
+    /** 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;
+        eventId?: string;
+        message?: string;
+        error?: string;
+    }>;
+    /** Error message if batch failed */
+    error?: string;
+}
+
+declare class Databuddy {
+    private clientId;
+    private apiUrl;
+    private logger;
+    private enableBatching;
+    private batchSize;
+    private batchTimeout;
+    private queue;
+    private flushTimer;
+    private globalProperties;
+    private middleware;
+    private enableDeduplication;
+    private deduplicationCache;
+    private maxDeduplicationCacheSize;
+    constructor(config: DatabuddyConfig);
+    /**
+     * Track a custom event
+     * @param event - Event data to track
+     * @returns Promise with success/error response
+     * @example
+     * ```typescript
+     * await client.track({
+     *   name: 'user_signup',
+     *   properties: { plan: 'pro', source: 'web' }
+     * });
+     * ```
+     */
+    track(event: CustomEventInput): Promise<EventResponse>;
+    private send;
+    private scheduleFlush;
+    /**
+     * Manually flush all queued events
+     * Useful in serverless environments to ensure events are sent before process exits
+     * @returns Promise with batch results
+     * @example
+     * ```typescript
+     * await client.track({ name: 'api_call' });
+     * await client.flush(); // Ensure events are sent
+     * ```
+     */
+    flush(): Promise<BatchEventResponse>;
+    /**
+     * 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([
+     *   { type: 'custom', name: 'event1', properties: { foo: 'bar' } },
+     *   { type: 'custom', name: 'event2', properties: { baz: 'qux' } }
+     * ]);
+     * ```
+     */
+    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, GlobalProperties, Logger, Middleware };