@databuddy/sdk 2.2.12 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -39,8 +39,8 @@ export default function RootLayout({ children }) {
39
39
  <head />
40
40
  <Databuddy
41
41
  clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
42
- trackScreenViews
43
42
  trackPerformance
43
+ trackWebVitals
44
44
  trackErrors
45
45
  enableBatching
46
46
  batchSize={20}
@@ -61,32 +61,32 @@ All options are type-safe and documented in `DatabuddyConfig`:
61
61
  |-----------------------|-----------|--------------|-------------|
62
62
  | `clientId` | string | — | **Required.** Your Databuddy project client ID. |
63
63
  | `clientSecret` | string | — | (Advanced) For server-side use only. |
64
- | `apiUrl` | string | `https://api.databuddy.cc` | Custom API endpoint. |
64
+ | `apiUrl` | string | `https://basket.databuddy.cc` | Custom API endpoint. |
65
65
  | `scriptUrl` | string | `https://cdn.databuddy.cc/databuddy.js` | Custom script URL. |
66
66
  | `sdk` | string | `web` | SDK name. Only override for custom builds. |
67
67
  | `sdkVersion` | string | *auto* | SDK version. Defaults to package version. |
68
68
  | `disabled` | boolean | `false` | Disable all tracking. |
69
- | `waitForProfile` | boolean | `false` | Wait for user profile before sending events. |
70
- | `trackScreenViews` | boolean | `true` | Auto-track page/screen views. |
69
+ | `debug` | boolean | `false` | Enable debug logging (SDK-only). |
71
70
  | `trackHashChanges` | boolean | `false` | Track hash changes in URL. |
72
- | `trackAttributes` | boolean | `false` | Track data-* attributes. |
73
- | `trackOutgoingLinks` | boolean | `false` | Track outgoing link clicks. |
74
- | `trackSessions` | boolean | `true` | Track user sessions. |
75
- | `trackPerformance` | boolean | `true` | Track page performance. |
76
- | `trackWebVitals` | boolean | `true` | Track Web Vitals. |
77
- | `trackEngagement` | boolean | `false` | Track engagement metrics. |
78
- | `trackScrollDepth` | boolean | `false` | Track scroll depth. |
79
- | `trackExitIntent` | boolean | `false` | Track exit intent. |
71
+ | `trackAttributes` | boolean | `false` | Track data-* attributes on elements. |
72
+ | `trackOutgoingLinks` | boolean | `false` | Track clicks on outgoing links. |
80
73
  | `trackInteractions` | boolean | `false` | Track user interactions. |
81
- | `trackErrors` | boolean | `true` | Track JS errors. |
82
- | `trackBounceRate` | boolean | `false` | Track bounce rate. |
74
+ | `trackScrollDepth` | boolean | `false` | Track scroll depth. |
75
+ | `trackPerformance` | boolean | `true` | Track page performance metrics. |
76
+ | `trackWebVitals` | boolean | `false` | Track Web Vitals metrics. |
77
+ | `trackErrors` | boolean | `false` | Track JavaScript errors. |
78
+ | `ignoreBotDetection` | boolean | `false` | Ignore bot detection. |
79
+ | `usePixel` | boolean | `false` | Use pixel tracking instead of script. |
83
80
  | `samplingRate` | number | `1.0` | Sampling rate (0.0–1.0). |
84
- | `enableRetries` | boolean | `true` | Retry failed requests. |
81
+ | `enableRetries` | boolean | `false` | Enable retries for failed requests. |
85
82
  | `maxRetries` | number | `3` | Max retries. |
86
83
  | `initialRetryDelay` | number | `500` | Initial retry delay (ms). |
87
- | `enableBatching` | boolean | `true` | Enable event batching. |
88
- | `batchSize` | number | `20` | Events per batch (1–50). |
84
+ | `enableBatching` | boolean | `true` | Enable event batching. |
85
+ | `batchSize` | number | `10` | Events per batch (1–50). |
89
86
  | `batchTimeout` | number | `5000` | Batch timeout (ms, 100–30000). |
87
+ | `skipPatterns` | string[] | — | Array of glob patterns to skip tracking. |
88
+ | `maskPatterns` | string[] | — | Array of glob patterns to mask sensitive paths. |
89
+ | `filter` | function | — | Filter function to conditionally skip events. |
90
90
 
91
91
  ---
92
92
 
@@ -1,7 +1,7 @@
1
1
  import { S as StorageInterface, F as FlagsManager, a as FlagsManagerOptions, b as FlagResult, c as FlagState, d as FlagsConfig } from '../shared/@databuddy/sdk.OK9Nbqlf.mjs';
2
2
  export { e as FlagsContext } from '../shared/@databuddy/sdk.OK9Nbqlf.mjs';
3
- import { D as DatabuddyConfig, a as DatabuddyTracker } from '../shared/@databuddy/sdk.CLiT66HO.mjs';
4
- export { B as BaseEventProperties, d as DataAttributes, c as EventName, E as EventProperties, b as EventTypeMap, P as PropertiesForEvent, S as ScreenViewFunction, e as SetGlobalPropertiesFunction, T as TrackFunction } from '../shared/@databuddy/sdk.CLiT66HO.mjs';
3
+ import { D as DatabuddyConfig, a as DatabuddyTracker } from '../shared/@databuddy/sdk.CeYE_kaj.mjs';
4
+ export { B as BaseEventProperties, d as DataAttributes, c as EventName, E as EventProperties, b as EventTypeMap, P as PropertiesForEvent, S as ScreenViewFunction, e as SetGlobalPropertiesFunction, T as TrackFunction } from '../shared/@databuddy/sdk.CeYE_kaj.mjs';
5
5
 
6
6
  /**
7
7
  * Auto-detect Databuddy client ID from environment variables
@@ -48,40 +48,133 @@ declare class CoreFlagsManager implements FlagsManager {
48
48
  }
49
49
 
50
50
  declare function isScriptInjected(): boolean;
51
- declare function createScript({ scriptUrl, sdkVersion, ...props }: DatabuddyConfig): HTMLScriptElement;
51
+ declare function createScript({ scriptUrl, sdkVersion, clientSecret, filter, debug, ...props }: DatabuddyConfig): HTMLScriptElement;
52
52
 
53
53
  /**
54
- * Databuddy SDK Client-side Tracker
55
- * Provides type-safe tracking functions
56
- */
57
-
58
- /**
59
- * Check if the Databuddy tracker is available
54
+ * Checks if the Databuddy tracker script has loaded and is available.
55
+ * Use this before calling tracking functions in conditional scenarios.
56
+ *
57
+ * @returns `true` if tracker is available, `false` if not loaded or on server
58
+ *
59
+ * @example
60
+ * ```ts
61
+ * import { isTrackerAvailable, track } from "@databuddy/sdk";
62
+ *
63
+ * if (isTrackerAvailable()) {
64
+ * track("feature_used", { feature: "export" });
65
+ * }
66
+ * ```
60
67
  */
61
68
  declare function isTrackerAvailable(): boolean;
62
69
  /**
63
- * Get the Databuddy tracker instance
70
+ * Returns the raw Databuddy tracker instance for advanced use cases.
71
+ * Prefer using the exported functions (`track`, `flush`, etc.) instead.
72
+ *
73
+ * @returns Tracker instance or `null` if not available
74
+ *
75
+ * @example
76
+ * ```ts
77
+ * import { getTracker, getAnonymousId, getSessionId } from "@databuddy/sdk";
78
+ *
79
+ * const tracker = getTracker();
80
+ * if (tracker) {
81
+ * // Access tracker methods
82
+ * tracker.track("event", { prop: "value" });
83
+ *
84
+ * // Get IDs using dedicated functions
85
+ * const anonId = getAnonymousId();
86
+ * const sessionId = getSessionId();
87
+ * }
88
+ * ```
64
89
  */
65
90
  declare function getTracker(): DatabuddyTracker | null;
66
91
  /**
67
- * Track a custom event (lean, goes to custom_event_spans table)
92
+ * Tracks a custom event with optional properties.
93
+ * Events are batched and sent efficiently to minimize network overhead.
94
+ * Safe to call on server (no-op) or before tracker loads.
95
+ *
96
+ * @param name - Event name (e.g., "button_click", "purchase", "signup")
97
+ * @param properties - Key-value pairs of event data
98
+ *
99
+ * @example
100
+ * ```ts
101
+ * import { track } from "@databuddy/sdk";
102
+ *
103
+ * // Simple event
104
+ * track("signup_started");
105
+ *
106
+ * // Event with properties
107
+ * track("item_purchased", {
108
+ * itemId: "sku-123",
109
+ * price: 29.99,
110
+ * currency: "USD"
111
+ * });
112
+ *
113
+ * // In a React component
114
+ * function CheckoutButton() {
115
+ * return (
116
+ * <button onClick={() => track("checkout_clicked", { cartSize: 3 })}>
117
+ * Checkout
118
+ * </button>
119
+ * );
120
+ * }
121
+ * ```
68
122
  */
123
+ declare function track(name: string, properties?: Record<string, unknown>): void;
124
+ /** @deprecated Use `track()` instead. Will be removed in v3.0. */
69
125
  declare function trackCustomEvent(name: string, properties?: Record<string, unknown>): void;
70
126
  /**
71
- * Track a custom event (alias for trackCustomEvent)
72
- * Goes to the lean custom_event_spans table
73
- */
74
- declare function track(eventName: string, properties?: Record<string, unknown>): void;
75
- /**
76
- * Clear the current session
127
+ * Clears the current user session and generates new anonymous/session IDs.
128
+ * Use after logout to ensure the next user gets a fresh identity.
129
+ *
130
+ * @example
131
+ * ```ts
132
+ * import { clear } from "@databuddy/sdk";
133
+ *
134
+ * async function handleLogout() {
135
+ * await signOut();
136
+ * clear(); // Reset tracking identity
137
+ * router.push("/login");
138
+ * }
139
+ * ```
77
140
  */
78
141
  declare function clear(): void;
79
142
  /**
80
- * Flush any queued events
143
+ * Forces all queued events to be sent immediately.
144
+ * Useful before navigation or when you need to ensure events are captured.
145
+ *
146
+ * @example
147
+ * ```ts
148
+ * import { track, flush } from "@databuddy/sdk";
149
+ *
150
+ * function handleExternalLink(url: string) {
151
+ * track("external_link_clicked", { url });
152
+ * flush(); // Ensure event is sent before leaving
153
+ * window.location.href = url;
154
+ * }
155
+ * ```
81
156
  */
82
157
  declare function flush(): void;
83
158
  /**
84
- * Track an error event
159
+ * Tracks an error event. Convenience wrapper around `track("error", ...)`.
160
+ *
161
+ * @param message - Error message
162
+ * @param properties - Additional error context (filename, line number, stack trace)
163
+ *
164
+ * @example
165
+ * ```ts
166
+ * import { trackError } from "@databuddy/sdk";
167
+ *
168
+ * try {
169
+ * await riskyOperation();
170
+ * } catch (error) {
171
+ * trackError(error.message, {
172
+ * stack: error.stack,
173
+ * error_type: error.name,
174
+ * context: "checkout_flow"
175
+ * });
176
+ * }
177
+ * ```
85
178
  */
86
179
  declare function trackError(message: string, properties?: {
87
180
  filename?: string;
@@ -92,25 +185,90 @@ declare function trackError(message: string, properties?: {
92
185
  [key: string]: string | number | boolean | null | undefined;
93
186
  }): void;
94
187
  /**
95
- * Get anonymous ID from multiple sources
96
- * Priority: URL params > tracker instance > localStorage
188
+ * Gets the anonymous user ID. Persists across sessions via localStorage.
189
+ * Useful for server-side identification or cross-domain tracking.
190
+ *
191
+ * @param urlParams - Optional URLSearchParams to check for `anonId` param (highest priority)
192
+ * @returns Anonymous ID or `null` if unavailable
193
+ *
194
+ * Priority: URL params → tracker instance → localStorage
195
+ *
196
+ * @example
197
+ * ```ts
198
+ * import { getAnonymousId } from "@databuddy/sdk";
199
+ *
200
+ * // Get from tracker
201
+ * const anonId = getAnonymousId();
202
+ *
203
+ * // Check URL params first (for cross-domain tracking)
204
+ * const params = new URLSearchParams(window.location.search);
205
+ * const anonId = getAnonymousId(params);
206
+ *
207
+ * // Pass to server
208
+ * await fetch("/api/identify", {
209
+ * body: JSON.stringify({ anonId })
210
+ * });
211
+ * ```
97
212
  */
98
213
  declare function getAnonymousId(urlParams?: URLSearchParams): string | null;
99
214
  /**
100
- * Get session ID from multiple sources
101
- * Priority: URL params > tracker instance > sessionStorage
215
+ * Gets the current session ID. Resets after 30 min of inactivity.
216
+ * Useful for correlating events within a single browsing session.
217
+ *
218
+ * @param urlParams - Optional URLSearchParams to check for `sessionId` param (highest priority)
219
+ * @returns Session ID or `null` if unavailable
220
+ *
221
+ * Priority: URL params → tracker instance → sessionStorage
222
+ *
223
+ * @example
224
+ * ```ts
225
+ * import { getSessionId } from "@databuddy/sdk";
226
+ *
227
+ * const sessionId = getSessionId();
228
+ * console.log("Current session:", sessionId);
229
+ * ```
102
230
  */
103
231
  declare function getSessionId(urlParams?: URLSearchParams): string | null;
104
232
  /**
105
- * Get tracking IDs (anonymous ID and session ID) from multiple sources
106
- * Priority: URL params > tracker instance > localStorage/sessionStorage
233
+ * Gets both anonymous ID and session ID in a single call.
234
+ *
235
+ * @param urlParams - Optional URLSearchParams to check for tracking params
236
+ * @returns Object with `anonId` and `sessionId` (either may be null)
237
+ *
238
+ * @example
239
+ * ```ts
240
+ * import { getTrackingIds } from "@databuddy/sdk";
241
+ *
242
+ * const { anonId, sessionId } = getTrackingIds();
243
+ *
244
+ * // Send to your backend
245
+ * await api.identify({ anonId, sessionId, userId: user.id });
246
+ * ```
107
247
  */
108
248
  declare function getTrackingIds(urlParams?: URLSearchParams): {
109
249
  anonId: string | null;
110
250
  sessionId: string | null;
111
251
  };
112
252
  /**
113
- * Get tracking IDs as URL search params string
253
+ * Returns tracking IDs as a URL query string for cross-domain tracking.
254
+ * Append to URLs when linking to other domains you own.
255
+ *
256
+ * @param urlParams - Optional URLSearchParams to preserve existing params
257
+ * @returns Query string like `"anonId=xxx&sessionId=yyy"` or empty string
258
+ *
259
+ * @example
260
+ * ```ts
261
+ * import { getTrackingParams } from "@databuddy/sdk";
262
+ *
263
+ * // Link to subdomain with tracking continuity
264
+ * const params = getTrackingParams();
265
+ * const url = `https://app.example.com/dashboard${params ? `?${params}` : ""}`;
266
+ *
267
+ * // In a component
268
+ * <a href={`https://shop.example.com?${getTrackingParams()}`}>
269
+ * Visit Shop
270
+ * </a>
271
+ * ```
114
272
  */
115
273
  declare function getTrackingParams(urlParams?: URLSearchParams): string;
116
274
 
@@ -1,7 +1,7 @@
1
1
  import { S as StorageInterface, F as FlagsManager, a as FlagsManagerOptions, b as FlagResult, c as FlagState, d as FlagsConfig } from '../shared/@databuddy/sdk.OK9Nbqlf.js';
2
2
  export { e as FlagsContext } from '../shared/@databuddy/sdk.OK9Nbqlf.js';
3
- import { D as DatabuddyConfig, a as DatabuddyTracker } from '../shared/@databuddy/sdk.CLiT66HO.js';
4
- export { B as BaseEventProperties, d as DataAttributes, c as EventName, E as EventProperties, b as EventTypeMap, P as PropertiesForEvent, S as ScreenViewFunction, e as SetGlobalPropertiesFunction, T as TrackFunction } from '../shared/@databuddy/sdk.CLiT66HO.js';
3
+ import { D as DatabuddyConfig, a as DatabuddyTracker } from '../shared/@databuddy/sdk.CeYE_kaj.js';
4
+ export { B as BaseEventProperties, d as DataAttributes, c as EventName, E as EventProperties, b as EventTypeMap, P as PropertiesForEvent, S as ScreenViewFunction, e as SetGlobalPropertiesFunction, T as TrackFunction } from '../shared/@databuddy/sdk.CeYE_kaj.js';
5
5
 
6
6
  /**
7
7
  * Auto-detect Databuddy client ID from environment variables
@@ -48,40 +48,133 @@ declare class CoreFlagsManager implements FlagsManager {
48
48
  }
49
49
 
50
50
  declare function isScriptInjected(): boolean;
51
- declare function createScript({ scriptUrl, sdkVersion, ...props }: DatabuddyConfig): HTMLScriptElement;
51
+ declare function createScript({ scriptUrl, sdkVersion, clientSecret, filter, debug, ...props }: DatabuddyConfig): HTMLScriptElement;
52
52
 
53
53
  /**
54
- * Databuddy SDK Client-side Tracker
55
- * Provides type-safe tracking functions
56
- */
57
-
58
- /**
59
- * Check if the Databuddy tracker is available
54
+ * Checks if the Databuddy tracker script has loaded and is available.
55
+ * Use this before calling tracking functions in conditional scenarios.
56
+ *
57
+ * @returns `true` if tracker is available, `false` if not loaded or on server
58
+ *
59
+ * @example
60
+ * ```ts
61
+ * import { isTrackerAvailable, track } from "@databuddy/sdk";
62
+ *
63
+ * if (isTrackerAvailable()) {
64
+ * track("feature_used", { feature: "export" });
65
+ * }
66
+ * ```
60
67
  */
61
68
  declare function isTrackerAvailable(): boolean;
62
69
  /**
63
- * Get the Databuddy tracker instance
70
+ * Returns the raw Databuddy tracker instance for advanced use cases.
71
+ * Prefer using the exported functions (`track`, `flush`, etc.) instead.
72
+ *
73
+ * @returns Tracker instance or `null` if not available
74
+ *
75
+ * @example
76
+ * ```ts
77
+ * import { getTracker, getAnonymousId, getSessionId } from "@databuddy/sdk";
78
+ *
79
+ * const tracker = getTracker();
80
+ * if (tracker) {
81
+ * // Access tracker methods
82
+ * tracker.track("event", { prop: "value" });
83
+ *
84
+ * // Get IDs using dedicated functions
85
+ * const anonId = getAnonymousId();
86
+ * const sessionId = getSessionId();
87
+ * }
88
+ * ```
64
89
  */
65
90
  declare function getTracker(): DatabuddyTracker | null;
66
91
  /**
67
- * Track a custom event (lean, goes to custom_event_spans table)
92
+ * Tracks a custom event with optional properties.
93
+ * Events are batched and sent efficiently to minimize network overhead.
94
+ * Safe to call on server (no-op) or before tracker loads.
95
+ *
96
+ * @param name - Event name (e.g., "button_click", "purchase", "signup")
97
+ * @param properties - Key-value pairs of event data
98
+ *
99
+ * @example
100
+ * ```ts
101
+ * import { track } from "@databuddy/sdk";
102
+ *
103
+ * // Simple event
104
+ * track("signup_started");
105
+ *
106
+ * // Event with properties
107
+ * track("item_purchased", {
108
+ * itemId: "sku-123",
109
+ * price: 29.99,
110
+ * currency: "USD"
111
+ * });
112
+ *
113
+ * // In a React component
114
+ * function CheckoutButton() {
115
+ * return (
116
+ * <button onClick={() => track("checkout_clicked", { cartSize: 3 })}>
117
+ * Checkout
118
+ * </button>
119
+ * );
120
+ * }
121
+ * ```
68
122
  */
123
+ declare function track(name: string, properties?: Record<string, unknown>): void;
124
+ /** @deprecated Use `track()` instead. Will be removed in v3.0. */
69
125
  declare function trackCustomEvent(name: string, properties?: Record<string, unknown>): void;
70
126
  /**
71
- * Track a custom event (alias for trackCustomEvent)
72
- * Goes to the lean custom_event_spans table
73
- */
74
- declare function track(eventName: string, properties?: Record<string, unknown>): void;
75
- /**
76
- * Clear the current session
127
+ * Clears the current user session and generates new anonymous/session IDs.
128
+ * Use after logout to ensure the next user gets a fresh identity.
129
+ *
130
+ * @example
131
+ * ```ts
132
+ * import { clear } from "@databuddy/sdk";
133
+ *
134
+ * async function handleLogout() {
135
+ * await signOut();
136
+ * clear(); // Reset tracking identity
137
+ * router.push("/login");
138
+ * }
139
+ * ```
77
140
  */
78
141
  declare function clear(): void;
79
142
  /**
80
- * Flush any queued events
143
+ * Forces all queued events to be sent immediately.
144
+ * Useful before navigation or when you need to ensure events are captured.
145
+ *
146
+ * @example
147
+ * ```ts
148
+ * import { track, flush } from "@databuddy/sdk";
149
+ *
150
+ * function handleExternalLink(url: string) {
151
+ * track("external_link_clicked", { url });
152
+ * flush(); // Ensure event is sent before leaving
153
+ * window.location.href = url;
154
+ * }
155
+ * ```
81
156
  */
82
157
  declare function flush(): void;
83
158
  /**
84
- * Track an error event
159
+ * Tracks an error event. Convenience wrapper around `track("error", ...)`.
160
+ *
161
+ * @param message - Error message
162
+ * @param properties - Additional error context (filename, line number, stack trace)
163
+ *
164
+ * @example
165
+ * ```ts
166
+ * import { trackError } from "@databuddy/sdk";
167
+ *
168
+ * try {
169
+ * await riskyOperation();
170
+ * } catch (error) {
171
+ * trackError(error.message, {
172
+ * stack: error.stack,
173
+ * error_type: error.name,
174
+ * context: "checkout_flow"
175
+ * });
176
+ * }
177
+ * ```
85
178
  */
86
179
  declare function trackError(message: string, properties?: {
87
180
  filename?: string;
@@ -92,25 +185,90 @@ declare function trackError(message: string, properties?: {
92
185
  [key: string]: string | number | boolean | null | undefined;
93
186
  }): void;
94
187
  /**
95
- * Get anonymous ID from multiple sources
96
- * Priority: URL params > tracker instance > localStorage
188
+ * Gets the anonymous user ID. Persists across sessions via localStorage.
189
+ * Useful for server-side identification or cross-domain tracking.
190
+ *
191
+ * @param urlParams - Optional URLSearchParams to check for `anonId` param (highest priority)
192
+ * @returns Anonymous ID or `null` if unavailable
193
+ *
194
+ * Priority: URL params → tracker instance → localStorage
195
+ *
196
+ * @example
197
+ * ```ts
198
+ * import { getAnonymousId } from "@databuddy/sdk";
199
+ *
200
+ * // Get from tracker
201
+ * const anonId = getAnonymousId();
202
+ *
203
+ * // Check URL params first (for cross-domain tracking)
204
+ * const params = new URLSearchParams(window.location.search);
205
+ * const anonId = getAnonymousId(params);
206
+ *
207
+ * // Pass to server
208
+ * await fetch("/api/identify", {
209
+ * body: JSON.stringify({ anonId })
210
+ * });
211
+ * ```
97
212
  */
98
213
  declare function getAnonymousId(urlParams?: URLSearchParams): string | null;
99
214
  /**
100
- * Get session ID from multiple sources
101
- * Priority: URL params > tracker instance > sessionStorage
215
+ * Gets the current session ID. Resets after 30 min of inactivity.
216
+ * Useful for correlating events within a single browsing session.
217
+ *
218
+ * @param urlParams - Optional URLSearchParams to check for `sessionId` param (highest priority)
219
+ * @returns Session ID or `null` if unavailable
220
+ *
221
+ * Priority: URL params → tracker instance → sessionStorage
222
+ *
223
+ * @example
224
+ * ```ts
225
+ * import { getSessionId } from "@databuddy/sdk";
226
+ *
227
+ * const sessionId = getSessionId();
228
+ * console.log("Current session:", sessionId);
229
+ * ```
102
230
  */
103
231
  declare function getSessionId(urlParams?: URLSearchParams): string | null;
104
232
  /**
105
- * Get tracking IDs (anonymous ID and session ID) from multiple sources
106
- * Priority: URL params > tracker instance > localStorage/sessionStorage
233
+ * Gets both anonymous ID and session ID in a single call.
234
+ *
235
+ * @param urlParams - Optional URLSearchParams to check for tracking params
236
+ * @returns Object with `anonId` and `sessionId` (either may be null)
237
+ *
238
+ * @example
239
+ * ```ts
240
+ * import { getTrackingIds } from "@databuddy/sdk";
241
+ *
242
+ * const { anonId, sessionId } = getTrackingIds();
243
+ *
244
+ * // Send to your backend
245
+ * await api.identify({ anonId, sessionId, userId: user.id });
246
+ * ```
107
247
  */
108
248
  declare function getTrackingIds(urlParams?: URLSearchParams): {
109
249
  anonId: string | null;
110
250
  sessionId: string | null;
111
251
  };
112
252
  /**
113
- * Get tracking IDs as URL search params string
253
+ * Returns tracking IDs as a URL query string for cross-domain tracking.
254
+ * Append to URLs when linking to other domains you own.
255
+ *
256
+ * @param urlParams - Optional URLSearchParams to preserve existing params
257
+ * @returns Query string like `"anonId=xxx&sessionId=yyy"` or empty string
258
+ *
259
+ * @example
260
+ * ```ts
261
+ * import { getTrackingParams } from "@databuddy/sdk";
262
+ *
263
+ * // Link to subdomain with tracking continuity
264
+ * const params = getTrackingParams();
265
+ * const url = `https://app.example.com/dashboard${params ? `?${params}` : ""}`;
266
+ *
267
+ * // In a component
268
+ * <a href={`https://shop.example.com?${getTrackingParams()}`}>
269
+ * Visit Shop
270
+ * </a>
271
+ * ```
114
272
  */
115
273
  declare function getTrackingParams(urlParams?: URLSearchParams): string;
116
274
 
@@ -1,5 +1,5 @@
1
1
  export { d as detectClientId } from '../shared/@databuddy/sdk.BUsPV0LH.mjs';
2
- export { B as BrowserFlagStorage, C as CoreFlagsManager, c as createScript, i as isScriptInjected } from '../shared/@databuddy/sdk.IxoH6TAZ.mjs';
2
+ export { B as BrowserFlagStorage, C as CoreFlagsManager, c as createScript, i as isScriptInjected } from '../shared/@databuddy/sdk.ByNF_UxE.mjs';
3
3
 
4
4
  function isTrackerAvailable() {
5
5
  return typeof window !== "undefined" && (!!window.databuddy || !!window.db);
@@ -10,22 +10,22 @@ function getTracker() {
10
10
  }
11
11
  return window.databuddy || null;
12
12
  }
13
- function trackCustomEvent(name, properties) {
13
+ function track(name, properties) {
14
14
  if (typeof window === "undefined") {
15
15
  return;
16
16
  }
17
- const tracker = window.db?.trackCustomEvent || window.databuddy?.trackCustomEvent;
17
+ const tracker = window.db?.track || window.databuddy?.track;
18
18
  if (!tracker) {
19
19
  return;
20
20
  }
21
21
  try {
22
22
  tracker(name, properties);
23
23
  } catch (error) {
24
- console.error("Databuddy trackCustomEvent error:", error);
24
+ console.error("Databuddy track error:", error);
25
25
  }
26
26
  }
27
- function track(eventName, properties) {
28
- trackCustomEvent(eventName, properties);
27
+ function trackCustomEvent(name, properties) {
28
+ track(name, properties);
29
29
  }
30
30
  function clear() {
31
31
  if (typeof window === "undefined") {
@@ -62,13 +62,13 @@ function getAnonymousId(urlParams) {
62
62
  if (typeof window === "undefined") {
63
63
  return null;
64
64
  }
65
- return urlParams?.get("anonId") || window.databuddy?.anonymousId || localStorage.getItem("did") || null;
65
+ return urlParams?.get("anonId") || localStorage.getItem("did") || null;
66
66
  }
67
67
  function getSessionId(urlParams) {
68
68
  if (typeof window === "undefined") {
69
69
  return null;
70
70
  }
71
- return urlParams?.get("sessionId") || window.databuddy?.sessionId || sessionStorage.getItem("did_session") || null;
71
+ return urlParams?.get("sessionId") || sessionStorage.getItem("did_session") || null;
72
72
  }
73
73
  function getTrackingIds(urlParams) {
74
74
  return {
@@ -1,13 +1,5 @@
1
1
  function createLogger(debug = false) {
2
- try {
3
- const pino = require("pino");
4
- return pino({
5
- level: debug ? "debug" : "info",
6
- name: "databuddy"
7
- });
8
- } catch {
9
- return createConsoleLogger(debug);
10
- }
2
+ return createConsoleLogger(debug);
11
3
  }
12
4
  function createConsoleLogger(debug) {
13
5
  const noop = () => {
@@ -1,4 +1,4 @@
1
- import { D as DatabuddyConfig } from '../shared/@databuddy/sdk.CLiT66HO.mjs';
1
+ import { D as DatabuddyConfig } from '../shared/@databuddy/sdk.CeYE_kaj.mjs';
2
2
  import * as react from 'react';
3
3
  import { ReactNode } from 'react';
4
4
  import * as jotai_vanilla_internals from 'jotai/vanilla/internals';
@@ -6,10 +6,53 @@ import { d as FlagsConfig, c as FlagState } from '../shared/@databuddy/sdk.OK9Nb
6
6
  export { b as FlagResult, e as FlagsContext } from '../shared/@databuddy/sdk.OK9Nbqlf.mjs';
7
7
 
8
8
  /**
9
- * <Databuddy /> component for Next.js/React apps
10
- * Injects the databuddy.js script with all config as data attributes
11
- * Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
12
- * Or simply: <Databuddy /> (auto-detects clientId from environment variables)
9
+ * React/Next.js component that injects the Databuddy tracking script.
10
+ * Place this in your root layout or `_app.tsx`. Renders nothing to the DOM.
11
+ *
12
+ * Auto-detects `clientId` from `NEXT_PUBLIC_DATABUDDY_CLIENT_ID` env var if not provided.
13
+ *
14
+ * @param props - Configuration options for the tracker
15
+ *
16
+ * @example
17
+ * ```tsx
18
+ * // app/layout.tsx (Next.js App Router)
19
+ * import { Databuddy } from "@databuddy/sdk/react";
20
+ *
21
+ * export default function RootLayout({ children }) {
22
+ * return (
23
+ * <html>
24
+ * <body>
25
+ * {children}
26
+ * <Databuddy
27
+ * apiUrl="https://basket.databuddy.cc"
28
+ * trackWebVitals
29
+ * trackErrors
30
+ * />
31
+ * </body>
32
+ * </html>
33
+ * );
34
+ * }
35
+ * ```
36
+ *
37
+ * @example
38
+ * ```tsx
39
+ * // With explicit clientId
40
+ * <Databuddy
41
+ * clientId="your-client-id"
42
+ * trackWebVitals
43
+ * trackScrollDepth
44
+ * trackOutgoingLinks
45
+ * />
46
+ * ```
47
+ *
48
+ * @example
49
+ * ```tsx
50
+ * // Disable in development
51
+ * <Databuddy
52
+ * disabled={process.env.NODE_ENV === "development"}
53
+ * trackWebVitals
54
+ * />
55
+ * ```
13
56
  */
14
57
  declare function Databuddy(props: DatabuddyConfig): null;
15
58
 
@@ -1,4 +1,4 @@
1
- import { D as DatabuddyConfig } from '../shared/@databuddy/sdk.CLiT66HO.js';
1
+ import { D as DatabuddyConfig } from '../shared/@databuddy/sdk.CeYE_kaj.js';
2
2
  import * as react from 'react';
3
3
  import { ReactNode } from 'react';
4
4
  import * as jotai_vanilla_internals from 'jotai/vanilla/internals';
@@ -6,10 +6,53 @@ import { d as FlagsConfig, c as FlagState } from '../shared/@databuddy/sdk.OK9Nb
6
6
  export { b as FlagResult, e as FlagsContext } from '../shared/@databuddy/sdk.OK9Nbqlf.js';
7
7
 
8
8
  /**
9
- * <Databuddy /> component for Next.js/React apps
10
- * Injects the databuddy.js script with all config as data attributes
11
- * Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
12
- * Or simply: <Databuddy /> (auto-detects clientId from environment variables)
9
+ * React/Next.js component that injects the Databuddy tracking script.
10
+ * Place this in your root layout or `_app.tsx`. Renders nothing to the DOM.
11
+ *
12
+ * Auto-detects `clientId` from `NEXT_PUBLIC_DATABUDDY_CLIENT_ID` env var if not provided.
13
+ *
14
+ * @param props - Configuration options for the tracker
15
+ *
16
+ * @example
17
+ * ```tsx
18
+ * // app/layout.tsx (Next.js App Router)
19
+ * import { Databuddy } from "@databuddy/sdk/react";
20
+ *
21
+ * export default function RootLayout({ children }) {
22
+ * return (
23
+ * <html>
24
+ * <body>
25
+ * {children}
26
+ * <Databuddy
27
+ * apiUrl="https://basket.databuddy.cc"
28
+ * trackWebVitals
29
+ * trackErrors
30
+ * />
31
+ * </body>
32
+ * </html>
33
+ * );
34
+ * }
35
+ * ```
36
+ *
37
+ * @example
38
+ * ```tsx
39
+ * // With explicit clientId
40
+ * <Databuddy
41
+ * clientId="your-client-id"
42
+ * trackWebVitals
43
+ * trackScrollDepth
44
+ * trackOutgoingLinks
45
+ * />
46
+ * ```
47
+ *
48
+ * @example
49
+ * ```tsx
50
+ * // Disable in development
51
+ * <Databuddy
52
+ * disabled={process.env.NODE_ENV === "development"}
53
+ * trackWebVitals
54
+ * />
55
+ * ```
13
56
  */
14
57
  declare function Databuddy(props: DatabuddyConfig): null;
15
58
 
@@ -1,6 +1,6 @@
1
1
  'use client';
2
2
 
3
- import { i as isScriptInjected, c as createScript, B as BrowserFlagStorage, C as CoreFlagsManager, l as logger } from '../shared/@databuddy/sdk.IxoH6TAZ.mjs';
3
+ import { i as isScriptInjected, c as createScript, B as BrowserFlagStorage, C as CoreFlagsManager, l as logger } from '../shared/@databuddy/sdk.ByNF_UxE.mjs';
4
4
  import { d as detectClientId } from '../shared/@databuddy/sdk.BUsPV0LH.mjs';
5
5
  import { createStore, atom, Provider, useAtom } from 'jotai';
6
6
  import { useRef, useEffect, createElement } from 'react';
@@ -434,7 +434,7 @@ class CoreFlagsManager {
434
434
  }
435
435
  }
436
436
 
437
- const version = "2.2.11";
437
+ const version = "2.3.0";
438
438
 
439
439
  const INJECTED_SCRIPT_ATTRIBUTE = "data-databuddy-injected";
440
440
  function isScriptInjected() {
@@ -443,6 +443,9 @@ function isScriptInjected() {
443
443
  function createScript({
444
444
  scriptUrl,
445
445
  sdkVersion,
446
+ clientSecret,
447
+ filter,
448
+ debug,
446
449
  ...props
447
450
  }) {
448
451
  const script = document.createElement("script");
@@ -452,6 +455,9 @@ function createScript({
452
455
  script.setAttribute(INJECTED_SCRIPT_ATTRIBUTE, "true");
453
456
  script.setAttribute("data-sdk-version", sdkVersion || version);
454
457
  for (const [key, value] of Object.entries(props)) {
458
+ if (value === void 0 || value === null) {
459
+ continue;
460
+ }
455
461
  const dataKey = `data-${key.replace(/([A-Z])/g, "-$1").toLowerCase()}`;
456
462
  if (Array.isArray(value) || value && typeof value === "object") {
457
463
  script.setAttribute(dataKey, JSON.stringify(value));
@@ -1,6 +1,17 @@
1
1
  /**
2
- * Configuration options for the Databuddy SDK and <Databuddy /> component.
3
- * All options are passed as data attributes to the injected script.
2
+ * Configuration for the `<Databuddy />` component and tracker script.
3
+ *
4
+ * @example
5
+ * ```tsx
6
+ * <Databuddy
7
+ * clientId="your-client-id"
8
+ * apiUrl="https://basket.databuddy.cc"
9
+ * trackWebVitals
10
+ * trackErrors
11
+ * trackScrollDepth
12
+ * samplingRate={0.5}
13
+ * />
14
+ * ```
4
15
  */
5
16
  type DatabuddyConfig = {
6
17
  /**
@@ -82,7 +93,7 @@ type DatabuddyConfig = {
82
93
  */
83
94
  samplingRate?: number;
84
95
  /**
85
- * Enable retries for failed requests (default: true).
96
+ * Enable retries for failed requests (default: false).
86
97
  */
87
98
  enableRetries?: boolean;
88
99
  /**
@@ -96,7 +107,7 @@ type DatabuddyConfig = {
96
107
  */
97
108
  initialRetryDelay?: number;
98
109
  /**
99
- * Enable event batching (default: false).
110
+ * Enable event batching (default: true).
100
111
  */
101
112
  enableBatching?: boolean;
102
113
  /**
@@ -111,8 +122,32 @@ type DatabuddyConfig = {
111
122
  * Min: 100, Max: 30000
112
123
  */
113
124
  batchTimeout?: number;
125
+ /**
126
+ * Ignore bot detection (default: false).
127
+ * If true, bot detection will be disabled and bots will be tracked.
128
+ */
129
+ ignoreBotDetection?: boolean;
130
+ /**
131
+ * Use pixel tracking instead of script (default: false).
132
+ * When enabled, uses a 1x1 pixel image for tracking.
133
+ */
134
+ usePixel?: boolean;
135
+ /**
136
+ * Filter function to conditionally skip events.
137
+ * Return false to skip the event, true to send it.
138
+ *
139
+ * @example
140
+ * ```ts
141
+ * filter: (event) => {
142
+ * // Skip events from admin pages
143
+ * return !event.path?.includes('/admin');
144
+ * }
145
+ * ```
146
+ */
147
+ filter?: (event: any) => boolean;
114
148
  /** Array of glob patterns to skip tracking on matching paths (e.g., ['/admin/**']) */
115
149
  skipPatterns?: string[];
150
+ /** Array of glob patterns to mask sensitive paths (e.g., ['/users/*']) */
116
151
  maskPatterns?: string[];
117
152
  };
118
153
  /**
@@ -219,41 +254,57 @@ type EventName = keyof EventTypeMap;
219
254
  */
220
255
  type PropertiesForEvent<T extends EventName> = T extends keyof EventTypeMap ? EventTypeMap[T] & EventProperties : EventProperties;
221
256
  /**
222
- * Databuddy tracker instance interface
257
+ * The global tracker instance available at `window.databuddy` or `window.db`.
258
+ *
259
+ * @example
260
+ * ```ts
261
+ * // Direct access (prefer SDK functions instead)
262
+ * window.databuddy.track("signup", { plan: "pro" });
263
+ * window.databuddy.flush();
264
+ *
265
+ * // Access tracker options
266
+ * const options = window.databuddy.options;
267
+ * ```
223
268
  */
224
269
  type DatabuddyTracker = {
225
270
  /**
226
- * Current anonymous user ID
227
- */
228
- anonymousId: string;
229
- /**
230
- * Current session ID
231
- */
232
- sessionId: string;
233
- /**
234
- * Track a custom event
271
+ * Track a custom event.
272
+ * @param eventName - Name of the event (e.g., "purchase", "signup")
273
+ * @param properties - Additional data to attach
235
274
  */
236
- track<T extends EventName>(eventName: T, properties?: PropertiesForEvent<T>): Promise<void>;
275
+ track(eventName: string, properties?: Record<string, unknown>): void;
237
276
  /**
238
- * Track a screen/page view
277
+ * Manually track a page view. Called automatically on route changes.
278
+ * @param properties - Additional properties to attach to the screen view event
239
279
  */
240
- screenView(path?: string, properties?: EventProperties): void;
280
+ screenView(properties?: Record<string, unknown>): void;
241
281
  /**
242
- * Set global properties that will be attached to all events
282
+ * Set properties that will be attached to ALL future events.
283
+ * Useful for user traits like plan, role, or A/B test variants.
284
+ *
285
+ * @example
286
+ * ```ts
287
+ * window.databuddy.setGlobalProperties({
288
+ * plan: "enterprise",
289
+ * abVariant: "checkout-v2"
290
+ * });
291
+ * ```
243
292
  */
244
- setGlobalProperties(properties: EventProperties): void;
293
+ setGlobalProperties(properties: Record<string, unknown>): void;
245
294
  /**
246
- * Clear the current user session and generate new IDs
295
+ * Reset the user session. Generates new anonymous and session IDs.
296
+ * Call after logout to ensure clean slate for next user.
247
297
  */
248
298
  clear(): void;
249
299
  /**
250
- * Flush any queued events immediately
300
+ * Force send all queued events immediately.
301
+ * Call before navigation to external sites.
251
302
  */
252
303
  flush(): void;
253
304
  /**
254
- * Track a lean custom event (goes to custom_event_spans table)
305
+ * Current tracker configuration options.
255
306
  */
256
- trackCustomEvent(eventName: string, properties?: Record<string, unknown>): void;
307
+ options: DatabuddyConfig;
257
308
  };
258
309
  /**
259
310
  * Global window interface extensions
@@ -267,24 +318,47 @@ declare global {
267
318
  clear: DatabuddyTracker["clear"];
268
319
  flush: DatabuddyTracker["flush"];
269
320
  setGlobalProperties: DatabuddyTracker["setGlobalProperties"];
270
- trackCustomEvent: DatabuddyTracker["trackCustomEvent"];
271
321
  };
272
322
  }
273
323
  }
274
324
  /**
275
- * Helper type for HTML data attributes for automatic tracking
325
+ * HTML data attributes for declarative click tracking.
326
+ * Add these to any clickable element to track without JavaScript.
327
+ *
328
+ * @example
329
+ * ```tsx
330
+ * // Track button clicks with properties
331
+ * <button
332
+ * data-track="cta_clicked"
333
+ * data-button-text="Get Started"
334
+ * data-location="hero"
335
+ * >
336
+ * Get Started
337
+ * </button>
338
+ *
339
+ * // Properties are auto-converted to camelCase:
340
+ * // { buttonText: "Get Started", location: "hero" }
341
+ * ```
342
+ *
343
+ * @example
344
+ * ```tsx
345
+ * // Track navigation
346
+ * <a href="/pricing" data-track="nav_link_clicked" data-destination="pricing">
347
+ * Pricing
348
+ * </a>
349
+ * ```
276
350
  */
277
351
  type DataAttributes = {
278
352
  /** Event name to track when element is clicked */
279
353
  "data-track": string;
280
- /** Additional data attributes (converted to camelCase) */
354
+ /** Additional data attributes (auto-converted from kebab-case to camelCase) */
281
355
  [key: `data-${string}`]: string;
282
356
  };
283
357
  /**
284
358
  * Utility types for creating typed event tracking functions
285
359
  */
286
360
  type TrackFunction = <T extends EventName>(eventName: T, properties?: PropertiesForEvent<T>) => Promise<void>;
287
- type ScreenViewFunction = (path?: string, properties?: EventProperties) => void;
361
+ type ScreenViewFunction = (properties?: Record<string, unknown>) => void;
288
362
  type SetGlobalPropertiesFunction = (properties: EventProperties) => void;
289
363
 
290
364
  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 };
@@ -1,6 +1,17 @@
1
1
  /**
2
- * Configuration options for the Databuddy SDK and <Databuddy /> component.
3
- * All options are passed as data attributes to the injected script.
2
+ * Configuration for the `<Databuddy />` component and tracker script.
3
+ *
4
+ * @example
5
+ * ```tsx
6
+ * <Databuddy
7
+ * clientId="your-client-id"
8
+ * apiUrl="https://basket.databuddy.cc"
9
+ * trackWebVitals
10
+ * trackErrors
11
+ * trackScrollDepth
12
+ * samplingRate={0.5}
13
+ * />
14
+ * ```
4
15
  */
5
16
  type DatabuddyConfig = {
6
17
  /**
@@ -82,7 +93,7 @@ type DatabuddyConfig = {
82
93
  */
83
94
  samplingRate?: number;
84
95
  /**
85
- * Enable retries for failed requests (default: true).
96
+ * Enable retries for failed requests (default: false).
86
97
  */
87
98
  enableRetries?: boolean;
88
99
  /**
@@ -96,7 +107,7 @@ type DatabuddyConfig = {
96
107
  */
97
108
  initialRetryDelay?: number;
98
109
  /**
99
- * Enable event batching (default: false).
110
+ * Enable event batching (default: true).
100
111
  */
101
112
  enableBatching?: boolean;
102
113
  /**
@@ -111,8 +122,32 @@ type DatabuddyConfig = {
111
122
  * Min: 100, Max: 30000
112
123
  */
113
124
  batchTimeout?: number;
125
+ /**
126
+ * Ignore bot detection (default: false).
127
+ * If true, bot detection will be disabled and bots will be tracked.
128
+ */
129
+ ignoreBotDetection?: boolean;
130
+ /**
131
+ * Use pixel tracking instead of script (default: false).
132
+ * When enabled, uses a 1x1 pixel image for tracking.
133
+ */
134
+ usePixel?: boolean;
135
+ /**
136
+ * Filter function to conditionally skip events.
137
+ * Return false to skip the event, true to send it.
138
+ *
139
+ * @example
140
+ * ```ts
141
+ * filter: (event) => {
142
+ * // Skip events from admin pages
143
+ * return !event.path?.includes('/admin');
144
+ * }
145
+ * ```
146
+ */
147
+ filter?: (event: any) => boolean;
114
148
  /** Array of glob patterns to skip tracking on matching paths (e.g., ['/admin/**']) */
115
149
  skipPatterns?: string[];
150
+ /** Array of glob patterns to mask sensitive paths (e.g., ['/users/*']) */
116
151
  maskPatterns?: string[];
117
152
  };
118
153
  /**
@@ -219,41 +254,57 @@ type EventName = keyof EventTypeMap;
219
254
  */
220
255
  type PropertiesForEvent<T extends EventName> = T extends keyof EventTypeMap ? EventTypeMap[T] & EventProperties : EventProperties;
221
256
  /**
222
- * Databuddy tracker instance interface
257
+ * The global tracker instance available at `window.databuddy` or `window.db`.
258
+ *
259
+ * @example
260
+ * ```ts
261
+ * // Direct access (prefer SDK functions instead)
262
+ * window.databuddy.track("signup", { plan: "pro" });
263
+ * window.databuddy.flush();
264
+ *
265
+ * // Access tracker options
266
+ * const options = window.databuddy.options;
267
+ * ```
223
268
  */
224
269
  type DatabuddyTracker = {
225
270
  /**
226
- * Current anonymous user ID
227
- */
228
- anonymousId: string;
229
- /**
230
- * Current session ID
231
- */
232
- sessionId: string;
233
- /**
234
- * Track a custom event
271
+ * Track a custom event.
272
+ * @param eventName - Name of the event (e.g., "purchase", "signup")
273
+ * @param properties - Additional data to attach
235
274
  */
236
- track<T extends EventName>(eventName: T, properties?: PropertiesForEvent<T>): Promise<void>;
275
+ track(eventName: string, properties?: Record<string, unknown>): void;
237
276
  /**
238
- * Track a screen/page view
277
+ * Manually track a page view. Called automatically on route changes.
278
+ * @param properties - Additional properties to attach to the screen view event
239
279
  */
240
- screenView(path?: string, properties?: EventProperties): void;
280
+ screenView(properties?: Record<string, unknown>): void;
241
281
  /**
242
- * Set global properties that will be attached to all events
282
+ * Set properties that will be attached to ALL future events.
283
+ * Useful for user traits like plan, role, or A/B test variants.
284
+ *
285
+ * @example
286
+ * ```ts
287
+ * window.databuddy.setGlobalProperties({
288
+ * plan: "enterprise",
289
+ * abVariant: "checkout-v2"
290
+ * });
291
+ * ```
243
292
  */
244
- setGlobalProperties(properties: EventProperties): void;
293
+ setGlobalProperties(properties: Record<string, unknown>): void;
245
294
  /**
246
- * Clear the current user session and generate new IDs
295
+ * Reset the user session. Generates new anonymous and session IDs.
296
+ * Call after logout to ensure clean slate for next user.
247
297
  */
248
298
  clear(): void;
249
299
  /**
250
- * Flush any queued events immediately
300
+ * Force send all queued events immediately.
301
+ * Call before navigation to external sites.
251
302
  */
252
303
  flush(): void;
253
304
  /**
254
- * Track a lean custom event (goes to custom_event_spans table)
305
+ * Current tracker configuration options.
255
306
  */
256
- trackCustomEvent(eventName: string, properties?: Record<string, unknown>): void;
307
+ options: DatabuddyConfig;
257
308
  };
258
309
  /**
259
310
  * Global window interface extensions
@@ -267,24 +318,47 @@ declare global {
267
318
  clear: DatabuddyTracker["clear"];
268
319
  flush: DatabuddyTracker["flush"];
269
320
  setGlobalProperties: DatabuddyTracker["setGlobalProperties"];
270
- trackCustomEvent: DatabuddyTracker["trackCustomEvent"];
271
321
  };
272
322
  }
273
323
  }
274
324
  /**
275
- * Helper type for HTML data attributes for automatic tracking
325
+ * HTML data attributes for declarative click tracking.
326
+ * Add these to any clickable element to track without JavaScript.
327
+ *
328
+ * @example
329
+ * ```tsx
330
+ * // Track button clicks with properties
331
+ * <button
332
+ * data-track="cta_clicked"
333
+ * data-button-text="Get Started"
334
+ * data-location="hero"
335
+ * >
336
+ * Get Started
337
+ * </button>
338
+ *
339
+ * // Properties are auto-converted to camelCase:
340
+ * // { buttonText: "Get Started", location: "hero" }
341
+ * ```
342
+ *
343
+ * @example
344
+ * ```tsx
345
+ * // Track navigation
346
+ * <a href="/pricing" data-track="nav_link_clicked" data-destination="pricing">
347
+ * Pricing
348
+ * </a>
349
+ * ```
276
350
  */
277
351
  type DataAttributes = {
278
352
  /** Event name to track when element is clicked */
279
353
  "data-track": string;
280
- /** Additional data attributes (converted to camelCase) */
354
+ /** Additional data attributes (auto-converted from kebab-case to camelCase) */
281
355
  [key: `data-${string}`]: string;
282
356
  };
283
357
  /**
284
358
  * Utility types for creating typed event tracking functions
285
359
  */
286
360
  type TrackFunction = <T extends EventName>(eventName: T, properties?: PropertiesForEvent<T>) => Promise<void>;
287
- type ScreenViewFunction = (path?: string, properties?: EventProperties) => void;
361
+ type ScreenViewFunction = (properties?: Record<string, unknown>) => void;
288
362
  type SetGlobalPropertiesFunction = (properties: EventProperties) => void;
289
363
 
290
364
  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 };
@@ -27,6 +27,9 @@ declare const Databuddy: vue.DefineComponent<{
27
27
  enableBatching?: boolean | undefined;
28
28
  batchSize?: number | undefined;
29
29
  batchTimeout?: number | undefined;
30
+ ignoreBotDetection?: boolean | undefined;
31
+ usePixel?: boolean | undefined;
32
+ filter?: ((event: any) => boolean) | undefined;
30
33
  skipPatterns?: string[] | undefined;
31
34
  maskPatterns?: string[] | undefined;
32
35
  }, () => null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<{
@@ -53,6 +56,9 @@ declare const Databuddy: vue.DefineComponent<{
53
56
  enableBatching?: boolean | undefined;
54
57
  batchSize?: number | undefined;
55
58
  batchTimeout?: number | undefined;
59
+ ignoreBotDetection?: boolean | undefined;
60
+ usePixel?: boolean | undefined;
61
+ filter?: ((event: any) => boolean) | undefined;
56
62
  skipPatterns?: string[] | undefined;
57
63
  maskPatterns?: string[] | undefined;
58
64
  }> & Readonly<{}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
@@ -27,6 +27,9 @@ declare const Databuddy: vue.DefineComponent<{
27
27
  enableBatching?: boolean | undefined;
28
28
  batchSize?: number | undefined;
29
29
  batchTimeout?: number | undefined;
30
+ ignoreBotDetection?: boolean | undefined;
31
+ usePixel?: boolean | undefined;
32
+ filter?: ((event: any) => boolean) | undefined;
30
33
  skipPatterns?: string[] | undefined;
31
34
  maskPatterns?: string[] | undefined;
32
35
  }, () => null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<{
@@ -53,6 +56,9 @@ declare const Databuddy: vue.DefineComponent<{
53
56
  enableBatching?: boolean | undefined;
54
57
  batchSize?: number | undefined;
55
58
  batchTimeout?: number | undefined;
59
+ ignoreBotDetection?: boolean | undefined;
60
+ usePixel?: boolean | undefined;
61
+ filter?: ((event: any) => boolean) | undefined;
56
62
  skipPatterns?: string[] | undefined;
57
63
  maskPatterns?: string[] | undefined;
58
64
  }> & Readonly<{}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
@@ -1,5 +1,5 @@
1
1
  import { defineComponent, ref, onMounted, onUnmounted, watch, reactive, watchEffect, computed } from 'vue';
2
- import { i as isScriptInjected, c as createScript, B as BrowserFlagStorage, C as CoreFlagsManager } from '../shared/@databuddy/sdk.IxoH6TAZ.mjs';
2
+ import { i as isScriptInjected, c as createScript, B as BrowserFlagStorage, C as CoreFlagsManager } from '../shared/@databuddy/sdk.ByNF_UxE.mjs';
3
3
 
4
4
  const Databuddy = defineComponent({
5
5
  props: {},
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@databuddy/sdk",
3
- "version": "2.2.12",
3
+ "version": "2.3.1",
4
4
  "description": "Official Databuddy Analytics SDK",
5
5
  "main": "./dist/core/index.mjs",
6
6
  "types": "./dist/core/index.d.ts",