humanbehavior-js 0.5.66 → 0.5.67

package/README.md

@@ -1,25 +1,89 @@
-# HumanBehavior JS - Modular Edition
+# HumanBehavior JS - Modular SDK
 
-This is the modular version of the HumanBehavior JavaScript SDK, organized into separate packages for better maintainability and tree-shaking.
+A modular JavaScript SDK for recording user sessions and tracking events with high-fidelity session replay, automatic event tracking, and comprehensive analytics capabilities.
 
-## Quick Start
+## Architecture
+
+This SDK is built as a **monorepo** using npm workspaces and Turbo, organized into separate packages for optimal tree-shaking, maintainability, and framework-specific optimizations.
 
-### Simple Installation (Recommended)
+### Package Structure
 
-The easiest way to get started is with the main package:
+```
+humanbehavior-js/
+├── packages/
+│   ├── browser/      # Main entry point (re-exports from core)
+│   ├── core/         # Core SDK functionality
+│   ├── react/        # React hooks and context provider
+│   └── wizard/       # AI-enhanced installation wizard
+└── tooling/          # Shared build tools and configs
+```
+
+### Core Packages
+
+#### `humanbehavior-js` (Main Package)
+The primary package that provides everything you need out of the box. Re-exports from `@humanbehavior/core` and provides UMD builds for direct browser usage.
+
+**Exports:**
+- `HumanBehaviorTracker` - Main tracker class
+- `init()` - Initialization helper
+- Framework integrations via subpaths: `/react`, `/core`, `/wizard`
+
+#### `@humanbehavior/core`
+Core SDK functionality including:
+- **Session Recording**: High-fidelity session replay using rrweb
+- **Event Tracking**: Automatic and manual event tracking
+- **API Client**: Communication with HumanBehavior ingestion servers
+- **Redaction Manager**: Privacy-first data redaction
+- **Persistence Layer**: Session persistence across page reloads
+- **Retry Queue**: Reliable event delivery with retry logic
+- **Utilities**: Logger, property manager, global tracker
+
+#### `@humanbehavior/react`
+React-specific integrations:
+- `HumanBehaviorProvider` - Context provider for React apps
+- `useHumanBehavior()` - Hook to access tracker instance
+- `useRedaction()` - Hook for managing redaction fields
+- `useUserTracking()` - Hook for user identification
+- Automatic page view tracking for SPAs
+
+#### `@humanbehavior/wizard`
+AI-enhanced installation wizard:
+- Framework detection and auto-installation
+- Code modification suggestions
+- CLI tools for setup automation
+- Centralized AI service integration
+
+## Installation
+
+### Quick Start (Recommended)
 
 ```bash
 npm install humanbehavior-js
 ```
 
-This gives you everything you need to start recording user sessions and events. The package automatically includes:
-- Core session recording functionality
+This single package includes everything you need:
+- Core session recording
 - Automatic event tracking
 - User identification
 - Data redaction
 - Session persistence
+- Framework integrations
+
+### Framework-Specific Packages (Optional)
+
+For better tree-shaking, you can install framework-specific packages:
+
+```bash
+# React
+npm install @humanbehavior/react
+
+# Or use subpath imports
+import { useHumanBehavior } from 'humanbehavior-js/react';
+```
+
+## Quick Start
 
-### Basic Usage
+### Vanilla JavaScript
 
 ```javascript
 import { HumanBehaviorTracker } from 'humanbehavior-js';
@@ -28,165 +92,491 @@ const tracker = HumanBehaviorTracker.init('your-api-key');
 tracker.start();
 ```
 
-## Package Structure
+### React
 
-### Main Package
+```jsx
+import { HumanBehaviorProvider, useHumanBehavior } from 'humanbehavior-js/react';
+
+function App() {
+  return (
+    <HumanBehaviorProvider apiKey="your-api-key">
+      <YourApp />
+    </HumanBehaviorProvider>
+  );
+}
 
-- **`humanbehavior-js`** - Complete SDK with all features (recommended for most users)
+function MyComponent() {
+  const tracker = useHumanBehavior();
+  
+  const handleClick = () => {
+    tracker.customEvent('button_clicked', { buttonId: 'signup' });
+  };
+  
+  return <button onClick={handleClick}>Sign Up</button>;
+}
+```
 
