@emulates/caretalk 0.0.0-stage → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog — @emulates/caretalk
+
+## 3.0.0 (2026-10-07)
+
+### ⚠️ Breaking changes
+
+- point the repo at crvouga/emulates ([cdb5e53](https://github.com/crvouga/emulates/commit/cdb5e536ed8c1f52345e3984f089001c25fdb08a))
+
+### Fixes and improvements
+
+- format the emulates records query ([8698872](https://github.com/crvouga/emulates/commit/8698872509d06002be5a8fcdc85d79f8462320c3))
+
+### Dependencies
+
+- `@emulates/sqlite`
+
+## 2.3.1 (2026-10-06)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @emulates/caretalk discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@emulates/caretalk/`; 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: **Forms, patients, and appointments**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- caretalk`.
+- 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/emulates/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: `caretalk`.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# @emulates/caretalk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Part of [Emulates](https://github.com/crvouga/emulates): high-fidelity, in-process emulators for APIs and databases.
+
+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](https://github.com/crvouga/emulates/blob/main/packages/service/caretalk/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
+
+```bash
+npm install -D @emulates/caretalk
+```
+
+ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with
+`npx emulates-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.
+
+```bash
+npx emulates-caretalk serve --port 8823 --api-user "$CARETALK_USERNAME:$CARETALK_PASSWORD" --api-key "$CARETALK_API_KEY"
+```
+
+```ts
+import { createRuntime } from "@emulates/caretalk"
+
+const caretalk = createRuntime()
+const call = (path: string, init: RequestInit = {}) =>
+  caretalk.fetch(new Request(`http://caretalk.test${path}`, init))
+
+const { token } = (await (
+  await call("/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() }),
+  })
+).json()) as { token: string }
+const [form] = (await (
+  await call("/externalapi/Forms/GetForm/health-history", {
+    headers: { authorization: `Bearer ${token}` },
+  })
+).json()) as { fullFormDto: { id: number } }[]
+// After the app's form-submission queue runs, assert what reached CareTalk:
+const { submissions } = (await (await call("/__admin/form-submissions")).json()) as {
+  submissions: unknown[]
+}
+```
+
+### Routes
+
+| Route | Behaviour |
+| --- | --- |
+| `POST /externalapi/Auth/client-login` | `{userName, password}` → `{token, expiration}`. Tokens last `tokenTtlSeconds` (default 3600, what our client caches for) on the emulator clock. |
+| `GET /externalapi/Forms/GetForm/{formName}` | By name or slug, case-insensitive: `[{formRoundId, patientAppointmentId, submitDate, fullFormDto}]`; an unknown form is `[]`. With `PatientId` (and `AppointmentId`), the patient's latest saved round: chosen answers `isChecked`, free text echoed. Accepts a login token or a static API key. |
+| `POST /externalapi/Forms/SavePatientForm?patientId=&patientAppointmentId=` | The submission (`fullFormDto.groups[].groupQuestions[]`). Question ids must belong to the form, answer ids to the question (text questions take `id: 0` with the typed value), single-choice questions one answer; violations are 400 ProblemDetails, an unknown patient or form 404. → `{success: true, message}`. |
+| `GET /externalapi/Patients/SearchForPatient?FirstName&LastName&zipCode&DateOfBirth` | Case-insensitive names, ZIP, and the date in any of `YYYY-MM-DD`, `MM/DD/YYYY`, ISO → `{isExists: true, eligibleId, programId}`; no match is **400** `{isExists: false, message}` (our client reads 400 as "no such patient"). |
+| `GET /externalapi/States` | 51 states `{id, stateUid, name, abbreviation, …}` (UT is 45). |
+| `POST /externalapi/Patients` | Creates a patient and echoes CareTalk's full record (`id`, `eligibilityId` = `id`, `userState`, `formattedUserMobile`, `clientId`, …). |
+| `GET /externalapi/PatientAppointments/GetFreeSlots?date&programId&eligibleId` | Half-hour slots 09:00–16:30 for two physicians, minus booked ones. |
+| `POST /externalapi/PatientAppointments` | `{doctorId, patientId (the eligible id), from, to}` → `{id, patientId: null, eligibilityId, appointmentStatus: 1, physicianId}`; a taken or unknown slot is 400. |
+| `GET /externalapi/PatientAppointments/GetPatientAppointmentsByEligibleId/{id}` | That patient's appointments. |
+
+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)
+
+| Route | Effect |
+| --- | --- |
+| `GET /__admin/form-submissions[?patientId=]` | Saved rounds: `{formRoundId, formId, patientId, patientAppointmentId, submitDate, answers: [{questionId, answerIds, freeAnswerText}]}`. |
+| `GET` / `POST /__admin/patients` | List patients, or create one directly (the Patients POST body) so a search finds it. |
+| `GET /__admin/forms`, `PUT /__admin/forms/:id` | List or add/replace a form definition (`fullFormDto` shape). |
+| `POST /__admin/appointments/:id/status` | `{appointmentStatus}`: change an appointment's status code. |
+| `GET/PUT /__admin/settings` | `{tokenTtlSeconds?, users?: [{userName, password}], apiKeys?, programId?}`. |
+
+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-emulates-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
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `CareTalkAPI` | class | The in-process emulator: `fetch(request)`, `reset()`, `addPatient(body)`, `slots(date)`, `setAppointmentStatus(id, status)`, `upsertForm(form)`, `rounds()`, `patients()`. Options: `sqlite`, `now`, `namespace`, `forms`, `settings`. |
+| `createRuntime` | function | The emulator with the full service contract (health, admin, namespaces, credentials, presets). Options: `forms`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
+| `CARETALK_PRESETS` | object | Every named fault preset. |
+| `CARETALK_NAMESPACE` | string | The service name, `"caretalk"`. |
+| `DEFAULT_FORMS` | array | The seeded form definitions (Health History 101, AOE Questions 102). |
+| `DEFAULT_DOCTORS` | array | The physicians free slots are generated for. |
+| `US_STATES` | array | The `/externalapi/States` rows. |
+| `tokenCredential` | function | The API user a token was issued to, or the static key (how credentials map to namespaces). |
+| `normalizeDate` | function | `YYYY-MM-DD` from ISO, `YYYY-MM-DD` or `MM/DD/YYYY`. |
+| `problem` | function | Build an ASP.NET ProblemDetails response. |
+| `document`, `operationIds`, `supportedOperationIds` | values | The OpenAPI contract and its operation ids. |
+| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--api-user`, `--api-key`); port 8823. |
+
+Part of [Emulates](https://github.com/crvouga/emulates).

package/SUPPORT.md

@@ -0,0 +1,19 @@
+# CareTalk external 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 |
+| --- | --- | --- | --- | --- |
+| `ClientLogin` | `POST /externalapi/Auth/client-login` | ✅ supported | ✅ |  |
+| `GetForm` | `GET /externalapi/Forms/GetForm/{formName}` | ✅ supported | ✅ |  |
+| `SavePatientForm` | `POST /externalapi/Forms/SavePatientForm` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `SearchForPatient` | `GET /externalapi/Patients/SearchForPatient` | ✅ supported | ✅ |  |
+| `ListStates` | `GET /externalapi/States` | ✅ supported | ✅ |  |
+| `InsertPatient` | `POST /externalapi/Patients` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `GetFreeSlots` | `GET /externalapi/PatientAppointments/GetFreeSlots` | ✅ supported | ✅ |  |
+| `ScheduleAppointment` | `POST /externalapi/PatientAppointments` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `GetPatientAppointments` | `GET /externalapi/PatientAppointments/GetPatientAppointmentsByEligibleId/{eligibleId}` | ✅ supported | ✅ |  |