npm package: @pandastack/event-tracker
Description: Event tracking SDK for browser and server applications
Author: Pandastack
Latest version: 1.0.1

# @pandastack/event-tracker

A lightweight SDK for tracking events in both browser and server environments. Events are automatically batched and sent to your specified endpoint.

## Features

- 🌐 Browser event tracking (page views, clicks)
- 🖥️ Server-side API request tracking
- 📦 Automatic event batching
- 🔄 Offline support (browser)
- 📊 Custom event support
- 🛡️ TypeScript support

## Installation

```bash
npm install @pandastack/event-tracker
# or
yarn add @pandastack/event-tracker
```

## Browser Usage

```javascript
import { browserTracker } from '@pandastack/event-tracker';

// Initialize with configuration
browserTracker.init({
  projectId: 'my-project', // optional
  endpoint: 'https://your-endpoint.com/events', // optional
  debug: true // optional
});

// Track custom events
browserTracker.track('button_click', {
  buttonId: 'signup',
  page: '/home'
});

// Automatic tracking includes:
// - Page views
// - Click events (with element details)
```

### Advanced Browser Usage

```javascript
import { BrowserTracker } from '@pandastack/event-tracker';

// Create custom instance
const tracker = new BrowserTracker({
  projectId: 'my-project',
  endpoint: 'https://your-endpoint.com/events',
  batchSize: 10, // events per batch
  batchInterval: 5000, // flush interval in ms
  debug: true
});

tracker.init();

// Custom event with metadata
tracker.track('form_submit', {
  formId: 'contact',
  success: true,
  duration: 1500
});

// Cleanup when needed
tracker.destroy();
```

## Server Usage (Express Middleware)

```javascript
import express from 'express';
import { createRequestTracker } from '@pandastack/event-tracker';

const app = express();

// Add the tracking middleware
app.use(createRequestTracker({
  projectId: 'my-project',
  endpoint: 'https://your-endpoint.com/events',
  ignorePaths: ['/health', '/metrics'],
  customFields: (req) => ({
    userId: req.user?.id,
    // Add any custom fields from the request
  })
}));

// Your routes
app.get('/api/data', (req, res) => {
  res.json({ message: 'Hello!' });
});
```

### Advanced Server Usage

```javascript
import { ServerTracker } from '@pandastack/event-tracker';

const tracker = new ServerTracker({
  projectId: 'my-project',
  endpoint: 'https://your-endpoint.com/events',
  batchSize: 50,
  batchInterval: 10000,
  debug: true,
  ignorePaths: [
    '/health',
    '/metrics',
    /^\/static\//  // Regex support
  ],
  customFields: (req) => ({
    userId: req.user?.id,
    ip: req.ip,
    userAgent: req.get('user-agent')
  })
});

app.use(tracker.middleware());
```

## Event Types

### Browser Events

```typescript
// Page View Event
{
  event_type: 'pageview',
  timestamp: 1645568732000,
  project_id: 'my-project',
  session_id: 'abc123',
  page_url: 'https://example.com/products',
  referrer: 'https://google.com',
  user_agent: '...'
}

// Click Event
{
  event_type: 'click',
  timestamp: 1645568732000,
  project_id: 'my-project',
  session_id: 'abc123',
  page_url: 'https://example.com/products',
  element_id: 'signup-button',
  element_class: 'btn primary',
  element_text: 'Sign Up Now'
}
```

### API Events

```typescript
{
  event_type: 'api_request',
  timestamp: 1645568732000,
  project_id: 'my-project',
  method: 'GET',
  path: '/api/products',
  status_code: 200,
  duration_ms: 150,
  request_id: 'req_abc123',
  ip_address: '127.0.0.1',
  user_agent: '...',
  metadata: {
    query: { page: '1' },
    // Custom fields...
  }
}
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Examples

The SDK comes with example implementations for both browser and server usage.

### Browser Example

```bash
# First build the SDK
npm run build

# Then serve the examples directory using any static server
# For example, using Python's built-in server:
python3 -m http.server 8000

# Visit http://localhost:8000/examples/browser/
```

The browser example demonstrates:
- Automatic page view tracking
- Click event tracking
- Custom event tracking
- Event batching
- Debug logging

### Server Example

```bash
# First build the SDK
npm run build

# Then install dependencies and run the server example
cd examples/server
npm install
npm start

# The server will start at http://localhost:3000
# Try these endpoints:
# - GET /api/hello
# - GET /api/error
# - GET /api/slow
```

The server example demonstrates:
- API request tracking
- Response time monitoring
- Error tracking
- Custom field injection
- Debug logging

## License

MIT