npm package: @komitech/debux
Description: A lightweight, flexible error tracking SDK for JavaScript/TypeScript applications
Author: Your Name
Latest version: 0.1.0

# Debux SDK

A lightweight, flexible error tracking SDK for JavaScript/TypeScript applications.

## Features

- 🚀 Simple initialization and setup
- 🔍 Customizable error filtering
- 💾 Offline error caching
- 🔄 Automatic error recovery
- 📝 Rich error metadata support
- 🐛 Debug mode for development

## Installation

```bash
npm install debux
# or
yarn add debux
```

## Quick Start

```typescript
import { Debux } from 'debux';

// Initialize the SDK
const debux = Debux.init({
  apiKey: 'your-api-key',
  debug: true,              // Optional: Enable debug logging
  offlineCache: true,       // Optional: Enable offline caching
  filterErrors: (error) => error.message !== 'ignored' // Optional: Filter out specific errors
});

// Basic error capture
try {
  throw new Error('Something went wrong');
} catch (error) {
  if (error instanceof Error) {
    Debux.captureError(error);
  }
}
```

## Configuration Options

The SDK can be initialized with the following options:

```typescript
interface DebuxOptions {
  apiKey: string;          // Required: Your Debux API key
  debug?: boolean;         // Optional: Enable debug logging (default: false)
  filterErrors?: (error: Error) => boolean;  // Optional: Custom error filter
  offlineCache?: boolean;  // Optional: Enable offline caching (default: false)
}
```

### API Key

The `apiKey` is required for authentication. You can obtain one by signing up at [your-api-domain].

### Debug Mode

Enable debug mode to see detailed logs in the console:

```typescript
Debux.init({
  apiKey: 'your-api-key',
  debug: true
});
```

### Error Filtering

Filter out specific errors using a custom function:

```typescript
Debux.init({
  apiKey: 'your-api-key',
  filterErrors: (error) => {
    // Filter out 404 errors
    if (error.message.includes('404')) {
      return false;
    }
    return true;
  }
});
```

### Offline Caching

Enable offline caching to store errors when the network is unavailable:

```typescript
Debux.init({
  apiKey: 'your-api-key',
  offlineCache: true
});
```

## Error Capture

### Basic Error Capture

```typescript
Debux.captureError(new Error('Something went wrong'));
```

### Capture with Metadata

```typescript
Debux.captureError(new Error('Payment failed'), {
  userId: '123',
  severity: 'error',
  customData: {
    orderId: 'order_123',
    amount: 99.99
  }
});
```

### Different Severity Levels

```typescript
// Info level
Debux.captureError(new Error('User logged in'), {
  severity: 'info',
  userId: '123'
});

// Warning level
Debux.captureError(new Error('API response slow'), {
  severity: 'warning',
  customData: { responseTime: 5000 }
});

// Error level
Debux.captureError(new Error('Payment failed'), {
  severity: 'error',
  customData: { orderId: '123' }
});
```

## Best Practices

1. **Initialize Early**: Initialize the SDK as early as possible in your application lifecycle.

2. **Error Context**: Always include relevant metadata when capturing errors:
   ```typescript
   Debux.captureError(error, {
     userId: user.id,
     environment: process.env.NODE_ENV,
     component: 'CheckoutForm'
   });
   ```

3. **Error Filtering**: Use error filtering to reduce noise:
   ```typescript
   Debux.init({
     apiKey: 'your-api-key',
     filterErrors: (error) => {
       // Filter out cancelled requests
       if (error.message.includes('cancelled')) {
         return false;
       }
       return true;
     }
   });
   ```

4. **Enable Offline Caching**: For web applications that might be used offline:
   ```typescript
   Debux.init({
     apiKey: 'your-api-key',
     offlineCache: true
   });
   ```

## TypeScript Support

The SDK is written in TypeScript and includes type definitions. You'll get full type support out of the box.

## Browser Support

The SDK supports all modern browsers:
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.