# @crvouga/mockingbird-service-healthie Stateful mock of the **Healthie GraphQL API**, covering the legacy surface our backend still calls: - sign-in, users, the current user, and profile, password and avatar updates - client updates and addresses - documents and folders, including multipart uploads, with downloads served by the mock - requested forms and form answers - offerings and billing items - the IP-allowlisted status webhooks GraphQL documents run on the reference [`graphql`](https://www.npmjs.com/package/graphql) implementation against a subset of Healthie's schema written by hand. Selection sets, aliases, fragments, variables, `__typename` and validation errors therefore behave as they do on Healthie, and the mock returns only the fields a document asks for. - Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/healthie/SUPPORT.md) - Healthie publishes an SDL but no OpenAPI. `openapi.yaml` describes the HTTP side: one GraphQL operation and the file-download route. The GraphQL schema is `HEALTHIE_SDL`. > **Is this worth testing?** The catalog (S23) marks Healthie as legacy. Appointments and > providers moved to Medplum. What is left is legacy sign-in, password reset, profile and > address, the ODX document upload, and admin export and migration. Check that a suite still > exercises these paths before you wire the mock into the stack. It is fully implemented > either way. ## Install ```bash npm install -D @crvouga/mockingbird-service-healthie ``` ESM only. Node >= 22 or Bun >= 1.2. The one runtime dependency besides `hono` is the public `graphql` package (pinned to 16.11.0, the version our backend uses). See [Why `graphql`](#why-graphql-is-a-runtime-dependency). Serve it with `npx mockingbird-healthie serve`, `createServer` from `./server` (Node), or `createRuntime` with any Fetch server. ## Usage Point `HEALTHIE_API_URL` at `http://127.0.0.1:8816/graphql`. This needs seam **G-H1** first: the backend's Joi and zod schemas currently accept only the staging or prod URL, and `HEALTHIE_WEBHOOK_IP_ADDRESS` only the two IP lists. Set `HEALTHIE_API_AUTH_TOKEN` in the app and pass the same value as `--api-key`. ```bash npx mockingbird-healthie serve --port 8816 \ --api-key "$HEALTHIE_API_AUTH_TOKEN" \ --webhook-base-url http://127.0.0.1:3000 \ --webhook-ip 18.206.70.225 ``` ```ts import { createRuntime, SEED } from "@crvouga/mockingbird-service-healthie" const healthie = createRuntime({ settings: { orgApiKeys: ["gh_sbox_test_org"] }, webhooks: { baseUrl: "http://127.0.0.1:3000", ip: "18.206.70.225" }, }) const graphql = (query: string, variables: object, key?: string) => healthie.fetch( new Request("http://healthie.test/graphql", { method: "POST", headers: { "content-type": "application/json", AuthorizationSource: "API", ...(key ? { authorization: `Basic ${key}` } : {}), }, body: JSON.stringify({ query, variables }), }), ) // The seeded demo patient signs in and gets an API key, as the member app does. const signedIn = await graphql( `mutation($e: String, $p: String) { signIn(input: { email: $e, password: $p, generate_api_token: true }) { api_key user { id active } } }`, { e: SEED.patientEmail, p: SEED.patientPassword }, ) // Ask Healthie to request a form from the patient; POST /forms/webhooks/status follows. await healthie.fetch( new Request("http://healthie.test/__admin/requested-forms", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ recipient_id: SEED.patientId }), }), ) ``` ### Routes | Route | Behaviour | | --- | --- | | `POST /graphql` | One document per request, sent as JSON `{query, variables, operationName}` or as a [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec) (`operations`, `map`, file parts) for `Upload` variables. The `Authorization` header carries the API key as `Bearer `, `Basic ` or the bare key. `AuthorizationSource: API` is accepted and ignored. Errors come back with HTTP 200, as on Healthie. A body that is not GraphQL gets a 400. | | `GET /files/{token}` | The bytes behind `document.expiring_url` and `user.avatar_url`, which point here on the request's own origin (with `/ns/` when namespaced). Links are signed and expire on the mock clock (`expiringUrlSeconds`, default 300). A tampered or expired link gets a 403 and a deleted file a 404. Each download adds one entry to `document.opens`. | GraphQL root fields: `currentUser`, `user(id)`, `users(keywords, should_paginate, …)`, `location(id)`, `locations`, `documents(…)`, `document(id)`, `folders(…)`, `requestedFormCompletion(id)`, `formAnswerGroups(user_id, …)`, `formAnswerGroup(id)`, `initialFormAnswers(custom_module_form_id, incomplete_form_id, user_id)`, `offerings(client_visibility, offering_id, …)` and `billingItems(offerings_only, client_id, status)`. Mutations: - `signIn(input)`: `generate_api_token` and `allow_multiple_api_keys` are honoured, and so is `namespace` when one is set. - `updateUser(input)`: sets profile fields, uploads an avatar as an `Upload`, removes it with `avatar: null`, or changes the password. The password variant sends no `id` and checks `current_password` and `password_confirmation`. - `updateClient(input)`: `metadata`, `phone_number`, `password`, `other_provider_ids`, `user_group_id`, `dietitian_id`, `active`, and `location` as a `ClientLocationInput`. - `createLocation` and `updateLocation`. - `createFolder`: parses `share_users` given as `"user-,…"`. - `createDocument`: takes an `Upload` or a `file_string` data URL, plus `share_users` and `rel_user_id`. - `deleteDocument`. - `updateBillingItem`: `is_paused`, `is_canceled`, `note` and `state`. Our client sends it as two aliased mutations in one document; each emits `billing_item.updated`. Behaviour our code branches on: - **Bad key:** an unknown API key returns `errors: [{message: "API Key is Invalid"}]`, which our client maps to 401. - **No key:** `currentUser` is `null`, lists are empty and mutations other than `signIn` fail. Our `listFiles` turns the `null` into a 401. - **Validation:** failures come back as `messages: [{field, message}]` with a `null` payload, which our client maps to 400. `messages` is `null` on success; our `getFolderByPath` treats any non-null value as failure. - **Sign-in:** a wrong email or password returns `user: null`, which our client maps to `INVALID_SIGN_IN_CREDENTIALS`. An archived user signs in with `active: false`, which maps to `USER_ARCHIVED`. - **Who sees what:** a patient key sees only its own user, its care team, its own files and anything shared with it. The organization key sees everything. ### Webhooks Healthie events are posted as `{resource_id, resource_id_type, event_type, changed_fields?}`. `resource_id` is sent as a string, because our DTOs validate `@IsString()`. Each request carries `x-forwarded-for: `, and that header is our receivers' only check against `HEALTHIE_WEBHOOK_IP_ADDRESS`. Nothing is signed. | Event | Receiver (`--webhook-base-url` + path) | Emitted by | | --- | --- | --- | | `patient.created`, `patient.updated` | `/users/webhook/status` | `updateUser`, `updateClient`, `POST /__admin/users`, archive and unarchive | | `requested_form_completion.created`, `form_answer_group.created` | `/forms/webhooks/status` | `POST /__admin/requested-forms`, `POST /__admin/form-answer-groups` | | `billing_item.updated` | (none by default; add one with `PUT /__admin/webhook-endpoints`) | `updateBillingItem` | `POST /__admin/events {event_type, resource_id, resource_id_type}` emits any event. Deliveries are retried immediately, then after 5 s, 5 min, 30 min and 2 h. The standard admin routes also apply: `GET /__admin/webhooks`, `…/events`, `…/:id/replay` and `…/flush`. ### Admin (beyond the standard contract) | Route | Effect | | --- | --- | | `GET /__admin/users`, `POST /__admin/users` | List users (never passwords). Create one from `{email, password, first_name?, last_name?, role?: patient \| provider, active?, dietitian_id?, …}` and get back `{user, api_key}`. | | `POST /__admin/users/:id/archive` \| `/unarchive` | Set `active` (archived users sign in with `active: false`). | | `POST /__admin/users/:id/api-keys` | Issue another API key for a user. | | `POST /__admin/offerings` | `{name, price?, billing_frequency?, visibility_status?}`. | | `POST /__admin/billing-items` | `{sender_id, offering_id?, amount_paid?, state?, is_recurring?, next_payment_date?}`. | | `POST /__admin/form-answer-groups` | `{user_id, custom_module_form_id?, filler_id?, answers?: {