index-ticketing/README.md

Automatic error tracking and ticketing system integration

# IndexTicketing 🎫

Automatic error tracking and ticketing system integration for JavaScript applications.

## Features

- 🚨 **Automatic Error Capture**: Catches JavaScript errors, unhandled promises, and React errors
- 🎯 **Smart Grouping**: Groups similar errors using fingerprinting
- 📊 **Rich Context**: Captures breadcrumbs, user info, and environment data
- 🔄 **Retry Logic**: Robust error reporting with automatic retries
- ⚛️ **React Integration**: Error boundaries and hooks for React applications
- 🛡️ **Privacy First**: Automatic filtering of sensitive data
- 📈 **Performance**: Minimal overhead with sampling and batching

## Installation

```bash
npm install index-ticketing
```

## Quick Start

### Basic Setup

```javascript
import { init } from 'index-ticketing';

init({
  endpoint: 'https://your-ticketing-system.com',
  apiKey: 'your-api-key',
  projectId: 'your-project-id',
  organizationId: 'your-org-id',
  environment: 'production',
  user: {
    id: '123',
    email: 'user@example.com',
    name: 'John Doe'
  }
});
```

### React Integration

```jsx
import React from 'react';
import { IndexTicketingErrorBoundary, useIndexTicketing } from 'index-ticketing';
import { getCurrentHub } from 'index-ticketing';

function App() {
  const errorHandler = getCurrentHub()?.getErrorHandler();
  
  return (
    <IndexTicketingErrorBoundary 
      errorHandler={errorHandler}
      fallback={<div>Something went wrong!</div>}
    >
      <MyComponent />
    </IndexTicketingErrorBoundary>
  );
}

function MyComponent() {
  const { captureError, addBreadcrumb } = useIndexTicketing(
    getCurrentHub()?.getErrorHandler()
  );

  const handleClick = () => {
    addBreadcrumb('User clicked button', 'user', 'info');
    
    try {
      riskyOperation();
    } catch (error) {
      captureError(error, { context: 'button-click' });
    }
  };

  return <button onClick={handleClick}>Click me</button>;
}
```

### Manual Error Capture

```javascript
import { captureError, captureMessage, addBreadcrumb } from 'index-ticketing';

// Capture an error
try {
  somethingRisky();
} catch (error) {
  captureError(error, { context: 'user-action' });
}

// Capture a message
captureMessage('User completed checkout', 'info', { 
  orderId: '12345',
  amount: 99.99 
});

// Add breadcrumb for context
addBreadcrumb('User navigated to checkout', 'navigation', 'info');
```

## Configuration

```javascript
import { init } from 'index-ticketing';

init({
  // Required
  endpoint: 'https://your-ticketing-system.com',
  apiKey: 'your-api-key', 
  projectId: 'your-project-id',
  organizationId: 'your-org-id',

  // Optional
  environment: 'production', // 'development', 'staging', 'production'
  release: '1.0.0', // Your app version
  sampleRate: 1.0, // 0.0 to 1.0 (percentage of errors to capture)
  maxBreadcrumbs: 50, // Maximum number of breadcrumbs to keep
  autoCapture: true, // Automatically install global handlers
  
  // User context
  user: {
    id: 'user-id',
    email: 'user@example.com', 
    name: 'User Name'
  },

  // Custom tags
  tags: {
    team: 'frontend',
    feature: 'checkout'
  },

  // Filter sensitive data
  beforeSend: (event) => {
    // Remove sensitive information
    if (event.extra?.creditCard) {
      delete event.extra.creditCard;
    }
    return event;
  }
});
```

## API Reference

### Core Methods

- `init(config)` - Initialize IndexTicketing
- `captureError(error, extra?)` - Manually capture an error
- `captureMessage(message, level?, extra?)` - Capture a message
- `addBreadcrumb(message, category?, level?, data?)` - Add a breadcrumb
- `setUser(user)` - Update user context
- `setTags(tags)` - Update tags

### React Components

- `<IndexTicketingErrorBoundary>` - Error boundary component
- `withIndexTicketingErrorBoundary(Component)` - HOC wrapper
- `useIndexTicketing(errorHandler)` - React hook

### Error Levels

- `error` - Error level (default for exceptions)
- `warning` - Warning level  
- `info` - Info level
- `debug` - Debug level

## How It Works

1. **Error Capture**: Automatically captures JavaScript errors, unhandled promises, and React errors
2. **Context Collection**: Gathers breadcrumbs, user info, environment data, and stack traces
3. **Smart Grouping**: Uses fingerprinting to group similar errors together
4. **Ticket Creation**: Automatically creates tickets in your ticketing system with rich context
5. **Email Notifications**: Sends email notifications to relevant team members

## Integration with Your Ticketing System

The package integrates with your existing ticketing system API. When an error occurs:

1. Error is captured with full context
2. A ticket is automatically created via your API
3. Email notifications are sent to assigned developers
4. Similar errors are grouped together to avoid spam

## Examples

### Next.js Integration

```javascript
// pages/_app.js
import { init } from 'index-ticketing';

init({
  endpoint: process.env.NEXT_PUBLIC_TICKETING_ENDPOINT,
  apiKey: process.env.NEXT_PUBLIC_TICKETING_API_KEY,
  projectId: process.env.NEXT_PUBLIC_PROJECT_ID,
  organizationId: process.env.NEXT_PUBLIC_ORG_ID,
  environment: process.env.NODE_ENV,
});

export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}
```

### Express.js Integration

```javascript
const express = require('express');
const { init, captureError } = require('index-ticketing');

init({
  endpoint: process.env.TICKETING_ENDPOINT,
  apiKey: process.env.TICKETING_API_KEY,
  projectId: process.env.PROJECT_ID,
  organizationId: process.env.ORG_ID,
  environment: process.env.NODE_ENV,
});

const app = express();

// Global error handler
app.use((error, req, res, next) => {
  captureError(error, {
    url: req.url,
    method: req.method,
    user: req.user?.id,
  });
  
  res.status(500).json({ error: 'Internal Server Error' });
});
```

## License

MIT License - see LICENSE file for details.