keys-for-all/docs/API_SPECIFICATION.md

# Keys for All - API Specification

## Base URL
```
Production: https://api.keysforall.com/v1
Development: http://localhost:3000/v1
```

## Authentication

All API requests require authentication using an API key in the header:
```
X-API-Key: your-api-key-here
```

## Endpoints

### Key Management

#### Generate Keys
```http
POST /keys/generate
```

**Request Body:**
```json
{
  "count": 5,
  "type": "purchase",
  "metadata": {
    "app_id": "com.voiceuwu.app",
    "purchase_id": "SK123456789",
    "price": 19.99
  }
}
```

**Response:**
```json
{
  "success": true,
  "keys": [
    {
      "key": "ABCD-EFGH-IJKL-MNOP",
      "created_at": "2024-01-20T10:00:00Z",
      "expires_at": null,
      "type": "purchase"
    }
  ],
  "transaction_id": "txn_123456"
}
```

#### Validate Key
```http
POST /keys/validate
```

**Request Body:**
```json
{
  "key": "ABCD-EFGH-IJKL-MNOP",
  "app_id": "com.voiceuwu.app"
}
```

**Response:**
```json
{
  "valid": true,
  "key_info": {
    "created_at": "2024-01-20T10:00:00Z",
    "first_used_at": "2024-01-20T10:05:00Z",
    "uses_remaining": null,
    "level": 1
  }
}
```

#### Activate Key
```http
POST /keys/activate
```

**Request Body:**
```json
{
  "key": "ABCD-EFGH-IJKL-MNOP",
  "app_id": "com.voiceuwu.app",
  "device_id": "iPhone14,2",
  "metadata": {
    "app_version": "1.2.0",
    "os_version": "17.2"
  }
}
```

**Response:**
```json
{
  "success": true,
  "activation": {
    "id": "act_123456",
    "activated_at": "2024-01-20T10:05:00Z",
    "level": 1
  }
}
```

#### Get Key Status
```http
GET /keys/{key}/status
```

**Response:**
```json
{
  "key": "ABCD-EFGH-IJKL-MNOP",
  "status": "active",
  "created_at": "2024-01-20T10:00:00Z",
  "activations": 1,
  "shares": 0,
  "level": 1
}
```

### Key Sharing

#### Create Share Link
```http
POST /keys/share
```

**Request Body:**
```json
{
  "key": "ABCD-EFGH-IJKL-MNOP",
  "count": 1,
  "expires_in": 86400,
  "message": "Enjoy this key!"
}
```

**Response:**
```json
{
  "success": true,
  "share": {
    "id": "shr_123456",
    "code": "SHARE-CODE-123",
    "url": "https://keysforall.com/claim/SHARE-CODE-123",
    "expires_at": "2024-01-21T10:00:00Z"
  }
}
```

#### Claim Shared Key
```http
POST /keys/claim
```

**Request Body:**
```json
{
  "share_code": "SHARE-CODE-123",
  "app_id": "com.voiceuwu.app"
}
```

**Response:**
```json
{
  "success": true,
  "key": {
    "key": "WXYZ-1234-5678-9ABC",
    "level": 1,
    "from": "anonymous"
  }
}
```

### Community Pool

#### Donate to Pool
```http
POST /community/donate
```

**Request Body:**
```json
{
  "keys": ["ABCD-EFGH-IJKL-MNOP"],
  "message": "Happy to help the community!",
  "anonymous": true
}
```

**Response:**
```json
{
  "success": true,
  "donation": {
    "id": "don_123456",
    "keys_donated": 1,
    "pool_size": 42
  }
}
```

#### Request from Pool
```http
POST /community/request
```

**Request Body:**
```json
{
  "app_id": "com.voiceuwu.app",
  "reason": "Student learning voice training",
  "email": "user@example.com"
}
```

**Response:**
```json
{
  "success": true,
  "request": {
    "id": "req_123456",
    "status": "pending",
    "queue_position": 5
  }
}
```

#### Get Pool Status
```http
GET /community/status
```

**Response:**
```json
{
  "pool": {
    "available_keys": 42,
    "pending_requests": 15,
    "total_donated": 1337,
    "total_distributed": 1295
  },
  "stats": {
    "donations_today": 5,
    "requests_today": 8,
    "average_wait_time": 3600
  }
}
```

### Purchase Verification

#### Verify StoreKit Purchase
```http
POST /purchase/verify
```

**Request Body:**
```json
{
  "receipt_data": "base64-encoded-receipt",
  "product_id": "com.voiceuwu.keys.pack5",
  "transaction_id": "1000000123456789"
}
```

**Response:**
```json
{
  "success": true,
  "verification": {
    "valid": true,
    "product_id": "com.voiceuwu.keys.pack5",
    "keys_granted": 5,
    "keys": ["ABCD-EFGH-IJKL-MNOP", "..."]
  }
}
```

### Analytics

#### Get App Statistics
```http
GET /analytics/app/{app_id}
```

**Response:**
```json
{
  "app_id": "com.voiceuwu.app",
  "period": "30d",
  "stats": {
    "keys_activated": 150,
    "keys_shared": 45,
    "active_users": 120,
    "conversion_rate": 0.15
  }
}
```

## Error Responses

All errors follow this format:
```json
{
  "error": {
    "code": "INVALID_KEY",
    "message": "The provided key is not valid",
    "details": {
      "key": "XXXX-XXXX-XXXX-XXXX"
    }
  }
}
```

### Error Codes
- `INVALID_KEY` - Key format or validation failed
- `KEY_ALREADY_USED` - Key has been activated elsewhere
- `KEY_EXPIRED` - Key has passed expiration date
- `RATE_LIMITED` - Too many requests
- `INVALID_API_KEY` - Authentication failed
- `INSUFFICIENT_KEYS` - Not enough keys to share
- `POOL_EMPTY` - Community pool has no keys

## Rate Limits

- Key validation: 100 requests per minute
- Key generation: 10 requests per minute
- Community requests: 1 per hour per IP
- General API: 1000 requests per hour

## Webhooks

Apps can register webhooks for events:

### Webhook Events
- `key.activated` - When a key is activated
- `key.shared` - When a key is shared
- `pool.donation` - When keys are donated
- `purchase.verified` - When a purchase is verified

### Webhook Payload
```json
{
  "event": "key.activated",
  "timestamp": "2024-01-20T10:05:00Z",
  "data": {
    "key": "ABCD-EFGH-IJKL-MNOP",
    "app_id": "com.voiceuwu.app",
    "level": 1
  }
}
```