-### Framework Integrations (Optional)
+### UMD Build (Browser)
 
-These packages provide framework-specific optimizations and are **completely optional**:
+```html
+<script src="https://unpkg.com/humanbehavior-js"></script>
+<script>
+  const tracker = HumanBehaviorTracker.init('your-api-key');
+  tracker.start();
+</script>
+```
 
-- **`@humanbehavior/react`** - React hooks and context (or use `humanbehavior-js/react`)
-- **`@humanbehavior/vue`** - Vue.js plugin (or use `humanbehavior-js/vue`)
-- **`@humanbehavior/svelte`** - Svelte integration (or use `humanbehavior-js/svelte`)
-- **`@humanbehavior/remix`** - Remix.js integration (or use `humanbehavior-js/remix`)
-- **`@humanbehavior/angular`** - Angular integration (or use `humanbehavior-js/angular`)
+## Key Features
+
+### 🎥 Session Recording
+- **High-fidelity replay** using rrweb
+- Captures mouse movements, clicks, scrolls, keyboard input
+- Canvas recording support (optional)
+- Multi-window tracking
+- Session persistence across page reloads (30-minute window)
+
+### 📊 Event Tracking
+- **Automatic tracking** of buttons, links, and forms
+- Custom event tracking
+- Console and network error tracking
+- Navigation tracking for SPAs
+- Rage click and dead click detection
+
+### 🔒 Privacy & Security
+- **Privacy-first redaction** by default
+- Configurable redaction strategies
+- Field-level data masking
+- Unredaction for specific fields when needed
+
+### 👤 User Identification
+- User property tracking
+- Session-to-user association
+- Global user identification across sessions
+
+### 🚀 Performance
+- Event batching and queueing
+- Automatic retry on failures
+- Configurable queue sizes
+- Tree-shakeable modules
+
+## Configuration Options
 
-### Advanced Packages
+```javascript
+const tracker = HumanBehaviorTracker.init('your-api-key', {
+  ingestionUrl: 'https://your-ingestion-url.com',
+  redactionStrategy: {
+    mode: 'privacy-first', // or 'visibility-first'
+    unredactFields: ['email', 'name'] // Fields to keep visible
+  },
+  enableAutomaticTracking: true,
+  automaticTrackingOptions: {
+    trackButtons: true,
+    trackLinks: true,
+    trackForms: true,
+    includeText: true,
+    includeClasses: true
+  },
+  recordCanvas: false, // Enable canvas recording
+  maxQueueSize: 1000, // Maximum events in queue
+  enableConsoleTracking: true, // Track console errors
+  enableNetworkTracking: true // Track network errors
+});
+```
 
-- **`@humanbehavior/core`** - Core SDK functionality (for advanced users)
-- **`@humanbehavior/wizard`** - Installation wizard and CLI tools
+## API Reference
 
-## Installation Options
+### Core Methods
 
-### Option 1: Single Package (Simplest)
+```javascript
+// Initialize
+const tracker = HumanBehaviorTracker.init(apiKey, options);
 
-```bash
-npm install humanbehavior-js
+// Start/Stop recording
+tracker.start();
+tracker.stop();
+
+// User identification
+tracker.identifyUser({ userProperties: { email: 'user@example.com' } });
+
+// Custom events
+tracker.customEvent('event_name', { property: 'value' });
+
+// Redaction
+tracker.setUnredactedFields(['email', 'name']);
+tracker.getUnredactedFields();
+
+// Session info
+tracker.getSessionId();
+tracker.getCurrentUrl();
 ```
 
-Then import framework features as needed:
+## API Endpoints
+
+The SDK communicates with HumanBehavior ingestion servers through the following endpoints. All requests include authentication via `Authorization: Bearer {apiKey}` header.
+
+### `POST /api/ingestion/events`
+
+**When:** Called automatically when events are batched (every 3 seconds) or when queue reaches maximum size
+
+**Request Body:**
+```json
+{
+  "sessionId": "string",
+  "events": [
+    {
+      "type": "string",
+      "timestamp": number,
+      "data": {...},
+      ...
+    }
+  ],
+  "endUserId": "string | null",
+  "windowId": "string (optional)",
+  "automaticProperties": {...} (optional),
+  "sdkVersion": "string"
+}
+```
 
-```javascript
-// Core functionality
-import { HumanBehaviorTracker } from 'humanbehavior-js';
+**Headers:**
+- `Authorization: Bearer {apiKey}`
+- `Content-Type: application/json`
+
+**Response:**
+```json
+{
+  "success": true,
+  "appended": number,
+  "sessionCreated": boolean,
+  "monthlyLimitReached": boolean (optional)
+}
+```
 
