@emulates/daily 2.3.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog — @emulates/daily
+
+## 2.3.1 (2026-10-06)
+
+Initial release.
+
+### Dependencies
+
+- `@emulates/sqlite`

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @emulates/daily discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@emulates/daily/`; no repository checkout is needed to discover the emulator's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `emulates.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **Rooms, tokens, and webhooks**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- daily`.
+- Evidence model: Run from an Emulates checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Emulates
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-emulates-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/emulators/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual emulator result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `daily`.

package/README.md

@@ -0,0 +1,162 @@
+# @emulates/daily
+
+> Part of [Emulates](https://github.com/crvouga/emulators): high-fidelity, in-process emulators for APIs and databases.
+
+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](https://github.com/crvouga/emulators/blob/main/packages/service/daily/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
+
+```bash
+npm install -D @emulates/daily
+```
+
+ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with
+`npx emulates-daily serve`, `createServer` from `./server` (Node), or `createRuntime` with
+any Fetch server.
+
+## Usage
+
+Point the apps at the emulator (the G-D1 seams):
+
+| App | Env | Value |
+| --- | --- | --- |
+| backend | `DAILY_API_BASE_URL` | `http://127.0.0.1:8800/v1` (needs the http-loopback exception) |
+| backend | `DAILY_API_KEY`, `DAILY_API_DOMAIN_ID` | any key (or `--api-key`), and the same value as `--domain-id` |
+| EMR backend | `DailyService.baseUrl` | `http://127.0.0.1:8800/v1` (hardcoded today) |
+| EMR backend | `DEFAULT_DAILY_BASE_URL` | the same value as `--room-url-base` |
+| EMR backend | `DAILY_WEBHOOK_SECRET` | the same value as `--webhook-secret` |
+| member-app | `EXPO_PUBLIC_DAILY_BASE_URL` | the same value as `--room-url-base` |
+
+```bash
+npx emulates-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"
+```
+
+```ts
+import { createRuntime } from "@emulates/daily"
+
+const daily = createRuntime({
+  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" },
+})
+const admin = (path: string, body: unknown) =>
+  daily.fetch(
+    new Request(`http://daily.test/__admin${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    }),
+  )
+
+// …the EMR books an appointment: POST /v1/rooms + POST /v1/meeting-tokens…
+
+// End the call: writes <room>/<session>.json to S3, then fires transcription.stopped.
+await admin("/rooms/<room name>/session", {
+  participants: [{ userId: "prac-1" }, { userId: "pat-1" }],
+  durationSec: 1200,
+  transcript: [{ s: "prac-1", t: "How are you feeling?", ts: 0.5, te: 2.1 }],
+})
+```
+
+### Routes
+
+| Route | Behaviour |
+| --- | --- |
+| `GET /v1/rooms` | `{total_count, data}` in newest-first creation order; `limit` (default 100), `ending_before` and `starting_after` use room IDs. Shares state with room creation, updates and deletion. |
+| `POST /v1/rooms` | `{name?, privacy?, properties?}`; unknown properties, bad types and a duplicate `name` are 400 `{error: "invalid-request-error", info}`. No name → a random 20-character one. Answers `{id, name, api_created, privacy, url: <roomUrlBase><name>, created_at, config}` with `config` echoing the properties. Accepts both the backend's strict body and the EMR's `generateRoomConfig` body. |
+| `GET /v1/rooms/:name` | The room, or 404 `{error: "not-found", info: "room <name> not found"}` (the EMR branches on `message.includes('404')`). |
+| `POST /v1/rooms/:name` | Merge `properties` (and `privacy`) into the room; 404 when missing. |
+| `DELETE /v1/rooms/:name` | `{deleted: true, name}`; 404 when missing (the EMR tolerates it). |
+| `GET /v1/rooms/:name/presence` | `{total_count, data: [{room, id, userId, userName, joinTime, duration}]}` — exactly the backend's strict schema. Participants come from `PUT /__admin/rooms/:name/presence`. |
+| `POST /v1/rooms/:name/eject` | `{user_ids?, ids?}` → `{ejectedIds}` (participant session ids), removing them from presence. |
+| `POST /v1/meeting-tokens` | `{properties}` → `{token}`: an HS256 JWT signed with the caller's API key, claims under Daily's abbreviations (`r`, `d`, `o`, `u`, `ud`, `nbf`, `exp`, `ejt`, `eje`, `er`, `erui`, `sr`, `ast`, `p`, …) plus `iat`. |
+| `GET /v1/meeting-tokens/:token` | Verifies a token (minted by the emulator **or self-signed by our backend**) with the caller's API key and its `nbf`/`exp` on the emulator clock (`?ignoreNbf=true` skips nbf); answers its properties under full names, else 400. |
+
+**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)
+
+| Route | Effect |
+| --- | --- |
+| `POST /__admin/rooms/:name/session` | `{participants: [{userId, userName?}], durationSec, transcript?: [{s, t, ts, te}], sessionId?, recording?}` writes the transcript JSON to S3 at `{roomName}/{sessionId}.json` (SigV4 `PutObject` to the `--s3-endpoint` / `transcripts` target; a synthetic transcript alternating between participants when none is given), clears presence, then emits `transcription.stopped` (and `recording.ready-to-download` unless `recording: false`). Answers `{sessionId, s3Key, transcript: "s3://…" \| null, events}`; 502 when S3 refuses. The transcript text is never kept. |
+| `PUT /__admin/rooms/:name/presence` | `{participants: [{userId, userName?, joinedAt?}]}` — who `GET …/presence` reports. |
+| `POST /__admin/tokens/decode` | `{token, apiKey?}` → `{decodable, header, claims, properties, signatureValid, room, joinable, problems, warnings}`: signature (against `apiKey` or `apiKeys`), the backend's strict claim set, `ud` ≤ 36, domain id, ms timestamps, and the token and room `nbf`/`exp` windows on the emulator clock (owners may enter before the room's `nbf`). |
+| `GET /__admin/rooms`, `GET /__admin/rooms/:name` | Rooms with config, presence and session metadata. |
+| `GET /__admin/warnings` | Tolerated oddities (millisecond timestamps, tokens for rooms that do not exist). |
+| `PUT /__admin/settings` | `{apiKeys?, domainId?, roomUrlBase?}` for the calling namespace (`GET` masks keys). |
+
+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-emulates-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
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `DailyAPI` | class | The in-process emulator: `fetch(request)`, `reset()`, `inspectToken(token, keys?)`, `setPresence(name, participants)`, `endSession(name, input)`, `rooms()`. Options: `sqlite`, `now`, `namespace`, `settings`, `onWebhook`, `transcripts`. |
+| `createRuntime` | function | The emulator with the full service contract. Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `transcripts: {endpoint, bucket, region?, accessKeyId?, secretAccessKey?, keyPattern?, fetch?}`, `settings`, `clock`, `seed`, `adminKey`, `onLog`. |
+| `DAILY_PRESETS` | object | Every named fault preset. |
+| `DAILY_NAMESPACE` | string | The service name, `"daily"`. |
+| `WEBHOOK_PATH` | string | `"/v1/webhooks/daily"`, our EMR receiver's route. |
+| `dailyWebhookSigner` | function | The `x-webhook-signature` signer (hex HMAC-SHA256 of the raw body). |
+| `signToken`, `decodeToken`, `verifySignature` | functions | HS256 meeting-token helpers. |
+| `claimsToProperties`, `propertiesToClaims`, `CLAIM_NAMES` | values | Daily's abbreviated claim names ↔ full property names. |
+| `synthesizeTranscript` | function | The default transcript for a session with none given. |
+| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
+| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8800. |
+
+Part of [emulators](https://github.com/crvouga/emulators).

package/SUPPORT.md

@@ -0,0 +1,19 @@
+# Daily.co REST API (Emulates subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **9**
+- supported by the emulator: **9**
+- parity enabled: **9**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `ListRooms` | `GET /v1/rooms` | ✅ supported | ✅ |  |
+| `CreateRoom` | `POST /v1/rooms` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `GetRoom` | `GET /v1/rooms/{name}` | ✅ supported | ✅ |  |
+| `UpdateRoom` | `POST /v1/rooms/{name}` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `DeleteRoom` | `DELETE /v1/rooms/{name}` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `GetRoomPresence` | `GET /v1/rooms/{name}/presence` | ✅ supported | ✅ |  |
+| `EjectParticipants` | `POST /v1/rooms/{name}/eject` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `CreateMeetingToken` | `POST /v1/meeting-tokens` | ✅ supported | ✅ |  |
+| `ValidateMeetingToken` | `GET /v1/meeting-tokens/{token}` | ✅ supported | ✅ |  |