Server: API Routes & Infrastructure

[ggondim]

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

[claude]

@claude Implement this issue.

• Base branch: meta/17
• Target your PR to meta/17
• Include fixes #11 in the PR body

This is P0 — auto-merge is enabled.

[claude]

Claude finished @claude[bot]'s task in 14m 59s —— View job • claude/17-issue-11-20260410-2220 • Create PR ➔

---

Implementing Issue #11: Server API Routes & Infrastructure

Todo List

• Read CLAUDE.md and explore codebase structure
• Understand existing dependencies (Router, Reply Engine, Token/Thread, MongoDB, Slack)
• Add mongodb dependency to server package
• Implement lib/db.ts — MongoDB singleton + typed CRUD helpers
• Implement lib/auth.ts — token/API key validation middleware
• Implement lib/rate-limit.ts — in-memory sliding-window rate limiter
• Implement lib/logger.ts — structured request logging
• Implement lib/fanout.ts — concurrent recipient delivery
• Implement GET /health and GET /api/health
• Implement Management CRUD routes (channels, recipients, routes, threads, turns)
• Implement POST /send/channel/:channelId/target/:groupOrUser — new thread send
• Implement POST /send/.../thread/:threadId — existing thread send
• Implement POST /webhook/:channelId — channel webhook receiver (Slack + Telegram sig verification)
• Add instrumentation.ts — graceful shutdown on SIGTERM/SIGINT
• Commit and push changes

What was implemented

23 files, 2036 insertions across the packages/server/ package:

Area	Files
Send endpoints	/send/channel/[channelId]/target/[groupOrUser]/route.ts (new thread) and .../thread/[threadId]/route.ts (existing thread)
Webhook receiver	/webhook/[channelId]/route.ts — Slack HMAC + Telegram token verification, event normalization, router fan-out
Management API	/api/channels, /api/recipients, /api/routes, /api/threads + detail/turns routes — all with management API key auth
Health check	/health + /api/health — MongoDB ping + uptime
Auth	lib/auth.ts — ephemeral token, channel API key, management key
Rate limiting	lib/rate-limit.ts — 60 req/min for webhooks, 30/min for send
Storage	lib/db.ts — MongoDB singleton, typed CRUD helpers, index setup
Fan-out	lib/fanout.ts — concurrent delivery to matched recipients via fetch()
Shutdown	src/instrumentation.ts — SIGTERM/SIGINT → MongoDB close

| Branch