@raphaelscunha/event-tracker/README.md

A simple event tracking and user identification package with streaming capabilities

# Event Tracker Package

This package provides a simple way to track events in your application and send them to your analytics server.

## Installation

\`\`\`bash
npm install @survey/event-tracker
\`\`\`

## API

### `EventTracker(options)`

Creates a new event tracker instance.

**Options:**

- `serverUrl` (string, required): The URL of your analytics server API.
- `apiKey` (string, required): Your API key.
- `batchSize` (number, optional): The number of events to batch before sending (default: 10).
- `flushInterval` (number, optional): The flush interval in milliseconds (default: 5000).


### `tracker.identify(userId, properties)`

Identifies a user.

- `userId` (string, required): The user ID.
- `properties` (object, optional): Additional user properties.


### `tracker.track(eventName, properties)`

Tracks an event.

- `eventName` (string, required): The name of the event.
- `properties` (object, optional): Additional event properties.


### `tracker.shutdown()`

Flushes any remaining events and clears the flush interval. Call this method when your application is closing to ensure all data is sent.

## Streaming and Batching

This package now supports event batching and periodic flushing for improved performance:

- Events are collected in a queue and sent in batches.
- You can configure the `batchSize` to set how many events should be collected before sending.
- A `flushInterval` determines how often the event queue should be sent, even if the batch size hasn't been reached.
- If sending fails, events are added back to the queue to be sent later.
- The `shutdown` method ensures all remaining events are sent before your application closes.

## Usage

```javascript
import EventTracker from '@survey/event-tracker';

const tracker = new EventTracker({
  serverUrl: 'https://your-analytics-server.com/api',
  apiKey: 'your-api-key-here',
  batchSize: 20, // Optional: number of events to batch before sending (default: 10)
  flushInterval: 10000 // Optional: flush interval in milliseconds (default: 5000)
});

// Identify a user
await tracker.identify('user123', { email: 'user@example.com' });

// Track events (these will be batched and sent periodically)
tracker.track('Button Clicked', { buttonName: 'Submit' });
tracker.track('Page Viewed', { pageName: 'Home' });

// When your application is closing, make sure to call shutdown
await tracker.shutdown();
```