@databuddy/sdk 2.3.1 → 2.3.21

package/dist/shared/@databuddy/{sdk.CeYE_kaj.d.mts → sdk.BsF1xr6_.d.mts}

@@ -13,7 +13,7 @@
  * />
  * ```
  */
-type DatabuddyConfig = {
+interface DatabuddyConfig {
     /**
      * Your Databuddy project client ID.
      * If not provided, will automatically detect from NEXT_PUBLIC_DATABUDDY_CLIENT_ID environment variable.
@@ -149,11 +149,11 @@ type DatabuddyConfig = {
     skipPatterns?: string[];
     /** Array of glob patterns to mask sensitive paths (e.g., ['/users/*']) */
     maskPatterns?: string[];
-};
+}
 /**
  * Base event properties that can be attached to any event
  */
-type BaseEventProperties = {
+interface BaseEventProperties {
     /** Page URL */
     __path?: string;
     /** Page title */
@@ -180,7 +180,7 @@ type BaseEventProperties = {
     utm_campaign?: string;
     utm_term?: string;
     utm_content?: string;
-};
+}
 /**
  * Custom event properties that can be attached to any event
  */
@@ -191,7 +191,7 @@ interface EventProperties extends BaseEventProperties {
 /**
  * Pre-defined event types with their specific properties
  */
-type EventTypeMap = {
+interface EventTypeMap {
     screen_view: {
         time_on_page?: number;
         scroll_depth?: number;
@@ -244,7 +244,7 @@ type EventTypeMap = {
         error_type?: string;
     };
     [eventName: string]: EventProperties;
-};
+}
 /**
  * Available event names
  */
@@ -266,7 +266,7 @@ type PropertiesForEvent<T extends EventName> = T extends keyof EventTypeMap ? Ev
  * const options = window.databuddy.options;
  * ```
  */
-type DatabuddyTracker = {
+interface DatabuddyTracker {
     /**
      * Track a custom event.
      * @param eventName - Name of the event (e.g., "purchase", "signup")
@@ -305,7 +305,7 @@ type DatabuddyTracker = {
      * Current tracker configuration options.
      */
     options: DatabuddyConfig;
-};
+}
 /**
  * Global window interface extensions
  */
