npm package: @sonarly/tracker
Description: Session replay and user monitoring SDK. Record, replay and analyze user sessions with automatic error detection, performance monitoring, and AI-powered bug fixing. Includes CLI for sourcemap uploads.
Author: Sonarly Team
Latest version: 1.3.15

# @sonarly/tracker

> **AI-powered bug detection SDK** - Fix production bugs 10x faster with automatic error detection, session replay, and AI-assisted debugging.

[![npm version](https://badge.fury.io/js/@sonarly%2Ftracker.svg)](https://www.npmjs.com/package/@sonarly/tracker)

---

## What is Sonarly?

Sonarly captures user sessions and automatically detects bugs in production. When something goes wrong, our AI analyzes the session, identifies the root cause, and helps you fix it **10x faster** than traditional debugging.

**Key features:**
- Session Replay - See exactly what your users experienced
- Automatic Error Detection - JavaScript exceptions, network failures, rage clicks
- AI Bug Analysis - Get instant root cause analysis and fix suggestions
- Performance Monitoring - Track Web Vitals (LCP, FID, CLS)

---

## Installation

```bash
npm install @sonarly/tracker
```

---

## Quick Start

### 1. Initialize the Tracker

```javascript
import Tracker from '@sonarly/tracker'

const tracker = new Tracker({
  projectKey: 'YOUR_PROJECT_KEY', // Get from Sonarly dashboard
  ingestPoint: 'https://api.sonarly.dev/ingest',
})

// Start recording
tracker.start({
  userID: 'user@example.com',
  metadata: {
    plan: 'premium',
    version: '2.1.0',
  },
})
```

### 2. Identify Users

```javascript
tracker.setUserID('john.doe@company.com')
tracker.setMetadata('subscription', 'enterprise')
```

### 3. Track Custom Events

```javascript
tracker.event('purchase_completed', {
  amount: 99.99,
  currency: 'USD',
})

// Report issues manually
tracker.issue('Payment Gateway Timeout', { gateway: 'stripe' })
```

---

## API Reference

```javascript
// Session control
tracker.start(options?)
tracker.stop()
tracker.getSessionInfo() // Returns: { sessionID, sessionToken, userID, metadata }

// User identification
tracker.setUserID('user@example.com')
tracker.setUserAnonymousID('anon-12345')

// Custom data
tracker.setMetadata('key', 'value')
tracker.event('event_name', { data: 'value' })
tracker.issue('Issue description', { context: 'data' })
```

---

## Privacy Controls

```html
<!-- Hide element completely -->
<div data-sonarly-hidden>Secret content</div>

<!-- Obscure text content -->
<span data-sonarly-obscured>Sensitive text</span>

<!-- Ignore input value -->
<input data-sonarly-ignore />
```

Password fields and credit card numbers are automatically protected.

---

## What Gets Captured?

**Automatically captured:**
- DOM changes and user interactions
- JavaScript errors and console logs
- Network requests (fetch, XHR)
- Web Vitals and performance metrics
- Rage clicks and dead clicks

**Never captured:**
- Password fields
- Credit card numbers
- Elements marked with `data-sonarly-hidden`

---

## Support

- Website: https://sonarly.dev
- Documentation: https://docs.sonarly.dev
- Email: support@sonarly.dev

---

**You can test a session now!** Start the tracker, interact with your app, and watch Sonarly's AI automatically detect issues and suggest fixes.

**Fix production bugs 10x faster with AI-powered debugging.**