@emulates/easypost 0.0.0-stage → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog — @emulates/easypost
+
+## 3.0.0 (2026-10-07)
+
+### ⚠️ Breaking changes
+
+- point the repo at crvouga/emulates ([cdb5e53](https://github.com/crvouga/emulates/commit/cdb5e536ed8c1f52345e3984f089001c25fdb08a))
+
+### Fixes and improvements
+
+- format the emulates records query ([8698872](https://github.com/crvouga/emulates/commit/8698872509d06002be5a8fcdc85d79f8462320c3))
+
+### Dependencies
+
+- `@emulates/sqlite`
+
+## 2.3.1 (2026-10-06)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @emulates/easypost discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@emulates/easypost/`; no repository checkout is needed to discover the emulator's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `emulates.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **Trackers**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- easypost`.
+- Evidence model: Run from an Emulates checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Emulates
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-emulates-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/emulates/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual emulator result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `easypost`.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @emulates/easypost
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Part of [Emulates](https://github.com/crvouga/emulates): high-fidelity, in-process emulators for APIs and databases.
+
+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](https://github.com/crvouga/emulates/blob/main/packages/service/easypost/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
+
+```bash
+npm install -D @emulates/easypost
+```
+
+ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with
+`npx emulates-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).
+
+```bash
+npx emulates-easypost serve --port 8818
+```
+
+```ts
+import { createRuntime } from "@emulates/easypost"
+
+const easypost = createRuntime()
+const auth = { authorization: `Basic ${btoa("EZTK_test:")}` }
+
+// Seed a status before the app looks the code up (or move an existing tracker).
+await easypost.fetch(
+  new Request("http://easypost.test/__admin/trackers/1Z999AA10123456784/transition", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ status: "out_for_delivery" }),
+  }),
+)
+const tracker = await easypost.fetch(
+  new Request("http://easypost.test/v2/trackers", {
+    method: "POST",
+    headers: { ...auth, "content-type": "application/x-www-form-urlencoded" },
+    body: "tracker[tracking_code]=1Z999AA10123456784&tracker[carrier]=UPS",
+  }),
+)
+// → 201 {id: "trk_…", status: "out_for_delivery", carrier: "UPS", status_detail: "out_for_delivery", …}
+```
+
+### Routes
+
+| Route | Behaviour |
+| --- | --- |
+| `POST /v2/trackers` | Form (`tracker[tracking_code]`, `tracker[carrier]`) or JSON (`{tracker: {…}}`), `Authorization: Basic base64(key:)`. Answers 201 with the Tracker (`id`, `object`, `mode`, `tracking_code`, `status`, `status_detail`, `carrier`, `tracking_details`, `public_url`, `signed_by`, `est_delivery_date`, …). The same code and carrier re-use the existing tracker, as EasyPost does. Carrier: the given one (`DHL` is normalised to `DHLExpress`), else detected from the code's shape, else `USPS`. A blank code is 422 `PARAMETER.REQUIRED`; a bad carrier 422 `PARAMETER.INVALID`. |
+| `GET /v2/trackers/{id}` | The tracker, or 404 `NOT_FOUND`. |
+| `GET /v2/trackers` | `?tracking_code=&carrier=&page_size=` → `{trackers, has_more}`, newest first. |
+
+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)
+
+| Route | Effect |
+| --- | --- |
+| `POST /__admin/trackers/:idOrCode/transition` | `{status, status_detail?, message?, signed_by?, carrier?}`. Moves the tracker (by id or tracking code) and appends a tracking detail. With no tracker for that code yet, registers one first, so the app's next lookup sees the status. `status` is one of `unknown`, `pre_transit`, `in_transit`, `out_for_delivery`, `delivered`, `available_for_pickup`, `return_to_sender`, `failure`, `cancelled`, `error`. |
+| `GET /__admin/trackers` | The namespace's trackers. |
+| `GET/PUT /__admin/settings` | `{apiKeys?: string[]}`: accept only these keys (default: any). |
+
+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-emulates-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
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `EasyPostAPI` | class | The in-process emulator: `fetch(request)`, `reset()`, `transition(idOrCode, {status, …}, carrier?)`, `trackers()`. Options: `sqlite`, `now`, `namespace`, `settings`. |
+| `createRuntime` | function | The emulator with the full service contract (health, admin, namespaces, credentials, presets). Options: `settings`, `clock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
+| `EASYPOST_PRESETS` | object | Every named fault preset. |
+| `EASYPOST_NAMESPACE` | string | The service name, `"easypost"`. |
+| `TEST_TRACKING_CODES` | object | EasyPost's test codes and the status / detail each answers. |
+| `TRACKER_STATUSES` | array | Every Tracker `status`. |
+| `apiKeyCredential` | function | The API key from `Basic base64(key:)` (how credentials map to namespaces). |
+| `detectCarrier` | function | The carrier the emulator assigns a code with no carrier given. |
+| `easyPostError` | function | Build an EasyPost error response `{error: {code, message, errors}}`. |
+| `isTrackerStatus` | function | Whether a value is a Tracker status. |
+| `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; port 8818. |
+
+Part of [Emulates](https://github.com/crvouga/emulates).

package/SUPPORT.md

@@ -0,0 +1,13 @@
+# EasyPost Trackers API (Emulates subset) — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **3**
+- supported by the emulator: **3**
+- parity enabled: **3**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `ListTrackers` | `GET /v2/trackers` | ✅ supported | ✅ |  |
+| `CreateTracker` | `POST /v2/trackers` | ✅ supported | ✅ |  |
+| `RetrieveTracker` | `GET /v2/trackers/{id}` | ✅ supported | ✅ |  |