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