Junction

Stateful mock of the Junction (formerly Vital) API: users (/v2/user), the lab-testing catalog, lab orders (create, cancel, simulate, results, requisitions), at-home phlebotomy and patient-service-center (PSC) scheduling, and the labtest.order.* / labtest.appointment.updated webhooks. All 40 operations in the vendored OpenAPI subset are served, and behaviour is checked by differential property tests against the Junction sandbox.

Use it to take Junction off your suite's critical path: no sandbox key, no shared 50-user sandbox cap (the mock enforces no sandbox limit unless a test asks for one), no cross-suite interference. Serve it as a local origin with one command, or run it in-process.

npx mockingbird-junction serve   # http://127.0.0.1:8787, recorded sandbox corpus loaded

• Operation coverage: SUPPORT.md
• Drop-in readiness and the sandbox quirks the mock mirrors: docs/drop-in.md
• Behaviour notes: docs/behavior.md
• What the mock does not model: below. Read it before trusting a green suite.

#Install

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

ESM only; Node >= 22 or Bun >= 1.2 (CommonJS callers on Node >= 22.12 can require() it). No native dependencies: state lives in an in-memory SQLite engine written in TypeScript, bundled in.

#Usage

#mockingbird-junction serve

npx mockingbird-junction serve --port 8787
npx mockingbird-junction serve --corpus ./test/junction-corpus.json --lab-accounts ./test/lab-accounts.json
npx mockingbird-junction serve --webhook-url http://127.0.0.1:3100/webhooks/junction --webhook-secret whsec_...
npx mockingbird-junction serve --help

At startup it prints the listen address, the loaded corpus (its version label, observation, ZIP, lab-test and lab-account counts, recording date and source), the geo mode, the team id, the lab-account count, which sandbox limits are on (normally none), the identity mode, and whether webhook delivery is on.

#Many services from one config

Any Mockingbird service's CLI can boot every service in a config file, so a stack adds a config entry per vendor instead of a wrapper process per vendor. Each service named must be installed (junction loads @crvouga/mockingbird-service-junction).

{
  "log": "json",
  "services": {
    "junction": {
      "port": 8787,
      "adminKey": "local-admin",
      "options": { "corpus": "./test/junction-corpus.json", "webhook-url": "http://127.0.0.1:3100/webhooks/junction" }
    },
    "stripe": { "port": 12111 }
  }
}

npx mockingbird-junction serve --config mockingbird.json

options takes the service's own serve flags by long name.

#createServer (Node)

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

const server = await createServer() // shipped corpus, any free port
const health = await fetch(`${server.url}/health`)
console.log(health.status) // 200

// Point the Vital SDK (or your backend's Junction base URL) at server.url, then:
await server.close()

createServer(options) takes every createRuntime option plus port (default 0), host (default 127.0.0.1) and corpus ("default", "none", a file path or a loaded corpus). The result has url, port, runtime and close().

#createRuntime (any Fetch server)

createRuntime is the whole served mock — health, admin, namespaces, clock, faults, metrics — as a single runtime-neutral fetch(request). Hand it to Bun.serve, a Worker, or call it directly:

import { createRuntime } from "@crvouga/mockingbird-service-junction"
import { defaultCorpus } from "@crvouga/mockingbird-service-junction/corpus"

const junction = createRuntime({ corpus: defaultCorpus })
const as = (worker: string) => ({
  "x-vital-api-key": "sk_us_mockingbird",
  "x-mockingbird-namespace": worker, // isolates this worker's data
  "content-type": "application/json",
})

await junction.fetch(
  new Request("http://junction.local/v2/user", {
    method: "POST",
    headers: as("worker-1"),
    body: JSON.stringify({ client_user_id: "patient-1" }),
  }),
)
const other = await junction.fetch(new Request("http://junction.local/v2/user", { headers: as("worker-2") }))
console.log(await other.json()) // worker-2 sees none of worker-1's users

await junction.reset("worker-1") // or junction.reset("*") for every namespace

#In-process (inject fetch)

import { JunctionAPI } from "@crvouga/mockingbird-service-junction"

const junction = new JunctionAPI({ now: () => Date.UTC(2030, 0, 1) })
const headers = { "x-vital-api-key": "sk_us_mockingbird", "content-type": "application/json" }

