failover-sdk/README.md

One-line API failover with zero downtime. Native Rust performance with TypeScript interface.

# failover

**One-line API failover with zero downtime. Works with your existing Stripe, SendGrid, and other native SDKs.**

Never lose revenue to API outages again. When Stripe goes down, automatically switch to Square. When SendGrid fails, instantly use Mailgun. Your existing code works unchanged.

## 🚀 Quick Start

### Installation

```bash
npm install failover-sdk
```

### Usage (The Magic One-Liner)

```typescript
import 'failover-sdk/register'; // ← Add this line at the top of your app

// Your existing code works unchanged!
import Stripe from 'stripe';
import SendGrid from '@sendgrid/mail';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const charge = await stripe.charges.create({
  amount: 2000,
  currency: 'usd',
  source: 'tok_visa',
});
// ↑ Automatically fails over to Square/PayPal/Adyen if Stripe is down

SendGrid.setApiKey(process.env.SENDGRID_API_KEY);
await SendGrid.send({
  to: 'customer@example.com',
  from: 'noreply@yourapp.com',
  subject: 'Welcome!',
  html: '<h1>Welcome to our app!</h1>',
});
// ↑ Automatically fails over to Mailgun/Postmark/Resend if SendGrid is down
```

## 🎯 How It Works

1. **In-Memory Config Cache**: Fetches routing decisions from our monitoring SaaS every 60 seconds
2. **Smart Provider Selection**: Routes your API calls to healthy providers based on real-time monitoring
3. **Native SDK Compatibility**: Your existing Stripe, SendGrid code works unchanged
4. **Bulletproof Fallback**: HTTP interceptor catches double failures and routes to backup providers
5. **Zero Secrets Exposure**: Your API keys stay in your environment, we never see them

## 🏗️ Architecture Benefits

- **🚀 Fast**: Sub-millisecond routing decisions using cached config
- **🛡️ Reliable**: Works even if our service goes down (graceful fallback)
- **🔒 Secure**: Zero-knowledge - we never see your API keys or data
- **📦 Simple**: One import line, existing code unchanged
- **🌍 Universal**: Works on Vercel, Netlify, Docker, serverless, anywhere

## ⚙️ Configuration

### Environment Variables

```bash
# Optional: Your project ID from dashboard.failover.dev
FAILOVER_PROJECT_ID=proj_abc123

# Your existing API keys (unchanged)
STRIPE_SECRET_KEY=sk_live_...
SENDGRID_API_KEY=SG.xyz...
SQUARE_ACCESS_TOKEN=sq0atp...
MAILGUN_API_KEY=key-123...
```

### SaaS Dashboard

Visit [dashboard.failover.dev](https://dashboard.failover.dev) to:

- Monitor your API providers in real-time
- Configure failover policies
- View analytics and cost savings
- Set up alerts and notifications

## 🚦 Supported Providers

### Payments (Automatic Failover Chain)

- **Stripe** → **Square** → **PayPal** → **Adyen**
- Identical APIs, seamless failover
- Supports charges, payment intents, refunds

### Email (Automatic Failover Chain)

- **SendGrid** → **Mailgun** → **Postmark** → **Resend** → **Amazon SES**
- Drop-in compatible with existing code
- Transactional & marketing emails

## 💰 Pricing

- **Free Tier**: 10,000 API calls/month
- **Pro**: $29/month + $0.001 per failover event
- **Enterprise**: Custom pricing with SLA guarantees

[Sign up at dashboard.failover.dev](https://dashboard.failover.dev)

## 🔍 Debugging

Enable debug logs to see failover activity:

```bash
# Set environment variable
DEBUG=failover*

# Or in code
process.env.DEBUG = 'failover*';
```

Output:

```
[Failover] Using payment provider: square
[Failover] Config updated: { payments: 'square', email: 'sendgrid' }
[Failover] Primary provider failed, attempting failover for: api.stripe.com
```

## 📊 Advanced Usage

### Programmatic Access

```typescript
import { getCachedConfig, startConfigRefresh } from 'failover';

// Get current routing config
const config = getCachedConfig();
console.log('Active providers:', config.services);

// Manual config refresh
await startConfigRefresh('your-project-id');
```

### Custom Provider Support

```typescript
import { custom } from 'failover';

// Any API with automatic failover
const sms = custom('twilio');

const result = await sms.request(
  'send',
  'POST',
  'https://api.twilio.com/2010-04-01/Accounts/YOUR_ACCOUNT/Messages.json',
  { Authorization: `Basic ${token}` },
  { To: '+1234567890', Body: 'Hello from failover!' }
);
```

## 🤝 Support

- 📖 [Full Documentation](https://docs.failover.dev)
- 🐛 [Report Issues](https://github.com/plyght/failover/issues)
- 💬 [Discord Community](https://discord.gg/failover)
- 📧 Enterprise Support: enterprise@failover.dev

## 📄 License

MIT License - Use it everywhere, no restrictions.

---

**Stop losing revenue to API outages. Start using Failover today.**

[![npm](https://img.shields.io/npm/v/failover.svg)](https://www.npmjs.com/package/failover)
[![downloads](https://img.shields.io/npm/dm/failover.svg)](https://www.npmjs.com/package/failover)
[![license](https://img.shields.io/npm/l/failover.svg)](https://github.com/plyght/failover/blob/main/LICENSE)