# Error Filtering - Quick Reference

## TL;DR

The BugMail SDK automatically filters out its own internal errors to prevent infinite loops. SDK errors are logged to console but NOT sent to your dashboard.

## What's Filtered

✅ **Filtered (NOT sent to dashboard):**
- SDK network errors: `[BugMail Network] Failed to send error`
- SDK internal errors: Errors with SDK code in stack trace
- API validation errors: Invalid API key, inactive key, etc.
- SDK console messages: Messages starting with `[BugMail`

❌ **Not Filtered (SENT to dashboard):**
- Your application errors
- Third-party library errors
- Browser errors
- Any error without SDK patterns

## Quick Examples

### Example 1: Invalid API Key (Filtered)

```javascript
const bugmail = new BugMail({ apiKey: 'invalid_key' });
// Console shows:
// [BugMail Network] Failed to send error: { status: 401, body: { detail: "Invalid API key" } }
// ✅ Logged once, NOT captured, NO loop
```

### Example 2: Your App Error (Not Filtered)

```javascript
function myFunction() {
  throw new Error('Something broke in my app');
}
// ✅ Captured and sent to dashboard
```

### Example 3: Network Down (Filtered)

```javascript
// Network is offline
const bugmail = new BugMail({ apiKey: 'valid_key' });
// Console shows:
// [BugMail Network] Failed to send error: network_error
// ✅ Logged, NOT captured, stored offline
```

## Debug Mode

Enable to see filtering decisions:

```javascript
const bugmail = new BugMail({
  apiKey: 'YOUR_API_KEY',
  debug: true  // 👈 Add this
});

// Console will show:
// [BugMail Filter] Filtered: SDK pattern in message
// [BugMail Filter] Filtered: SDK pattern in stack trace
```

## Filtered Patterns

### Stack Trace Patterns
- `@bugmail-js`
- `bugmail-sdk`
- `bugmail-client`
- `bugmail-core`
- `network-manager`
- `error-processor`
- `context-collector`

### Message Patterns
- `[BugMail`
- `BugMail Network`
- `BugMail SDK`
- `BugMail:`

## Common Questions

**Q: Why aren't SDK errors in my dashboard?**  
A: This is intentional! Check browser console for SDK errors.

**Q: How do I know if my API key is wrong?**  
A: Check console for: `[BugMail Network] Failed to send error: 401`

**Q: Can I disable filtering?**  
A: No. Filtering prevents infinite loops and is always enabled.

**Q: My app errors are being filtered!**  
A: Avoid using "bugmail" in your filenames or `[BugMail` in error messages.

## Troubleshooting

### Problem: No errors in dashboard

**Check:**
1. Is your API key correct?
2. Is backend endpoint accessible?
3. Are errors from YOUR code (not SDK)?
4. Enable debug mode to see what's happening

**Console:**
```javascript
const bugmail = new BugMail({
  apiKey: 'YOUR_API_KEY',
  debug: true  // See detailed logging
});
```

### Problem: SDK errors in console

**This is normal!** SDK errors are logged for debugging but not sent to dashboard.

**Common SDK errors:**
- `[BugMail Network] Failed to send error: 401` → Invalid API key
- `[BugMail Network] Failed to send error: 403` → Inactive API key
- `[BugMail Network] Failed to send error: network_error` → Network down

**Fix:**
- Verify API key is correct
- Check network connectivity
- Ensure API key is active in dashboard

## Testing Filtering

### Test 1: Verify SDK errors are filtered

```javascript
// Use invalid API key
const bugmail = new BugMail({ 
  apiKey: 'invalid_key',
  debug: true 
});

// Trigger an error
throw new Error('Test error');

// Expected:
// ✅ Console shows: [BugMail Network] Failed to send error: 401
// ✅ Console shows: [BugMail Filter] Filtered: ...
// ✅ No infinite loop
// ✅ No repeated network requests
```

### Test 2: Verify app errors are NOT filtered

```javascript
// Use valid API key
const bugmail = new BugMail({ 
  apiKey: 'valid_key',
  debug: true 
});

// Trigger an error
throw new Error('Test error from my app');

// Expected:
// ✅ Error sent to backend
// ✅ Error appears in dashboard
// ✅ Console shows: [BugMail Network] Response: 201 Created
```

## Advanced: Custom Filtering

Filter additional errors using `beforeSend`:

```javascript
const bugmail = new BugMail({
  apiKey: 'YOUR_API_KEY',
  beforeSend: (error, context) => {
    // Filter third-party errors
    if (error.stack?.includes('third-party-lib')) {
      return null;  // Don't send
    }
    
    // Filter known issues
    if (error.message.includes('ResizeObserver loop')) {
      return null;  // Don't send
    }
    
    // Redact sensitive data
    error.message = error.message.replace(/password=\w+/g, 'password=[REDACTED]');
    
    return error;  // Send modified error
  }
});
```

## Related Docs

- [Full Error Filtering Guide](./ERROR_FILTERING.md)
- [FAQ](./FAQ.md)
- [Main README](../README.md)
- [Troubleshooting](./TROUBLESHOOTING.md)

## Need Help?

1. Enable debug mode
2. Check browser console
3. Check Network tab in DevTools
4. Search GitHub issues
5. File new issue with details