-// React features (if needed)
-import { useHumanBehavior } from 'humanbehavior-js/react';
+**Purpose:** Sends session replay events (rrweb events) and custom events to the server. Supports chunking for large payloads (max 1MB per chunk). Events are automatically batched and sent every 3 seconds. **Sessions are created automatically on the server when the first event is received** (PostHog-style, no separate init call needed).
+
+**Special Features:**
+- Automatic chunking for payloads > 1MB
+- Retry logic with exponential backoff
+- Persistence to localStorage for offline scenarios
+- Falls back to `sendBeacon` on page unload or CSP violations
+
+---
+
+### `POST /api/ingestion/user`
+
+**When:** Called when `tracker.identifyUser()` is invoked
 
-// Vue features (if needed)
-import { HumanBehaviorPlugin } from 'humanbehavior-js/vue';
+**Request Body:**
+```json
+{
+  "userId": "string",
+  "userAttributes": {
+    "email": "string",
+    "name": "string",
+    ...
+  },
+  "sessionId": "string",
+  "posthogName": "string | null"
+}
 ```
 
-### Option 2: Framework-Specific Packages
+**Headers:**
+- `Authorization: Bearer {apiKey}`
+- `Content-Type: application/json`
 
-If you prefer separate packages for better tree-shaking:
+**Response:**
+```json
+{
+  "success": true,
+  "userId": "string",
+  "sessionId": "string"
+}
+```
 
-```bash
-# React
-npm install @humanbehavior/react
+**Purpose:** Identifies and associates user properties with a session. Creates or updates user profile on the server.
 
-# Vue
-npm install @humanbehavior/vue
+---
 
-# Svelte
-npm install @humanbehavior/svelte
+### `POST /api/ingestion/user/auth`
 
-# Remix
-npm install @humanbehavior/remix
+**When:** Called when `tracker.auth()` is invoked
+
+**Request Body:**
+```json
+{
+  "userId": "string",
+  "userAttributes": {
+    "email": "string",
+    "name": "string",
+    ...
+  },
+  "sessionId": "string",
+  "authFields": ["email", "password", ...]
+}
+```
 
-# Angular
-npm install @humanbehavior/angular
+**Headers:**
+- `Authorization: Bearer {apiKey}`
+- `Content-Type: application/json`
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "User authenticated",
+  "userId": "string",
+  "sessionId": "string"
+}
 ```
 
-## Usage Examples
+**Purpose:** Authenticates a user and marks specific fields as authentication-related for enhanced security handling.
 
-### Basic Usage (Vanilla JS)
+---
 
-```javascript
-import { HumanBehaviorTracker } from 'humanbehavior-js';
+### `POST /api/ingestion/customEvent`
 
-const tracker = HumanBehaviorTracker.init('your-api-key');
-tracker.start();
+**When:** Called when `tracker.customEvent()` is invoked
+
+**Request Body:**
+```json
+{
+  "sessionId": "string",
+  "eventName": "string",
+  "eventProperties": {
+    "property1": "value1",
+    ...
+  },
+  "endUserId": "string | null"
+}
 ```
 
-### React Integration
+**Headers:**
+- `Authorization: Bearer {apiKey}`
+- `Content-Type: application/json`
 
-```jsx
-import { useHumanBehavior } from 'humanbehavior-js/react';
+**Response:**
+```json
+{
+  "success": true,
+  "eventId": "string"
+}
+```
 
