firecrawl-reliability-patterns

# FireCrawl Reliability Patterns

## Overview
Production-grade reliability patterns for FireCrawl integrations.

## Prerequisites
- Understanding of circuit breaker pattern
- opossum or similar library installed
- Queue infrastructure for DLQ
- Caching layer for fallbacks

## Circuit Breaker

```typescript
import CircuitBreaker from 'opossum';

const firecrawlBreaker = new CircuitBreaker(
  async (operation: () => Promise<any>) => operation(),
  {
    timeout: 30000,
    errorThresholdPercentage: 50,
    resetTimeout: 30000,
    volumeThreshold: 10,
  }
);

// Events
firecrawlBreaker.on('open', () => {
  console.warn('FireCrawl circuit OPEN - requests failing fast');
  alertOps('FireCrawl circuit breaker opened');
});

firecrawlBreaker.on('halfOpen', () => {
  console.info('FireCrawl circuit HALF-OPEN - testing recovery');
});

firecrawlBreaker.on('close', () => {
  console.info('FireCrawl circuit CLOSED - normal operation');
});

// Usage
async function safeFireCrawlCall<T>(fn: () => Promise<T>): Promise<T> {
  return firecrawlBreaker.fire(fn);
}
```

## Idempotency Keys

```typescript
import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// Generate deterministic idempotency key from input
function generateIdempotencyKey(
  operation: string,
  params: Record<string, any>
): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

// Or use random key with storage
class IdempotencyManager {
  private store: Map<string, { key: string; expiresAt: Date }> = new Map();

  getOrCreate(operationId: string): string {
    const existing = this.store.get(operationId);
    if (existing && existing.expiresAt > new Date()) {
      return existing.key;
    }

    const key = uuidv4();
    this.store.set(operationId, {
      key,
      expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
    });
    return key;
  }
}
```

## Bulkhead Pattern

```typescript
import PQueue from 'p-queue';

//