@crvouga/mockingbird-service-checkr

Local emulators. Real API contracts. Part of Mockingbird.

WIP Checkr v1 emulator for synthetic candidates, package/hierarchy enumeration, invitations and seeded report/ETA reads. No checks run, emails are sent or real personal data is needed.

Install

bun add -d @crvouga/mockingbird-service-checkr

Usage

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

// Test setup: the emulator. The application's Checkr origin becomes server.url.
const server = await createServer()
const baseUrl = server.url

// Application code: the request it sends to api.checkr.com, Basic auth with the API key.
const response = await fetch(`${baseUrl}/v1/packages`, {
  headers: { authorization: `Basic ${btoa("mock_checkr_key:")}` },
})
const packages = (await response.json()) as { data: { slug: string }[] }
await server.close()

Inject server.url into the consumer's origin seam; it replaces the production/staging origin, not the /v1 prefix. createRuntime().fetch(Request) supports in-process adapters. Basic auth accepts apiKey (default mock_checkr_key) as username and an empty password.

Routes

GET /v1/packages, /v1/nodes, /v1/candidates, /v1/invitations enumerate with page/per_page and local next_href links. Candidate email and invitation candidate/status filters are supported. POST /v1/candidates and /v1/invitations create records; invitations validate candidate/package references and work locations before storing anything. GET/DELETE /v1/invitations/{id} reads/cancels an invitation. Cancellation is deletion, not an invented canceled status: deleted_at is set, ordinary reads/lists exclude it, and GET ?include_deleted=true exposes it. This follows the documented cancellation/delete and include_deleted mechanism; the reference's generic DELETE response example does not demonstrate post-delete timestamps. Pending invitations expire after seven days by default. GET /v1/reports/{id} and /v1/reports/{id}/eta read seeded reports; missing ETA returns 404.

State and controls

Runtime seeds: packages, nodes, candidates, reports; hierarchyEnabled defaults false, so nodes returns 403 while other APIs work. Enabled hierarchy requires an available node/package on invitation creation. invitationTtlMs and the emulator clock drive expiration. All records and settings are collections in /__admin/state: edit prices, report state/ETA, invitation expiry/completion and hierarchy access without external services. An admin-seeded report is reflected in its candidate's report_ids. The admin controls intentionally do not enforce vendor referential integrity; seed coherent fixtures.

Standard admin reset, Timeline snapshots/branches, clocks and journals are available. Namespaces use x-mockingbird-namespace, /__admin/ns/<name>/…, or mapped Basic credentials; pagination URLs retain the namespace, including relocated adminPrefix paths. Journals retain request metadata only, not candidate data or credentials. Presets: forbidden, hierarchy_denied, rate_limited, server_error, non_json, connection_drop. Generic fault latency and client AbortSignal model deterministic timeouts. No webhooks are implemented or claimed.

Verification

bun test covers each reported behavior through a raw-fetch client port, served HTTP, namespaces/faults/reset, independent OpenAPI walks and deliberately divergent instances. No official SDK is used by this consumer. The port follows the issue's surface; unchanged private app acceptance is not claimed. The official Checkr reference is the oracle; no live credentials or background-check requests were used. CHECKR_API_KEY=… bun run parity safely checks a package-list response shape; without the key it exits 2. It never creates candidates, invitations or reports.

Deliberately not modelled

Actual background screening, criminal records, real PII, invitation email delivery, hosted candidate consent UI, webhook delivery and production adjudication decisions. Reports are explicit synthetic fixtures; no automatic report is created merely by inviting a candidate. Error diagnostic strings and full vendor per-field validation are outside this scoped WIP.

API

Root runtime exports: CheckrAPI, CHECKR_NAMESPACE, DEFAULT_PACKAGES, createRuntime, CHECKR_PRESETS, document, operationIds, supportedOperationIds. Types: Package, Node, Candidate, Invitation, Report, CheckrAPIOptions, CheckrRuntimeOptions, CheckrRuntime, OperationId, SupportedOperationId. The /server entry exports createServer, serveTarget, DEFAULT_PORT.