@databuddy/sdk 1.1.0 → 1.3.0

package/README.md

@@ -1,8 +1,14 @@
-# Databuddy SDK
+# Databuddy SDK & React Component
 
-A modern, type-safe analytics SDK and React component for integrating [Databuddy](https://www.databuddy.cc) into your web apps.
+[![npm version](https://img.shields.io/npm/v/@databuddy/sdk?style=flat-square)](https://www.npmjs.com/package/@databuddy/sdk)
+[![License](https://img.shields.io/npm/l/@databuddy/sdk?style=flat-square)](./LICENSE)
+[![Docs](https://img.shields.io/badge/docs-databuddy.cc-blue?style=flat-square)](https://docs.databuddy.cc)
 
-## Features
+> **The easiest, privacy-first way to add analytics to your web app.**
+
+---
+
+## ✨ Features
 
 - 📊 **Automatic page/screen view tracking**
 - ⚡ **Performance, Web Vitals, and error tracking**
@@ -13,7 +19,7 @@ A modern, type-safe analytics SDK and React component for integrating [Databuddy
 
 ---
 
-## Installation
+## 🚀 Quickstart
 
 ```sh
 bun add @databuddy/sdk
@@ -21,13 +27,7 @@ bun add @databuddy/sdk
 npm install @databuddy/sdk
 ```
 
----
-
-## Usage
-
-### 1. **React/Next.js: Drop-in Component**
-
-Add the `<Databuddy />` component to your root layout (e.g. `app/layout.tsx`):
+Add to your root layout (Next.js/React):
 
 ```tsx
 import { Databuddy } from '@databuddy/sdk';
@@ -50,63 +50,62 @@ export default function RootLayout({ children }) {
 }
 ```
 
-- **All config options are type-safe and passed as data attributes to the script.**
-- **No need to manually add `<Script />` or manage the script tag.**
+---
 
-### 2. **Script Tag (Vanilla HTML/JS)**
+## 🛠️ Configuration Options
 
-If you don't use React, you can add the script directly:
+All options are type-safe and documented in `DatabuddyConfig`:
 
-```html
-<script
-  src="https://app.databuddy.cc/databuddy.js"
-  data-client-id="YOUR_CLIENT_ID"
-  data-track-screen-views="true"
-  data-track-performance="true"
-  defer
-></script>
-```
+| Option                | Type      | Default      | Description |
+|-----------------------|-----------|--------------|-------------|
+| `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. |
+| `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. |
+| `waitForProfile`      | boolean   | `false`      | Wait for user profile before sending events. |
+| `trackScreenViews`    | boolean   | `true`       | Auto-track page/screen views. |
+| `trackHashChanges`    | boolean   | `false`      | Track hash changes in URL. |
+| `trackAttributes`     | boolean   | `false`      | Track data-* attributes. |
+| `trackOutgoingLinks`  | boolean   | `false`      | Track outgoing link clicks. |
+| `trackSessions`       | boolean   | `true`       | Track user sessions. |
+| `trackPerformance`    | boolean   | `true`       | Track page performance. |
+| `trackWebVitals`      | boolean   | `true`       | Track Web Vitals. |
+| `trackEngagement`     | boolean   | `false`      | Track engagement metrics. |
+| `trackScrollDepth`    | boolean   | `false`      | Track scroll depth. |
+| `trackExitIntent`     | boolean   | `false`      | Track exit intent. |
+| `trackInteractions`   | boolean   | `false`      | Track user interactions. |
+| `trackErrors`         | boolean   | `true`       | Track JS errors. |
+| `trackBounceRate`     | boolean   | `false`      | Track bounce rate. |
+| `samplingRate`        | number    | `1.0`        | Sampling rate (0.0–1.0). |
+| `enableRetries`       | boolean   | `true`       | Retry failed requests. |
+| `maxRetries`          | number    | `3`          | Max retries. |
+| `initialRetryDelay`   | number    | `500`        | Initial retry delay (ms). |
+| `enableBatching`      | boolean   | `true`       | Enable event batching. |
+| `batchSize`           | number    | `20`         | Events per batch (1–50). |
+| `batchTimeout`        | number    | `5000`       | Batch timeout (ms, 100–30000). |
 
 ---
 
-## Configuration Options
+## 💡 FAQ
 
-All options are type-safe and documented in `DatabuddyConfig`:
+**Q: Is Databuddy privacy-friendly?**  
+A: Yes! All analytics are anonymized by default. No cookies, no fingerprinting, no PII.
+
+**Q: Can I use this in Next.js, Remix, or plain React?**  
+A: Yes! `<Databuddy />` works in any React app. For non-React, use the script tag directly.
+
+**Q: How do I disable analytics in development?**  
+A: Use the `disabled` prop: `<Databuddy disabled={process.env.NODE_ENV === 'development'} ... />`
 
-| Option              | Type      | Default      | Description |
-|---------------------|-----------|--------------|-------------|
-| `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. |
-| `sdk`               | string    | `web`        | SDK name. Only override for custom builds. |
-| `sdkVersion`        | string    | `1.0.0`      | SDK version. Only override for custom builds. |
-| `disabled`          | boolean   | `false`      | Disable all tracking. |
-| `waitForProfile`    | boolean   | `false`      | Wait for user profile before sending events. |
-| `trackScreenViews`  | boolean   | `true`       | Auto-track page/screen views. |
-| `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. |
-| `trackPerformance`  | boolean   | `true`       | Track page performance. |
-| `trackWebVitals`    | boolean   | `true`       | Track Web Vitals. |
-| `trackEngagement`   | boolean   | `false`      | Track engagement metrics. |
-| `trackScrollDepth`  | boolean   | `false`      | Track scroll depth. |
-| `trackExitIntent`   | boolean   | `false`      | Track exit intent. |
-| `trackInteractions` | boolean   | `false`      | Track user interactions. |
-| `trackErrors`       | boolean   | `true`       | Track JS errors. |
-| `trackBounceRate`   | boolean   | `false`      | Track bounce rate. |
-| `samplingRate`      | number    | `1.0`        | Sampling rate (0.0–1.0). |
-| `enableRetries`     | boolean   | `true`       | Retry failed requests. |
-| `maxRetries`        | number    | `3`          | Max retries. |
-| `initialRetryDelay` | number    | `500`        | Initial retry delay (ms). |
-| `enableBatching`    | boolean   | `true`       | Enable event batching. |
-| `batchSize`         | number    | `20`         | Events per batch (1–50). |
-| `batchTimeout`      | number    | `5000`       | Batch timeout (ms, 100–30000). |
+**Q: Where do I find my `clientId`?**  
+A: In your [Databuddy dashboard](https://app.databuddy.cc).
 
 ---
 
-## Troubleshooting
+## 🧑‍💻 Troubleshooting
 
 - **Script not loading?**
   - Make sure your `clientId` is correct and the script URL is reachable.
@@ -119,7 +118,7 @@ All options are type-safe and documented in `DatabuddyConfig`:
 
 ---
 
-## Documentation & Support
+## 📚 Documentation & Support
 
 - [Databuddy Docs](https://docs.databuddy.cc)
 - [Dashboard](https://app.databuddy.cc)

package/dist/Databuddy.d.ts

@@ -0,0 +1,8 @@
+import type { DatabuddyConfig } from './types';
+/**
+ * <Databuddy /> component for Next.js/React apps
+ * Injects the databuddy.js script with all config as data attributes
+ * Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
+ */
+export declare function Databuddy(props: DatabuddyConfig): null;
+export default Databuddy;

package/dist/Databuddy.js

@@ -0,0 +1,47 @@
+'use client';
+import pkg from '../package.json';
+import { useEffect } from 'react';
+/**
+ * <Databuddy /> component for Next.js/React apps
+ * Injects the databuddy.js script with all config as data attributes
+ * Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
+ */
+export function Databuddy(props) {
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        if (props.disabled)
+            return;
+        if (document.querySelector('script[data-databuddy-injected]'))
+            return;
+        const script = document.createElement('script');
+        script.src = props.scriptUrl || 'https://app.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;
+        script.setAttribute('data-sdk-version', sdkVersion);
+        for (const [key, value] of Object.entries(props)) {
+            if (value !== undefined && key !== 'sdkVersion') {
+                const dataKey = `data-${key.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
+                // Convert booleans and numbers to string for HTML attributes
+                if (typeof value === 'boolean') {
+                    script.setAttribute(dataKey, value ? 'true' : 'false');
+                }
+                else if (typeof value === 'number') {
+                    script.setAttribute(dataKey, value.toString());
+                }
+                else {
+                    script.setAttribute(dataKey, String(value));
+                }
+            }
+        }
+        document.head.appendChild(script);
+        return () => {
+            script.remove();
+        };
+    }, [props]);
+    return null;
+}
+export default Databuddy;

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,2 +1,4 @@
-export * from './DatabuddyProvider';
+// 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,7 +16,7 @@ export interface DatabuddyConfig {
     clientSecret?: string;
     /**
      * Custom API endpoint for event ingestion.
-     * Default: 'https://api.databuddy.cc'
+     * Default: 'https://basket.databuddy.cc'
      */
     apiUrl?: string;
     /**
@@ -30,7 +30,7 @@ export interface DatabuddyConfig {
      */
     sdk?: string;
     /**
-     * SDK version (default: '1.0.0').
+     * SDK version (defaults to package.json version).
      * Only override for custom builds.
      */
     sdkVersion?: 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,6 +1,6 @@
 {
   "name": "@databuddy/sdk",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "private": false,
   "description": "Official Databuddy Analytics SDK",
   "main": "dist/index.js",