const call = async (method: string, path: string, body?: unknown) => {
  const response = await junction.fetch(
    new Request(`https://api.sandbox.tryvital.io${path}`, {
      method,
      headers,
      body: body === undefined ? undefined : JSON.stringify(body),
    }),
  )
  return { status: response.status, json: (await response.json()) as Record<string, unknown> }
}

const user = await call("POST", "/v2/user", { client_user_id: "app-user-1" })
const userId = String(user.json.user_id)

const catalog = await call("GET", "/v3/lab_test")
const labTests = catalog.json.data as { id: string; method: string }[]
const testkit = labTests.find((test) => test.method === "testkit")
if (testkit === undefined) throw new Error("default catalog has a testkit test")

const order = await call("POST", "/v3/order", {
  user_id: userId,
  patient_details: {
    first_name: "Ada",
    last_name: "Lovelace",
    dob: "1990-01-01",
    gender: "female",
    phone_number: "+14155551234",
    email: "ada@example.com",
  },
  patient_address: {
    first_line: "1 N Central Ave",
    city: "Phoenix",
    state: "AZ",
    zip: "85004",
    country: "US",
  },
  order_set: { lab_test_ids: [testkit.id] },
})
console.log(order.status, (order.json.order as { id: string }).id) // 200 "<uuid>"

// Every event the mock published, oldest first:
console.log(junction.webhookEvents().map((event) => event.event_type)) // ["labtest.order.created"]

now (milliseconds) drives created_on/updated_at fields, webhook timestamps, and when delayed simulations (POST /v3/order/{id}/test?final_status=completed&delay=<seconds>) become due; the delayed transition is applied on the next GET /v3/order/{id} whose now is past the due time.

#Pointing @tryvital/vital-node at it

