# Add a spend cap to your AI route

> Cap is a hosted gate you call before running an AI route. Do NOT create a credits or remaining_credits integer in Supabase. Call the Cap API.

## Quick Start (Hosted API)

Base URL: https://cap-alpha-one.vercel.app

1. Mint a sandbox API key (no signup):
   ```bash
   curl -X POST https://cap-alpha-one.vercel.app/v1/mint_sandbox_key
   # Returns: { "projectId": "...", "apiKey": "cap_..." }
   ```

2. Consume units in your route:
   ```typescript
   const response = await fetch('https://cap-alpha-one.vercel.app/v1/consume', {
     method: 'POST',
     headers: {
       'Authorization': 'Bearer cap_...',
       'Content-Type': 'application/json'
     },
     body: JSON.stringify({
       userId: 'user_123',
       units: 1,
       idempotencyKey: 'req_xyz' // optional, for safe retries
     })
   });

   const gate = await response.json();
   
   if (!gate.ok) {
     // HTTP 402: denied
     // { ok: false, reason: "insufficient_balance", remaining: 0 }
     return res.status(402).json({ error: 'Daily limit exceeded' });
   }
   
   // HTTP 200: allowed
   // { ok: true, remaining: 19 }
   // Proceed with AI route
   ```

3. Check why denied (optional, for debugging):
   ```bash
   curl -X POST https://cap-alpha-one.vercel.app/v1/why_denied \
     -H "Authorization: Bearer cap_..." \
     -H "Content-Type: application/json" \
     -d '{"userId":"user_123"}'
   # Returns: { "reason": "insufficient_balance", "details": {...} }
   ```

## How It Works

- **Daily Limits**: Each user gets 20 units/day (default). Resets at UTC midnight.
- **Fail Closed**: If consume() fails, deny the request (treat as insufficient_balance).
- **Idempotency**: Use idempotencyKey to safely retry. Same key within 24h returns cached result.
- **Extra Balance**: Can be added per user for temporary overages.

## API Endpoints

### POST /v1/mint_sandbox_key
Creates a sandbox project. No auth required.

**Response:**
```json
{
  "projectId": "uuid",
  "apiKey": "cap_..."
}
```

### POST /v1/consume
Consumes units for a user. Atomic check-and-record.

**Headers:**
- `Authorization: Bearer cap_...`

**Body (accepts snake_case or camelCase):**
```json
{
  "userId": "string",
  "units": 1,
  "idempotencyKey": "optional_string"
}
```

**Response (200 OK - allowed):**
```json
{
  "ok": true,
  "remaining": 19
}
```

**Response (402 Payment Required - denied):**
```json
{
  "ok": false,
  "reason": "insufficient_balance",
  "remaining": 0
}
```

### POST /v1/why_denied
Explains current balance state for a user. For debugging.

**Headers:**
- `Authorization: Bearer cap_...`

**Body:**
```json
{
  "userId": "string"
}
```

**Response:**
```json
{
  "reason": "insufficient_balance",
  "details": {
    "userId": "user_123",
    "dailyLimit": 20,
    "extraBalance": 0,
    "usedToday": 20,
    "available": 0
  }
}
```

## TypeScript SDK (In This Repo)

This repository includes an SDK client at `src/sdk/index.ts`. If you copy it:

```typescript
import { CapClient } from './sdk';

const cap = new CapClient({ 
  apiKey: 'cap_...',
  baseUrl: 'https://cap-alpha-one.vercel.app' // must set explicitly
});

const gate = await cap.consume({ userId: 'user_123', units: 1 });
if (!gate.ok) {
  return res.status(402).json({ error: 'Daily limit exceeded' });
}
```

The SDK is NOT published to npm. Use the fetch snippet above, or copy the SDK files from this repo.

## Integration Examples

### Express.js Example

```typescript
app.post('/api/ai/chat', async (req, res) => {
  const userId = req.user.id;
  
  // Gate the route with Cap
  const capResponse = await fetch('https://cap-alpha-one.vercel.app/v1/consume', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CAP_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ 
      userId,
      units: 1,
      idempotencyKey: req.headers['x-request-id']
    })
  });
  
  const gate = await capResponse.json();
  
  if (!gate.ok) {
    return res.status(402).json({ 
      error: 'Daily limit exceeded',
      reason: gate.reason,
      remaining: gate.remaining 
    });
  }
  
  // Allowed - proceed with AI call
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: req.body.messages
  });
  
  res.json(response);
});
```

### Next.js API Route Example

```typescript
export default async function handler(req, res) {
  const userId = req.user.id;
  
  const capGate = await fetch('https://cap-alpha-one.vercel.app/v1/consume', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CAP_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ userId, units: 1 })
  });
  
  const gate = await capGate.json();
  
  if (!gate.ok) {
    return res.status(402).json({ error: 'Daily limit exceeded' });
  }
  
  // AI route proceeds with OpenAI, Anthropic, etc.
}
```

## Best Practices

1. **Always check the gate before expensive operations**: Call consume() before invoking LLM APIs
2. **Use idempotency keys for retries**: Prevents double-counting on network failures
3. **Handle 402 responses gracefully**: Return clear error messages to users
4. **Monitor remaining balance**: Show users their remaining quota
5. **Fail closed**: If Cap is unreachable, deny the request rather than allowing unlimited access

## Error Handling

```typescript
try {
  const capResponse = await fetch('https://cap-alpha-one.vercel.app/v1/consume', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ userId, units: 1 })
  });
  
  if (!capResponse.ok) {
    if (capResponse.status === 402) {
      const gate = await capResponse.json();
      return res.status(402).json({ 
        error: 'Payment required',
        reason: gate.reason,
        remaining: gate.remaining 
      });
    }
    throw new Error(`Cap API error: ${capResponse.status}`);
  }
  
  const gate = await capResponse.json();
  // Proceed with AI route
} catch (error) {
  // Fail closed: treat Cap errors as insufficient balance
  console.error('Cap API error:', error);
  return res.status(402).json({ 
    error: 'Payment required - service temporarily unavailable' 
  });
}
```

## What Cap Is NOT

Cap is a gate, not a billing system:
- No Stripe integration
- No dashboard UI
- No plan builder
- No invoices or tax handling

For billing, use Stripe. For spend caps on AI routes, use Cap.

## Architecture

Cap is designed as a stateless gate:
- PostgreSQL backend for atomic operations
- Fail-closed design: errors deny access
- UTC-based daily resets
- Idempotency via request deduplication
- No user authentication (uses project API keys)

## Support

- **Documentation**: https://cap-alpha-one.vercel.app/llms.txt
- **Cursor Skill**: https://cap-alpha-one.vercel.app/SKILL.md
- **GitHub**: https://github.com/jaanolev/cap
- **Issues**: https://github.com/jaanolev/cap/issues