136 lines
7.4 KiB
Markdown
136 lines
7.4 KiB
Markdown
# 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 |
|