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

npm install debux
# or
yarn add debux

Quick Start

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:

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:

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

Error Filtering

Filter out specific errors using a custom function:

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:

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

Error Capture

Basic Error Capture

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

Capture with Metadata

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

Different Severity Levels

// 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:

   Debux.captureError(error, {
     userId: user.id,
     environment: process.env.NODE_ENV,
     component: 'CheckoutForm'
   });

3. Error Filtering: Use error filtering to reduce noise:

   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:

   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 for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.