@databuddy/sdk 1.2.0 → 1.4.0

package/README.md

@@ -61,7 +61,7 @@ All options are type-safe and documented in `DatabuddyConfig`:
 | `clientId`            | string    | —            | **Required.** Your Databuddy project client ID. |
 | `clientSecret`        | string    | —            | (Advanced) For server-side use only. |
 | `apiUrl`              | string    | `https://api.databuddy.cc` | Custom API endpoint. |
-| `scriptUrl`           | string    | `https://app.databuddy.cc/databuddy.js` | Custom script URL. |
+| `scriptUrl`           | string    | `https://cdn.databuddy.cc/databuddy.js` | Custom script URL. |
 | `sdk`                 | string    | `web`        | SDK name. Only override for custom builds. |
 | `sdkVersion`          | string    | *auto*       | SDK version. Defaults to package version. |
 | `disabled`            | boolean   | `false`      | Disable all tracking. |
@@ -70,7 +70,7 @@ All options are type-safe and documented in `DatabuddyConfig`:
 | `trackHashChanges`    | boolean   | `false`      | Track hash changes in URL. |
 | `trackAttributes`     | boolean   | `false`      | Track data-* attributes. |
 | `trackOutgoingLinks`  | boolean   | `false`      | Track outgoing link clicks. |
-| `trackSessions`       | boolean   | `false`      | Track user sessions. |
+| `trackSessions`       | boolean   | `true`       | Track user sessions. |
 | `trackPerformance`    | boolean   | `true`       | Track page performance. |
 | `trackWebVitals`      | boolean   | `true`       | Track Web Vitals. |
 | `trackEngagement`     | boolean   | `false`      | Track engagement metrics. |

package/dist/Databuddy.js

