npm package: @handle-it/error-report-client
Description: A simple client for sending error reports to the error-report-v2 service
Author: Handle IT
Latest version: 1.0.0

# Error Report Client

A simple JavaScript client for sending error reports to your error-report-v2 Cloudflare Worker endpoint.

## Installation

You can include this library directly in your project:

```html
<script src="path/to/error-report-client/index.js"></script>
```

Or import it in your JavaScript project:

```javascript
// ES Modules
import ErrorReport from './path/to/error-report-client/index.js';

// CommonJS
const ErrorReport = require('./path/to/error-report-client/index.js');
```

## Usage

### Basic Usage

Send an error report with minimal information:

```javascript
ErrorReport.send({
  errorType: "JavaScript Error",
  message: "Something went wrong"
});
```

### Detailed Error Report

Send a detailed error report:

```javascript
try {
  // Some code that might throw an error
  nonExistentFunction();
} catch (error) {
  ErrorReport.send({
    errorType: "JavaScript Error",
    message: error.message,
    stack: error.stack,
    url: window.location.href,
    userAgent: navigator.userAgent,
    // Add any custom data you want
    customData: {
      userId: "user-123",
      action: "checkout"
    }
  });
}
```

### Configure Custom Endpoint

If you need to use a different endpoint:

```javascript
// Set a custom endpoint for all future reports
ErrorReport.configure({
  endpoint: "https://your-custom-endpoint.com/error-report"
});

// Or specify an endpoint for a single report
ErrorReport.send(errorData, {
  endpoint: "https://your-custom-endpoint.com/error-report"
});
```

### Auto-Capture Errors

Automatically capture and report unhandled errors and promise rejections:

```javascript
ErrorReport.autoCaptureErrors({
  // Both are true by default
  unhandledErrors: true,
  unhandledRejections: true,
  
  // Optional: Filter or modify reports before sending
  beforeSend: (errorData, originalEvent) => {
    // Add custom data
    errorData.customData = { userId: getCurrentUserId() };
    
    // Return the modified data
    return errorData;
    
    // Or return false to prevent sending
    // return false;
  }
});
```

## API Reference

### `ErrorReport.send(data, options)`

Sends an error report to the configured endpoint.

- `data`: Object containing error information
  - `errorType`: Type of error (e.g., "JavaScript Error", "API Error")
  - `message`: Error message
  - `stack`: Error stack trace
  - `url`: URL where the error occurred
  - `userAgent`: User agent string
  - `timestamp`: ISO timestamp (added automatically if not provided)
  - Any other custom properties you want to include
- `options`: Additional options
  - `endpoint`: Override the default endpoint URL

Returns a Promise that resolves to the server response.

### `ErrorReport.configure(config)`

Configures the error reporting client.

- `config`: Configuration object
  - `endpoint`: Set a custom endpoint URL

### `ErrorReport.autoCaptureErrors(options)`

Sets up automatic capture of unhandled errors and promise rejections.

- `options`: Options for auto-capture
  - `unhandledErrors`: Capture unhandled errors (default: `true`)
  - `unhandledRejections`: Capture unhandled promise rejections (default: `true`)
  - `beforeSend`: Function to modify or filter error reports before sending

## Example

```javascript
// Configure the client
ErrorReport.configure({
  endpoint: "https://error-report-v2.james-quinn.workers.dev"
});

// Auto-capture errors
ErrorReport.autoCaptureErrors();

// Manually send an error
document.getElementById("testButton").addEventListener("click", () => {
  try {
    // Simulate an error
    throw new Error("Test error");
  } catch (error) {
    ErrorReport.send({
      errorType: "Test Error",
      message: error.message,
      stack: error.stack
    }).then(response => {
      console.log("Error report sent:", response);
    }).catch(err => {
      console.error("Failed to send error report:", err);
    });
  }
});
```