userpath-js 0.0.0 → 0.0.1

package/README.md

@@ -0,0 +1,609 @@
+# UserPath Client SDK
+
+UserPath is a privacy-focused analytics tool that serves as an alternative to Google Analytics. It's built with a focus on reliability, performance, and data privacy. The platform offers first-party integration capabilities, allowing you to collect and analyze user data directly from your own servers without external dependencies, resulting in more accurate and comprehensive insights.
+
+## Installation
+
+```bash
+npm install userpath-js
+```
+
+## Usage
+
+UserPath can be used both in the browser and server in different contexts.
+
+### NPM
+
+In a browser environment, you can import the `UserPath` class and initialize it with your app ID and base URL. The library will automatically track events and send them to the server, but you can also track custom events.
+
+```ts
+// file: src/userpath.ts
+import { UserPath } from 'userpath-js';
+
+const up = new UserPath({
+	appId: 'my-app-id',
+	serverUrl: 'https://my-userpath-domain.com/events', // Optional
+	version: 1,
+	flushIntervalMs: 5000, // Optional: Time in milliseconds between event batch sends (default: 5000)
+});
+
+export { up };
+```
+
+```ts
+// file: src/pricing.ts
+import { up } from './userpath';
+
+up.track('purchase', {
+	price: 42,
+	amount: 10,
+	currency: 'USD',
+	properties: {
+		product_id: '123',
+		product_name: 'Product 1',
+	},
+});
+```
+
+### Browser
+
+Alternatively, you can include the UserPath Pixel using a script tag in your HTML file. This will initialize the client and automatically start tracking events. You can also track custom events using the exposed `userpath` object in the global scope.
+
+```html
+<!-- index.html -->
+<script
+	src="https://my-userpath-domain.com/events/v1/px.js"
+	data-up-app="my-app-id"
+></script>
+```
+
+```js
+// index.js
+const up = window.userpath;
+up.track('purchase', {
+	price: 42,
+	amount: 10,
+	currency: 'USD',
+});
+```
+
+### Server Integration
+
+In order to avoid privacy-first browsers and ad blockers, you can use the UserPath server integration to provide a first-party analytics solution. This will proxy all requests to the main UserPath server, so you can continue to use the client in the browser as usual without worrying about being blocked.
+
+```ts
+// file: src/index.ts
+import { userpath } from 'userpath-js/server';
+
+// Using Node.js
+http
+	.createServer(function (req, res) {
+		return userpath.fetch(req);
+	})
+	.listen(3000);
+
+// Using Bun
+Bun.serve({
+	fetch(req) {
+		return userpath.fetch(req);
+	},
+});
+
+// Using Elysia
+const app = new Elysia({ name: 'my-userpath' });
+
+app.get('/', () => 'Hello World from Elysia');
+
+app.mount('/events', userpath.fetch); // Mount the UserPath server
+
+app.listen(3000);
+```
+
+UserPath also provides easy and native integrations for the most popular server frameworks:
+
+- [Elysia](./elysia/README.md)
+- [Express](./express/README.md) (soon)
+- [Fastify](./fastify/README.md) (soon)
+- [Koa](./koa/README.md) (soon)
+- [Nest](./nest/README.md) (soon)
+- [Next](./next/README.md) (soon)
+- [Nuxt](./nuxt/README.md) (soon)
+
+## Automatic Event Tracking
+
+When using the client in the browser, UserPath automatically tracks various user interactions without any additional configuration. Here's what gets tracked automatically, but you can also track custom events.
+
+### Form Interactions
+
+#### Form Submissions (`form_submit`)
+
+Tracks when users submit forms:
+
+```ts
+{
+  name: 'form_submit',
+  url: 'https://example.com/signup',
+  referrer: 'https://example.com/home',
+  properties: {
+    form_name: 'signup-form', // Form name, id, or aria-label
+    time_to_complete: 15000, // Time in milliseconds from first interaction to submission
+  }
+}
+```
+
+#### Text Input Fields (`input_fill`)
+
+Tracks when users complete filling in text-based input fields. Events are only fired when:
+
+- The input value has actually changed
+- The new value is not empty
+- The user has finished editing (on blur)
+
+```ts
+{
+  name: 'input_fill',
+  url: 'https://example.com/signup',
+  referrer: 'https://example.com/home',
+  properties: {
+    input_type: 'text', // text, email, number, etc.
+    label: 'Full Name', // Input label or identifier
+    form_name: 'signup-form', // If available
+  }
+}
+```
+
+#### Select Dropdowns (`input_select`)
+
+Tracks when users select an option from dropdowns:
+
+```ts
+{
+  name: 'input_select',
+  url: 'https://example.com/checkout',
+  referrer: 'https://example.com/cart',
+  properties: {
+    input_type: 'select',
+    label: 'Country',
+    option_label: 'United States',
+    form_name: 'shipping-form',
+  }
+}
+```
+
+#### Radio Buttons (`input_radio`)
+
+Tracks radio button selections:
+
+```ts
+{
+  name: 'input_radio',
+  url: 'https://example.com/profile',
+  referrer: 'https://example.com/settings',
+  properties: {
+    input_type: 'radio',
+    group: 'gender',
+    label: 'Male',
+    form_name: 'profile-form',
+  }
+}
+```
+
+#### Checkboxes (`input_checkbox`)
+
+Tracks checkbox interactions:
+
+```ts
+{
+  name: 'input_checkbox',
+  url: 'https://example.com/preferences',
+  referrer: 'https://example.com/signup',
+  properties: {
+    input_type: 'checkbox',
+    label: 'Subscribe to newsletter',
+    checked: true,
+    form_name: 'preferences-form',
+  }
+}
+```
+
+#### Range Inputs (`input_range`)
+
+Tracks range slider changes:
+
+```ts
+{
+  name: 'input_range',
+  url: 'https://example.com/settings',
+  referrer: 'https://example.com/profile',
+  properties: {
+    input_type: 'range',
+    label: 'Volume',
+    form_name: 'settings-form',
+  }
+}
+```
+
+### Click Tracking
+
+Automatically tracks meaningful clicks on:
+
+- Buttons
+- Links
+- Interactive elements with labels
+
+```ts
+{
+  name: 'click',
+  url: 'https://example.com/form',
+  referrer: 'https://example.com/home',
+  properties: {
+    label: 'Submit',
+    element: 'button',
+    id: 'submit-btn',
+  }
+}
+```
+
+### Scroll Tracking
+
+Tracks meaningful scroll depth on pages:
+
+```ts
+{
+  name: 'scroll',
+  url: 'https://example.com/blog/post',
+  title: 'Blog Post Title',
+  referrer: 'https://example.com'
+}
+```
+
+### Video Tracking
+
+Automatically tracks video interactions for HTML5 video elements:
+
+#### Video Play (`video_play`)
+
+Tracks when a video starts playing:
+
+```ts
+{
+  name: 'video_play',
+  url: 'https://example.com/page',
+  referrer: 'https://example.com',
+  title: 'Introduction Video', // Video title if available
+  properties: {
+    duration: 180, // Total video duration in seconds
+    current_time: 0, // Current playback position in seconds
+    src: 'https://example.com/video.mp4',
+    video_id: 'intro-video', // Video element ID if available
+  }
+}
+```
+
+#### Video Pause (`video_pause`)
+
+Tracks when a video is paused:
+
+```ts
+{
+  name: 'video_pause',
+  url: 'https://example.com/page',
+  referrer: 'https://example.com',
+  title: 'Introduction Video',
+  properties: {
+    duration: 180,
+    current_time: 45,
+    watch_time: 45, // Time watched in this session in seconds
+    src: 'https://example.com/video.mp4',
+    video_id: 'intro-video',
+  }
+}
+```
+
+#### Video Complete (`video_complete`)
+
+Tracks when a video playback completes:
+
+```ts
+{
+  name: 'video_complete',
+  url: 'https://example.com/page',
+  referrer: 'https://example.com',
+  title: 'Introduction Video',
+  properties: {
+    duration: 180,
+    current_time: 180,
+    watch_time: 180, // Total time watched in this session in seconds
+    src: 'https://example.com/video.mp4',
+    video_id: 'intro-video',
+  }
+}
+```
+
+### Page Time Tracking
+
+Automatically tracks how long users spend on pages, including active (visible) time:
+
+### User Activity Tracking
+
+Automatically tracks user activity and inactivity periods:
+
+#### User Inactive (`user_inactive`)
+
+Tracks when a user becomes inactive (no mouse movement, keyboard input, or other interactions for 60 seconds):
+
+```ts
+{
+  name: 'user_inactive',
+  url: 'https://example.com/page',
+  title: 'Page Title'
+}
+```
+
+#### User Active (`user_active`)
+
+Tracks when a user becomes active again after being inactive:
+
+```ts
+{
+  name: 'user_active',
+  properties: {
+    inactive_duration: 75, // How long the user was inactive in seconds
+    url: 'https://example.com/page',
+    title: 'Page Title'
+  }
+}
+```
+
+#### Page View (`page_view`)
+
+Tracks when a page is initially loaded:
+
+```ts
+{
+  name: 'page_view',
+  url: 'https://example.com/page',
+  title: 'Page Title',
+  referrer: 'https://example.com'
+}
+```
+
+#### Page Visibility (`page_visibility`)
+
+Tracks when users switch tabs or minimize the browser:
+
+```ts
+{
+  name: 'page_visibility',
+  url: 'https://example.com/page',
+  title: 'Page Title',
+  referrer: 'https://example.com',
+  properties: {
+    visible: true, // or false
+    total_time: 120, // Total time since page load in seconds
+    visible_time: 85 // Time the page was actually visible in seconds
+  }
+}
+```
+
+#### Page Exit (`page_exit`)
+
+Tracks timing information when users leave the page:
+
+```ts
+{
+  name: 'page_exit',
+  url: 'https://example.com/page',
+  title: 'Page Title',
+  referrer: 'https://example.com',
+  properties: {
+    total_time: 300, // Total time spent on page in seconds
+    visible_time: 240 // Time the page was actually visible in seconds
+  }
+}
+```
+
+### Privacy Considerations
+
+- Password fields are never tracked
+- Only interaction events are tracked, not actual input values
+- Form submissions are tracked without capturing sensitive data
+- All tracking respects user privacy settings and GDPR compliance
+
+### Error Tracking
+
+UserPath automatically captures uncaught errors and unhandled promise rejections in your application, providing valuable insights about JavaScript errors that users encounter.
+
+#### Automatic Error Tracking
+
+When enabled (on by default), the SDK will automatically capture:
+
+- Uncaught exceptions via the global `error` event
+- Unhandled promise rejections via the `unhandledrejection` event
+
+```ts
+{
+  name: 'error',
+  message: 'Cannot read property of undefined',
+  stack: 'Error: Cannot read property of undefined\n    at button.onClick (app.js:42)',
+  source: 'window.onerror',
+  filename: 'app.js',
+  lineno: 42,
+  colno: 24
+}
+```
+
+#### Manual Error Tracking
+
+You can also manually track errors in try/catch blocks:
+
+```ts
+try {
+	// Some code that might throw an error
+	processUserPurchase();
+} catch (error) {
+	// Log the error to UserPath
+	up.trackError(error, {
+		context: 'purchase_flow',
+		product_id: '123',
+	});
+
+	// Handle the error appropriately
+	showErrorMessage();
+}
+```
+
+#### Disabling Automatic Tracking Features
+
+UserPath automatically tracks various user interactions, but you can customize which features are enabled:
+
+```ts
+// All tracking options are enabled by default
+const up = new UserPath({
+	appId: 'my-app-id',
+	autoTrack: {
+		errors: true, // Track JavaScript errors
+		clicks: true, // Track clicks on buttons, links, etc.
+		scrolling: true, // Track scroll depth
+		forms: true, // Track form interactions and submissions
+		videos: true, // Track video play/pause/end events
+		pageVisibility: true, // Track page visibility and time spent
+		inactivity: true, // Track user activity/inactivity
+	},
+});
+```
+
+You can disable any specific tracking feature individually:
+
+```ts
+const up = new UserPath({
+	appId: 'my-app-id',
+	autoTrack: {
+		forms: false, // Disable form tracking
+		videos: false, // Disable video tracking
+	},
+});
+```
+
+You can also disable error tracking after initialization:
+
+```ts
+up.uninstallErrorHandler();
+```
+
+And re-enable it later if needed:
+
+```ts
+up.installErrorHandler();
+```
+
+## User Identification
+
+There are several ways to identify users in UserPath:
+
+### Via Script Tag
+
+You can add a `data-up-user` attribute to your script tag to identify users immediately:
+
+```html
+<script
+	src="https://api.userpath.co/v1/px.js"
+	data-up-app="your-app-id"
+	data-up-user="user123"
+></script>
+```
+
+### Via SDK
+
+You can also identify users programmatically using the SDK:
+
+```js
+// On initialization
+const up = new UserPath({
+	appId: 'your-app-id',
+	userId: 'user123',
+});
+
+// Set user ID programmatically
+up.setUserId('user123');
+
+// Or with additional user information
+up.identify({
+	id: 'user123',
+	email: 'user@example.com',
+	name: 'John Doe',
+	properties: {
+		plan: 'premium',
+		signupDate: '2023-01-15',
+	},
+});
+```
+
+### Retrieving User ID
+
+You can get the current user ID:
+
+```js
+const currentUserId = userpath.getUserId();
+```
+
+## Questions
+
+Got questions? We're here to help!
+
+Email us at `support@userpath.co`
+
+## Configuration Options
+
+When initializing the UserPath SDK, you can provide several configuration options:
+
+| Option            | Type   | Default                   | Description                                                                                                                           |
+| ----------------- | ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `appId`           | string | (required)                | Your UserPath application ID                                                                                                          |
+| `serverUrl`       | string | "https://api.userpath.co" | The base URL for the UserPath API                                                                                                     |
+| `version`         | number | 1                         | API version to use                                                                                                                    |
+| `userId`          | string | undefined                 | Optional user ID to associate with all events                                                                                         |
+| `flushIntervalMs` | number | 5000                      | Time in milliseconds between event batch sends. Events are batched and sent in groups rather than individually to reduce server load. |
+| `autoTrack`       | object | see below                 | Configuration for automatic event tracking                                                                                            |
+
+### Auto-tracking Configuration
+
+```ts
+// All tracking options are enabled by default
+const up = new UserPath({
+	appId: 'my-app-id',
+	autoTrack: {
+		errors: true, // Track JavaScript errors
+		clicks: true, // Track clicks on buttons, links, etc.
+		scrolling: true, // Track scroll depth
+		forms: true, // Track form interactions and submissions
+		videos: true, // Track video play/pause/end events
+		pageVisibility: true, // Track page visibility and time spent
+		inactivity: true, // Track user activity/inactivity
+	},
+});
+```
+
+You can disable any specific tracking feature individually:
+
+```ts
+const up = new UserPath({
+	appId: 'my-app-id',
+	autoTrack: {
+		forms: false, // Disable form tracking
+		videos: false, // Disable video tracking
+	},
+});
+```
+
+You can also disable error tracking after initialization:
+
+```ts
+up.uninstallErrorHandler();
+```
+
+And re-enable it later if needed:
+
+```ts
+up.installErrorHandler();
+```