apiVersion: capsule.dev/v0.1
kind: Capsule
name: f4c-room-api
version: 0.1.0
type: adapter
purpose:
summary: 'Provides API endpoints for creating and joining chat rooms, issuing RealtimeKit
participant tokens, and persisting room metadata in Cloudflare KV. It handles
room type negotiation, expiry, and initial rate limiting.
'
owns:
- API endpoint for token generation and room creation
- Room metadata persistence in Cloudflare KV
- RealtimeKit meeting creation and participant token issuance
- IP-based rate limiting for token requests
- Turnstile token verification
does_not_own:
- Actual real-time communication
- Bot logic
- Frontend UI components
interfaces:
provides:
- kind: http_api
name: /api/token
description: Endpoint to request an authentication token for a chat room, creating
the room if it doesn't exist.
requires:
- kind: env
name: ROOMS_KV
description: Cloudflare KV Namespace for storing room metadata.
- kind: env
name: CF_API_TOKEN
description: Cloudflare API token for interacting with RealtimeKit API.
- kind: env
name: CF_ACCOUNT_ID
description: Cloudflare account ID for RealtimeKit API calls.
- kind: env
name: RTK_APP_ID
description: RealtimeKit application ID.
- kind: env
name: RTK_PRESET_NAME
description: Default RealtimeKit preset name for meetings.
- kind: env
name: RTK_SCREENSHARE_PRESET_NAME
description: RealtimeKit preset name for screen share enabled meetings.
- kind: env
name: RTK_AUDIO_PRESET_NAME
description: RealtimeKit preset name for audio-only meetings.
- kind: env
name: TURNSTILE_SECRET_KEY
description: Secret key for Cloudflare Turnstile verification.
- kind: http_api
name: Cloudflare RealtimeKit API
description: External API for creating meetings and participants.
- kind: http_api
name: Cloudflare Turnstile API
description: External API for verifying Turnstile tokens.
dependencies:
capsules:
- name: f4c-turnstile-gate
version: '>=0.1.0'
agent:
summary_for_ai: 'This capsule manages room lifecycle and authentication. Agents
should focus on refining rate limiting, improving room expiry logic, or integrating
with different real-time communication backends. Ensure security best practices
for token generation and origin checks.
'
avoid:
- Embedding UI logic or specific frontend dependencies.
- Hardcoding RealtimeKit-specific values that could be parameterized.
verification:
invariants:
- Room records in KV must accurately reflect the current state (meetingId, roomType,
botEnabled, createdAt).
- Rate limits must be enforced per IP.
- Turnstile tokens must be validated if `TURNSTILE_SECRET_KEY` is set.
x-reuse:
notes: 'app/src/pages/api/token.ts: `ALLOWED_ORIGINS` is hardcoded. `MAX_ROOM_LENGTH`,
`MAX_NAME_LENGTH`, `ROOM_MAX_AGE_MS`, `RATE_LIMIT_WINDOW_S`, `RATE_LIMIT_MAX`,
`ROOM_KV_TTL_S` are hardcoded. Assumes Cloudflare RealtimeKit for meeting management.
'
x-reconstruct:
install: install.json