npm package: @signal-js/browser
Description: Signal SDK - Session replay, network monitoring, and analytics for all platforms
Latest version: 1.0.6

# @signal-js/browser

Signal SDK for browsers — session replay, network monitoring, and analytics.

## Installation

```bash
npm install @signal-js/browser
# or
pnpm add @signal-js/browser
# or
yarn add @signal-js/browser
```

## CDN

```html
<!-- Full bundle (includes rrweb) -->
<script src="https://unpkg.com/@signal-js/browser/dist/signal-full.global.js"></script>
<script>
  const signal = SignalSDK.createSignal({ endpoint: '...', apiKey: '...', projectId: '...' });
  signal.start();
</script>
```

<!-- Same bundle via main entry: -->
<!-- <script src="https://unpkg.com/@signal-js/browser/dist/signal.global.js"></script> -->

## Quick Start

```javascript
import { createSignal } from '@signal-js/browser';

const signal = createSignal({
  endpoint: 'https://your-api.com/events',
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  enableSessionReplay: true,
  enableNetworkCapture: true,
  enableConsoleCapture: true,
});

await signal.start();
signal.capture('button_clicked', { buttonId: 'submit' });

window.addEventListener('beforeunload', () => signal.flush());
```

## Features

### Session Replay

Records user interactions using rrweb.

```javascript
createSignal({
  enableSessionReplay: true,
  sessionRecordingMasking: { maskAllInputs: true },
});
```

### Network Capture

```javascript
createSignal({
  enableNetworkCapture: true,
  networkCaptureOptions: {
    recordHeaders: true,
    recordBody: ['application/json'],
    sensitiveHeaders: ['authorization', 'cookie'],
    urlDenyList: [/analytics\.google\.com/],
    payloadSizeLimitBytes: 100000,
  },
});
```

### Console Capture

```javascript
createSignal({
  enableConsoleCapture: true,
  consoleCaptureOptions: {
    levels: ['warn', 'error'],
    captureErrors: true,
    captureUnhandledRejections: true,
  },
});
```

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `endpoint` | string | - | HTTP endpoint for events |
| `apiKey` | string | - | API key for authentication |
| `projectId` | string | - | Project identifier |
| `compression` | boolean | `true` | Enable gzip compression |
| `flushInterval` | number | `2000` | Flush interval (ms) |
| `maxBatchSize` | number | `50` | Max events per batch |
| `sessionIdleTimeoutSeconds` | number | `1800` | Session idle timeout |
| `maxSessionLengthSeconds` | number | `86400` | Max session length |
| `enableSessionReplay` | boolean | `true` | Enable rrweb recording |
| `enableNetworkCapture` | boolean | `true` | Enable network capture |
| `enableConsoleCapture` | boolean | `true` | Enable console capture |
| `debug` | boolean | `false` | Enable debug logging |

## API

### SignalJS

- `start(): Promise<void>` — Start recording
- `stop(): void` — Stop recording
- `flush(): Promise<void>` — Flush pending events
- `capture(eventName: string, properties?: object): void` — Capture custom event
- `identify(distinctId: string, traits?: object): void` — Identify user
- `group(groupType: string, groupKey: string, properties?: object): void` — Associate with group
- `pauseRecording(): void` / `resumeRecording(): void` — Pause/resume replay
- `dispose(): Promise<void>` — Shutdown SDK

### Subpath exports

- **Main:** `@signal-js/browser` → SDK with rrweb bundled (CJS, ESM, IIFE as `SignalSDK`). Use this for NPM/bundlers.
- **Full:** `@signal-js/browser/full` → Same as main (SDK + rrweb). Use for CDN when you want the same bundle as main.
- **Recorder only:** `@signal-js/browser/recorder` → rrweb recorder only (~300KB). Use if you load the SDK separately and want to load rrweb from another script (e.g. `/static/recorder.js`).

## Bundle sizes (approx.)

| File | Description |
|------|-------------|
| `dist/signal.js` | SDK + rrweb bundled (~345KB ESM, ~347KB CJS). Default entry; use for NPM. |
| `dist/signal-full.js` | Same as `signal.js` (SDK + rrweb). Alternative entrypoint; use for CDN. |
| `dist/recorder.js` | rrweb only (~300KB). For loading recorder separately. |

**Why both `signal.js` and `signal-full.js`?** Both include the SDK and rrweb. The main entry (`signal`) is for NPM/bundlers; `signal-full` is an alternative entrypoint (e.g. for CDN or when you want to import `@signal-js/browser/full`). You can use either; they are equivalent. The `recorder` bundle is for advanced use when you load rrweb from a separate script.

## Browser support

Chrome 80+, Firefox 78+, Safari 14+, Edge 80+.

## License

MIT