@crvouga/mockingbird-service-vpi 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @crvouga/mockingbird-service-vpi
+
+## 0.1.0 (2026-09-22)
+
+Initial release.

package/README.md

@@ -0,0 +1,164 @@
+# @crvouga/mockingbird-service-vpi
+
+> [!WARNING]
+> **Our app's `VPI_API_URL` defaults to PRODUCTION** (`https://api.vpicompounding.net`, see
+> `apps/backend/src/modules/erx/clients/vpi-api.client.ts`). An unset variable sends real
+> prescriptions to the real pharmacy. The stack **must** set `VPI_API_URL` to this mock (e.g.
+> `http://127.0.0.1:8802`) whenever the VPI rail is reachable.
+
+Stateful mock of the **VPI** compounding-pharmacy clinic API that our backend drives as a
+draft-only eRx rail: JWT authentication, the product taxonomy/details/discounts, day supply,
+shipping states and rates, the clinic location, providers, the patient roster and details,
+the provider-signature duplicate check, `saveNewPrescription`, and the three paged prescription
+status lists our poller reads. Prescriptions move only when a test says so (an admin
+transition). VPI sends no webhooks: our backend polls page 1 (limit 5) of each list.
+
+- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/vpi/SUPPORT.md)
+- The vendor publishes no spec: the contract (`openapi.yaml`) is hand-derived from our client's
+  zod schemas (`vpi-api.contracts.ts` plus the client-local schemas in `vpi-api.client.ts`).
+  The acceptance tests parse every mock response with a verbatim port of those schemas.
+
+## Install
+
+```bash
+npm install -D @crvouga/mockingbird-service-vpi
+```
+
+ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with
+`npx mockingbird-vpi serve`, `createServer` from `./server` (Node), or `createRuntime` with any
+Fetch server.
+
+## Usage
+
+Point the app at the mock and give it any credentials (any pair logs in unless `accounts` is set):
+
+```bash
+npx mockingbird-vpi serve --port 8802
+# app env:
+#   VPI_API_URL=http://127.0.0.1:8802           (REQUIRED: the default is production)
+#   VPI_API_EMAIL=clinic@example.com  VPI_API_PASSWORD=anything
+#   VPI_CLINIC_LOCATION_ID=65a1c0de00000000000000d1
+```
+
+```ts
+import { createRuntime } from "@crvouga/mockingbird-service-vpi"
+
+const vpi = createRuntime()
+const post = (path: string, body: unknown, headers: Record<string, string> = {}) =>
+  vpi.fetch(
+    new Request(`http://vpi.test${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(body),
+    }),
+  )
+
+const { jwtToken } = (await (
+  await post("/accounts/authenticate", { email: "clinic@example.com", password: "x" })
+).json()) as { jwtToken: string }
+// …the app saves a draft with POST /clinic/rxOrdering/saveNewPrescription (Bearer jwtToken)…
+
+// Move it the way the pharmacy would; our poller maps each status.
+await post("/__admin/prescriptions/66b200000000000000000001/transition", {
+  to: "Order Completed",
+  trackingNumber: "1Z999",
+})
+```
+
+### Seed data
+
+Every namespace starts with: user `65a1c0de00000000000000a1` (every login resolves to it unless
+`accounts` is set), clinic `65a1c0de00000000000000c1`, clinic location
+`65a1c0de00000000000000d1` ("Geviti Main"), providers Grace Hopper (NPI `1234567893`, id
+`65a1c0de00000000000000e1`) and Alan Turing (NPI `1987654320`), patient Ada Lovelace
+(`65a1c0de00000000000000f1`, DOB 1985-02-14, 1 Main St, Phoenix AZ 85004), and four products:
+Testosterone Cypionate (`64f1c2a9e4b0a1b2c3d4e5f6` / `2185_INJ`, sterile, 10% clinic discount),
+Semaglutide / B6 Troche (`3097_POW`, cold-shipped), Enclomiphene (`4410_CAP`, no compounding
+reason needed) and Nandrolone (`5120_INJ`, **controlled**: refused by `saveNewPrescription`).
+Replace any of it with `createRuntime({ data: { products, providers, clinicLocations, patients } })`.
+
+### Routes
+
+| Route | Behaviour |
+| --- | --- |
+| `POST /accounts/authenticate` | `{email, password, isPatientLogin: false}` → `{id, jwtToken, refreshToken}`. The JWT payload carries `sub` (user id), `email`, `iat` and `exp` = mock-clock now + `tokenTtlSeconds` (default 3600). Our client caches it until `exp` − 30 s and re-authenticates once on a 401. `isPatientLogin: true` is refused. |
+| every other route | Requires `Authorization: Bearer <jwtToken>`: missing or tampered → 401 `Unauthorized`; expired on the mock clock → 401 `jwt expired`. |
+| `GET /products/getAllFamiliesAndCategories` | `[{family, categories: [subCategory1…]}]`. |
+| `POST /products/getProductsByCategory` | `{category, subCategory1}` → `[{subCategory2_item, commonNames: [{commonName, products: [...]}]}]`. |
+| `GET /products/getProductDetailsByProductId/{id}` | By Mongo id: full details incl. `sigOptions`, `reasonForCompoundedMedication`, `patientPayAmount`, `ndc` (a number). 404 if unknown. |
+| `POST /products/getProductDiscountByProductIds` | `{clinicId, productIds}` → `[{id, productId, discountedPrice, unitPrice, discountedPercentage, controlledSubstance}]` for known products. |
+| `POST /products/calculateDaySupply` | `{productId, quantity, sig}` → `{daySupply, daySupplyReason}` (per-each products: 1 per day; otherwise 30). |
+| `GET /admin/rxOrdering/getShippingStates` | `{data: [{states: [{name: "Arizona", booleanCheck, nonSterile, sterile}]}]}` (full names; no sterile shipping to Alabama or DC). |
+| `POST /portal/getShippingRate` | `{clinicId, clinicLocationId, patientId, productIds, shippingState: "AZ", isRushOrder}` → `{shippingMethod, rushOrderCost, rushOrderMethod, isSignatureRequired}`; 400 for a state VPI does not ship (sterile) to. |
+| `POST /clinic/rxOrdering/checkProviderSignatureNeededDuplicate` | `isDuplicate` is true when an active (not archived) prescription exists for the same patient and product; `isProviderSignatureNeeded` from settings (default true). |
+| `POST /clinic/rxOrdering/saveNewPrescription` | Validates the whole payload against the contract (the shipping state must be the **canonical full name**, `controlledSubstance` must be `"0"`, …) → 400 `{message, errors: [{path, message}]}`; unknown clinic/location/provider/patient/product → 404; a controlled or code-mismatched product → 400. Success: a draft `Provider Signature Needed` in the incomplete list → `{message, prescriptionId, isRefillRequest: false, refillFromPrescriptionId: null}`. |
+| `POST /patients/getPatientByPatientId`, `…/getPatientAddressesByPatientId` | `{patientId, userId}` → the patient (`dateOfBirth`, `phoneNumber`, `cellPhone`), or `{addresses: [...]}`. |
+| `POST /patients/getPatientsInClinic` | `{clinicId, userId, limit, currentPage}` → `{pagination: {hasNextPage, currentPage, limit, totalCount}, patients}`. |
+| `POST /staffs/getAllProvidersByClinicLocationId` | `{clinicLocationId, clinicId}` → providers with `npi`. |
+| `POST /clinicLocations/getClinicLocationByClinicLocationId` | `{clinicLocationId}` → `{id, clinicId, locationName, …}`. |
+| `POST /clinic/rxOrdering/getIncompleteSavedPrescriptionsInClinicLocation`, `…/getSubmittedPrescriptionsInClinicLocation`, `…/getArchivedPrescriptionsInClinic` | `{clinicLocationId, userId, limit, currentPage}` → one page, newest first, of `{prescriptionId, prescriptionStatus, trackingNumber, patientId, createdAt}`. Envelope per `statusEnvelope` (default `vendor`: submitted `{message: {prescriptions}}`, archived `{message: [...]}` with rows keyed `id`, incomplete a bare array). |
+
+### Lifecycle and status lists
+
+| Transition `to` | List | Our consumer's mapping |
+| --- | --- | --- |
+| `Provider Signature Needed` (draft), `Signature Needed`, `New Formula Pending` | incomplete | processing |
+| `Received`, `Order Received` | submitted | submitted |
+| `In Process`, `Order In Process`, `Prescriptions In Process`, `On Hold`, `Order On Hold` | submitted | processing |
+| `Completed`, `Order Complete`, `Order Completed` (adds a `1Z…` tracking number when none is given) | submitted | shipped |
+| `Cancelled`, `Order Cancelled` | archived | cancelled |
+| `Archived`, or any other string (used verbatim) | archived / submitted | unmapped (no refresh) |
+
+Our consumer has **no delivered status** for VPI and the draft rail starts at `processing`, so a
+payment on this rail moves processing → shipped (or cancelled).
+
+### Admin (beyond the standard contract)
+
+| Route | Effect |
+| --- | --- |
+| `POST /__admin/prescriptions/:id/transition` | `{to, trackingNumber?, list?: "incomplete" \| "submitted" \| "archived"}`. |
+| `GET /__admin/prescriptions` | The namespace's prescriptions (ids and status only). |
+| `POST /__admin/patients` | Seed a clinic patient `{firstName, lastName, dateOfBirth, email?, phoneNumber?, cellPhone?, id?, clinicId?, addresses?: [{addressLine1, addressLine2?, city, state, zipcode}]}` (VPI patient creation is not part of our client). `GET` lists them. |
+| `GET /__admin/catalog` | Products, providers and clinic locations. |
+| `PUT /__admin/settings` | `{tokenTtlSeconds?, accounts?: [{email, password, id}], statusEnvelope?, isProviderSignatureNeeded?}`. |
+
+Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
+`token_expired` (401 on authorized calls; with `count: 1` our client re-authenticates exactly
+once and the retry succeeds), `unauthorized_twice` (the retry fails too), `auth_rejected`,
+`server_error`, `duplicate_prescription`, `save_ambiguous_409` (saves the draft, then 409: our
+classifier says needs_review), `save_rate_limited` (429, not saved: needs_review), `save_400`
+(retry via the browser agent), `response_drift` (taxonomy and product-details fields change type:
+our zod parse fails closed).
+
+### Namespaces
+
+`x-mockingbird-namespace`, a `/ns/<name>` prefix on `VPI_API_URL`, or by login email:
+`PUT /__admin/credentials {"credentials": {"<VPI_API_EMAIL>": "<namespace>"}}` (the JWT carries
+the email). Authentication itself lands in the default namespace (or the `/ns/` one); tokens
+verify in every namespace.
+
+### Deliberately not modelled
+
+- Webhooks: VPI has none; our backend polls.
+- Patient creation, clinic default-card billing (`encryptedBillingInfo`) and provider signing:
+  our client has not captured those contracts; seed patients through the admin API.
+- The refresh-token exchange (our client re-authenticates with email/password instead).
+- Real pricing, tax and shipping-rate tables: rates are fixed per cold/sterile/rush.
+- The live catalog: the seed is synthesised in our client's field names (no sandbox recording).
+
+## API
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `VpiAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `transition(id, {to, trackingNumber?, list?})`, `addPatient(input)`, `prescriptions()`. Options: `sqlite`, `now`, `namespace`, `seed`, `settings`. |
+| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, journal). Options: `data`, `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
+| `VPI_PRESETS` | object | Every named fault preset. |
+| `VPI_NAMESPACE` | string | The service name, `"vpi"`. |
+| `tokenCredential` | function | The login email a bearer JWT carries (how credentials map to namespaces). |
+| `issueJwt` | function | Mint a JWT the mock accepts, from `{sub, email, iat, exp}`. |
+| `DEFAULT_USER_ID`, `DEFAULT_CLINIC_ID`, `DEFAULT_CLINIC_LOCATION_ID`, `DEFAULT_PROVIDER_ID`, `DEFAULT_PATIENT_ID` | strings | The seeded ids. |
+| `DEFAULT_PRODUCTS`, `DEFAULT_PROVIDERS`, `DEFAULT_PATIENTS`, `DEFAULT_CLINIC_LOCATION`, `SHIPPING_STATES` | values | The seed data. |
+| `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 (`--token-ttl`); port 8802. |
+
+Part of [mockingbird](https://github.com/crvouga/mockingbird).