@databuddy/sdk 2.1.77 → 2.2.0
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 +129 -129
- package/dist/core/index.mjs +3 -3
- package/dist/node/index.d.mts +132 -0
- package/dist/node/index.d.ts +132 -0
- package/dist/node/index.mjs +344 -0
- package/dist/react/index.d.mts +1 -10
- package/dist/react/index.d.ts +1 -10
- package/dist/react/index.mjs +2 -2
- package/dist/shared/@databuddy/{sdk.VZOaS2Dk.mjs → sdk.aVQee-4k.mjs} +1 -1
- package/dist/shared/@databuddy/{sdk.DsZMb6-q.mjs → sdk.tFAHtL2M.mjs} +1 -1
- package/dist/vue/index.d.mts +1 -194
- package/dist/vue/index.d.ts +1 -194
- package/dist/vue/index.mjs +1 -1
- package/package.json +20 -3
package/README.md
CHANGED
|
@@ -1,130 +1,130 @@
|
|
|
1
|
-
# Databuddy SDK & React Component
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/@databuddy/sdk)
|
|
4
|
-
[](./LICENSE)
|
|
5
|
-
[](https://www.databuddy.cc/docs)
|
|
6
|
-
|
|
7
|
-
> **The easiest, privacy-first way to add analytics to your web app.**
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## ✨ Features
|
|
12
|
-
|
|
13
|
-
- 📊 **Automatic page/screen view tracking**
|
|
14
|
-
- ⚡ **Performance, Web Vitals, and error tracking**
|
|
15
|
-
- 🧑💻 **Custom event tracking**
|
|
16
|
-
- 🧩 **Drop-in React/Next.js component: `<Databuddy />`**
|
|
17
|
-
- 🛡️ **Privacy-first: anonymized by default, sampling, batching, and more**
|
|
18
|
-
- 🛠️ **Type-safe config and autocompletion**
|
|
19
|
-
- 📋 **Observability: logging, error tracking, and distributed tracing**
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## 🚀 Quickstart
|
|
24
|
-
|
|
25
|
-
```sh
|
|
26
|
-
bun add @databuddy/sdk
|
|
27
|
-
# or
|
|
28
|
-
npm install @databuddy/sdk
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
Add to your root layout (Next.js/React):
|
|
32
|
-
|
|
33
|
-
```tsx
|
|
34
|
-
import { Databuddy } from '@databuddy/sdk';
|
|
35
|
-
|
|
36
|
-
export default function RootLayout({ children }) {
|
|
37
|
-
return (
|
|
38
|
-
<html lang="en">
|
|
39
|
-
<head />
|
|
40
|
-
<Databuddy
|
|
41
|
-
clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
|
|
42
|
-
trackScreenViews
|
|
43
|
-
trackPerformance
|
|
44
|
-
trackErrors
|
|
45
|
-
enableBatching
|
|
46
|
-
batchSize={20}
|
|
47
|
-
/>
|
|
48
|
-
<body>{children}</body>
|
|
49
|
-
</html>
|
|
50
|
-
);
|
|
51
|
-
}
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
---
|
|
55
|
-
|
|
56
|
-
## 🛠️ Configuration Options
|
|
57
|
-
|
|
58
|
-
All options are type-safe and documented in `DatabuddyConfig`:
|
|
59
|
-
|
|
60
|
-
| Option | Type | Default | Description |
|
|
61
|
-
|-----------------------|-----------|--------------|-------------|
|
|
62
|
-
| `clientId` | string | — | **Required.** Your Databuddy project client ID. |
|
|
63
|
-
| `clientSecret` | string | — | (Advanced) For server-side use only. |
|
|
64
|
-
| `apiUrl` | string | `https://api.databuddy.cc` | Custom API endpoint. |
|
|
65
|
-
| `scriptUrl` | string | `https://cdn.databuddy.cc/databuddy.js` | Custom script URL. |
|
|
66
|
-
| `sdk` | string | `web` | SDK name. Only override for custom builds. |
|
|
67
|
-
| `sdkVersion` | string | *auto* | SDK version. Defaults to package version. |
|
|
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. |
|
|
71
|
-
| `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. |
|
|
80
|
-
| `trackInteractions` | boolean | `false` | Track user interactions. |
|
|
81
|
-
| `trackErrors` | boolean | `true` | Track JS errors. |
|
|
82
|
-
| `trackBounceRate` | boolean | `false` | Track bounce rate. |
|
|
83
|
-
| `samplingRate` | number | `1.0` | Sampling rate (0.0–1.0). |
|
|
84
|
-
| `enableRetries` | boolean | `true` | Retry failed requests. |
|
|
85
|
-
| `maxRetries` | number | `3` | Max retries. |
|
|
86
|
-
| `initialRetryDelay` | number | `500` | Initial retry delay (ms). |
|
|
87
|
-
| `enableBatching` | boolean | `true` | Enable event batching. |
|
|
88
|
-
| `batchSize` | number | `20` | Events per batch (1–50). |
|
|
89
|
-
| `batchTimeout` | number | `5000` | Batch timeout (ms, 100–30000). |
|
|
90
|
-
|
|
91
|
-
---
|
|
92
|
-
|
|
93
|
-
## 💡 FAQ
|
|
94
|
-
|
|
95
|
-
**Q: Is Databuddy privacy-friendly?**
|
|
96
|
-
A: Yes! All analytics are anonymized by default. No cookies, no fingerprinting, no PII.
|
|
97
|
-
|
|
98
|
-
**Q: Can I use this in Next.js, Remix, or plain React?**
|
|
99
|
-
A: Yes! `<Databuddy />` works in any React app. For non-React, use the script tag directly.
|
|
100
|
-
|
|
101
|
-
**Q: How do I disable analytics in development?**
|
|
102
|
-
A: Use the `disabled` prop: `<Databuddy disabled={process.env.NODE_ENV === 'development'} ... />`
|
|
103
|
-
|
|
104
|
-
**Q: Where do I find my `clientId`?**
|
|
105
|
-
A: In your [Databuddy dashboard](https://app.databuddy.cc).
|
|
106
|
-
|
|
107
|
-
---
|
|
108
|
-
|
|
109
|
-
## 🧑💻 Troubleshooting
|
|
110
|
-
|
|
111
|
-
- **Script not loading?**
|
|
112
|
-
- Make sure your `clientId` is correct and the script URL is reachable.
|
|
113
|
-
- **No events in dashboard?**
|
|
114
|
-
- Check your config, especially `clientId` and network requests in the browser dev tools.
|
|
115
|
-
- **Type errors?**
|
|
116
|
-
- All config options are type-safe. Use your IDE's autocomplete for help.
|
|
117
|
-
- **SSR/Next.js?**
|
|
118
|
-
- The component is safe for SSR/React Server Components. It only injects the script on the client.
|
|
119
|
-
|
|
120
|
-
---
|
|
121
|
-
|
|
122
|
-
## 📚 Documentation & Support
|
|
123
|
-
|
|
124
|
-
- [Databuddy Docs](https://www.databuddy.cc/docs)
|
|
125
|
-
- [Dashboard](https://app.databuddy.cc)
|
|
126
|
-
- [Contact Support](https://www.databuddy.cc/contact)
|
|
127
|
-
|
|
128
|
-
---
|
|
129
|
-
|
|
1
|
+
# Databuddy SDK & React Component
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@databuddy/sdk)
|
|
4
|
+
[](./LICENSE)
|
|
5
|
+
[](https://www.databuddy.cc/docs)
|
|
6
|
+
|
|
7
|
+
> **The easiest, privacy-first way to add analytics to your web app.**
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## ✨ Features
|
|
12
|
+
|
|
13
|
+
- 📊 **Automatic page/screen view tracking**
|
|
14
|
+
- ⚡ **Performance, Web Vitals, and error tracking**
|
|
15
|
+
- 🧑💻 **Custom event tracking**
|
|
16
|
+
- 🧩 **Drop-in React/Next.js component: `<Databuddy />`**
|
|
17
|
+
- 🛡️ **Privacy-first: anonymized by default, sampling, batching, and more**
|
|
18
|
+
- 🛠️ **Type-safe config and autocompletion**
|
|
19
|
+
- 📋 **Observability: logging, error tracking, and distributed tracing**
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 🚀 Quickstart
|
|
24
|
+
|
|
25
|
+
```sh
|
|
26
|
+
bun add @databuddy/sdk
|
|
27
|
+
# or
|
|
28
|
+
npm install @databuddy/sdk
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Add to your root layout (Next.js/React):
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
import { Databuddy } from '@databuddy/sdk/react';
|
|
35
|
+
|
|
36
|
+
export default function RootLayout({ children }) {
|
|
37
|
+
return (
|
|
38
|
+
<html lang="en">
|
|
39
|
+
<head />
|
|
40
|
+
<Databuddy
|
|
41
|
+
clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
|
|
42
|
+
trackScreenViews
|
|
43
|
+
trackPerformance
|
|
44
|
+
trackErrors
|
|
45
|
+
enableBatching
|
|
46
|
+
batchSize={20}
|
|
47
|
+
/>
|
|
48
|
+
<body>{children}</body>
|
|
49
|
+
</html>
|
|
50
|
+
);
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 🛠️ Configuration Options
|
|
57
|
+
|
|
58
|
+
All options are type-safe and documented in `DatabuddyConfig`:
|
|
59
|
+
|
|
60
|
+
| Option | Type | Default | Description |
|
|
61
|
+
|-----------------------|-----------|--------------|-------------|
|
|
62
|
+
| `clientId` | string | — | **Required.** Your Databuddy project client ID. |
|
|
63
|
+
| `clientSecret` | string | — | (Advanced) For server-side use only. |
|
|
64
|
+
| `apiUrl` | string | `https://api.databuddy.cc` | Custom API endpoint. |
|
|
65
|
+
| `scriptUrl` | string | `https://cdn.databuddy.cc/databuddy.js` | Custom script URL. |
|
|
66
|
+
| `sdk` | string | `web` | SDK name. Only override for custom builds. |
|
|
67
|
+
| `sdkVersion` | string | *auto* | SDK version. Defaults to package version. |
|
|
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. |
|
|
71
|
+
| `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. |
|
|
80
|
+
| `trackInteractions` | boolean | `false` | Track user interactions. |
|
|
81
|
+
| `trackErrors` | boolean | `true` | Track JS errors. |
|
|
82
|
+
| `trackBounceRate` | boolean | `false` | Track bounce rate. |
|
|
83
|
+
| `samplingRate` | number | `1.0` | Sampling rate (0.0–1.0). |
|
|
84
|
+
| `enableRetries` | boolean | `true` | Retry failed requests. |
|
|
85
|
+
| `maxRetries` | number | `3` | Max retries. |
|
|
86
|
+
| `initialRetryDelay` | number | `500` | Initial retry delay (ms). |
|
|
87
|
+
| `enableBatching` | boolean | `true` | Enable event batching. |
|
|
88
|
+
| `batchSize` | number | `20` | Events per batch (1–50). |
|
|
89
|
+
| `batchTimeout` | number | `5000` | Batch timeout (ms, 100–30000). |
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## 💡 FAQ
|
|
94
|
+
|
|
95
|
+
**Q: Is Databuddy privacy-friendly?**
|
|
96
|
+
A: Yes! All analytics are anonymized by default. No cookies, no fingerprinting, no PII.
|
|
97
|
+
|
|
98
|
+
**Q: Can I use this in Next.js, Remix, or plain React?**
|
|
99
|
+
A: Yes! `<Databuddy />` works in any React app. For non-React, use the script tag directly.
|
|
100
|
+
|
|
101
|
+
**Q: How do I disable analytics in development?**
|
|
102
|
+
A: Use the `disabled` prop: `<Databuddy disabled={process.env.NODE_ENV === 'development'} ... />`
|
|
103
|
+
|
|
104
|
+
**Q: Where do I find my `clientId`?**
|
|
105
|
+
A: In your [Databuddy dashboard](https://app.databuddy.cc).
|
|
106
|
+
|
|
107
|
+
---
|
|
108
|
+
|
|
109
|
+
## 🧑💻 Troubleshooting
|
|
110
|
+
|
|
111
|
+
- **Script not loading?**
|
|
112
|
+
- Make sure your `clientId` is correct and the script URL is reachable.
|
|
113
|
+
- **No events in dashboard?**
|
|
114
|
+
- Check your config, especially `clientId` and network requests in the browser dev tools.
|
|
115
|
+
- **Type errors?**
|
|
116
|
+
- All config options are type-safe. Use your IDE's autocomplete for help.
|
|
117
|
+
- **SSR/Next.js?**
|
|
118
|
+
- The component is safe for SSR/React Server Components. It only injects the script on the client.
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## 📚 Documentation & Support
|
|
123
|
+
|
|
124
|
+
- [Databuddy Docs](https://www.databuddy.cc/docs)
|
|
125
|
+
- [Dashboard](https://app.databuddy.cc)
|
|
126
|
+
- [Contact Support](https://www.databuddy.cc/contact)
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
130
|
© Databuddy. All rights reserved.
|
package/dist/core/index.mjs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { D as Databuddy$1 } from '../shared/@databuddy/sdk.
|
|
2
|
-
export { d as detectClientId } from '../shared/@databuddy/sdk.
|
|
3
|
-
export { B as BrowserFlagStorage, C as CoreFlagsManager, c as createScript, i as isScriptInjected } from '../shared/@databuddy/sdk.
|
|
1
|
+
import { D as Databuddy$1 } from '../shared/@databuddy/sdk.aVQee-4k.mjs';
|
|
2
|
+
export { d as detectClientId } from '../shared/@databuddy/sdk.aVQee-4k.mjs';
|
|
3
|
+
export { B as BrowserFlagStorage, C as CoreFlagsManager, c as createScript, i as isScriptInjected } from '../shared/@databuddy/sdk.tFAHtL2M.mjs';
|
|
4
4
|
|
|
5
5
|
function isTrackerAvailable() {
|
|
6
6
|
return typeof window !== "undefined" && (!!window.databuddy || !!window.db);
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
interface Logger {
|
|
2
|
+
info(msg: string, data?: Record<string, unknown>): void;
|
|
3
|
+
error(msg: string, data?: Record<string, unknown>): void;
|
|
4
|
+
warn(msg: string, data?: Record<string, unknown>): void;
|
|
5
|
+
debug(msg: string, data?: Record<string, unknown>): void;
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
interface DatabuddyConfig {
|
|
9
|
+
clientId: string;
|
|
10
|
+
apiUrl?: string;
|
|
11
|
+
debug?: boolean;
|
|
12
|
+
logger?: Logger;
|
|
13
|
+
/**
|
|
14
|
+
* Enable automatic batching of events
|
|
15
|
+
* Default: true
|
|
16
|
+
*/
|
|
17
|
+
enableBatching?: boolean;
|
|
18
|
+
/**
|
|
19
|
+
* Number of events to batch before auto-flushing
|
|
20
|
+
* Default: 10, Max: 100
|
|
21
|
+
*/
|
|
22
|
+
batchSize?: number;
|
|
23
|
+
/**
|
|
24
|
+
* Time in milliseconds before auto-flushing batched events
|
|
25
|
+
* Default: 2000ms (2 seconds)
|
|
26
|
+
*/
|
|
27
|
+
batchTimeout?: number;
|
|
28
|
+
/**
|
|
29
|
+
* Maximum number of events to queue before auto-flushing
|
|
30
|
+
* Default: 1000
|
|
31
|
+
*/
|
|
32
|
+
maxQueueSize?: number;
|
|
33
|
+
}
|
|
34
|
+
interface CustomEventInput {
|
|
35
|
+
name: string;
|
|
36
|
+
eventId?: string;
|
|
37
|
+
anonymousId?: string | null;
|
|
38
|
+
sessionId?: string | null;
|
|
39
|
+
timestamp?: number | null;
|
|
40
|
+
properties?: Record<string, unknown> | null;
|
|
41
|
+
}
|
|
42
|
+
interface EventResponse {
|
|
43
|
+
success: boolean;
|
|
44
|
+
eventId?: string;
|
|
45
|
+
error?: string;
|
|
46
|
+
}
|
|
47
|
+
interface BatchEventInput {
|
|
48
|
+
type: 'custom';
|
|
49
|
+
name: string;
|
|
50
|
+
eventId?: string;
|
|
51
|
+
anonymousId?: string | null;
|
|
52
|
+
sessionId?: string | null;
|
|
53
|
+
timestamp?: number | null;
|
|
54
|
+
properties?: Record<string, unknown> | null;
|
|
55
|
+
}
|
|
56
|
+
interface BatchEventResponse {
|
|
57
|
+
success: boolean;
|
|
58
|
+
processed?: number;
|
|
59
|
+
results?: Array<{
|
|
60
|
+
status: string;
|
|
61
|
+
type?: string;
|
|
62
|
+
eventId?: string;
|
|
63
|
+
message?: string;
|
|
64
|
+
error?: string;
|
|
65
|
+
}>;
|
|
66
|
+
error?: string;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
declare class Databuddy {
|
|
70
|
+
private clientId;
|
|
71
|
+
private apiUrl;
|
|
72
|
+
private logger;
|
|
73
|
+
private enableBatching;
|
|
74
|
+
private batchSize;
|
|
75
|
+
private batchTimeout;
|
|
76
|
+
private queue;
|
|
77
|
+
private flushTimer;
|
|
78
|
+
constructor(config: DatabuddyConfig);
|
|
79
|
+
/**
|
|
80
|
+
* Track a custom event
|
|
81
|
+
* If batching is enabled, queues the event and auto-flushes when batch size is reached or timeout expires
|
|
82
|
+
* If batching is disabled, sends the event immediately
|
|
83
|
+
*
|
|
84
|
+
* @param event - Custom event data
|
|
85
|
+
* @returns Response indicating success or failure
|
|
86
|
+
*
|
|
87
|
+
* @example
|
|
88
|
+
* ```typescript
|
|
89
|
+
* await client.track({
|
|
90
|
+
* name: 'user_signup',
|
|
91
|
+
* properties: { plan: 'pro' }
|
|
92
|
+
* });
|
|
93
|
+
* ```
|
|
94
|
+
*/
|
|
95
|
+
track(event: CustomEventInput): Promise<EventResponse>;
|
|
96
|
+
private send;
|
|
97
|
+
private scheduleFlush;
|
|
98
|
+
/**
|
|
99
|
+
* Manually flush all queued events
|
|
100
|
+
* Important for serverless/stateless environments where you need to ensure events are sent before the process exits
|
|
101
|
+
*
|
|
102
|
+
* @returns Response with batch results
|
|
103
|
+
*
|
|
104
|
+
* @example
|
|
105
|
+
* ```typescript
|
|
106
|
+
* // In serverless function
|
|
107
|
+
* await client.track({ name: 'api_call' });
|
|
108
|
+
* await client.flush(); // Ensure events are sent before function exits
|
|
109
|
+
* ```
|
|
110
|
+
*/
|
|
111
|
+
flush(): Promise<BatchEventResponse>;
|
|
112
|
+
/**
|
|
113
|
+
* Send multiple custom events in a single batch request
|
|
114
|
+
* Max 100 events per batch
|
|
115
|
+
* Note: Usually you don't need to call this directly - use track() with batching enabled instead
|
|
116
|
+
*
|
|
117
|
+
* @param events - Array of custom events
|
|
118
|
+
* @returns Response with results for each event
|
|
119
|
+
*
|
|
120
|
+
* @example
|
|
121
|
+
* ```typescript
|
|
122
|
+
* await client.batch([
|
|
123
|
+
* { type: 'custom', name: 'event1', properties: { foo: 'bar' } },
|
|
124
|
+
* { type: 'custom', name: 'event2', properties: { baz: 'qux' } }
|
|
125
|
+
* ]);
|
|
126
|
+
* ```
|
|
127
|
+
*/
|
|
128
|
+
batch(events: BatchEventInput[]): Promise<BatchEventResponse>;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
export { Databuddy, Databuddy as db };
|
|
132
|
+
export type { BatchEventInput, BatchEventResponse, CustomEventInput, DatabuddyConfig, EventResponse, Logger };
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
interface Logger {
|
|
2
|
+
info(msg: string, data?: Record<string, unknown>): void;
|
|
3
|
+
error(msg: string, data?: Record<string, unknown>): void;
|
|
4
|
+
warn(msg: string, data?: Record<string, unknown>): void;
|
|
5
|
+
debug(msg: string, data?: Record<string, unknown>): void;
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
interface DatabuddyConfig {
|
|
9
|
+
clientId: string;
|
|
10
|
+
apiUrl?: string;
|
|
11
|
+
debug?: boolean;
|
|
12
|
+
logger?: Logger;
|
|
13
|
+
/**
|
|
14
|
+
* Enable automatic batching of events
|
|
15
|
+
* Default: true
|
|
16
|
+
*/
|
|
17
|
+
enableBatching?: boolean;
|
|
18
|
+
/**
|
|
19
|
+
* Number of events to batch before auto-flushing
|
|
20
|
+
* Default: 10, Max: 100
|
|
21
|
+
*/
|
|
22
|
+
batchSize?: number;
|
|
23
|
+
/**
|
|
24
|
+
* Time in milliseconds before auto-flushing batched events
|
|
25
|
+
* Default: 2000ms (2 seconds)
|
|
26
|
+
*/
|
|
27
|
+
batchTimeout?: number;
|
|
28
|
+
/**
|
|
29
|
+
* Maximum number of events to queue before auto-flushing
|
|
30
|
+
* Default: 1000
|
|
31
|
+
*/
|
|
32
|
+
maxQueueSize?: number;
|
|
33
|
+
}
|
|
34
|
+
interface CustomEventInput {
|
|
35
|
+
name: string;
|
|
36
|
+
eventId?: string;
|
|
37
|
+
anonymousId?: string | null;
|
|
38
|
+
sessionId?: string | null;
|
|
39
|
+
timestamp?: number | null;
|
|
40
|
+
properties?: Record<string, unknown> | null;
|
|
41
|
+
}
|
|
42
|
+
interface EventResponse {
|
|
43
|
+
success: boolean;
|
|
44
|
+
eventId?: string;
|
|
45
|
+
error?: string;
|
|
46
|
+
}
|
|
47
|
+
interface BatchEventInput {
|
|
48
|
+
type: 'custom';
|
|
49
|
+
name: string;
|
|
50
|
+
eventId?: string;
|
|
51
|
+
anonymousId?: string | null;
|
|
52
|
+
sessionId?: string | null;
|
|
53
|
+
timestamp?: number | null;
|
|
54
|
+
properties?: Record<string, unknown> | null;
|
|
55
|
+
}
|
|
56
|
+
interface BatchEventResponse {
|
|
57
|
+
success: boolean;
|
|
58
|
+
processed?: number;
|
|
59
|
+
results?: Array<{
|
|
60
|
+
status: string;
|
|
61
|
+
type?: string;
|
|
62
|
+
eventId?: string;
|
|
63
|
+
message?: string;
|
|
64
|
+
error?: string;
|
|
65
|
+
}>;
|
|
66
|
+
error?: string;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
declare class Databuddy {
|
|
70
|
+
private clientId;
|
|
71
|
+
private apiUrl;
|
|
72
|
+
private logger;
|
|
73
|
+
private enableBatching;
|
|
74
|
+
private batchSize;
|
|
75
|
+
private batchTimeout;
|
|
76
|
+
private queue;
|
|
77
|
+
private flushTimer;
|
|
78
|
+
constructor(config: DatabuddyConfig);
|
|
79
|
+
/**
|
|
80
|
+
* Track a custom event
|
|
81
|
+
* If batching is enabled, queues the event and auto-flushes when batch size is reached or timeout expires
|
|
82
|
+
* If batching is disabled, sends the event immediately
|
|
83
|
+
*
|
|
84
|
+
* @param event - Custom event data
|
|
85
|
+
* @returns Response indicating success or failure
|
|
86
|
+
*
|
|
87
|
+
* @example
|
|
88
|
+
* ```typescript
|
|
89
|
+
* await client.track({
|
|
90
|
+
* name: 'user_signup',
|
|
91
|
+
* properties: { plan: 'pro' }
|
|
92
|
+
* });
|
|
93
|
+
* ```
|
|
94
|
+
*/
|
|
95
|
+
track(event: CustomEventInput): Promise<EventResponse>;
|
|
96
|
+
private send;
|
|
97
|
+
private scheduleFlush;
|
|
98
|
+
/**
|
|
99
|
+
* Manually flush all queued events
|
|
100
|
+
* Important for serverless/stateless environments where you need to ensure events are sent before the process exits
|
|
101
|
+
*
|
|
102
|
+
* @returns Response with batch results
|
|
103
|
+
*
|
|
104
|
+
* @example
|
|
105
|
+
* ```typescript
|
|
106
|
+
* // In serverless function
|
|
107
|
+
* await client.track({ name: 'api_call' });
|
|
108
|
+
* await client.flush(); // Ensure events are sent before function exits
|
|
109
|
+
* ```
|
|
110
|
+
*/
|
|
111
|
+
flush(): Promise<BatchEventResponse>;
|
|
112
|
+
/**
|
|
113
|
+
* Send multiple custom events in a single batch request
|
|
114
|
+
* Max 100 events per batch
|
|
115
|
+
* Note: Usually you don't need to call this directly - use track() with batching enabled instead
|
|
116
|
+
*
|
|
117
|
+
* @param events - Array of custom events
|
|
118
|
+
* @returns Response with results for each event
|
|
119
|
+
*
|
|
120
|
+
* @example
|
|
121
|
+
* ```typescript
|
|
122
|
+
* await client.batch([
|
|
123
|
+
* { type: 'custom', name: 'event1', properties: { foo: 'bar' } },
|
|
124
|
+
* { type: 'custom', name: 'event2', properties: { baz: 'qux' } }
|
|
125
|
+
* ]);
|
|
126
|
+
* ```
|
|
127
|
+
*/
|
|
128
|
+
batch(events: BatchEventInput[]): Promise<BatchEventResponse>;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
export { Databuddy, Databuddy as db };
|
|
132
|
+
export type { BatchEventInput, BatchEventResponse, CustomEventInput, DatabuddyConfig, EventResponse, Logger };
|