Gene by Gene

Stateful mock of Gene by Gene's Nucleus API v2 (and its OAuth auth host) for test suites: client-credentials tokens with the credential-blocking failures, the product catalog, shipping quotes, order placement (shipped and quantity-only, plus orders for existing kits), order lines, fulfillments and address edits, kits and their demographics attributes, the three-layer cancel, results with presigned downloads, notification subscriptions, and GxG-signed notifications. Kits move along the lab's status ladder only when a test says so, so genomics suites that serialised on one staging slot with 15 s sleeps and 300 s waits resolve in milliseconds.

The catalog calls this package @crvouga/mockingbird-service-gene-by-gene; it is published as @crvouga/mockingbird-service-genebygene (bin mockingbird-genebygene).

• Operation coverage: SUPPORT.md (30 of the 51 operations; every one our consumer calls).
• Contract: openapi.yaml is the full Nucleus v2 Swagger document our consumer commits (GXG/transport/spec/gxg-openapi.json, from demo-api.genebygene.com), vendored by scripts/vendor-openapi.ts. The script adds operationIds and Mockingbird annotations, the fields the live API returns but Swagger omits (ProductDto.preassembly, OrderLineDto.placerOrderNumber/kitNumbers, CreateOrder_Item.placerOrderNumber, null courier objects), schemas for the bodies Swagger leaves out (eventTypes, kitorderlines/kits, results/search, presignedUrl), and the auth host's /connect/token.

#Install

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

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

#Usage

The mock serves the API and the auth host on one port. Point the app at it:

(Our backend's non-prod safety gate must allow loopback first: catalog item G-X1.)

npx mockingbird-genebygene serve --port 8788 \
  --webhook-url http://127.0.0.1:3000/webhooks/gene-by-gene --webhook-secret "$GXG_KV_SECRET" \
  --results-s3-endpoint http://127.0.0.1:4569 --results-s3-bucket geviti-gxg-results-dev

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

const gxg = createRuntime({ webhooks: { url: "http://127.0.0.1:3000/webhooks/gene-by-gene", secret: "kv-secret" } })
const call = (path: string, init: RequestInit = {}) => gxg.fetch(new Request(`http://gxg.test${path}`, init))

const { access_token } = (await (
  await call("/connect/token", {
    method: "POST",
    headers: { "content-type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({ grant_type: "client_credentials", client_id: "id", client_secret: "s" }),
  })
).json()) as { access_token: string }
// …the app places POST /api/v2/orders with Authorization: Bearer <access_token>; the response's
// orderLines[].kitNumbers carry the new kit (Order.Created + KitNumbersGenerated are sent)…

const admin = (path: string, body: unknown) =>
  call(`/__admin${path}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) })
await admin("/orders/<orderId>/ship", {}) // tracking numbers + Order.Shipped
await admin("/kits/WB3K9Q2X/transition", { to: "Received" }) // Kit.Received
await admin("/kits/WB3K9Q2X/transition", { to: "Completed", fixture: "pgx" }) // results + Kit.Completed
await admin("/kits/WB7ABCDE/transition", { to: "Error", errorCode: 19 }) // Kit.Error (new collection)

#Routes (vendor)

Every API route needs Authorization: Bearer <token>; a missing, expired, revoked (POST /__admin/tokens/revoke) or blocked-client token is an empty 401 with WWW-Authenticate: Bearer error="invalid_token", so our client invalidates and retries once. Handler errors are ErrorDto{statusCode, message, payload, errorType}; model-binding failures are ASP.NET problem details with errors.

#Webhooks

Notifications go to every active subscription for its events, signed with that subscription's secret, and to --webhook-url (all events) signed with --webhook-secret:

• gxg-signature: sha512=<hex HMAC-SHA512(secret, rawBody)>, gxg-eventtype: <event>, gxg-notificationid: <uuid>.
• Events: GxG.Nucleus.Order.Created (OrderGuid, OrderType, OrderItems — the real OrderGuid shape, which our receiver's OrderId extractor misses: kept on purpose), .Order.KitNumbersGenerated, .Order.Shipped, .Kit.Received, .Kit.Completed (one per result-bearing order line: JSON + PDF on the report line, CSV on the raw-data line), .Kit.Error (ErrorCode 4 "10 Day Delay", 19 "New collection requested"), and .Kit.KitOrderLine.Canceled. Bodies are PascalCase with the keys of the recorded samples (GXG/docs/webhook-events.json).
• Retries: immediately, 10 s, 1 min, 5 min (GxG retries up to three times). GET /__admin/webhooks, …/events, POST …/flush, …/:id/replay as usual.

#Admin (beyond the standard contract)

Result fixtures: normal is our consumer's own comprehensive-report fixture (synthetic "Jane Doe", trimmed to one item per section); pgx and ancestry are synthetic reports in the same schema. Every fixture also publishes the raw-data CSV and a one-page PDF.

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?, "latencyMs"?}): invalid_client, token_unauthorized, token_forbidden, token_revoked, rate_limited, shipping_empty_500, address_not_validated, slow_orders (5 s on POST /orders), no_kit_numbers, cancel_conflict (409), presigned_access_denied, server_error, webhook_duplicate, webhook_reorder, webhook_drop.

#Namespaces

x-mockingbird-namespace, a /ns/<name> prefix on both GENE_BY_GENE_API_URL and the token URL, or by client id: PUT /__admin/credentials {"credentials": {"<client_id>": "<namespace>"}} (tokens carry the client id they were issued to). Kit numbers and result keys are salted per namespace, so parallel workers never collide in the shared results bucket.

#Deliberately not modelled

• The 21 operations our consumer never calls (HL7 ehr/*, single-attribute edits, CSV/document uploads, resetSecret, bulk kit-order-line cancel, …): supported: false in openapi.yaml.
• Server-side subscription filters (GxG creates them on request), invoicing, insurance.
• Real carrier behaviour: shipping prices and tracking numbers are fixed-format synthetics.
• A live corpus pull: the catalog is the consumer's recorded gxg-list-products-dev.json; attribute definitions and event types are synthesised from the consumer's code (no recording exists), because staging credentials are not in Vault.
• Nothing moves on its own: every lab step is an admin transition.

#API

#Development

bun test                           # self-parity, acceptance through test/consumer.ts, contract, served-over-HTTP
bun scripts/vendor-openapi.ts      # re-vendor openapi.yaml from ~/geviti-monorepo, then bun run generate
bun run parity                     # live parity against GxG staging; exits 2 without
                                   # MOCKINGBIRD_GENEBYGENE_CLIENT_ID / _CLIENT_SECRET (env or Vault)

Part of mockingbird.