@databuddy/sdk 1.4.2 → 2.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![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)
+[![Docs](https://img.shields.io/badge/docs-databuddy.cc-blue?style=flat-square)](https://www.databuddy.cc/docs)
 
 > **The easiest, privacy-first way to add analytics to your web app.**
 
@@ -16,6 +16,7 @@
 - 🧩 **Drop-in React/Next.js component: `<Databuddy />`**
 - 🛡️ **Privacy-first: anonymized by default, sampling, batching, and more**
 - 🛠️ **Type-safe config and autocompletion**
+- 📋 **Observability: logging, error tracking, and distributed tracing**
 
 ---
 
@@ -120,7 +121,7 @@ A: In your [Databuddy dashboard](https://app.databuddy.cc).
 
 ## 📚 Documentation & Support
 
-- [Databuddy Docs](https://docs.databuddy.cc)
+- [Databuddy Docs](https://www.databuddy.cc/docs)
 - [Dashboard](https://app.databuddy.cc)
 - [Contact Support](https://www.databuddy.cc/contact)
 

package/dist/core/index.d.mts

@@ -0,0 +1,55 @@
+import { D as DatabuddyConfig, a as DatabuddyTracker, T as TrackFunction, b as Databuddy$1 } from '../shared/@databuddy/sdk.ClgMzRh8.mjs';
+export { B as BaseEventProperties, e as DataAttributes, d as EventName, E as EventProperties, c as EventTypeMap, P as PropertiesForEvent, S as ScreenViewFunction, f as SetGlobalPropertiesFunction } from '../shared/@databuddy/sdk.ClgMzRh8.mjs';
+
+/**
+ * Auto-detect Databuddy client ID from environment variables
+ * Supports Next.js, Nuxt, and other frameworks
+ */
+declare function detectClientId(providedClientId?: string): string | undefined;
+
+declare function isScriptInjected(): boolean;
+declare function createScript({ scriptUrl, sdkVersion, ...props }: DatabuddyConfig): HTMLScriptElement;
+
+/**
+ * Databuddy SDK Client-side Tracker
+ * Provides type-safe tracking functions
+ */
+
+/**
+ * Check if the Databuddy tracker is available
+ */
+declare function isTrackerAvailable(): boolean;
+/**
+ * Get the Databuddy tracker instance
+ */
+declare function getTracker(): DatabuddyTracker | null;
+/**
+ * Type-safe track function
+ */
+declare const track: TrackFunction;
+/**
+ * Clear the current session
+ */
+declare function clear(): void;
+/**
+ * Flush any queued events
+ */
+declare function flush(): void;
+/**
+ * Track an error event
+ */
+declare function trackError(message: string, properties?: {
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    stack?: string;
+    error_type?: string;
+    [key: string]: any;
+}): Promise<void>;
+
+/**
+ * @deprecated Use Databuddy from `@databuddy/sdk/react` instead
+ */
+declare const Databuddy: typeof Databuddy$1;
+
+export { Databuddy, DatabuddyConfig, DatabuddyTracker, TrackFunction, clear, createScript, detectClientId, flush, getTracker, isScriptInjected, isTrackerAvailable, track, trackError };

package/dist/core/index.d.ts

@@ -0,0 +1,55 @@
+import { D as DatabuddyConfig, a as DatabuddyTracker, T as TrackFunction, b as Databuddy$1 } from '../shared/@databuddy/sdk.ClgMzRh8.js';
+export { B as BaseEventProperties, e as DataAttributes, d as EventName, E as EventProperties, c as EventTypeMap, P as PropertiesForEvent, S as ScreenViewFunction, f as SetGlobalPropertiesFunction } from '../shared/@databuddy/sdk.ClgMzRh8.js';
+
+/**
+ * Auto-detect Databuddy client ID from environment variables
+ * Supports Next.js, Nuxt, and other frameworks
+ */
+declare function detectClientId(providedClientId?: string): string | undefined;
+
+declare function isScriptInjected(): boolean;
+declare function createScript({ scriptUrl, sdkVersion, ...props }: DatabuddyConfig): HTMLScriptElement;
+
+/**
+ * Databuddy SDK Client-side Tracker
+ * Provides type-safe tracking functions
+ */
+
+/**
+ * Check if the Databuddy tracker is available
+ */
+declare function isTrackerAvailable(): boolean;
+/**
+ * Get the Databuddy tracker instance
+ */
+declare function getTracker(): DatabuddyTracker | null;
+/**
+ * Type-safe track function
+ */
+declare const track: TrackFunction;
+/**
+ * Clear the current session
+ */
+declare function clear(): void;
+/**
+ * Flush any queued events
+ */
+declare function flush(): void;
+/**
+ * Track an error event
+ */
+declare function trackError(message: string, properties?: {
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    stack?: string;
+    error_type?: string;
+    [key: string]: any;
+}): Promise<void>;
+
+/**
+ * @deprecated Use Databuddy from `@databuddy/sdk/react` instead
+ */
+declare const Databuddy: typeof Databuddy$1;
+
+export { Databuddy, DatabuddyConfig, DatabuddyTracker, TrackFunction, clear, createScript, detectClientId, flush, getTracker, isScriptInjected, isTrackerAvailable, track, trackError };

package/dist/core/index.mjs

@@ -0,0 +1,59 @@
+import { D as Databuddy$1 } from '../shared/@databuddy/sdk.B72MFYNj.mjs';
+export { d as detectClientId } from '../shared/@databuddy/sdk.B72MFYNj.mjs';
+export { c as createScript, i as isScriptInjected } from '../shared/@databuddy/sdk.CtTNAIIE.mjs';
+
+function isTrackerAvailable() {
+  return typeof window !== "undefined" && (!!window.databuddy || !!window.db);
+}
+function getTracker() {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  return window.databuddy || null;
+}
+const track = async (eventName, properties) => {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const tracker = window.db?.track || window.databuddy?.track;
+  if (!tracker) {
+    return;
+  }
+  try {
+    await tracker(eventName, properties);
+  } catch (_error) {
+  }
+};
+function clear() {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const tracker = window.db?.clear || window.databuddy?.clear;
+  if (!tracker) {
+    return;
+  }
+  try {
+    tracker();
+  } catch (_error) {
+  }
+}
+function flush() {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const tracker = window.db?.flush || window.databuddy?.flush;
+  if (!tracker) {
+    return;
+  }
+  try {
+    tracker();
+  } catch (_error) {
+  }
+}
+function trackError(message, properties) {
+  return track("error", { message, ...properties });
+}
+
+const Databuddy = Databuddy$1;
+
+export { Databuddy, clear, flush, getTracker, isTrackerAvailable, track, trackError };

package/dist/react/index.d.mts

@@ -0,0 +1 @@
+export { b as Databuddy } from '../shared/@databuddy/sdk.ClgMzRh8.mjs';

package/dist/react/index.d.ts

@@ -0,0 +1 @@
+export { b as Databuddy } from '../shared/@databuddy/sdk.ClgMzRh8.js';

package/dist/react/index.mjs

@@ -0,0 +1,4 @@
+'use client';
+
+export { D as Databuddy } from '../shared/@databuddy/sdk.B72MFYNj.mjs';
+import '../shared/@databuddy/sdk.CtTNAIIE.mjs';

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

@@ -0,0 +1,44 @@
+import { i as isScriptInjected, c as createScript } from './sdk.CtTNAIIE.mjs';
+
+function detectClientId(providedClientId) {
+  if (providedClientId) {
+    return providedClientId;
+  }
+  if (typeof process !== "undefined" && process.env) {
+    return process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID || process.env.NUXT_PUBLIC_DATABUDDY_CLIENT_ID || process.env.VITE_DATABUDDY_CLIENT_ID || process.env.REACT_APP_DATABUDDY_CLIENT_ID;
+  }
+  if (typeof window !== "undefined") {
+    const nextEnv = window.__NEXT_DATA__?.env?.NEXT_PUBLIC_DATABUDDY_CLIENT_ID;
+    if (nextEnv) {
+      return nextEnv;
+    }
+    const nuxtEnv = window.__NUXT__?.env?.NUXT_PUBLIC_DATABUDDY_CLIENT_ID;
+    if (nuxtEnv) {
+      return nuxtEnv;
+    }
+    const viteEnv = window.__VITE_ENV__?.VITE_DATABUDDY_CLIENT_ID;
+    if (viteEnv) {
+      return viteEnv;
+    }
+  }
+  return;
+}
+
+function Databuddy(props) {
+  const clientId = detectClientId(props.clientId);
+  if (!clientId) {
+    if (typeof window !== "undefined" && !props.disabled) {
+      console.warn(
+        "Databuddy: No client ID found. Please provide clientId prop or set NEXT_PUBLIC_DATABUDDY_CLIENT_ID environment variable."
+      );
+    }
+    return null;
+  }
+  if (typeof window !== "undefined" && !props.disabled && !isScriptInjected()) {
+    const script = createScript({ ...props, clientId });
+    document.head.appendChild(script);
+  }
+  return null;
+}
+
+export { Databuddy as D, detectClientId as d };

package/dist/{types.d.ts → shared/@databuddy/sdk.ClgMzRh8.d.mts}

@@ -2,13 +2,14 @@
  * Configuration options for the Databuddy SDK and <Databuddy /> component.
  * All options are passed as data attributes to the injected script.
  */
-export interface DatabuddyConfig {
+interface DatabuddyConfig {
     /**
-     * Your Databuddy project client ID (required).
+     * 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;
+    clientId?: string;
     /**
      * (Advanced) Your Databuddy client secret for server-side operations.
      * Not required for browser usage.
@@ -95,6 +96,34 @@ export interface DatabuddyConfig {
      * 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.
@@ -134,7 +163,7 @@ export interface DatabuddyConfig {
 /**
  * Base event properties that can be attached to any event
  */
-export interface BaseEventProperties {
+interface BaseEventProperties {
     /** Page URL */
     __path?: string;
     /** Page title */
@@ -167,14 +196,14 @@ export interface BaseEventProperties {
 /**
  * Custom event properties that can be attached to any event
  */
-export interface EventProperties extends BaseEventProperties {
+interface EventProperties extends BaseEventProperties {
     /** Custom properties for the event */
     [key: string]: string | number | boolean | null | undefined;
 }
 /**
  * Pre-defined event types with their specific properties
  */
-export interface EventTypeMap {
+interface EventTypeMap {
     screen_view: {
         time_on_page?: number;
         scroll_depth?: number;
@@ -231,15 +260,15 @@ export interface EventTypeMap {
 /**
  * Available event names
  */
-export type EventName = keyof EventTypeMap;
+type EventName = keyof EventTypeMap;
 /**
  * Properties for a specific event type
  */
-export type PropertiesForEvent<T extends EventName> = T extends keyof EventTypeMap ? EventTypeMap[T] & EventProperties : EventProperties;
+type PropertiesForEvent<T extends EventName> = T extends keyof EventTypeMap ? EventTypeMap[T] & EventProperties : EventProperties;
 /**
  * Databuddy tracker instance interface
  */
-export interface DatabuddyTracker {
+interface DatabuddyTracker {
     /**
      * Track a custom event
      */
@@ -284,7 +313,7 @@ declare global {
 /**
  * Helper type for HTML data attributes for automatic tracking
  */
-export interface DataAttributes {
+interface DataAttributes {
     /** Event name to track when element is clicked */
     'data-track': string;
     /** Additional data attributes (converted to camelCase) */
@@ -293,6 +322,17 @@ export interface DataAttributes {
 /**
  * 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;
+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 };