Portal Agent

Stateful mock of our eRx portal agent (the LifeFile / VPI browser runner) for test suites: the job endpoint the backend posts fulfilment jobs to, a job store, and the callback the agent posts back to POST /prescriptions/webhooks/portal-agent with x-internal-key. Jobs finish only when a test says so (POST /__admin/jobs/:id/complete), so the eRx portal path runs without a browser, a pharmacy portal or provider credentials.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from our backend's wire shapes (portal-agent-fulfillment.base.ts, the LifeFile and VPI adapters' buildPayload, and the pharmacy webhook controller). The portal agent is our own service, so there is no vendor spec.

#Install

npm install -D @crvouga/mockingbird-service-portal-agent

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

#Usage

Point the app at the mock and give both sides the same keys:

npx mockingbird-portal-agent serve --port 8804 \
  --webhook-url http://127.0.0.1:3000/prescriptions/webhooks/portal-agent \
  --callback-key "$ERX_PORTAL_AGENT_CALLBACK_KEY" \
  --api-key "$ERX_PORTAL_AGENT_API_KEY"

import { createRuntime } from "@crvouga/mockingbird-service-portal-agent"

const agent = createRuntime({
  webhooks: { url: "http://127.0.0.1:3000/prescriptions/webhooks/portal-agent", secret: "cb-key" },
})
const post = (path: string, body: unknown) =>
  agent.fetch(
    new Request(`http://portal-agent.test${path}`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(body),
    }),
  )

// …the app posts POST /rx/portal-fulfillment/jobs and gets {status: "accepted", agentJobId}…
const [job] = agent.instance().jobs()
if (job) {
  await post(`/__admin/jobs/${job.agentJobId}/complete`, { status: "submitted" })
  await post(`/__admin/jobs/${job.agentJobId}/complete`, {
    status: "submitted",
    fulfillmentStatus: "shipped",
    trackingNumber: "1Z999",
  })
}

#Routes

Every answer follows the strict field rules our parser enforces: status is one of the five, every optional field is a string, accepted carries agentJobId, submitted carries an order id, draft_ready carries portalDraftOrderId. Presets break each rule on purpose.

#Callbacks

POST /__admin/jobs/:id/complete {status, fulfillmentStatus?, portalOrderId?, portalDraftOrderId?, confirmationNumber?, trackingNumber?, trackingCarrier?, message?, needsReviewReason?, errorCode?, errorDetail?, screenshotArtifactId?} posts {status, paymentId, prescriptionOrderItemId, pharmacyId, agentJobId, …} (plus portalOrderId/confirmationNumber/submittedAt for submitted, a portalDraftOrderId for draft_ready) with header x-internal-key: <callback key> (plain equality, as our controller checks). The route first runs our controller's isPortalAgentFulfillmentCallback rules and answers 400 for a callback the receiver would reject; add ?force=1 to send it anyway (negative tests). Note: a job for pharmacyId: "pharmetika" echoes that id, which our receiver refuses (it admits only lifefile and vpi).

Non-2xx answers are retried (immediately, 5 s, 5 min, 30 min, 2 h). GET /__admin/webhooks, /webhooks/events, POST /webhooks/flush, /webhooks/:id/replay and PUT /__admin/webhook-endpoints work as in every Mockingbird service.

#Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets): respond_submitted, respond_draft_ready, respond_needs_review, respond_error, accepted_without_job_id, submitted_without_order_id, draft_ready_without_draft_id, non_string_field (each rejected by our parser as "an invalid success response"), http_500 (500 with errorDetail), timeout (the connection drops), slow (answers after 21 s, past our 20 s timeout; or post your own {latencyMs} rule), callback_duplicate, callback_reorder, callback_drop.

#Namespaces

x-mockingbird-namespace, a /ns/<name> prefix on ERX_PORTAL_AGENT_API_URL, or by bearer key: PUT /__admin/credentials {"credentials": {"<ERX_PORTAL_AGENT_API_KEY>": "<namespace>"}}.

#Journal and secrets

The job payload carries LifeFile/VPI portal credentials and patient/prescriber PHI. None of it is stored: the job store keeps metadata only, and the request journal records operation, status and ids, never bodies.

#Deliberately not modelled

• The browser automation itself: no portal is driven, nothing is actually submitted, and allowSubmit / stageForProviderSignature are recorded but do not change the answer (choose the outcome with respondWith, presets or the complete route).
• Automatic completion: jobs finish only through POST /__admin/jobs/:id/complete.
• Screenshot artifacts: screenshotArtifactId is passed through when given, never produced.
• Portal credential verification: any well-formed credentials are accepted.

#API

Part of mockingbird.