@databuddy/sdk 1.4.2 → 2.1.0

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

@@ -0,0 +1,338 @@
+/**
+ * Configuration options for the Databuddy SDK and <Databuddy /> component.
+ * All options are passed as data attributes to the injected script.
+ */
+interface DatabuddyConfig {
+    /**
+     * Your Databuddy project client ID.
+     * If not provided, will automatically detect from NEXT_PUBLIC_DATABUDDY_CLIENT_ID environment variable.
+     * Get this from your Databuddy dashboard.
+     * Example: '3ed1fce1-5a56-4cbc-a917-66864f6d18e3'
+     */
+    clientId?: string;
+    /**
+     * (Advanced) Your Databuddy client secret for server-side operations.
+     * Not required for browser usage.
+     */
+    clientSecret?: string;
+    /**
+     * Custom API endpoint for event ingestion.
+     * Default: 'https://basket.databuddy.cc'
+     */
+    apiUrl?: string;
+    /**
+     * Custom script URL for the Databuddy browser bundle.
+     * Default: 'https://cdn.databuddy.cc/databuddy.js'
+     */
+    scriptUrl?: string;
+    /**
+     * SDK name for analytics (default: 'web').
+     * Only override if you are building a custom integration.
+     */
+    sdk?: string;
+    /**
+     * SDK version (defaults to package.json version).
+     * Only override for custom builds.
+     */
+    sdkVersion?: string;
+    /**
+     * Disable all tracking (default: false).
+     * If true, no events will be sent.
+     */
+    disabled?: boolean;
+    /**
+     * Wait for user profile before sending events (advanced, default: false).
+     */
+    waitForProfile?: boolean;
+    /**
+     * Automatically track screen/page views (default: true).
+     */
+    trackScreenViews?: boolean;
+    /**
+     * Track hash changes in the URL (default: false).
+     */
+    trackHashChanges?: boolean;
+    /**
+     * Track user sessions (default: true).
+     */
+    trackSessions?: boolean;
+    /**
+     * Track data-* attributes on elements (default: false).
+     */
+    trackAttributes?: boolean;
+    /**
+     * Track clicks on outgoing links (default: false).
+     */
+    trackOutgoingLinks?: boolean;
+    /**
+     * Track user interactions (default: false).
+     */
+    trackInteractions?: boolean;
+    /**
+     * Track user engagement metrics (default: false).
+     */
+    trackEngagement?: boolean;
+    /**
+     * Track scroll depth (default: false).
+     */
+    trackScrollDepth?: boolean;
+    /**
+     * Track exit intent (default: false).
+     */
+    trackExitIntent?: boolean;
+    /**
+     * Track bounce rate (default: false).
+     */
+    trackBounceRate?: boolean;
+    /**
+     * Track page performance metrics (default: true).
+     */
+    trackPerformance?: boolean;
+    /**
+     * Track Web Vitals metrics (default: false).
+     */
+    trackWebVitals?: boolean;
+    /**
+     * Track JavaScript errors (default: false).
+     */
+    trackErrors?: boolean;
+    /**
+     * Enable observability features (logging, error tracking, tracing) (default: false).
+     */
+    enableObservability?: boolean;
+    /**
+     * Service name for observability events.
+     */
+    observabilityService?: string;
+    /**
+     * Environment for observability events.
+     */
+    observabilityEnvironment?: string;
+    /**
+     * Service version for observability events.
+     */
+    observabilityVersion?: string;
+    /**
+     * Enable structured logging (default: false).
+     */
+    enableLogging?: boolean;
+    /**
+     * Enable distributed tracing (default: false).
+     */
+    enableTracing?: boolean;
+    /**
+     * Enable error tracking (default: false).
+     */
+    enableErrorTracking?: boolean;
+    /**
+     * Sampling rate for events (0.0 to 1.0, default: 1.0).
+     * Example: 0.5 = 50% of events sent.
+     */
+    samplingRate?: number;
+    /**
+     * Enable retries for failed requests (default: true).
+     */
+    enableRetries?: boolean;
+    /**
+     * Maximum number of retries for failed requests (default: 3).
+     * Only used if enableRetries is true.
+     */
+    maxRetries?: number;
+    /**
+     * Initial retry delay in milliseconds (default: 500).
+     * Only used if enableRetries is true.
+     */
+    initialRetryDelay?: number;
+    /**
+     * Enable event batching (default: false).
+     */
+    enableBatching?: boolean;
+    /**
+     * Number of events to batch before sending (default: 10).
+     * Only used if enableBatching is true.
+     * Min: 1, Max: 50
+     */
+    batchSize?: number;
+    /**
+     * Batch timeout in milliseconds (default: 2000).
+     * Only used if enableBatching is true.
+     * Min: 100, Max: 30000
+     */
+    batchTimeout?: number;
+}
+/**
+ * Base event properties that can be attached to any event
+ */
+interface BaseEventProperties {
+    /** Page URL */
+    __path?: string;
+    /** Page title */
+    __title?: string;
+    /** Referrer URL */
+    __referrer?: string;
+    /** Event timestamp in milliseconds */
+    __timestamp_ms?: number;
+    /** Session ID */
+    sessionId?: string;
+    /** Session start time */
+    sessionStartTime?: number;
+    /** Page count in session */
+    page_count?: number;
+    /** Screen resolution */
+    screen_resolution?: string;
+    /** Viewport size */
+    viewport_size?: string;
+    /** User timezone */
+    timezone?: string;
+    /** User language */
+    language?: string;
+    /** UTM parameters */
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+}
+/**
+ * Custom event properties that can be attached to any event
+ */
+interface EventProperties extends BaseEventProperties {
+    /** Custom properties for the event */
+    [key: string]: string | number | boolean | null | undefined;
+}
+/**
+ * Pre-defined event types with their specific properties
+ */
+interface EventTypeMap {
+    screen_view: {
+        time_on_page?: number;
+        scroll_depth?: number;
+        interaction_count?: number;
+        has_exit_intent?: boolean;
+        is_bounce?: 0 | 1;
+    };
+    page_exit: {
+        time_on_page: number;
+        scroll_depth: number;
+        interaction_count: number;
+        has_exit_intent: boolean;
+        page_count: number;
+        is_bounce: 0 | 1;
+    };
+    button_click: {
+        button_text?: string;
+        button_type?: string;
+        button_id?: string;
+        element_class?: string;
+    };
+    link_out: {
+        href: string;
+        text?: string;
+        target_domain?: string;
+    };
+    form_submit: {
+        form_id?: string;
+        form_name?: string;
+        form_type?: string;
+        success?: boolean;
+    };
+    web_vitals: {
+        fcp?: number;
+        lcp?: number;
+        cls?: string;
+        fid?: number;
+        ttfb?: number;
+        load_time?: number;
+        dom_ready_time?: number;
+        render_time?: number;
+        request_time?: number;
+    };
+    error: {
+        message: string;
+        filename?: string;
+        lineno?: number;
+        colno?: number;
+        stack?: string;
+        error_type?: string;
+    };
+    [eventName: string]: EventProperties;
+}
+/**
+ * Available event names
+ */
+type EventName = keyof EventTypeMap;
+/**
+ * Properties for a specific event type
+ */
+type PropertiesForEvent<T extends EventName> = T extends keyof EventTypeMap ? EventTypeMap[T] & EventProperties : EventProperties;
+/**
+ * Databuddy tracker instance interface
+ */
+interface DatabuddyTracker {
+    /**
+     * Track a custom event
+     */
+    track<T extends EventName>(eventName: T, properties?: PropertiesForEvent<T>): Promise<void>;
+    /**
+     * Track a screen/page view
+     */
+    screenView(path?: string, properties?: EventProperties): void;
+    /**
+     * Set global properties that will be attached to all events
+     */
+    setGlobalProperties(properties: EventProperties): void;
+    /**
+     * Clear the current user session and generate new IDs
+     */
+    clear(): void;
+    /**
+     * Flush any queued events immediately
+     */
+    flush(): void;
+    /**
+     * Track a custom event with full type safety
+     */
+    trackCustomEvent(eventName: string, properties?: EventProperties): void;
+}
+/**
+ * Global window interface extensions
+ */
+declare global {
+    interface Window {
+        databuddy?: DatabuddyTracker;
+        db?: {
+            track: DatabuddyTracker['track'];
+            screenView: DatabuddyTracker['screenView'];
+            clear: DatabuddyTracker['clear'];
+            flush: DatabuddyTracker['flush'];
+            setGlobalProperties: DatabuddyTracker['setGlobalProperties'];
+            trackCustomEvent: DatabuddyTracker['trackCustomEvent'];
+        };
+    }
+}
+/**
+ * Helper type for HTML data attributes for automatic tracking
+ */
+interface DataAttributes {
+    /** Event name to track when element is clicked */
+    'data-track': string;
+    /** Additional data attributes (converted to camelCase) */
+    [key: `data-${string}`]: string;
+}
+/**
+ * Utility types for creating typed event tracking functions
+ */
+type TrackFunction = <T extends EventName>(eventName: T, properties?: PropertiesForEvent<T>) => Promise<void>;
+type ScreenViewFunction = (path?: string, properties?: EventProperties) => void;
+type SetGlobalPropertiesFunction = (properties: EventProperties) => void;
+
+/**
+ * <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;
+
+export { Databuddy as b };
+export type { BaseEventProperties as B, DatabuddyConfig as D, EventProperties as E, PropertiesForEvent as P, ScreenViewFunction as S, TrackFunction as T, DatabuddyTracker as a, EventTypeMap as c, EventName as d, DataAttributes as e, SetGlobalPropertiesFunction as f };

package/dist/shared/@databuddy/sdk.CtTNAIIE.mjs

@@ -0,0 +1,25 @@
+const version = "2.0.0";
+
+const INJECTED_SCRIPT_ATTRIBUTE = "data-databuddy-injected";
+function isScriptInjected() {
+  return !!document.querySelector(`script[${INJECTED_SCRIPT_ATTRIBUTE}]`);
+}
+function createScript({
+  scriptUrl,
+  sdkVersion,
+  ...props
+}) {
+  const script = document.createElement("script");
+  script.src = scriptUrl || "https://cdn.databuddy.cc/databuddy.js";
+  script.async = true;
+  script.crossOrigin = "anonymous";
+  script.setAttribute(INJECTED_SCRIPT_ATTRIBUTE, "true");
+  script.setAttribute("data-sdk-version", sdkVersion || version);
+  for (const [key, value] of Object.entries(props)) {
+    const dataKey = `data-${key.replace(/([A-Z])/g, "-$1").toLowerCase()}`;
+    script.setAttribute(dataKey, String(value));
+  }
+  return script;
+}
+
+export { createScript as c, isScriptInjected as i };

package/dist/vue/index.d.mts

@@ -0,0 +1,182 @@
+import * as vue from 'vue';
+
+declare const Databuddy: vue.DefineComponent<{
+    clientId?: {
+        type: StringConstructor;
+        required: false;
+    } | undefined;
+    clientSecret?: {
+        type: StringConstructor;
+        required: false;
+    } | undefined;
+    apiUrl?: {
+        type: StringConstructor;
+        required: false;
+    } | undefined;
+    scriptUrl?: {
+        type: StringConstructor;
+        required: false;
+    } | undefined;
+    sdk?: {
+        type: StringConstructor;
+        required: false;
+    } | undefined;
+    sdkVersion?: {
+        type: StringConstructor;
+        required: false;
+    } | undefined;
+    disabled?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    waitForProfile?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackScreenViews?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackHashChanges?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackSessions?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackAttributes?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackOutgoingLinks?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackInteractions?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackEngagement?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackScrollDepth?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackExitIntent?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackBounceRate?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackPerformance?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackWebVitals?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    trackErrors?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    enableObservability?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    observabilityService?: {
+        type: StringConstructor;
+        required: false;
+    } | undefined;
+    observabilityEnvironment?: {
+        type: StringConstructor;
+        required: false;
+    } | undefined;
+    observabilityVersion?: {
+        type: StringConstructor;
+        required: false;
+    } | undefined;
+    enableLogging?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    enableTracing?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    enableErrorTracking?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    samplingRate?: {
+        type: NumberConstructor;
+        required: false;
+    } | undefined;
+    enableRetries?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    maxRetries?: {
+        type: NumberConstructor;
+        required: false;
+    } | undefined;
+    initialRetryDelay?: {
+        type: NumberConstructor;
+        required: false;
+    } | undefined;
+    enableBatching?: {
+        type: BooleanConstructor;
+        required: false;
+    } | undefined;
+    batchSize?: {
+        type: NumberConstructor;
+        required: false;
+    } | undefined;
+    batchTimeout?: {
+        type: NumberConstructor;
+        required: false;
+    } | undefined;
+}, () => null, unknown, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, Record<string, any>, string, vue.VNodeProps & vue.AllowedComponentProps & vue.ComponentCustomProps, Readonly<{} & {
+    sdk?: string | undefined;
+    clientId?: string | undefined;
+    clientSecret?: string | undefined;
+    apiUrl?: string | undefined;
+    scriptUrl?: string | undefined;
+    sdkVersion?: string | undefined;
+    disabled?: boolean | undefined;
+    waitForProfile?: boolean | undefined;
+    trackScreenViews?: boolean | undefined;
+    trackHashChanges?: boolean | undefined;
+    trackSessions?: boolean | undefined;
+    trackAttributes?: boolean | undefined;
+    trackOutgoingLinks?: boolean | undefined;
+    trackInteractions?: boolean | undefined;
+    trackEngagement?: boolean | undefined;
+    trackScrollDepth?: boolean | undefined;
+    trackExitIntent?: boolean | undefined;
+    trackBounceRate?: boolean | undefined;
+    trackPerformance?: boolean | undefined;
+    trackWebVitals?: boolean | undefined;
+    trackErrors?: boolean | undefined;
+    enableObservability?: boolean | undefined;
+    observabilityService?: string | undefined;
+    observabilityEnvironment?: string | undefined;
+    observabilityVersion?: string | undefined;
+    enableLogging?: boolean | undefined;
+    enableTracing?: boolean | undefined;
+    enableErrorTracking?: boolean | undefined;
+    samplingRate?: number | undefined;
+    enableRetries?: boolean | undefined;
+    maxRetries?: number | undefined;
+    initialRetryDelay?: number | undefined;
+    enableBatching?: boolean | undefined;
+    batchSize?: number | undefined;
+    batchTimeout?: number | undefined;
+}>, {}>;
+
+export { Databuddy };