-function MyComponent() {
-  const tracker = useHumanBehavior();
-  
-  const handleClick = () => {
-    tracker.customEvent('button_clicked');
-  };
+**Purpose:** Sends a single custom event to the server for analytics tracking.
 
-  return <button onClick={handleClick}>Click me</button>;
+---
+
+### `POST /api/ingestion/customEvent/batch`
+
+**When:** Called when multiple custom events need to be sent together
+
+**Request Body:**
+```json
+{
+  "sessionId": "string",
+  "events": [
+    {
+      "eventName": "string",
+      "eventProperties": {...}
+    },
+    ...
+  ],
+  "endUserId": "string | null"
 }
 ```
 
-### Vue Integration
+**Headers:**
+- `Authorization: Bearer {apiKey}`
+- `Content-Type: application/json`
 
-```javascript
-import { createApp } from 'vue';
-import { HumanBehaviorPlugin } from 'humanbehavior-js/vue';
+**Response:**
+```json
+{
+  "success": true,
+  "eventIds": ["string", ...]
+}
+```
 
-const app = createApp(App);
-app.use(HumanBehaviorPlugin, {
-  apiKey: 'your-api-key'
-});
+**Purpose:** Sends multiple custom events in a single request for better efficiency.
+
+---
+
+### `POST /api/ingestion/logs`
+
+**When:** Called automatically when console warnings or errors occur (if `enableConsoleTracking` is true)
+
+**Request Body:**
+```json
+{
+  "level": "warn" | "error",
+  "message": "string",
+  "stack": "string (optional)",
+  "url": "string",
+  "timestampMs": number,
+  "sessionId": "string",
+  "endUserId": "string | null"
+}
 ```
 
-### Svelte Integration
+**Headers:**
+- `Authorization: Bearer {apiKey}`
+- `Content-Type: application/json`
 
-```javascript
-import { humanBehaviorStore } from 'humanbehavior-js/svelte';
+**Response:**
+```json
+{
+  "success": true
+}
+```
+
+**Purpose:** Tracks console warnings and errors for debugging and monitoring. Only sends `warn` and `error` level logs, not `log` or `info`.
+
+---
+
+### `POST /api/ingestion/network`
+
+**When:** Called automatically when network requests fail (4xx, 5xx errors) or encounter network errors (if `enableNetworkTracking` is true)
+
+**Request Body:**
+```json
+{
+  "requestId": "string",
+  "url": "string",
+  "method": "string",
+  "status": number | null,
+  "statusText": "string | null",
+  "duration": number,
+  "timestampMs": number,
+  "sessionId": "string",
+  "endUserId": "string | null",
+  "errorType": "client_error" | "server_error" | "network_error" | "timeout_error" | "cors_error" | "csp_violation" | "blocked_by_client" | "unknown_error",
+  "errorMessage": "string | null",
+  "errorName": "string | null",
+  "startTimeMs": number (optional),
+  "spanName": "string (optional)",
+  "spanStatus": "error" | "success" | "slow" (optional),
+  "attributes": {
+    "http.status_code": number,
+    "http.status_text": "string",
+    ...
+  }
+}
+```
 
-const tracker = humanBehaviorStore.init('your-api-key');
+**Headers:**
+- `Authorization: Bearer {apiKey}`
+- `Content-Type: application/json`
+
+**Response:**
+```json
+{
+  "success": true
+}
 ```
 
+**Purpose:** Tracks network errors and failed HTTP requests for monitoring and debugging. Automatically classifies error types (CORS, timeout, CSP violations, etc.). **Note:** SDK's own requests to ingestion endpoints are excluded from tracking to avoid recursion.
+
+---
+
+## Request Flow & Timing
+
+1. **Initialization**: SDK creates session ID locally (no server call)
+2. **Event Batching**: `POST /api/ingestion/events` is called:
+   - Every 3 seconds (automatic flush interval)
+   - When event queue reaches maximum size
+   - On page unload (via `sendBeacon` if available)
+3. **User Actions**: `POST /api/ingestion/user` or `/user/auth` when user identification occurs
+4. **Custom Events**: `POST /api/ingestion/customEvent` immediately when `customEvent()` is called
+5. **Error Tracking**: `POST /api/ingestion/logs` and `/network` are called asynchronously when errors occur
+
+## Error Handling
+
+- **429 (Rate Limit)**: SDK sets `monthlyLimitReached` flag and stops sending events
+- **413 (Payload Too Large)**: SDK automatically reduces batch size and retries
+- **Network Errors**: Events are persisted to localStorage and retried with exponential backoff
+- **CSP Violations**: SDK automatically falls back to `sendBeacon` API
+- **Offline**: Events are queued and sent when connection is restored
+
 ## Development
 
+### Prerequisites
+- Node.js 18+
+- npm 10+
+
 ### Setup
+
 ```bash
+# Install dependencies
 npm install
-```
 
-### Build all packages
-```bash
+# Build all packages
 npm run build
-```
 
-### Build specific package
-```bash
+# Build specific package
 npm run build --workspace=@humanbehavior/core
-```
 
-### Development mode
-```bash
+# Development mode (watch)
 npm run dev
-```
 
-## Architecture
+# Linting
+npm run lint
+npm run lint:fix
+
+# Testing
+npm run test
+```
 
-This modular structure provides several benefits:
+### Project Structure
 
-1. **Simple Start**: Install just `humanbehavior-js` and everything works
-2. **Progressive Enhancement**: Add framework-specific features as needed
-3. **Tree-shaking**: Only import what you need
-4. **Framework-specific optimizations**: Each framework package is optimized for its target
-5. **Better maintainability**: Clear separation of concerns
-6. **Reduced bundle size**: Smaller packages for specific use cases
-7. **Easier testing**: Isolated packages are easier to test
+- **Monorepo**: Uses npm workspaces for package management
+- **Build System**: Turbo for fast, cached builds
+- **Bundling**: Rollup for ESM, CJS, and UMD outputs
+- **TypeScript**: Full TypeScript support with type definitions
 
-## Migration from v1
+### Package Exports
 
-The API remains the same, but the import paths have changed:
+The main package uses modern package.json exports:
 
 ```javascript
-// Old
-import { HumanBehaviorTracker } from 'humanbehavior-js';
-
-// New - Same as before!
+// Main entry
 import { HumanBehaviorTracker } from 'humanbehavior-js';
 
-// Or for framework-specific features
+// React integration
 import { useHumanBehavior } from 'humanbehavior-js/react';
+
+// Core package (advanced)
+import { HumanBehaviorTracker } from 'humanbehavior-js/core';
+
+// Wizard (CLI)
+import { AIAutoInstallCLI } from 'humanbehavior-js/wizard';
 ```
 
+## Architecture Benefits
+
+1. **Simple Start**: Install one package and everything works
+2. **Progressive Enhancement**: Add framework-specific features as needed
+3. **Tree-shaking**: Only bundle what you use
+4. **Framework Optimizations**: Each framework package is optimized for its target
+5. **Better Maintainability**: Clear separation of concerns
+6. **Reduced Bundle Size**: Smaller packages for specific use cases
+7. **Easier Testing**: Isolated packages are easier to test
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## License
+
+ISC
+
+## Links
+
+- **Documentation**: https://documentation.humanbehavior.co
+- **Repository**: https://github.com/humanbehavior-gh/humanbehavior-js
+- **Homepage**: https://documentation.humanbehavior.co
+
 ## Contributing
 
 1. Fork the repository
@@ -195,6 +585,7 @@ import { useHumanBehavior } from 'humanbehavior-js/react';
 4. Add tests
 5. Submit a pull request
 
-## License
+---
+
+Built with ❤️ by the HumanBehavior team
 
-ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanbehavior-js",
-  "version": "0.5.66",
+  "version": "0.5.67",
   "description": "SDK for HumanBehavior session and event recording",
   "private": false,
   "packageManager": "npm@10.0.0",