@bugster/bugster-js/README.md

An SDK to capture user interactions on web applications

# bugster-js

bugster-js is an open-source SDK for capturing user interactions in frontend web applications. It provides a robust and flexible solution for tracking user behavior, events, and page views, helping you gain valuable insights into how users interact with your web application.

## Features

- **Event Tracking**: Capture custom events and user interactions.
- **Automatic Tracking**: Built-in tracking for page views, clicks, form submissions, and more.
- **Session Management**: Automatically manage user sessions with configurable timeout.
- **User Identification**: Easy user identification and property assignment.
- **Batched Event Sending**: Efficiently send events in batches to reduce network requests.
- **Flexible Storage**: Choose between localStorage, cookies, or in-memory storage for persisting user data.
- **Privacy-Focused**: Configurable input sanitization to protect user data.
- **Customizable**: Extensive configuration options to tailor the SDK to your needs.

## Installation

You can install bugster-js using npm:

```bash
npm i @bugster/bugster-js
```

Or using yarn:

```bash
yarn add @bugster/bugster-js
```

## Usage

### Basic Setup

```javascript
import  BugsterTracker  from '@bugster/bugster-js';

const bugster = new BugsterTracker({
  apiKey: 'YOUR_API_KEY',
  endpoint: 'https://your-endpoint.bugster.app'
});
```

### Tracking Events

```javascript
// Track a custom event
bugster.capture('Button Clicked', {
  buttonId: 'submit-form',
  pageSection: 'header'
});

// Identify a user
bugster.identify('user123', {
  name: 'John Doe',
  email: 'john@example.com'
});
```

### Configuration Options

When initializing BugsterTracker, you can pass various configuration options:

```javascript
const bugster = new BugsterTracker({
  apiKey: 'YOUR_API_KEY',
  endpoint: 'https://your-endpoint.bugster.app',
  batchSize: 30,
  flushInterval: 300000, // 5 minutes
  sessionTimeout: 1800000, // 30 minutes
  persistence: 'localStorage',
  capturePageview: true,
  capturePageleave: true,
  captureUtm: true,
  captureReferrer: true,
  inputDebounceTime: 500
});
```

## API Reference

### `capture(eventName: string, properties: Record<string, any>)`

Captures a custom event with the given name and properties.

### `identify(distinctId: string, properties: Record<string, any>)`

Identifies a user with a unique ID and optional properties.

### `flush()`

Manually sends all queued events to the server.

## Privacy and Data Protection

bugster-js is designed with privacy in mind:

- Sensitive input fields (e.g., passwords) are automatically sanitized.
- You can configure which data to capture and which to ignore.
- User data is stored securely based on your chosen persistence method.

## Contributing

We welcome contributions to bugster-js! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.

## License

bugster-js is released under the [MIT License](LICENSE).

## Support

For issues, feature requests, or questions, please [open an issue](https://github.com/your-repo/bugster-js/issues) on our GitHub repository.