humanbehavior-js/README.md

SDK for HumanBehavior session and event recording

# HumanBehavior JS - Modular SDK

A modular JavaScript SDK for recording user sessions and tracking events with high-fidelity session replay, automatic event tracking, and comprehensive analytics capabilities.

## 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.

### Package Structure

```
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 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

### Vanilla JavaScript

```javascript
import { HumanBehaviorTracker } from 'humanbehavior-js';

const tracker = HumanBehaviorTracker.init('your-api-key');
tracker.start();
```

### React

```jsx
import { HumanBehaviorProvider, useHumanBehavior } from 'humanbehavior-js/react';

function App() {
  return (
    <HumanBehaviorProvider apiKey="your-api-key">
      <YourApp />
    </HumanBehaviorProvider>
  );
}

function MyComponent() {
  const tracker = useHumanBehavior();
  
  const handleClick = () => {
    tracker.customEvent('button_clicked', { buttonId: 'signup' });
  };
  
  return <button onClick={handleClick}>Sign Up</button>;
}
```

### UMD Build (Browser)

```html
<script src="https://unpkg.com/humanbehavior-js"></script>
<script>
  const tracker = HumanBehaviorTracker.init('your-api-key');
  tracker.start();
</script>
```

## 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

```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
});
```

## API Reference

### Core Methods

```javascript
// Initialize
const tracker = HumanBehaviorTracker.init(apiKey, options);

// 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();
```

## 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"
}
```

**Headers:**
- `Authorization: Bearer {apiKey}`
- `Content-Type: application/json`

**Response:**
```json
{
  "success": true,
  "appended": number,
  "sessionCreated": boolean,
  "monthlyLimitReached": boolean (optional)
}
```

**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

**Request Body:**
```json
{
  "userId": "string",
  "userAttributes": {
    "email": "string",
    "name": "string",
    ...
  },
  "sessionId": "string",
  "posthogName": "string | null"
}
```

**Headers:**
- `Authorization: Bearer {apiKey}`
- `Content-Type: application/json`

**Response:**
```json
{
  "success": true,
  "userId": "string",
  "sessionId": "string"
}
```

**Purpose:** Identifies and associates user properties with a session. Creates or updates user profile on the server.

---

### `POST /api/ingestion/user/auth`

**When:** Called when `tracker.auth()` is invoked

**Request Body:**
```json
{
  "userId": "string",
  "userAttributes": {
    "email": "string",
    "name": "string",
    ...
  },
  "sessionId": "string",
  "authFields": ["email", "password", ...]
}
```

**Headers:**
- `Authorization: Bearer {apiKey}`
- `Content-Type: application/json`

**Response:**
```json
{
  "success": true,
  "message": "User authenticated",
  "userId": "string",
  "sessionId": "string"
}
```

**Purpose:** Authenticates a user and marks specific fields as authentication-related for enhanced security handling.

---

### `POST /api/ingestion/customEvent`

**When:** Called when `tracker.customEvent()` is invoked

**Request Body:**
```json
{
  "sessionId": "string",
  "eventName": "string",
  "eventProperties": {
    "property1": "value1",
    ...
  },
  "endUserId": "string | null"
}
```

**Headers:**
- `Authorization: Bearer {apiKey}`
- `Content-Type: application/json`

**Response:**
```json
{
  "success": true,
  "eventId": "string"
}
```

**Purpose:** Sends a single custom event to the server for analytics tracking.

---

### `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"
}
```

**Headers:**
- `Authorization: Bearer {apiKey}`
- `Content-Type: application/json`

**Response:**
```json
{
  "success": true,
  "eventIds": ["string", ...]
}
```

**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"
}
```

**Headers:**
- `Authorization: Bearer {apiKey}`
- `Content-Type: application/json`

**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",
    ...
  }
}
```

**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
npm run build

# Build specific package
npm run build --workspace=@humanbehavior/core
```

## Testing & Deployment

### Testing Process

After making changes to the SDK:

1. **Run the testing script:**
   ```bash
   npm run testing
   ```
   This cleans, builds, and packages the SDK for testing.

2. **Clean and reinstall dependencies** (especially important when testing in other projects):
   ```bash
   # For regular projects
   rm -rf node_modules package-lock.json && npm i
   
   # For Next.js projects (also remove .next)
   rm -rf node_modules package-lock.json .next && npm i
   ```

3. **Test in your target project** - The SDK should now work with your changes.

### Publishing Process

To publish a new version to npm:

1. **Commit your changes:**
   ```bash
   git add .
   git commit -m "Your commit message"
   ```

2. **Bump version and build:**
   ```bash
   npm version patch  # or 'minor' or 'major'
   npm run build
   ```

3. **Publish to npm:**
   ```bash
   npm publish
   ```

4. **Push to git:**
   ```bash
   git push
   git push --tags  # Push version tag if needed
   ```

**Note:** The `prepublishOnly` script automatically runs `npm run clean && npm run build` before publishing, ensuring the latest build is always published.

### Project Structure

- **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

### Package Exports

The main package uses modern package.json exports:

```javascript
// Main entry
import { HumanBehaviorTracker } from 'humanbehavior-js';

// 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
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

---

Built with ❤️ by the HumanBehavior team