The official SDK takes the base URL as environment (this is how the package's SDK drop-in test constructs it):

import { VitalClient } from "@tryvital/vital-node"

const client = new VitalClient({ apiKey: "sk_us_mockingbird", environment: baseUrl })
const user = await client.user.create({ clientUserId: "app-user-1" })

If your app guards Junction hosts with an allowlist, allow 127.0.0.1 / localhost for tests while keeping the production and sandbox guards intact.

#The service contract

Every Mockingbird service answers the same control surface, outside the vendor's auth gate:

• GET /health — unauthenticated readiness probe: { "status": "ok", "service": "junction", "corpus": "<label>", "geo": "corpus", … }.
• /__admin/* — the control plane. Open by default; with --admin-key / adminKey it requires x-mockingbird-admin-key, which is separate from any vendor key. Admin errors have one shape, { "error": { "type": "mockingbird_admin", "message": "…" } }, so they can never be confused with a Junction error. GET /__admin lists every route.
• x-mockingbird-namespace: <name> — isolates a request's data ([A-Za-z0-9_.-]{1,64}). Each namespace is a separate team over one shared database, so parallel workers share one process without seeing each other. The corpus is shared read-only; creating a namespace is cheap. Admin routes take the namespace from ?namespace=, then the header, then default. Configuration set through the admin API (lab accounts, limits, identity, geo) belongs to one namespace and survives that namespace's POST /__admin/reset; data does not.
• x-mockingbird: junction@<version>; ns=<namespace> — on every response: vendor answers, errors, faults, admin and health. Junction never sends it, so it tells the mock from the vendor (see Is this the mock?).

GET /__admin/metrics → unmatched counts requests to paths the contract does not have. It is how a new SDK call shows up — as a count — before it fails a suite as a 404.

#Corpus

Provider-owned inventory — area serviceability, PSC site lists, the lab catalog, labs, lab accounts — cannot be synthesized faithfully. A corpus is an exact recording of those parameter-stable reads, and the mock answers them byte for byte.

The shipped corpus (defaultCorpus, and what serve loads unless told otherwise) was recorded from the Junction sandbox. It covers area and PSC serviceability for 57 ZIPs across the US, the PSC labs those ZIPs reach, and the recording team's catalog. The catalog and lab accounts belong to the recording team: lab-test ids are per team, so your product's ids will not be in it. For your catalog and your lab accounts, record your own team and commit the file:

npx mockingbird-junction corpus pull --real-key "$JUNCTION_SANDBOX_KEY" --out test/junction-corpus.json
npx mockingbird-junction corpus pull --real-key "$JUNCTION_SANDBOX_KEY" --base test/junction-corpus.json \
  --zip 10001,94105 --coverage-only --out test/junction-corpus.json   # add ZIPs to it
npx mockingbird-junction corpus diff test/junction-corpus.json /tmp/fresh.json   # exit 1 when they differ

corpus pull only issues GETs, refuses non-sandbox keys (sk_us_… / sk_eu_…) unless given --allow-any-key, and stamps the file with a SHA-256 fingerprint of its content (not its recording time), so re-pulling unchanged data yields the same fingerprint. Availability is never recorded: its slot dates and single-use booking_keys cannot be replayed, so it always comes from the deterministic generator.

#Geo: corpus or synthetic

With a corpus loaded, serviceability reads (area/info, psc/info, phlebotomy and PSC availability) answer only for ZIPs the corpus covers. Any other well-formed ZIP gets:

{
  "detail": {
    "error_type": "MOCKINGBIRD_UNKNOWN_ZIP",
    "error_message": "ZIP 00501 is not in the loaded Junction corpus (57 ZIPs covered). Record it with `mockingbird-junction corpus pull --zip 00501`, or serve with --geo synthetic to invent coverage.",
    "zip_code": "00501",
    "corpus": "v1-2026-09-18-HqFDuEAuhkwD"
  }
}

with status 424, which Junction never sends and HTTP clients do not retry: a fixture gap fails loudly instead of silently disagreeing with production. A malformed ZIP still gets Junction's own 422. --geo synthetic (the default without a corpus) invents plausible, deterministic coverage instead — right for property tests that walk random ZIPs, wrong for a suite standing in for production.

#Lab accounts

create_order routes, accepts and rejects lab_account_id against the team's lab accounts, following Junction's documented rules: an explicit id must exist, be linked to the team, belong to the ordered lab and be active; with no id, one active account for the lab is selected, several are an error, and a lab with none falls back to Junction's platform account. The billing type must be allowed in the patient's state by the account's allowed_billing.

The accounts come from, in order: labAccounts / --lab-accounts, else the corpus (a pulled corpus carries your team's real accounts), else built-in fixtures. Configure them as ClientFacingLabAccounts, with states as shorthand for client-bill states:

import { createRuntime, US_STATES } from "@crvouga/mockingbird-service-junction"

const junction = createRuntime({
  labAccounts: [
    { id: "acct-bioref-nynj", lab: "bioreference", states: ["NY", "NJ"] },
    {
      id: "acct-labcorp-47",
      lab: "labcorp",
      states: US_STATES.filter((state) => !["NY", "NJ", "RI"].includes(state)),
    },
    { id: "acct-quest", lab: "quest", delegated_flow: "order_delegated" },
  ],
})
console.log(junction.instance().labAccounts().length) // 3

Rejections keep Junction's body shape, 400 {"detail": "Lab account is not associated with lab labcorp"}. delegated_flow is stored and listed, but see not modelled.

Availability reads that take a lab_account_id (GET /v3/order/area/info) check it against the same live list, so an id create_order accepts is never a 404 there.

#Changing accounts at runtime

Each namespace has its own layout, kept across its own reset. Change one account at a time, or replace them all:

curl -X POST  localhost:8787/__admin/lab-accounts/presets/bioreference_ny_nj_delegated
curl -X PATCH localhost:8787/__admin/lab-accounts/$ID -d '{"status": "suspended"}'
curl -X POST  localhost:8787/__admin/lab-accounts -d '{"id": "…", "lab": "quest", "states": ["AZ"]}'
curl -X DELETE localhost:8787/__admin/lab-accounts/$ID
curl -X PUT   localhost:8787/__admin/lab-accounts -d '{"presets": ["quest_platform"], "accounts": []}'

A bad field is a 400 in the admin shape naming it, e.g. lab account x: states: ZZ is not a US state code. --lab-accounts and the labAccounts option take the same layout, so a stack can declare it at boot with no admin call:

{ "presets": ["bioreference_ny_nj_delegated", { "name": "quest_platform", "id": "…" }], "accounts": [] }

#Lab-account presets

Named after what they model; ids are deterministicUuid("junction:lab-account:<name>") unless given. Where a preset copies an account recorded from a real BioReference-linked sandbox team (2026-09-21), its billing states are the recording's. PLATFORM_ACCOUNT_STATES is every state but NJ, NY and RI (47).

Every preset is status: "active" unless named suspended_*. GET /__admin/lab-accounts/presets returns the full records.

#Team identity

The mock answers as one team: team_id on users, orders and webhooks, and the team that team_id_allowlist is checked against. It is, in order: teamId / --team-id, the team a version-2 corpus recorded (corpus pull reads it from a listed user, else from the accounts' allowlists), else the fixed MOCK_TEAM_ID. GET /__admin/team reports it.

A version-2 corpus keeps each account's allowlist verbatim, so an account the real team is not linked to answers 400 {"detail": "Lab account is not linked to your team"} exactly as it does live. A version-1 corpus (no teamId) still loads and behaves as 0.2.0 did: every recorded account is also linked to the mock team.

Open question — empty allowlists. Junction's own Quest, Labcorp and BioReference accounts carry team_id_allowlist: [], and a real team's listing returns them, so the mock lists them and treats them as linked. Whether ordering through one — by explicit id, or when it is one of several active accounts for a lab with the id omitted — behaves the same live is not verified. verify --orders checks it whenever the corpus has such an account; until a run records the answer, a suite that depends on it should run against the sandbox too.

#Sandbox limits

The mock exists to escape the sandbox's restrictions, so it enforces none of them unless a test asks — this is a tested guarantee (500 users in a loop all succeed), not an accident.

PUT /__admin/limits merges (null lifts a numeric limit) and is per namespace; GET /__admin/limits returns the effective values. For a one-off failure instead of a standing limit, the sandbox_user_quota fault preset is still there.

#Fixtures and identity

A suite often needs state the public API cannot build: database fixtures that already carry real Junction user_ids, or an order already in some status. Insert them directly:

curl -X POST localhost:8787/__admin/users -d '{"user_id": "3f0c…", "client_user_id": "patient-1"}'
curl -X POST localhost:8787/__admin/orders -d '{"user_id": "3f0c…", "lab_test_id": "…", "status": "completed"}'
curl -X POST localhost:8787/__admin/import -d @test/junction-fixtures.json

• Users take user_id?, client_user_id, created_on?, fallback_time_zone?, fallback_birth_date?, ingestion_start?, ingestion_end?. A duplicate user_id or client_user_id is a 409; POST /__admin/users/bulk inserts all or none.
• Orders take order_id?, user_id, lab_test_id, lab_account_id?, status? (any transition target), collection_method?, patient_details?, patient_address?, billing_type?, created_at? and result_fixture? (as PUT /__admin/results/{id} takes it). Request validation is skipped; references are not — the user and lab test must exist (404 otherwise).
• Inserted records go through the same builders as create_user / create_order, so every read path (GET /v2/user/{id}, resolve by client_user_id, GET /v3/order/{id}, GET /v3/orders?user_id=) sees them as API-created. Default timestamps read the mock clock.
• No webhook fires unless the body has "emitWebhooks": true: fixtures should not trigger backend side effects.
• fixtures / --fixtures <file> loads { "users": [...], "orders": [...] } into every namespace at creation and again on each reset.

For flow suites that do not care about Junction identity, identity: "adopt-users" (or --identity adopt-users, or PUT /__admin/identity {"mode": "adopt-users"} per namespace) creates an unknown, well-formed user_id on first use — in create_order and GET /v3/orders?user_id= — and the request proceeds. The journal marks the request adopted: true. Orders are never adopted: an unknown order id always 404s, because inventing an order hides real bugs. The default, strict, is Junction's own behaviour.

#Is this the mock?

A mock 404 and a sandbox 404 are byte-identical, which is how a backend half-pointed at the sandbox goes unnoticed. Three things make it visible:

• x-mockingbird on every response. Assert on it in a test helper:

  import { expect } from "vitest"
  
  /** Wrap the fetch your Junction client uses; fails any call that did not reach the mock. */
  export const mockOnlyFetch =
    (inner: typeof fetch = fetch): typeof fetch =>
    async (input, init) => {
      const response = await inner(input, init)
      expect(response.headers.get("x-mockingbird"), `${String(input)} did not reach the Junction mock`).toMatch(
        /^junction@/,
      )
      return response
    }

• The request journal. Each namespace keeps its last 1000 requests (--journal-size, journalSize): operation id, method, path, status, duration, fault id, the user / order / lab-account ids it touched, and when (mock clock). GET /__admin/requests?operationId=create_order_v3_order_post proves an order was placed here; an empty answer proves it was not. Never bodies.

• Miss headers on 404s. A missing user or order keeps Junction's body byte for byte and adds x-mockingbird-miss: order <id> (or user <id>, user client:<client_user_id>) and x-mockingbird-known: users=<n> orders=<n>.

--log-requests prints the same fields as one JSON line per request.

#Order control

simulate_order (POST /v3/order/{id}/test) behaves like the sandbox's, including its stepwise rules. For direct control, the admin API moves an order straight to a status, recording the same event, dates and appointment cascade, and publishing the same webhook, a real transition does:

curl -X POST localhost:8787/__admin/orders/$ORDER/transition -d '{"to": "collected"}'
curl -X POST localhost:8787/__admin/orders/$ORDER/transition -d '{"to": "completed", "result": "critical"}'
curl -X POST localhost:8787/__admin/orders/$ORDER/transition -d '{"to": "cancelled.testkit.do_not_process"}'

to is a full status (completed.testkit.completed), a <phase>.<event> pair, or a name that maps onto the contract's own status for the order's collection method:

A name with no real status for the method (collected for a walk-in test) is refused with the valid choices, never approximated. result picks a named result — normal, abnormal, critical, missing_results — which steers the generator so the payload keeps Junction's exact shape. For an exact payload, PUT /__admin/results/{id} with { "results": [...], "missing_results": null, "interpretation": "critical", "pdf_base64": "…" }.

There is no isTestCancelled in Junction's contract; cancelling produces the vendor's cancelled.<method>.cancelled event and webhook, which is what a consumer derives that flag from.

Time. Every timestamp reads the runtime clock. POST /__admin/clock {"advance": "2h"} makes delayed simulations (?delay=<seconds>) due and moves appointment windows, with no sleeping.

#Faults and error shapes

Error bodies the mock reproduces byte for byte, checked against the sandbox by verify and the parity suite (ORDER_NOT_FOUND holds the unknown-order text per operation id):

Faults reproduce the sandbox's failure modes on demand, for retry paths and error handling:

import { createRuntime, FAULT_PRESETS } from "@crvouga/mockingbird-service-junction"

const junction = createRuntime()
junction.faults.add({ ...FAULT_PRESETS.sandbox_user_quota, id: "quota", count: 1 }) // next create_user only
junction.faults.add({ id: "flaky-orders", operationId: "create_order_v3_order_post", status: 503, rate: 0.25 })

A rule matches on operationId, method, pathPrefix and namespace (all optional), fires count times or forever, for a rate of matching requests (seeded, so a run replays identically), after an optional delayMs. A rule added through the admin API defaults to the calling namespace, so one worker's injected failure never lands on another's request; one added in-process, as above, applies to every namespace unless given a namespace. Over HTTP: POST /__admin/faults with the same fields, or POST /__admin/faults/presets/sandbox_user_quota.

#Webhooks

With webhooks / --webhook-url, every event is delivered signed, with retries:

• Standard Svix signatures: svix-id, svix-timestamp, and svix-signature: v1,<base64 HMAC-SHA256 of "<svix-id>.<svix-timestamp>.<body>">, keyed by the base64 part of whsec_…. The official svix verifier, and a receiver written for real Junction, accept it unchanged. (Signing "<timestamp>.<body>" without the message id, as this package's own server script did before, is not Svix-compatible.)
• Timestamps are wall-clock even when the mock clock is moved, because receivers reject timestamps outside a few minutes of their own clock.
• Any 2xx is delivered; anything else is retried on Svix's schedule (immediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h) or retryDelaysMs. POST /__admin/webhooks/flush runs pending retries now; POST /__admin/webhooks/{id}/replay redelivers one message.

import { createRuntime, verifySvix } from "@crvouga/mockingbird-service-junction"

const secret = "whsec_bW9ja2luZ2JpcmQtdGVzdC1zZWNyZXQ="
const junction = createRuntime({
  webhooks: { url: "http://127.0.0.1:3100/webhooks/junction", secret, retryDelaysMs: [0, 500, 2000] },
})

// In a test receiver:
const accept = async (request: Request) =>
  verifySvix(
    secret,
    {
      "svix-id": request.headers.get("svix-id") ?? "",
      "svix-timestamp": request.headers.get("svix-timestamp") ?? "",
      "svix-signature": request.headers.get("svix-signature") ?? "",
    },
    await request.text(),
  )
console.log(typeof accept, junction.webhooks?.deliveries().length) // "function" 0

#Verify

verify is the fidelity guarantee: it runs the same requests against real Junction and the mock and reports every divergence.

npx mockingbird-junction verify --real-key "$JUNCTION_SANDBOX_KEY" --corpus test/junction-corpus.json
npx mockingbird-junction verify --real-key "$JUNCTION_SANDBOX_KEY" --orders --sample 50 --json

• Drift: re-fetches each recorded observation (or --sample n of them) and reports any that no longer match production — the signal to re-pull.
• Scenario: creates a user, reads it back, provokes the documented 404s (including every order-scoped operation against a random unknown order), reads the catalog (paged and bare) and a covered ZIP's serviceability, and deletes the user; with --orders, also places, reads and cancels an order for the corpus's first lab test, and — when the corpus has an account with an empty team_id_allowlist — orders through it with and without its id. Status codes must match; bodies must match in shape, and byte for byte for the documented error bodies.

It exits 1 on any divergence. The scenario always deletes its user (and cancels its order), because it runs against the same capped sandbox the mock exists to relieve. verifyAgainstReal is the same check as a function. This repo runs it in CI against the Junction sandbox.

#Determinism

With a fixed clock (clock / POST /__admin/clock {"set": …, "freeze": true}) and seed, a run replays exactly. Stable across runs: user ids, order ids, event ids, sample ids, booking keys and webhook message ids (derived from sequence numbers), timestamps (from the clock), generated availability, and which requests a partial-rate fault hits. Wall-clock by design: webhook svix-timestamp, /health uptime, and request log durations.

#What is and is not modelled

A mock that is silent about its gaps is how a green suite starts lying. Specifically:

• Corpus-backed (byte-exact): area and PSC serviceability for covered ZIPs; the catalog, labs, expected results and lab accounts of the team the corpus was recorded from.
• Synthetic (deterministic, shape-faithful, values invented): availability slots and booking keys; results (biomarker lines and PDFs) unless a fixture is installed; requisition PDFs; coverage for any ZIP in --geo synthetic mode.
• Not modelled:
  • delegated_flow-specific ordering. Accounts carry the field and orders follow the documented selection and billing rules above, but any additional behaviour Junction applies to delegated accounts is not reproduced. Run verify --orders with your team's corpus to check what you rely on.
  • Rate limits and outages, except when injected as faults or switched on as limits.
  • Whether an account with an empty team_id_allowlist can be ordered through (see Team identity); the mock assumes it can.
  • Adopted users (adopt-users) have client_user_id equal to their user_id; nothing in Junction corresponds to adoption.
  • Real 429 / 5xx bodies: the presets are plausible, not recorded.
  • Phlebotomy availability breadth: the sandbox serves it only for 85004; the mock generates slots for any covered ZIP.
  • Webhook retry jitter across a snapshot restore (the jitter stream is not part of a snapshot).
  • Operations outside the vendored OpenAPI subset: they return 404 and are counted as unmatched in /__admin/metrics.

#API

Main entry (@crvouga/mockingbird-service-junction, runtime-neutral):

./server (Node): createServer(options?) => Promise<JunctionServer>, serveTarget (what serve and serve --config use), loadCorpus(source), DEFAULT_PORT (8787). ./corpus: defaultCorpus.

JunctionRuntime (from createRuntime) members: fetch, instance(namespace?), namespaces(), reset(namespace? | "*"), snapshot(namespace?), restore(snapshot, namespace?), clock (now, set, advance, freeze, unfreeze, reset, state), faults (add, list, remove, clear), metrics (report, reset), journal (list, clear, size), webhooks (deliveries, replay, flush, idle, clear), sqlite, rng.

JunctionAPI members:

Options and types:

type JunctionAPIOptions = {
  sqlite?: SqliteClient          // share one client across services; default: fresh in-memory DB
  namespace?: string             // storage namespace; default "junction"
  now?: () => number             // clock in ms; default Date.now
  corpus?: SealedCorpus          // installed now and on every reset()
  geo?: "corpus" | "synthetic"   // default "corpus" with a corpus, else "synthetic"
  labAccounts?: LabAccountInput[] | { presets?: (string | { name; id? })[]; accounts?: LabAccountInput[] }
  teamId?: string                // default: the corpus's recorded team, else MOCK_TEAM_ID
  limits?: { maxUsers?: number | null; simulateRequiresSandbox?: boolean; rateLimitPerSecond?: number | null }
  identity?: "strict" | "adopt-users"  // default "strict"
  fixtures?: { users?: UserFixture[]; orders?: OrderFixture[] }  // loaded now and on every reset()
  onWebhook?: WebhookPublisher   // called with every recorded event
  webhook?: JunctionWebhookOptions
}
type LabAccountInput = { id; lab; status?; delegated_flow?; account_name?; provider_account_id?; org_id?;
  business_units?; default_clinical_notes?; allowed_billing?: Record<billingType, State[]>; states?: State[];
  team_id_allowlist? }
type WebhookEndpoint = { url; secret: "whsec_…"; retryDelaysMs?: number[]; timeoutMs?; headers?; fetch? }
type ResultFixture = { name; results?: unknown[]; missing_results?: unknown[] | null; interpretation?; pdf_base64? }
type FaultRule = { id; operationId?; method?; pathPrefix?; status; body?; headers?; count?; rate?; delayMs? }
type JunctionWebhookOptions = { seed?: number; jitterRatio?: number /* 0..1, default 0.1 */; timeoutMs?: number }
type JunctionWebhookEvent = {
  event_type: "labtest.order.created" | "labtest.order.updated" | "labtest.appointment.updated"
  data: Record<string, unknown>; team_id: string; user_id: string; client_user_id: string
}
type SealedCorpus = { version: 1 | 2; recordedAt; source; teamId?; fingerprint?; observations; catalog: { labTests; labs; expectedResults }; labAccounts }
type SeedSource = { fetch: (request: Request) => Promise<Response>; baseUrl: string; headers: Record<string, string> }
type OperationId / SupportedOperationId  // string unions of operationIds / supportedOperationIds

Seeding from the real sandbox (needs network and a real key):

import { JunctionAPI } from "@crvouga/mockingbird-service-junction"

const junction = new JunctionAPI()
const report = await junction.seedFrom({
  fetch: (request) => globalThis.fetch(request),
  baseUrl: "https://api.sandbox.tryvital.io",
  headers: { "x-vital-api-key": process.env.JUNCTION_API_KEY ?? "" },
})
console.log(report.users, report.orders)

#Development

For contributors to the mockingbird repo only.

bun test                                   # offline suites, incl. scheduling state space
bun test junction.runtime.property.test.ts # service contract, corpus, lab accounts, faults, webhooks, verify
bun test junction.sdk.property.test.ts     # drives the served mock through @tryvital/vital-node

bun run mock:serve                         # env-configured `serve`: HOST, PORT, MOCKINGBIRD_JUNCTION_CORPUS,
                                           # MOCKINGBIRD_JUNCTION_WEBHOOK_URL / _SECRET / _SCOPE
bun run corpus:record -- --force           # re-record the shipped corpus/sandbox-sealed.json (Vault key)
bun run verify -- --real-key "$KEY"        # `mockingbird-junction verify` from source

Live parity (primary proof is seedParity: warmup N on the sandbox, seedFrom, then lockstep M):

bun run parity                                   # default mode=seed against api.sandbox.tryvital.io
bun run parity -- --warmup 15 --compare 30 --runs 25
bun run parity -- --mode=empty                   # legacy empty-start differential

Webhook parity needs a public receiver; see docs/webhook-parity.md.

Part of mockingbird — agent integration guide: README · llms.txt · report an issue or request a feature.