@crvouga/mockingbird-service-caretalk

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of CareTalk's external API (/externalapi) for test suites: client login, form definitions (GetForm) and saved form rounds (SavePatientForm, the form-submission queue's call), patient search and insert (the account backfill), states, free slots and appointments. The backend requires CareTalk keys at boot, so the emulator lets a stack boot and run the CareTalk paths without the beta environment.

• Operation coverage: SUPPORT.md
• The vendor publishes no spec: the contract (openapi.yaml) is hand-authored from the consumer's zod schemas and interfaces (caretalk.types.ts, caretalk-forms.type.ts).

Install

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

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

Usage

Point CARETALK_API_URL at the emulator (the backend validates it as https-only, so relax that for loopback or front the emulator with TLS). getFormData hardcodes https://api.caretalkbeta.com (seam G-Y1). CARETALK_USERNAME, CARETALK_PASSWORD and CARETALK_API_KEY can be any values unless --api-user / --api-key pin them.

npx mockingbird-caretalk serve --port 8823 --api-user "$CARETALK_USERNAME:$CARETALK_PASSWORD" --api-key "$CARETALK_API_KEY"

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

// Test setup: the emulator. The application gets CARETALK_API_URL = server.url.
const server = await createServer()
const baseUrl = server.url

// Application code: log in, then read a form with the token.
const login = await fetch(`${baseUrl}/externalapi/Auth/client-login`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  // Any credentials log in unless --api-user pins them.
  body: JSON.stringify({ userName: "acme-api", password: crypto.randomUUID() }),
})
const { token } = (await login.json()) as { token: string }
const forms = await fetch(`${baseUrl}/externalapi/Forms/GetForm/health-history`, {
  headers: { authorization: `Bearer ${token}` },
})
const [form] = (await forms.json()) as { fullFormDto: { id: number } }[]

// Test control: after the app's form-submission queue runs, assert what reached CareTalk.
const saved = await fetch(`${baseUrl}/__admin/form-submissions`)
const { submissions } = (await saved.json()) as { submissions: unknown[] }
await server.close()

Routes

Unauthenticated or expired calls are an empty 401 with WWW-Authenticate: Bearer (our client logs in again once and retries). Validation errors are ASP.NET ProblemDetails {type, title, status, errors, traceId}.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}): login_failure, invalid_credentials, token_expired (count applies per operation), server_error, gateway_html, form_not_found, patient_not_found, save_rejected, connection_drop, slow.

Namespaces

x-mockingbird-namespace, a /__admin/ns/<name> prefix on CARETALK_API_URL, or by credential: tokens carry the API user they were issued to, so PUT /__admin/credentials {"credentials": {"<CARETALK_USERNAME>": "<ns>", "<CARETALK_API_KEY>": "<ns>"}} routes both auth styles.

Deliberately not modelled

• CareTalk's clinical workflows behind the forms (reviews, form rounds created by staff), eligibility files, Health Gorilla retrieval, medications and diagnostics.
• Real physician calendars: slots are synthesised; time zones are fixed to Mountain.
• The live form catalogue: DEFAULT_FORMS is synthesised in CareTalk's shape (the live-parity script seeds the emulator from the beta environment's forms instead).

API

Part of mockingbird.