Server: API Routes & Infrastructure #11

Summary

Implement the Next.js server with all API routes — the actual HTTP surface of OpenThreads. This includes the core sending endpoint, channel webhook receivers, management CRUD API, and server infrastructure.

Tasks

Recipient Inbound (core sending endpoint)

• POST /send/channel/:channelId/target/:groupOrUser/thread/:threadIdOrMessageId
  • Auth: ephemeral token (?token=) OR channel API key (Authorization: Bearer)
  • Body: { message: object | array }
  • Creates thread if :threadIdOrMessageId absent
  • Returns: synchronous response for A2H blocking intents, 202 for fire-and-forget
• POST /send/channel/:channelId/target/:groupOrUser — new thread variant

Channel Inbound Webhooks

• POST /webhook/:channelId — generic webhook receiver per channel
  • Verify platform-specific signatures (Slack signing secret, Telegram token hash, etc.)
  • Parse platform event → normalized inbound message
  • Run through Router → fan out to matched recipients

Management API (CRUD)

• GET/POST /api/channels — list / create channels
• GET/PUT/DELETE /api/channels/:id — channel detail / update / delete
• GET/POST /api/recipients — list / create recipients
• GET/PUT/DELETE /api/recipients/:id
• GET/POST /api/routes — list / create routes
• GET/PUT/DELETE /api/routes/:id
• GET /api/threads — list threads (filterable by channel, target)
• GET /api/threads/:threadId — thread detail
• GET /api/threads/:threadId/turns — list turns in thread

Auth

• Management API authentication (API key or session-based for dashboard)
• Ephemeral token validation middleware
• Channel API key validation middleware

Infrastructure

• Request logging and error handling middleware
• Rate limiting on public endpoints (webhook inbound, form submission)
• Health check endpoint (GET /health)
• Graceful shutdown (close channel subscriptions, drain pending requests)

Acceptance Criteria

• Recipient can POST to /send/... with token and receive response
• Recipient can POST to /send/... with API key and send proactively
• Channel webhooks receive and correctly route inbound messages
• Management CRUD works for all entities
• Invalid tokens/keys return 401
• Rate limiting prevents abuse on public endpoints
• Health check returns 200 with status

Dependencies

• Core: Router Implementation #3 (Core: Router) — webhook handler invokes the router
• Core: Reply Engine #4 (Core: Reply Engine) — send endpoint invokes the reply engine
• Core: Token & Thread/Turn Management #5 (Core: Token & Thread Management) — auth middleware and thread creation
• Storage: MongoDB Adapter #6 (Storage: MongoDB Adapter) — persistence for all entities
• Channel: Slack Adapter #7 (Channel: Slack Adapter) — at least one adapter needed for E2E validation

References

• VISION.md — Recipient Inbound
• VISION.md — Authentication modes
• PLAN.md — Phase 4.1, 4.4