@crvouga/mockingbird-service-easypost

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the EasyPost trackers API for test suites: POST /v2/trackers (create or re-use a tracker for a tracking code), GET /v2/trackers/{id} and GET /v2/trackers. EasyPost's documented test tracking codes answer their fixed statuses, and any other code moves through admin transitions, so the genomics admin's shipping-leg states can be driven deterministically.

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is trimmed from EasyPost's published reference to what our tracking lookup (packages/lib/src/shipment-tracking-status/easypost-client.ts) calls.

Install

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

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

Usage

The app hardcodes https://api.easypost.com/v2/trackers (seam G-Y1: add a base-URL env to easypost-client.ts). Point that base URL at the emulator; EASYPOST_API_KEY can be any value (--api-key restricts it).

npx mockingbird-easypost serve --port 8818

import EasyPostClient from "@easypost/api"
import { createServer } from "@crvouga/mockingbird-service-easypost/server"

const server = await createServer()

// Test setup: seed a status before the app looks the code up (or move an existing tracker).
await fetch(`${server.url}/__admin/trackers/1Z999AA10123456784/transition`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ status: "out_for_delivery" }),
})

// The EasyPost SDK your application already uses. Only its base URL changes.
// @ts-ignore @easypost/api 8.9.0 types its ESM default export as CommonJS (NodeNext only).
const easypost = new EasyPostClient("EZTK_test", { baseUrl: `${server.url}/v2/` })
const tracker = await easypost.Tracker.create({ tracking_code: "1Z999AA10123456784", carrier: "UPS" })
console.log(tracker.id, tracker.status, tracker.carrier) // trk_… out_for_delivery UPS

await server.close()

Routes

Every error is EasyPost's envelope {error: {code, message, errors}}; our client reads error.message. A missing key is 401 APIKEY.REQUIRED, a key outside apiKeys 401 APIKEY.INACTIVE. Keys starting EZAK are production mode (test codes are not special there); anything else is test mode.

Test tracking codes (test mode, carrier USPS): EZ1000000001 pre_transit, EZ2000000002 in_transit, EZ3000000003 out_for_delivery, EZ4000000004 delivered, EZ5000000005 return_to_sender, EZ6000000006 failure, EZ7000000007 unknown. Any other code starts unknown / unknown.

Admin (beyond the standard contract)

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}): rate_limited (429), server_error (500), invalid_api_key (401), gateway_html (502 HTML, our client falls back to EasyPost tracker request failed (502)), connection_drop (fetch rejects; our batch lookup records unknown and warns), slow (5 s).

Namespaces

x-mockingbird-namespace, a /__admin/ns/<name> prefix on the base URL, or by API key: PUT /__admin/credentials {"credentials": {"<EASYPOST_API_KEY>": "<namespace>"}}.

Deliberately not modelled

• Tracker webhooks (tracker.updated, X-Hmac-Signature): our app has no receiver.
• Carrier lookups: a real-shaped code never moves on its own; statuses come from admin transitions.
• Shipments, rates, labels, addresses, batches and every other EasyPost resource.
• Pagination cursors (before_id / after_id) on the list: page_size and has_more only.

API

Part of mockingbird.