# Consumer Integration Guide

How external services integrate with messenger. Life-manager is the primary consumer.

## Architecture

Messenger exposes three API surfaces. Consumers pick the ones they need:

```
                              ┌──────────────────────────────────────┐
                              │        MESSENGER PLATFORM            │
                              │                                      │
┌──────────────┐              │  ┌──────────────────────────────┐    │
│  Consumer    │  X-Service-  │  │  SERVICE API                 │    │
│  (e.g.      │  Key header  │  │                              │    │
│  life-mgr)  │─────────────▶│  │  POST /api/send-queue/enqueue│    │
│              │              │  │  GET  /api/messages/self     │    │
│              │              │  │  GET  /api/send-queue/stats  │    │
│              │              │  │  GET  /api/send-queue/history│    │
│              │              │  │  GET  /api/health/status     │    │
│              │              │  └──────────────────────────────┘    │
│              │              │                                      │
│              │  no auth     │  ┌──────────────────────────────┐    │
│              │  (internal   │  │  BROWSE API                  │    │
│              │   network)   │  │                              │    │
│              │─────────────▶│  │  GET /api/browse/conversations│   │
│              │              │  │  GET /api/browse/convo/:id/  │    │
│              │              │  │    messages                  │    │
│              │              │  │  GET /api/browse/search      │    │
│              │              │  │  GET /api/browse/folders     │    │
│              │              │  │  GET /api/browse/folders/:id/│    │
│              │              │  │    messages                  │    │
│              │              │  │  GET /api/browse/stats       │    │
└──────────────┘              │  └──────────────────────────────┘    │
                              │                                      │
┌──────────────┐              │  ┌──────────────────────────────┐    │
│  Claude Code │  stdio       │  │  MCP SERVER                  │    │
│  (MCP client)│─────────────▶│  │                              │    │
│              │              │  │  14 tools (list, get, search,│    │
│              │              │  │  send, cancel, folders,      │    │
│              │              │  │  display rules)              │    │
│              │              │  │                              │    │
│              │              │  │  Direct SQL to Postgres      │    │
└──────────────┘              │  └──────────────────────────────┘    │
                              │                                      │
                              └──────────────────────────────────────┘
```

## API Surfaces

### 1. Browse API (read-only, no auth)

For querying conversations, messages, folders, and stats. Internal network only.

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/browse/conversations` | GET | List conversations (limit, offset, search, provider) |
| `/api/browse/conversations/:id/messages` | GET | Message thread (limit, before cursor) |
| `/api/browse/search` | GET | Full-text message search (query, provider, limit) |
| `/api/browse/folders` | GET | Email folder list (provider) |
| `/api/browse/folders/:id/messages` | GET | Messages in folder (limit, offset) |
| `/api/browse/stats` | GET | Conversation statistics per provider |

### 2. Service API (authenticated, inter-service)

For sending messages, polling self-messages, and health checks. Requires `X-Service-Key` header.

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/send-queue/enqueue` | POST | Enqueue a message for delivery |
| `/api/messages/self` | GET | Self-addressed messages since timestamp |
| `/api/send-queue/stats` | GET | Queue statistics |
| `/api/send-queue/history` | GET | Recent send queue entries |
| `/api/health/status` | GET | Health with DB latency and device info |

**Enqueue payload:**
```json
{
  "phoneNumber": "+15551234567",
  "body": "Message text",
  "provider": "imessage",
  "delaySeconds": 60
}
```

### 3. MCP Server (stdio, direct SQL)

For Claude Code integration. Connects directly to Postgres — no HTTP layer.

14 tools: `list_conversations`, `get_conversation`, `get_contact`, `search_messages`, `get_conversation_stats`, `send_message`, `check_send_status`, `cancel_message`, `list_folders`, `get_folder`, `get_new_messages`, `list_display_rules`, `add_display_rule`, `remove_display_rule`.

## Life-Manager Integration (primary consumer)

Life-manager uses all three surfaces plus a reverse dependency (credential keyring).

### Proxy Pattern

Life-manager proxies messenger's browse API through its own `/api/messages/*` endpoints so the web frontend never talks to messenger directly:

```
/api/messages/conversations   →  /api/browse/conversations
/api/messages/folders         →  /api/browse/folders
/api/messages/search          →  /api/browse/search
/api/messages/stats           →  /api/browse/stats
/api/messages/self            →  /api/messages/self
/api/messages/queue-stats     →  /api/send-queue/stats
/api/messages/queue-history   →  /api/send-queue/history
/api/messages/attachment       →  (streams file)
```

### AI Loop

Life-manager polls `GET /api/messages/self` every minute (when `user_awake` is true), routes new messages through its agent system, and replies via `POST /api/send-queue/enqueue`.

### Credential Keyring (reverse dependency)

Messenger fetches IMAP/SMTP credentials from life-manager's `/api/credentials` endpoint at startup. Falls back to env vars if unavailable.

### Health Check

Life-manager pings `GET /api/health/status` and includes messenger's status in its combined `/api/services/status` response.

## Environment Variables (consumer-side)

| Variable | Purpose |
|----------|---------|
| `IMESSAGE_SYNC_API_URL` | Base URL for messenger (default: `http://localhost:3100`) |
| `IMESSAGE_SYNC_API_KEY` | Value sent as `X-Service-Key` header |

## Environment Variables (messenger-side)

| Variable | Purpose |
|----------|---------|
| `SERVICE_API_KEY` | Validates incoming `X-Service-Key` headers |
| `LIFE_MANAGER_API_URL` | Base URL for credential keyring (default: `http://localhost:3700/api`) |
| `DATABASE_URL` | PostgreSQL connection string |