@@ -348,12 +348,12 @@ declare global {
  * </a>
  * ```
  */
-type DataAttributes = {
+interface DataAttributes {
     /** Event name to track when element is clicked */
     "data-track": string;
     /** Additional data attributes (auto-converted from kebab-case to camelCase) */
     [key: `data-${string}`]: string;
-};
+}
 /**
  * Utility types for creating typed event tracking functions
  */
@@ -361,4 +361,227 @@ type TrackFunction = <T extends EventName>(eventName: T, properties?: Properties
 type ScreenViewFunction = (properties?: Record<string, unknown>) => void;
 type SetGlobalPropertiesFunction = (properties: EventProperties) => void;
 
-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 b, EventName as c, DataAttributes as d, SetGlobalPropertiesFunction as e };
+/**
+ * Checks if the Databuddy tracker script has loaded and is available.
+ * Use this before calling tracking functions in conditional scenarios.
+ *
+ * @returns `true` if tracker is available, `false` if not loaded or on server
+ *
+ * @example
+ * ```ts
+ * import { isTrackerAvailable, track } from "@databuddy/sdk";
+ *
+ * if (isTrackerAvailable()) {
+ *   track("feature_used", { feature: "export" });
+ * }
+ * ```
+ */
+declare function isTrackerAvailable(): boolean;
+/**
+ * Returns the raw Databuddy tracker instance for advanced use cases.
+ * Prefer using the exported functions (`track`, `flush`, etc.) instead.
+ *
+ * @returns Tracker instance or `null` if not available
+ *
+ * @example
+ * ```ts
+ * import { getTracker, getAnonymousId, getSessionId } from "@databuddy/sdk";
+ *
+ * const tracker = getTracker();
+ * if (tracker) {
+ *   // Access tracker methods
+ *   tracker.track("event", { prop: "value" });
+ *
+ *   // Get IDs using dedicated functions
+ *   const anonId = getAnonymousId();
+ *   const sessionId = getSessionId();
+ * }
+ * ```
+ */
+declare function getTracker(): DatabuddyTracker | null;
+/**
+ * Tracks a custom event with optional properties.
+ * Events are batched and sent efficiently to minimize network overhead.
+ * Safe to call on server (no-op) or before tracker loads.
+ *
+ * @param name - Event name (e.g., "button_click", "purchase", "signup")
+ * @param properties - Key-value pairs of event data
+ *
+ * @example
+ * ```ts
+ * import { track } from "@databuddy/sdk";
+ *
+ * // Simple event
+ * track("signup_started");
+ *
+ * // Event with properties
+ * track("item_purchased", {
+ *   itemId: "sku-123",
+ *   price: 29.99,
+ *   currency: "USD"
+ * });
+ *
+ * // In a React component
+ * function CheckoutButton() {
+ *   return (
+ *     <button onClick={() => track("checkout_clicked", { cartSize: 3 })}>
+ *       Checkout
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function track(name: string, properties?: Record<string, unknown>): void;
+/** @deprecated Use `track()` instead. Will be removed in v3.0. */
+declare function trackCustomEvent(name: string, properties?: Record<string, unknown>): void;
+/**
+ * Clears the current user session and generates new anonymous/session IDs.
+ * Use after logout to ensure the next user gets a fresh identity.
+ *
+ * @example
+ * ```ts
+ * import { clear } from "@databuddy/sdk";
+ *
+ * async function handleLogout() {
+ *   await signOut();
+ *   clear(); // Reset tracking identity
+ *   router.push("/login");
+ * }
+ * ```
+ */
+declare function clear(): void;
+/**
+ * Forces all queued events to be sent immediately.
+ * Useful before navigation or when you need to ensure events are captured.
+ *
+ * @example
+ * ```ts
+ * import { track, flush } from "@databuddy/sdk";
+ *
+ * function handleExternalLink(url: string) {
+ *   track("external_link_clicked", { url });
+ *   flush(); // Ensure event is sent before leaving
+ *   window.location.href = url;
+ * }
+ * ```
+ */
+declare function flush(): void;
+/**
+ * Tracks an error event. Convenience wrapper around `track("error", ...)`.
+ *
+ * @param message - Error message
+ * @param properties - Additional error context (filename, line number, stack trace)
+ *
+ * @example
+ * ```ts
+ * import { trackError } from "@databuddy/sdk";
+ *
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   trackError(error.message, {
+ *     stack: error.stack,
+ *     error_type: error.name,
+ *     context: "checkout_flow"
+ *   });
+ * }
+ * ```
+ */
+declare function trackError(message: string, properties?: {
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    stack?: string;
+    error_type?: string;
+    [key: string]: string | number | boolean | null | undefined;
+}): void;
+/**
+ * Gets the anonymous user ID. Persists across sessions via localStorage.
+ * Useful for server-side identification or cross-domain tracking.
+ *
+ * @param urlParams - Optional URLSearchParams to check for `anonId` param (highest priority)
+ * @returns Anonymous ID or `null` if unavailable
+ *
+ * Priority: URL params → tracker instance → localStorage
+ *
+ * @example
+ * ```ts
+ * import { getAnonymousId } from "@databuddy/sdk";
+ *
+ * // Get from tracker
+ * const anonId = getAnonymousId();
+ *
+ * // Check URL params first (for cross-domain tracking)
+ * const params = new URLSearchParams(window.location.search);
+ * const anonId = getAnonymousId(params);
+ *
+ * // Pass to server
+ * await fetch("/api/identify", {
+ *   body: JSON.stringify({ anonId })
+ * });
+ * ```
+ */
+declare function getAnonymousId(urlParams?: URLSearchParams): string | null;
+/**
+ * Gets the current session ID. Resets after 30 min of inactivity.
+ * Useful for correlating events within a single browsing session.
+ *
+ * @param urlParams - Optional URLSearchParams to check for `sessionId` param (highest priority)
+ * @returns Session ID or `null` if unavailable
+ *
+ * Priority: URL params → tracker instance → sessionStorage
+ *
+ * @example
+ * ```ts
+ * import { getSessionId } from "@databuddy/sdk";
+ *
+ * const sessionId = getSessionId();
+ * console.log("Current session:", sessionId);
+ * ```
+ */
+declare function getSessionId(urlParams?: URLSearchParams): string | null;
+/**
+ * Gets both anonymous ID and session ID in a single call.
+ *
+ * @param urlParams - Optional URLSearchParams to check for tracking params
+ * @returns Object with `anonId` and `sessionId` (either may be null)
+ *
+ * @example
+ * ```ts
+ * import { getTrackingIds } from "@databuddy/sdk";
+ *
+ * const { anonId, sessionId } = getTrackingIds();
+ *
+ * // Send to your backend
+ * await api.identify({ anonId, sessionId, userId: user.id });
+ * ```
+ */
+declare function getTrackingIds(urlParams?: URLSearchParams): {
+    anonId: string | null;
+    sessionId: string | null;
+};
+/**
+ * Returns tracking IDs as a URL query string for cross-domain tracking.
+ * Append to URLs when linking to other domains you own.
+ *
+ * @param urlParams - Optional URLSearchParams to preserve existing params
+ * @returns Query string like `"anonId=xxx&sessionId=yyy"` or empty string
+ *
+ * @example
+ * ```ts
+ * import { getTrackingParams } from "@databuddy/sdk";
+ *
+ * // Link to subdomain with tracking continuity
+ * const params = getTrackingParams();
+ * const url = `https://app.example.com/dashboard${params ? `?${params}` : ""}`;
+ *
+ * // In a component
+ * <a href={`https://shop.example.com?${getTrackingParams()}`}>
+ *   Visit Shop
+ * </a>
+ * ```
+ */
+declare function getTrackingParams(urlParams?: URLSearchParams): string;
+
+export { trackCustomEvent as a, trackError as b, clear as c, getAnonymousId as d, getSessionId as e, flush as f, getTracker as g, getTrackingIds as h, isTrackerAvailable as i, getTrackingParams as j, track as t };
+export type { BaseEventProperties as B, DatabuddyConfig as D, EventProperties as E, PropertiesForEvent as P, ScreenViewFunction as S, TrackFunction as T, EventTypeMap as k, EventName as l, DatabuddyTracker as m, DataAttributes as n, SetGlobalPropertiesFunction as o };

package/dist/shared/@databuddy/{sdk.CeYE_kaj.d.ts → sdk.BsF1xr6_.d.ts}

@@ -13,7 +13,7 @@
  * />
  * ```
  */
-type DatabuddyConfig = {
+interface DatabuddyConfig {
     /**
      * Your Databuddy project client ID.
      * If not provided, will automatically detect from NEXT_PUBLIC_DATABUDDY_CLIENT_ID environment variable.
@@ -149,11 +149,11 @@ type DatabuddyConfig = {
     skipPatterns?: string[];
     /** Array of glob patterns to mask sensitive paths (e.g., ['/users/*']) */
     maskPatterns?: string[];
-};
+}
 /**
  * Base event properties that can be attached to any event
  */
-type BaseEventProperties = {
+interface BaseEventProperties {
     /** Page URL */
     __path?: string;
     /** Page title */
@@ -180,7 +180,7 @@ type BaseEventProperties = {
     utm_campaign?: string;
     utm_term?: string;
     utm_content?: string;
-};
+}
 /**
  * Custom event properties that can be attached to any event
  */
@@ -191,7 +191,7 @@ interface EventProperties extends BaseEventProperties {
 /**
  * Pre-defined event types with their specific properties
  */
-type EventTypeMap = {
+interface EventTypeMap {
     screen_view: {
         time_on_page?: number;
         scroll_depth?: number;
@@ -244,7 +244,7 @@ type EventTypeMap = {
         error_type?: string;
     };
     [eventName: string]: EventProperties;
-};
+}
 /**
  * Available event names
  */
@@ -266,7 +266,7 @@ type PropertiesForEvent<T extends EventName> = T extends keyof EventTypeMap ? Ev
  * const options = window.databuddy.options;
  * ```
  */
-type DatabuddyTracker = {
+interface DatabuddyTracker {
     /**
      * Track a custom event.
      * @param eventName - Name of the event (e.g., "purchase", "signup")
@@ -305,7 +305,7 @@ type DatabuddyTracker = {
      * Current tracker configuration options.
      */
     options: DatabuddyConfig;
-};
+}
 /**
  * Global window interface extensions
  */
@@ -348,12 +348,12 @@ declare global {
  * </a>
  * ```
  */
-type DataAttributes = {
+interface DataAttributes {
     /** Event name to track when element is clicked */
     "data-track": string;
     /** Additional data attributes (auto-converted from kebab-case to camelCase) */
     [key: `data-${string}`]: string;
-};
+}
 /**
  * Utility types for creating typed event tracking functions
  */
@@ -361,4 +361,227 @@ type TrackFunction = <T extends EventName>(eventName: T, properties?: Properties
 type ScreenViewFunction = (properties?: Record<string, unknown>) => void;
 type SetGlobalPropertiesFunction = (properties: EventProperties) => void;
 
-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 b, EventName as c, DataAttributes as d, SetGlobalPropertiesFunction as e };
+/**
+ * Checks if the Databuddy tracker script has loaded and is available.
+ * Use this before calling tracking functions in conditional scenarios.
+ *
+ * @returns `true` if tracker is available, `false` if not loaded or on server
+ *
+ * @example
+ * ```ts
+ * import { isTrackerAvailable, track } from "@databuddy/sdk";
+ *
+ * if (isTrackerAvailable()) {
+ *   track("feature_used", { feature: "export" });
+ * }
+ * ```
+ */
+declare function isTrackerAvailable(): boolean;
+/**
+ * Returns the raw Databuddy tracker instance for advanced use cases.
+ * Prefer using the exported functions (`track`, `flush`, etc.) instead.
+ *
+ * @returns Tracker instance or `null` if not available
+ *
+ * @example
+ * ```ts
+ * import { getTracker, getAnonymousId, getSessionId } from "@databuddy/sdk";
+ *
+ * const tracker = getTracker();
+ * if (tracker) {
+ *   // Access tracker methods
+ *   tracker.track("event", { prop: "value" });
+ *
+ *   // Get IDs using dedicated functions
+ *   const anonId = getAnonymousId();
+ *   const sessionId = getSessionId();
+ * }
+ * ```
+ */
+declare function getTracker(): DatabuddyTracker | null;
+/**
+ * Tracks a custom event with optional properties.
+ * Events are batched and sent efficiently to minimize network overhead.
+ * Safe to call on server (no-op) or before tracker loads.
+ *
+ * @param name - Event name (e.g., "button_click", "purchase", "signup")
+ * @param properties - Key-value pairs of event data
+ *
+ * @example
+ * ```ts
+ * import { track } from "@databuddy/sdk";
+ *
+ * // Simple event
+ * track("signup_started");
+ *
+ * // Event with properties
+ * track("item_purchased", {
+ *   itemId: "sku-123",
+ *   price: 29.99,
+ *   currency: "USD"
+ * });
+ *
+ * // In a React component
+ * function CheckoutButton() {
+ *   return (
+ *     <button onClick={() => track("checkout_clicked", { cartSize: 3 })}>
+ *       Checkout
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function track(name: string, properties?: Record<string, unknown>): void;
+/** @deprecated Use `track()` instead. Will be removed in v3.0. */
+declare function trackCustomEvent(name: string, properties?: Record<string, unknown>): void;
+/**
+ * Clears the current user session and generates new anonymous/session IDs.
+ * Use after logout to ensure the next user gets a fresh identity.
+ *
+ * @example
+ * ```ts
+ * import { clear } from "@databuddy/sdk";
+ *
+ * async function handleLogout() {
+ *   await signOut();
+ *   clear(); // Reset tracking identity
+ *   router.push("/login");
+ * }
+ * ```
+ */
+declare function clear(): void;
+/**
+ * Forces all queued events to be sent immediately.
+ * Useful before navigation or when you need to ensure events are captured.
+ *
+ * @example
+ * ```ts
+ * import { track, flush } from "@databuddy/sdk";
+ *
+ * function handleExternalLink(url: string) {
+ *   track("external_link_clicked", { url });
+ *   flush(); // Ensure event is sent before leaving
+ *   window.location.href = url;
+ * }
+ * ```
+ */
+declare function flush(): void;
+/**
+ * Tracks an error event. Convenience wrapper around `track("error", ...)`.
+ *
+ * @param message - Error message
+ * @param properties - Additional error context (filename, line number, stack trace)
+ *
+ * @example
+ * ```ts
+ * import { trackError } from "@databuddy/sdk";
+ *
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   trackError(error.message, {
+ *     stack: error.stack,
+ *     error_type: error.name,
+ *     context: "checkout_flow"
+ *   });
+ * }
+ * ```
+ */
+declare function trackError(message: string, properties?: {
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+    stack?: string;
+    error_type?: string;
+    [key: string]: string | number | boolean | null | undefined;
+}): void;
+/**
+ * Gets the anonymous user ID. Persists across sessions via localStorage.
+ * Useful for server-side identification or cross-domain tracking.
+ *
+ * @param urlParams - Optional URLSearchParams to check for `anonId` param (highest priority)
+ * @returns Anonymous ID or `null` if unavailable
+ *
+ * Priority: URL params → tracker instance → localStorage
+ *
+ * @example
+ * ```ts
+ * import { getAnonymousId } from "@databuddy/sdk";
+ *
+ * // Get from tracker
+ * const anonId = getAnonymousId();
+ *
+ * // Check URL params first (for cross-domain tracking)
+ * const params = new URLSearchParams(window.location.search);
+ * const anonId = getAnonymousId(params);
+ *
+ * // Pass to server
+ * await fetch("/api/identify", {
+ *   body: JSON.stringify({ anonId })
+ * });
+ * ```
+ */
+declare function getAnonymousId(urlParams?: URLSearchParams): string | null;
+/**
+ * Gets the current session ID. Resets after 30 min of inactivity.
+ * Useful for correlating events within a single browsing session.
+ *
+ * @param urlParams - Optional URLSearchParams to check for `sessionId` param (highest priority)
+ * @returns Session ID or `null` if unavailable
+ *
+ * Priority: URL params → tracker instance → sessionStorage
+ *
+ * @example
+ * ```ts
+ * import { getSessionId } from "@databuddy/sdk";
+ *
+ * const sessionId = getSessionId();
+ * console.log("Current session:", sessionId);
+ * ```
+ */
+declare function getSessionId(urlParams?: URLSearchParams): string | null;
+/**
+ * Gets both anonymous ID and session ID in a single call.
+ *
+ * @param urlParams - Optional URLSearchParams to check for tracking params
+ * @returns Object with `anonId` and `sessionId` (either may be null)
+ *
+ * @example
+ * ```ts
+ * import { getTrackingIds } from "@databuddy/sdk";
+ *
+ * const { anonId, sessionId } = getTrackingIds();
+ *
+ * // Send to your backend
+ * await api.identify({ anonId, sessionId, userId: user.id });
+ * ```
+ */
+declare function getTrackingIds(urlParams?: URLSearchParams): {
+    anonId: string | null;
+    sessionId: string | null;
+};
+/**
+ * Returns tracking IDs as a URL query string for cross-domain tracking.
+ * Append to URLs when linking to other domains you own.
+ *
+ * @param urlParams - Optional URLSearchParams to preserve existing params
+ * @returns Query string like `"anonId=xxx&sessionId=yyy"` or empty string
+ *
+ * @example
+ * ```ts
+ * import { getTrackingParams } from "@databuddy/sdk";
+ *
+ * // Link to subdomain with tracking continuity
+ * const params = getTrackingParams();
+ * const url = `https://app.example.com/dashboard${params ? `?${params}` : ""}`;
+ *
+ * // In a component
+ * <a href={`https://shop.example.com?${getTrackingParams()}`}>
+ *   Visit Shop
+ * </a>
+ * ```
+ */
+declare function getTrackingParams(urlParams?: URLSearchParams): string;
+
+export { trackCustomEvent as a, trackError as b, clear as c, getAnonymousId as d, getSessionId as e, flush as f, getTracker as g, getTrackingIds as h, isTrackerAvailable as i, getTrackingParams as j, track as t };
+export type { BaseEventProperties as B, DatabuddyConfig as D, EventProperties as E, PropertiesForEvent as P, ScreenViewFunction as S, TrackFunction as T, EventTypeMap as k, EventName as l, DatabuddyTracker as m, DataAttributes as n, SetGlobalPropertiesFunction as o };

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

@@ -0,0 +1,35 @@
+const version = "2.3.21";
+
+const INJECTED_SCRIPT_ATTRIBUTE = "data-databuddy-injected";
+function isScriptInjected() {
+  return !!document.querySelector(`script[${INJECTED_SCRIPT_ATTRIBUTE}]`);
+}
+function createScript({
+  scriptUrl,
+  sdkVersion,
+  clientSecret,
+  filter,
+  debug,
+  ...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)) {
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    const dataKey = `data-${key.replace(/([A-Z])/g, "-$1").toLowerCase()}`;
+    if (Array.isArray(value) || value && typeof value === "object") {
+      script.setAttribute(dataKey, JSON.stringify(value));
+    } else {
+      script.setAttribute(dataKey, String(value));
+    }
+  }
+  return script;
+}
+
+export { createScript as c, isScriptInjected as i };