@@ -15,8 +15,9 @@ export function Databuddy(props) {
         if (document.querySelector('script[data-databuddy-injected]'))
             return;
         const script = document.createElement('script');
-        script.src = props.scriptUrl || 'https://app.databuddy.cc/databuddy.js';
-        script.defer = true;
+        script.src = props.scriptUrl || 'https://cdn.databuddy.cc/databuddy.js';
+        script.async = true;
+        script.crossOrigin = 'anonymous';
         script.setAttribute('data-databuddy-injected', 'true');
         // Always set sdkVersion from package.json unless explicitly overridden
         const sdkVersion = props.sdkVersion || pkg.version;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './Databuddy';
 export * from './types';
+export * from './tracker';

package/dist/index.js

@@ -1,2 +1,4 @@
+// Main exports
 export * from './Databuddy';
 export * from './types';
+export * from './tracker';

package/dist/tracker.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Databuddy SDK Client-side Tracker
+ * Provides type-safe tracking functions
+ */
+import type { DatabuddyTracker, TrackFunction } from './types';
+/**
+ * Check if the Databuddy tracker is available
+ */
+export declare function isTrackerAvailable(): boolean;
+/**
+ * Get the Databuddy tracker instance
+ */
+export declare function getTracker(): DatabuddyTracker | null;
+/**
+ * Type-safe track function
+ */
+export declare const track: TrackFunction;
+/**
+ * Clear the current session
+ */
+export declare function clear(): void;
+/**
+ * Flush any queued events
+ */
+export declare function flush(): void;
+/**
+ * Track an error event
+ */
+export declare function trackError(message: string, properties?: {
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    stack?: string;
+    error_type?: string;
+    [key: string]: any;
+}): Promise<void>;
+declare const _default: {
+    track: TrackFunction;
+    clear: typeof clear;
+    flush: typeof flush;
+    trackError: typeof trackError;
+};
+export default _default;

package/dist/tracker.js

@@ -0,0 +1,86 @@
+/**
+ * Databuddy SDK Client-side Tracker
+ * Provides type-safe tracking functions
+ */
+/**
+ * Check if the Databuddy tracker is available
+ */
+export function isTrackerAvailable() {
+    return typeof window !== 'undefined' &&
+        (!!window.databuddy || !!window.db);
+}
+/**
+ * Get the Databuddy tracker instance
+ */
+export function getTracker() {
+    if (typeof window === 'undefined')
+        return null;
+    return window.databuddy || null;
+}
+/**
+ * Type-safe track function
+ */
+export const track = async (eventName, properties) => {
+    var _a, _b;
+    if (typeof window === 'undefined') {
+        return;
+    }
+    // Try window.db first (shorthand), then window.databuddy
+    const tracker = ((_a = window.db) === null || _a === void 0 ? void 0 : _a.track) || ((_b = window.databuddy) === null || _b === void 0 ? void 0 : _b.track);
+    if (!tracker) {
+        return;
+    }
+    try {
+        await tracker(eventName, properties);
+    }
+    catch (error) {
+    }
+};
+/**
+ * Clear the current session
+ */
+export function clear() {
+    var _a, _b;
+    if (typeof window === 'undefined') {
+        return;
+    }
+    const tracker = ((_a = window.db) === null || _a === void 0 ? void 0 : _a.clear) || ((_b = window.databuddy) === null || _b === void 0 ? void 0 : _b.clear);
+    if (!tracker) {
+        return;
+    }
+    try {
+        tracker();
+    }
+    catch (error) {
+    }
+}
+/**
+ * Flush any queued events
+ */
+export function flush() {
+    var _a, _b;
+    if (typeof window === 'undefined') {
+        return;
+    }
+    const tracker = ((_a = window.db) === null || _a === void 0 ? void 0 : _a.flush) || ((_b = window.databuddy) === null || _b === void 0 ? void 0 : _b.flush);
+    if (!tracker) {
+        return;
+    }
+    try {
+        tracker();
+    }
+    catch (error) {
+    }
+}
+/**
+ * Track an error event
+ */
+export function trackError(message, properties) {
+    return track('error', { message, ...properties });
+}
+export default {
+    track,
+    clear,
+    flush,
+    trackError,
+};

package/dist/types.d.ts

@@ -16,12 +16,12 @@ export interface DatabuddyConfig {
     clientSecret?: string;
     /**
      * Custom API endpoint for event ingestion.
-     * Default: 'https://api.databuddy.cc'
+     * Default: 'https://basket.databuddy.cc'
      */
     apiUrl?: string;
     /**
      * Custom script URL for the Databuddy browser bundle.
-     * Default: 'https://app.databuddy.cc/databuddy.js'
+     * Default: 'https://cdn.databuddy.cc/databuddy.js'
      */
     scriptUrl?: string;
     /**
@@ -51,6 +51,10 @@ export interface DatabuddyConfig {
      * Track hash changes in the URL (default: false).
      */
     trackHashChanges?: boolean;
+    /**
+     * Track user sessions (default: true).
+     */
+    trackSessions?: boolean;
     /**
      * Track data-* attributes on elements (default: false).
      */
@@ -60,17 +64,9 @@ export interface DatabuddyConfig {
      */
     trackOutgoingLinks?: boolean;
     /**
-     * Track user sessions (default: false).
-     */
-    trackSessions?: boolean;
-    /**
-     * Track page performance metrics (default: true).
-     */
-    trackPerformance?: boolean;
-    /**
-     * Track Web Vitals metrics (default: true).
+     * Track user interactions (default: false).
      */
-    trackWebVitals?: boolean;
+    trackInteractions?: boolean;
     /**
      * Track user engagement metrics (default: false).
      */
@@ -84,17 +80,21 @@ export interface DatabuddyConfig {
      */
     trackExitIntent?: boolean;
     /**
-     * Track user interactions (default: false).
+     * Track bounce rate (default: false).
      */
-    trackInteractions?: boolean;
+    trackBounceRate?: boolean;
     /**
-     * Track JavaScript errors (default: true).
+     * Track page performance metrics (default: true).
      */
-    trackErrors?: boolean;
+    trackPerformance?: boolean;
     /**
-     * Track bounce rate (default: false).
+     * Track Web Vitals metrics (default: false).
      */
-    trackBounceRate?: boolean;
+    trackWebVitals?: boolean;
+    /**
+     * Track JavaScript errors (default: false).
+     */
+    trackErrors?: boolean;
     /**
      * Sampling rate for events (0.0 to 1.0, default: 1.0).
      * Example: 0.5 = 50% of events sent.
@@ -115,26 +115,184 @@ export interface DatabuddyConfig {
      */
     initialRetryDelay?: number;
     /**
-     * Enable event batching (default: true).
+     * Enable event batching (default: false).
      */
     enableBatching?: boolean;
     /**
-     * Number of events to batch before sending (default: 20).
+     * 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: 5000).
+     * Batch timeout in milliseconds (default: 2000).
      * Only used if enableBatching is true.
      * Min: 100, Max: 30000
      */
     batchTimeout?: number;
 }
 /**
- * Event properties that can be attached to any event
+ * Base event properties that can be attached to any event
  */
-export interface EventProperties {
+export 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
+ */
+export interface EventProperties extends BaseEventProperties {
     /** Custom properties for the event */
-    [key: string]: string | number | boolean | null | undefined | EventProperties;
+    [key: string]: string | number | boolean | null | undefined;
 }
+/**
+ * Pre-defined event types with their specific properties
+ */
+export 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
+ */
+export type EventName = keyof EventTypeMap;
+/**
+ * Properties for a specific event type
+ */
+export type PropertiesForEvent<T extends EventName> = T extends keyof EventTypeMap ? EventTypeMap[T] & EventProperties : EventProperties;
+/**
+ * Databuddy tracker instance interface
+ */
+export 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
+ */
+export 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
+ */
+export type TrackFunction = <T extends EventName>(eventName: T, properties?: PropertiesForEvent<T>) => Promise<void>;
+export type ScreenViewFunction = (path?: string, properties?: EventProperties) => void;
+export type SetGlobalPropertiesFunction = (properties: EventProperties) => void;

package/package.json

@@ -1,27 +1,27 @@
-{
-  "name": "@databuddy/sdk",
-  "version": "1.2.0",
-  "private": false,
-  "description": "Official Databuddy Analytics SDK",
-  "main": "dist/index.js",
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "keywords": [
-    "analytics",
-    "tracking",
-    "databuddy",
-    "sdk"
-  ],
-  "scripts": {
-    "build": "tsc --project tsconfig.json"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
-  }
+{
+  "name": "@databuddy/sdk",
+  "version": "1.4.0",
+  "private": false,
+  "description": "Official Databuddy Analytics SDK",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "analytics",
+    "tracking",
+    "databuddy",
+    "sdk"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
 }