@databuddy/sdk 1.1.0 → 1.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.
Files changed (7) hide show
  1. package/README.md +57 -58
  2. package/dist/Databuddy.d.ts +8 -0
  3. package/dist/Databuddy.js +46 -0
  4. package/dist/index.d.ts +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/types.d.ts +1 -1
  7. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,14 @@
1
- # Databuddy SDK
1
+ # Databuddy SDK & React Component
2
2
 
3
- A modern, type-safe analytics SDK and React component for integrating [Databuddy](https://www.databuddy.cc) into your web apps.
3
+ [![npm version](https://img.shields.io/npm/v/@databuddy/sdk?style=flat-square)](https://www.npmjs.com/package/@databuddy/sdk)
4
+ [![License](https://img.shields.io/npm/l/@databuddy/sdk?style=flat-square)](./LICENSE)
5
+ [![Docs](https://img.shields.io/badge/docs-databuddy.cc-blue?style=flat-square)](https://docs.databuddy.cc)
4
6
 
5
- ## Features
7
+ > **The easiest, privacy-first way to add analytics to your web app.**
8
+
9
+ ---
10
+
11
+ ## ✨ Features
6
12
 
7
13
  - 📊 **Automatic page/screen view tracking**
8
14
  - ⚡ **Performance, Web Vitals, and error tracking**
@@ -13,7 +19,7 @@ A modern, type-safe analytics SDK and React component for integrating [Databuddy
13
19
 
14
20
  ---
15
21
 
16
- ## Installation
22
+ ## 🚀 Quickstart
17
23
 
18
24
  ```sh
19
25
  bun add @databuddy/sdk
@@ -21,13 +27,7 @@ bun add @databuddy/sdk
21
27
  npm install @databuddy/sdk
22
28
  ```
23
29
 
24
- ---
25
-
26
- ## Usage
27
-
28
- ### 1. **React/Next.js: Drop-in Component**
29
-
30
- Add the `<Databuddy />` component to your root layout (e.g. `app/layout.tsx`):
30
+ Add to your root layout (Next.js/React):
31
31
 
32
32
  ```tsx
33
33
  import { Databuddy } from '@databuddy/sdk';
@@ -50,63 +50,62 @@ export default function RootLayout({ children }) {
50
50
  }
51
51
  ```
52
52
 
53
- - **All config options are type-safe and passed as data attributes to the script.**
54
- - **No need to manually add `<Script />` or manage the script tag.**
53
+ ---
55
54
 
56
- ### 2. **Script Tag (Vanilla HTML/JS)**
55
+ ## 🛠️ Configuration Options
57
56
 
58
- If you don't use React, you can add the script directly:
57
+ All options are type-safe and documented in `DatabuddyConfig`:
59
58
 
60
- ```html
61
- <script
62
- src="https://app.databuddy.cc/databuddy.js"
63
- data-client-id="YOUR_CLIENT_ID"
64
- data-track-screen-views="true"
65
- data-track-performance="true"
66
- defer
67
- ></script>
68
- ```
59
+ | Option | Type | Default | Description |
60
+ |-----------------------|-----------|--------------|-------------|
61
+ | `clientId` | string | — | **Required.** Your Databuddy project client ID. |
62
+ | `clientSecret` | string | — | (Advanced) For server-side use only. |
63
+ | `apiUrl` | string | `https://api.databuddy.cc` | Custom API endpoint. |
64
+ | `scriptUrl` | string | `https://app.databuddy.cc/databuddy.js` | Custom script URL. |
65
+ | `sdk` | string | `web` | SDK name. Only override for custom builds. |
66
+ | `sdkVersion` | string | *auto* | SDK version. Defaults to package version. |
67
+ | `disabled` | boolean | `false` | Disable all tracking. |
68
+ | `waitForProfile` | boolean | `false` | Wait for user profile before sending events. |
69
+ | `trackScreenViews` | boolean | `true` | Auto-track page/screen views. |
70
+ | `trackHashChanges` | boolean | `false` | Track hash changes in URL. |
71
+ | `trackAttributes` | boolean | `false` | Track data-* attributes. |
72
+ | `trackOutgoingLinks` | boolean | `false` | Track outgoing link clicks. |
73
+ | `trackSessions` | boolean | `false` | Track user sessions. |
74
+ | `trackPerformance` | boolean | `true` | Track page performance. |
75
+ | `trackWebVitals` | boolean | `true` | Track Web Vitals. |
76
+ | `trackEngagement` | boolean | `false` | Track engagement metrics. |
77
+ | `trackScrollDepth` | boolean | `false` | Track scroll depth. |
78
+ | `trackExitIntent` | boolean | `false` | Track exit intent. |
79
+ | `trackInteractions` | boolean | `false` | Track user interactions. |
80
+ | `trackErrors` | boolean | `true` | Track JS errors. |
81
+ | `trackBounceRate` | boolean | `false` | Track bounce rate. |
82
+ | `samplingRate` | number | `1.0` | Sampling rate (0.0–1.0). |
83
+ | `enableRetries` | boolean | `true` | Retry failed requests. |
84
+ | `maxRetries` | number | `3` | Max retries. |
85
+ | `initialRetryDelay` | number | `500` | Initial retry delay (ms). |
86
+ | `enableBatching` | boolean | `true` | Enable event batching. |
87
+ | `batchSize` | number | `20` | Events per batch (1–50). |
88
+ | `batchTimeout` | number | `5000` | Batch timeout (ms, 100–30000). |
69
89
 
70
90
  ---
71
91
 
72
- ## Configuration Options
92
+ ## 💡 FAQ
73
93
 
74
- All options are type-safe and documented in `DatabuddyConfig`:
94
+ **Q: Is Databuddy privacy-friendly?**
95
+ A: Yes! All analytics are anonymized by default. No cookies, no fingerprinting, no PII.
96
+
97
+ **Q: Can I use this in Next.js, Remix, or plain React?**
98
+ A: Yes! `<Databuddy />` works in any React app. For non-React, use the script tag directly.
99
+
100
+ **Q: How do I disable analytics in development?**
101
+ A: Use the `disabled` prop: `<Databuddy disabled={process.env.NODE_ENV === 'development'} ... />`
75
102
 
76
- | Option | Type | Default | Description |
77
- |---------------------|-----------|--------------|-------------|
78
- | `clientId` | string | — | **Required.** Your Databuddy project client ID. |
79
- | `clientSecret` | string | — | (Advanced) For server-side use only. |
80
- | `apiUrl` | string | `https://api.databuddy.cc` | Custom API endpoint. |
81
- | `scriptUrl` | string | `https://app.databuddy.cc/databuddy.js` | Custom script URL. |
82
- | `sdk` | string | `web` | SDK name. Only override for custom builds. |
83
- | `sdkVersion` | string | `1.0.0` | SDK version. Only override for custom builds. |
84
- | `disabled` | boolean | `false` | Disable all tracking. |
85
- | `waitForProfile` | boolean | `false` | Wait for user profile before sending events. |
86
- | `trackScreenViews` | boolean | `true` | Auto-track page/screen views. |
87
- | `trackHashChanges` | boolean | `false` | Track hash changes in URL. |
88
- | `trackAttributes` | boolean | `false` | Track data-* attributes. |
89
- | `trackOutgoingLinks`| boolean | `false` | Track outgoing link clicks. |
90
- | `trackSessions` | boolean | `false` | Track user sessions. |
91
- | `trackPerformance` | boolean | `true` | Track page performance. |
92
- | `trackWebVitals` | boolean | `true` | Track Web Vitals. |
93
- | `trackEngagement` | boolean | `false` | Track engagement metrics. |
94
- | `trackScrollDepth` | boolean | `false` | Track scroll depth. |
95
- | `trackExitIntent` | boolean | `false` | Track exit intent. |
96
- | `trackInteractions` | boolean | `false` | Track user interactions. |
97
- | `trackErrors` | boolean | `true` | Track JS errors. |
98
- | `trackBounceRate` | boolean | `false` | Track bounce rate. |
99
- | `samplingRate` | number | `1.0` | Sampling rate (0.0–1.0). |
100
- | `enableRetries` | boolean | `true` | Retry failed requests. |
101
- | `maxRetries` | number | `3` | Max retries. |
102
- | `initialRetryDelay` | number | `500` | Initial retry delay (ms). |
103
- | `enableBatching` | boolean | `true` | Enable event batching. |
104
- | `batchSize` | number | `20` | Events per batch (1–50). |
105
- | `batchTimeout` | number | `5000` | Batch timeout (ms, 100–30000). |
103
+ **Q: Where do I find my `clientId`?**
104
+ A: In your [Databuddy dashboard](https://app.databuddy.cc).
106
105
 
107
106
  ---
108
107
 
109
- ## Troubleshooting
108
+ ## 🧑‍💻 Troubleshooting
110
109
 
111
110
  - **Script not loading?**
112
111
  - Make sure your `clientId` is correct and the script URL is reachable.
@@ -119,7 +118,7 @@ All options are type-safe and documented in `DatabuddyConfig`:
119
118
 
120
119
  ---
121
120
 
122
- ## Documentation & Support
121
+ ## 📚 Documentation & Support
123
122
 
124
123
  - [Databuddy Docs](https://docs.databuddy.cc)
125
124
  - [Dashboard](https://app.databuddy.cc)
package/dist/Databuddy.d.ts ADDED
@@ -0,0 +1,8 @@
1
+ import type { DatabuddyConfig } from './types';
2
+ /**
3
+ * <Databuddy /> component for Next.js/React apps
4
+ * Injects the databuddy.js script with all config as data attributes
5
+ * Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
6
+ */
7
+ export declare function Databuddy(props: DatabuddyConfig): null;
8
+ export default Databuddy;
package/dist/Databuddy.js ADDED
@@ -0,0 +1,46 @@
1
+ 'use client';
2
+ import pkg from '../package.json';
3
+ import { useEffect } from 'react';
4
+ /**
5
+ * <Databuddy /> component for Next.js/React apps
6
+ * Injects the databuddy.js script with all config as data attributes
7
+ * Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
8
+ */
9
+ export function Databuddy(props) {
10
+ useEffect(() => {
11
+ if (typeof window === 'undefined')
12
+ return;
13
+ if (props.disabled)
14
+ return;
15
+ if (document.querySelector('script[data-databuddy-injected]'))
16
+ return;
17
+ const script = document.createElement('script');
18
+ script.src = props.scriptUrl || 'https://app.databuddy.cc/databuddy.js';
19
+ script.defer = true;
20
+ script.setAttribute('data-databuddy-injected', 'true');
21
+ // Always set sdkVersion from package.json unless explicitly overridden
22
+ const sdkVersion = props.sdkVersion || pkg.version;
23
+ script.setAttribute('data-sdk-version', sdkVersion);
24
+ for (const [key, value] of Object.entries(props)) {
25
+ if (value !== undefined && key !== 'sdkVersion') {
26
+ const dataKey = `data-${key.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
27
+ // Convert booleans and numbers to string for HTML attributes
28
+ if (typeof value === 'boolean') {
29
+ script.setAttribute(dataKey, value ? 'true' : 'false');
30
+ }
31
+ else if (typeof value === 'number') {
32
+ script.setAttribute(dataKey, value.toString());
33
+ }
34
+ else {
35
+ script.setAttribute(dataKey, String(value));
36
+ }
37
+ }
38
+ }
39
+ document.head.appendChild(script);
40
+ return () => {
41
+ script.remove();
42
+ };
43
+ }, [props]);
44
+ return null;
45
+ }
46
+ export default Databuddy;
package/dist/index.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- export * from './DatabuddyProvider';
1
+ export * from './Databuddy';
2
2
  export * from './types';
package/dist/index.js CHANGED
@@ -1,2 +1,2 @@
1
- export * from './DatabuddyProvider';
1
+ export * from './Databuddy';
2
2
  export * from './types';
package/dist/types.d.ts CHANGED
@@ -30,7 +30,7 @@ export interface DatabuddyConfig {
30
30
  */
31
31
  sdk?: string;
32
32
  /**
33
- * SDK version (default: '1.0.0').
33
+ * SDK version (defaults to package.json version).
34
34
  * Only override for custom builds.
35
35
  */
36
36
  sdkVersion?: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@databuddy/sdk",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "private": false,
5
5
  "description": "Official Databuddy Analytics SDK",
6
6
  "main": "dist/index.js",