npm package: @sidd6916/logger-lib
Description: A robust offline-first logging library for web applications with auto-capture of clicks, navigation, and screenshots.
Latest version: 1.0.0

# Logger Lib

A robust, offline-first logging library for web applications. It captures user actions, console logs, errors, and navigation events, storing them locally in IndexedDB before syncing to a configured webhook endpoint.

## Features

- **Offline First**: Logs are stored in IndexedDB and persist across reloads.
- **Auto-Sync**: Automatically syncs logs to the server when online (configurable).
- **Auto-Capture**:
  - **Global Errors**: Automatically catches `window.onerror` and `unhandledrejection`.
  - **User Clicks**: Automatically logs clicks on interactive elements (buttons, links).
  - **Navigation**: Tracks URL changes (pushState, replaceState, popstate) and captures **Screenshots** of the page state using `html2canvas`.
- **Screenshots**: Captures a base64 screenshot of the UI before navigation events.
- **Batched Uploads**: Sends logs in batches to reduce network requests.

## Installation

```bash
npm install logger-lib
# or linked locally
npm install ../logger-lib
```

## Usage

Initialize the logger at the entry point of your application (e.g., `main.tsx` or `App.tsx`).

```typescript
import { Logger } from 'logger-lib';

export const logger = new Logger({
  webhookUrl: 'http://localhost:3000/webhook', // Endpoint to receive logs
  batchSize: 10,       // Number of logs to send per batch
  syncInterval: 5000,  // Msg interval (in ms) to check for logs to sync
  offlineMode: false,  // Set true to disable auto-sync (manual sync only)
});

// Expose to window for debugging if needed
(window as any).appLogger = logger;
```

## API

### `logger.info(message, context?)`
Log an informational message.
```typescript
logger.info('User logged in', { userId: 123 });
```

### `logger.warn(message, context?)`
Log a warning.
```typescript
logger.warn('API latency high', { duration: 500 });
```

### `logger.error(message, context?, stack?)`
Log an error. Auto-captured errors use this internally.
```typescript
try {
  fail();
} catch (err) {
  logger.error('Operation failed', { attempt: 1 }, err.stack);
}
```

### `logger.action(actionName, context?)`
Log a specific user action.
```typescript
logger.action('Checkout Clicked', { cartValue: 99.99 });
```

### `logger.sync()`
Manually trigger a sync verification. Useful if `offlineMode` is true or to force flush before close.
```typescript
await logger.sync();
```

## Configuration Options

| Option | Type | Default | Description |
|path|to|file|
|---|---|---|---|
| `webhookUrl` | `string` | **Required** | The HTTP endpoint (POST) to receive JSON payloads. |
| `batchSize` | `number` | `10` | Number of logs to accumulate before attempting a sync. |
| `syncInterval` | `number` | `5000` | Interval (ms) to check for pending logs and sync. |
| `offlineMode` | `boolean` | `false` | If `true`, auto-sync is disabled. Logs accumulate until `sync()` is called. |

## Data Format

Logs sent to the webhook have the following structure:

```json
[
  {
    "id": 1,
    "timestamp": "2023-10-27T10:00:00.000Z",
    "level": "info", // info, warn, error, action
    "message": "Page View",
    "sessionId": "x8s7f6d8...",
    "context": {
      "page": "Home"
    },
    "screenshot": "data:image/png;base64,..." // Present on navigation logs
  }
]
```