@crvouga/mockingbird-service-daily

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the Daily.co REST API for test suites: rooms (create, get, update, delete, presence, eject), meeting tokens (mint and validate), verification of the HS256 meeting tokens our backend signs itself, and the end-of-call webhooks (transcription.stopped, recording.ready-to-download) with the transcript written to the stack's S3. Every EMR booking creates a room and a token; today a broken Daily integration is silent because booking swallows the error. Against the emulator it is observable and assertable.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is trimmed from Daily's documented REST API to the calls our backend and EMR make, with the fields they send.

Install

npm install -D @crvouga/mockingbird-service-daily

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-daily serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

Point the apps at the emulator (the G-D1 seams):

npx mockingbird-daily serve --port 8800 \
  --room-url-base https://acme-mock.daily.test/ \
  --domain-id "$DAILY_API_DOMAIN_ID" \
  --webhook-url http://127.0.0.1:4000/v1/webhooks/daily \
  --webhook-secret "$DAILY_WEBHOOK_SECRET" \
  --s3-endpoint http://127.0.0.1:4569 --s3-bucket "$S3_BUCKET_NAME"

import { createServer } from "@crvouga/mockingbird-service-daily/server"

// Test setup: the emulator, its webhook receiver and the S3 bucket transcripts land in.
const server = await createServer({
  settings: { roomUrlBase: "https://acme-mock.daily.test/" },
  webhooks: { url: "http://127.0.0.1:4000/v1/webhooks/daily", secret: "whsec-daily" },
  transcripts: { endpoint: "http://127.0.0.1:4569", bucket: "emr-transcripts" },
})

// Application code: DAILY_API_BASE_URL is `${server.url}/v1`. The EMR books an appointment.
const baseUrl = `${server.url}/v1`
const headers = { authorization: "Bearer daily-api-key", "content-type": "application/json" }
const created = await fetch(`${baseUrl}/rooms`, {
  method: "POST",
  headers,
  body: JSON.stringify({ privacy: "private" }),
})
const room = (await created.json()) as { name: string; url: string }
const minted = await fetch(`${baseUrl}/meeting-tokens`, {
  method: "POST",
  headers,
  body: JSON.stringify({ properties: { room_name: room.name, user_id: "prac-1", is_owner: true } }),
})
const { token } = (await minted.json()) as { token: string }

// Test control: end the call. Writes <room>/<session>.json to S3, then fires transcription.stopped.
await fetch(`${server.url}/__admin/rooms/${room.name}/session`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    participants: [{ userId: "prac-1" }, { userId: "pat-1" }],
    durationSec: 1200,
    transcript: [{ s: "prac-1", t: "How are you feeling?", ts: 0.5, te: 2.1 }],
  }),
})
await server.close()

Routes

Auth. Authorization: Bearer <DAILY_API_KEY>; any key unless apiKeys is set. Missing → 401 {error: "authentication-error"}.

Milliseconds. Some of our callers pass nbf/exp in milliseconds (e.g. the EMR's generatePatientToken passes Date.parse(end)). The emulator accepts them, interprets values ≥ 1e11 as ms in time checks, records each in GET /__admin/warnings, and tags the journal entry (ids.warning: "exp in milliseconds").

Webhooks

Admin sessions post Daily-shaped events: {version: "1.0.0", type, event, id, event_ts, payload} (our receiver reads event; Daily documents type; both are sent).

• transcription.stopped — payload: {room_name, session_id, duration, s3_key, instance_id}.
• recording.ready-to-download — payload: {type: "cloud", recording_id, room_name, session_id, start_ts, status: "finished", max_participants, duration, s3_key} (our EMR just acks it).

Signature — our scheme, not Daily's. x-webhook-signature = hex HMAC-SHA256(DAILY_WEBHOOK_SECRET, raw body), which is what our EMR verifies (only when the secret is set). Daily's documented scheme is different — base64 HMAC-SHA256 over "<X-Webhook-Timestamp>.<body>" with the base64-decoded secret — so a real Daily webhook would fail our check; the emulator signs the way our code checks. x-webhook-timestamp is sent too. Retries: immediately, 5 s, 5 min, 30 min, 2 h; GET /__admin/webhooks, …/events, …/replay, …/flush as usual.

Admin (beyond the standard contract)

Time rules run on the emulator clock (POST /__admin/clock): token/room nbf and exp, and therefore the backend's 13 h room-creation delay and 30-min guardrail window as seen by Daily.

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}): room_not_found (404 on /v1/rooms/:name…), unauthorized (401), rate_limited (429), server_error (500), webhook_duplicate, webhook_reorder, webhook_drop.

Namespaces

x-mockingbird-namespace, a /__admin/ns/<name> prefix on the base URL, or by API key: PUT /__admin/credentials {"credentials": {"<DAILY_API_KEY>": "<namespace>"}}.

Deliberately not modelled

• The media plane: SFU, WebRTC, knocking/admission, recording and transcription themselves. daily-js loads Daily's CDN bundle; member-app UI tests should inject a fake DailyCallLike through useCallProviderLogic(createCallObject).
• The room page at https://<domain>.daily.co/<room>?t= (the URL is produced, not served).
• Daily's own webhook signature scheme and webhook registration API (see above).
• Recordings/transcripts REST APIs, dial-out, streaming.

API

Part of mockingbird.