@databuddy/sdk 1.0.0 → 1.1.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 (6) hide show
  1. package/README.md +130 -0
  2. package/package.json +4 -2
  3. package/src/DatabuddyProvider.tsx +0 -33
  4. package/src/index.ts +0 -2
  5. package/src/types.ts +0 -173
  6. package/tsconfig.json +0 -19
package/README.md ADDED
@@ -0,0 +1,130 @@
1
+ # Databuddy SDK
2
+
3
+ A modern, type-safe analytics SDK and React component for integrating [Databuddy](https://www.databuddy.cc) into your web apps.
4
+
5
+ ## Features
6
+
7
+ - 📊 **Automatic page/screen view tracking**
8
+ - ⚡ **Performance, Web Vitals, and error tracking**
9
+ - 🧑‍💻 **Custom event tracking**
10
+ - 🧩 **Drop-in React/Next.js component: `<Databuddy />`**
11
+ - 🛡️ **Privacy-first: anonymized by default, sampling, batching, and more**
12
+ - 🛠️ **Type-safe config and autocompletion**
13
+
14
+ ---
15
+
16
+ ## Installation
17
+
18
+ ```sh
19
+ bun add @databuddy/sdk
20
+ # or
21
+ npm install @databuddy/sdk
22
+ ```
23
+
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`):
31
+
32
+ ```tsx
33
+ import { Databuddy } from '@databuddy/sdk';
34
+
35
+ export default function RootLayout({ children }) {
36
+ return (
37
+ <html lang="en">
38
+ <head />
39
+ <Databuddy
40
+ clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID!}
41
+ trackScreenViews
42
+ trackPerformance
43
+ trackErrors
44
+ enableBatching
45
+ batchSize={20}
46
+ />
47
+ <body>{children}</body>
48
+ </html>
49
+ );
50
+ }
51
+ ```
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.**
55
+
56
+ ### 2. **Script Tag (Vanilla HTML/JS)**
57
+
58
+ If you don't use React, you can add the script directly:
59
+
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
+ ```
69
+
70
+ ---
71
+
72
+ ## Configuration Options
73
+
74
+ All options are type-safe and documented in `DatabuddyConfig`:
75
+
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). |
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://docs.databuddy.cc)
125
+ - [Dashboard](https://app.databuddy.cc)
126
+ - [Contact Support](https://www.databuddy.cc/contact)
127
+
128
+ ---
129
+
130
+ © Databuddy. All rights reserved.
package/package.json CHANGED
@@ -1,12 +1,15 @@
1
1
  {
2
2
  "name": "@databuddy/sdk",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "private": false,
5
5
  "description": "Official Databuddy Analytics SDK",
6
6
  "main": "dist/index.js",
7
7
  "exports": {
8
8
  ".": "./dist/index.js"
9
9
  },
10
+ "files": [
11
+ "dist"
12
+ ],
10
13
  "keywords": [
11
14
  "analytics",
12
15
  "tracking",
@@ -16,7 +19,6 @@
16
19
  "scripts": {
17
20
  "build": "tsc --project tsconfig.json"
18
21
  },
19
- "author": "Databuddy",
20
22
  "license": "MIT",
21
23
  "devDependencies": {
22
24
  "@types/node": "^20.0.0",
package/src/DatabuddyProvider.tsx DELETED
@@ -1,33 +0,0 @@
1
- 'use client';
2
-
3
- import { useEffect } from 'react';
4
- import type { DatabuddyConfig } from './types';
5
-
6
- /**
7
- * <Databuddy /> component for Next.js/React apps
8
- * Injects the databuddy.js script with all config as data attributes
9
- * Usage: <Databuddy clientId="..." trackScreenViews trackPerformance ... />
10
- */
11
- export function Databuddy(props: DatabuddyConfig) {
12
- useEffect(() => {
13
- if (typeof window === 'undefined') return;
14
- if (document.querySelector('script[data-databuddy-injected]')) return;
15
- const script = document.createElement('script');
16
- script.src = props.scriptUrl || 'https://app.databuddy.cc/databuddy.js';
17
- script.defer = true;
18
- script.setAttribute('data-databuddy-injected', 'true');
19
- for (const [key, value] of Object.entries(props)) {
20
- if (value !== undefined) {
21
- const dataKey = `data-${key.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
22
- script.setAttribute(dataKey, String(value));
23
- }
24
- }
25
- document.head.appendChild(script);
26
- return () => {
27
- script.remove();
28
- };
29
- }, [props]);
30
- return null;
31
- }
32
-
33
- export default Databuddy;
package/src/index.ts DELETED
@@ -1,2 +0,0 @@
1
- export * from './DatabuddyProvider';
2
- export * from './types';
package/src/types.ts DELETED
@@ -1,173 +0,0 @@
1
- /**
2
- * Configuration options for the Databuddy SDK and <Databuddy /> component.
3
- * All options are passed as data attributes to the injected script.
4
- */
5
- export interface DatabuddyConfig {
6
- /**
7
- * Your Databuddy project client ID (required).
8
- * Get this from your Databuddy dashboard.
9
- * Example: '3ed1fce1-5a56-4cbc-a917-66864f6d18e3'
10
- */
11
- clientId: string;
12
-
13
- /**
14
- * (Advanced) Your Databuddy client secret for server-side operations.
15
- * Not required for browser usage.
16
- */
17
- clientSecret?: string;
18
-
19
- /**
20
- * Custom API endpoint for event ingestion.
21
- * Default: 'https://api.databuddy.cc'
22
- */
23
- apiUrl?: string;
24
-
25
- /**
26
- * Custom script URL for the Databuddy browser bundle.
27
- * Default: 'https://app.databuddy.cc/databuddy.js'
28
- */
29
- scriptUrl?: string;
30
-
31
- /**
32
- * SDK name for analytics (default: 'web').
33
- * Only override if you are building a custom integration.
34
- */
35
- sdk?: string;
36
-
37
- /**
38
- * SDK version (default: '1.0.0').
39
- * Only override for custom builds.
40
- */
41
- sdkVersion?: string;
42
-
43
- /**
44
- * Disable all tracking (default: false).
45
- * If true, no events will be sent.
46
- */
47
- disabled?: boolean;
48
-
49
- /**
50
- * Wait for user profile before sending events (advanced, default: false).
51
- */
52
- waitForProfile?: boolean;
53
-
54
- // --- Tracking Features ---
55
-
56
- /**
57
- * Automatically track screen/page views (default: true).
58
- */
59
- trackScreenViews?: boolean;
60
-
61
- /**
62
- * Track hash changes in the URL (default: false).
63
- */
64
- trackHashChanges?: boolean;
65
-
66
- /**
67
- * Track data-* attributes on elements (default: false).
68
- */
69
- trackAttributes?: boolean;
70
-
71
- /**
72
- * Track clicks on outgoing links (default: false).
73
- */
74
- trackOutgoingLinks?: boolean;
75
-
76
- /**
77
- * Track user sessions (default: false).
78
- */
79
- trackSessions?: boolean;
80
-
81
- /**
82
- * Track page performance metrics (default: true).
83
- */
84
- trackPerformance?: boolean;
85
-
86
- /**
87
- * Track Web Vitals metrics (default: true).
88
- */
89
- trackWebVitals?: boolean;
90
-
91
- /**
92
- * Track user engagement metrics (default: false).
93
- */
94
- trackEngagement?: boolean;
95
-
96
- /**
97
- * Track scroll depth (default: false).
98
- */
99
- trackScrollDepth?: boolean;
100
-
101
- /**
102
- * Track exit intent (default: false).
103
- */
104
- trackExitIntent?: boolean;
105
-
106
- /**
107
- * Track user interactions (default: false).
108
- */
109
- trackInteractions?: boolean;
110
-
111
- /**
112
- * Track JavaScript errors (default: true).
113
- */
114
- trackErrors?: boolean;
115
-
116
- /**
117
- * Track bounce rate (default: false).
118
- */
119
- trackBounceRate?: boolean;
120
-
121
- // --- Advanced/Performance ---
122
-
123
- /**
124
- * Sampling rate for events (0.0 to 1.0, default: 1.0).
125
- * Example: 0.5 = 50% of events sent.
126
- */
127
- samplingRate?: number;
128
-
129
- /**
130
- * Enable retries for failed requests (default: true).
131
- */
132
- enableRetries?: boolean;
133
-
134
- /**
135
- * Maximum number of retries for failed requests (default: 3).
136
- * Only used if enableRetries is true.
137
- */
138
- maxRetries?: number;
139
-
140
- /**
141
- * Initial retry delay in milliseconds (default: 500).
142
- * Only used if enableRetries is true.
143
- */
144
- initialRetryDelay?: number;
145
-
146
- /**
147
- * Enable event batching (default: true).
148
- */
149
- enableBatching?: boolean;
150
-
151
- /**
152
- * Number of events to batch before sending (default: 20).
153
- * Only used if enableBatching is true.
154
- * Min: 1, Max: 50
155
- */
156
- batchSize?: number;
157
-
158
- /**
159
- * Batch timeout in milliseconds (default: 5000).
160
- * Only used if enableBatching is true.
161
- * Min: 100, Max: 30000
162
- */
163
- batchTimeout?: number;
164
- }
165
-
166
- /**
167
- * Event properties that can be attached to any event
168
- */
169
- export interface EventProperties {
170
- /** Custom properties for the event */
171
- [key: string]: string | number | boolean | null | undefined | EventProperties;
172
- }
173
-
package/tsconfig.json DELETED
@@ -1,19 +0,0 @@
1
- {
2
- "compilerOptions": {
3
- "target": "es2018",
4
- "module": "esnext",
5
- "lib": ["dom", "esnext"],
6
- "declaration": true,
7
- "declarationDir": "dist",
8
- "strict": true,
9
- "moduleResolution": "node",
10
- "esModuleInterop": true,
11
- "skipLibCheck": true,
12
- "forceConsistentCasingInFileNames": true,
13
- "outDir": "dist",
14
- "rootDir": "src",
15
- "jsx": "react-jsx"
16
- },
17
- "include": ["src/**/*"],
18
- "exclude": ["node_modules", "dist", "**/*.test.ts"]
19
- }