# @crvouga/mockingbird-service-intercom > Stateful mock of the Intercom REST API 2.11: contacts (search, create with 409 on duplicates, update, get), conversations (create with Idempotency-Key, reply as JSON or multipart, close/open, get, cursor search), admins, and X-Hub-Signature-signed admin r Latest version **0.2.0** (published 2026-09-24) · MIT license · 0 weekly downloads ## Install ```sh npm install @crvouga/mockingbird-service-intercom pnpm add @crvouga/mockingbird-service-intercom yarn add @crvouga/mockingbird-service-intercom bun add @crvouga/mockingbird-service-intercom ``` Provides the command `mockingbird-intercom`. ## Health **Score 75/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score. Warnings: low downloads; pre 1.0. ## Facts | | | |---|---| | Version | 0.2.0 | | Published | 2026-09-24 | | First published | 2026-09-22 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 2 | | Unpacked size | 675 KB | | Known vulnerabilities | 0 (+34 in 1 direct dependencies) | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 2 | | Maintainers | crvouga | | Keywords | mockingbird, service, intercom, messaging, webhooks | ## Links - npm: https://www.npmjs.com/package/@crvouga/mockingbird-service-intercom - Repository: https://github.com/crvouga/mockingbird - Homepage: https://github.com/crvouga/mockingbird/tree/main/packages/service/intercom#readme - Issues: https://github.com/crvouga/mockingbird/issues - npm.io page: https://npm.io/package/@crvouga/mockingbird-service-intercom ## Dependencies (2) - [hono](https://npm.io/package/hono.md) 4.11.9 - [@crvouga/mockingbird-service-sqlite](https://npm.io/package/@crvouga/mockingbird-service-sqlite.md) 0.3.0 ## Alternatives - [pagerjs](https://npm.io/package/pagerjs.md) — 60 weekly downloads - [whistle.savefor-mock](https://npm.io/package/whistle.savefor-mock.md) — 4 weekly downloads - [@crvouga/mockingbird-service-prism](https://npm.io/package/@crvouga/mockingbird-service-prism.md) — 0 weekly downloads - [@crvouga/mockingbird-service-otel](https://npm.io/package/@crvouga/mockingbird-service-otel.md) — 0 weekly downloads - [@crvouga/mockingbird-service-plane](https://npm.io/package/@crvouga/mockingbird-service-plane.md) — 0 weekly downloads ## Recent versions - 0.2.0 (latest) — 2026-09-24 - 0.1.0 — 2026-09-22 ## README

🐦‍⬛
Mockingbird

**Mock the APIs you depend on, with the behavior they really have.** [![Ready](https://img.shields.io/badge/Ready-7-2ea44f)](#ready) [![Work in progress](https://img.shields.io/badge/In_progress-45-e36209)](#work-in-progress) [![CI](https://github.com/crvouga/mockingbird/actions/workflows/pr.yml/badge.svg)](https://github.com/crvouga/mockingbird/actions/workflows/pr.yml) [![License](https://img.shields.io/badge/license-MIT-5b4fe0)](#license) [Quick start](#quick-start) · [Services](#services) · [Why](docs/WHY.md) · [Guides](#guides) · [llms.txt](llms.txt)
> ⚠️ **Use at your own risk.** Mockingbird is under active development — APIs, behavior and package names may change without notice. Mockingbird is a catalog of stateful test doubles for third-party HTTP APIs and SQL databases. Each one speaks the vendor's real surface, keeps state, and runs in-process. ## Quick start ```bash npm install -D @crvouga/mockingbird-service-stripe ``` ```ts import { createRuntime } from "@crvouga/mockingbird-service-stripe" const stripe = createRuntime() const res = await stripe.fetch( new Request("https://api.stripe.com/v1/customers", { method: "POST", headers: { authorization: "Bearer sk_test_mockingbird", "content-type": "application/x-www-form-urlencoded", }, body: "email=ada@example.com", }), ) console.log(res.status) // 200 const customer = await res.json() // { id: "cus_…", object: "customer", email: "ada@example.com", … } // State persists: the customer is there when you list customers. const list = await stripe.fetch( new Request("https://api.stripe.com/v1/customers", { headers: { authorization: "Bearer sk_test_mockingbird" }, }), ) console.log((await list.json()).data[0].id === customer.id) // true ``` Every package is self-contained ESM with TypeScript types, for Node >= 22 or Bun >= 1.2. To browse every service with a live, in-browser playground, run the docs site: `bun docs`. ## Why Mockingbird - **The vendor's real surface.** Each mock answers the provider's own paths, headers, status codes and error envelopes through `fetch(Request) → Response`. Point the official SDK at it. - **State that behaves.** Records persist in an in-memory SQL engine. Created customers can be listed, orders move through their lifecycle, webhooks fire, and reset or snapshot takes one call. - **Checked against the real thing.** Random walks generated from each vendored OpenAPI contract run against two mock instances in CI, and against the live sandbox when credentials exist. - **No network, no waiting.** Everything runs in your test process. No sandbox keys, rate limits, shared test accounts or flaky round trips. - **Runs anywhere JavaScript runs.** Most mocks are portable: Node, Bun, browsers and Workers. The docs site's playgrounds run the published packages in your browser tab. - **One contract for every service.** Every HTTP mock shares `/health`, `/__admin` reset, snapshots, clock control, fault injection, request journals and per-namespace isolation. The full rationale, and when not to use it: [docs/WHY.md](docs/WHY.md). ## Services 52 services, each its own npm package. Every service declares a release tier: - **Ready** (7): Complete, checked against the vendor, and kept stable. Use it in your test suite. - **Work in progress** (45): Usable, but incomplete: operations, response shapes and options can still change between releases. Pin an exact version. ### Ready | Service | Category | Package | What it mocks | | --- | --- | --- | --- | | [Flex](packages/service/flex) | Payments | [`@crvouga/mockingbird-service-flex`](https://www.npmjs.com/package/@crvouga/mockingbird-service-flex) | Stateful mock of the Flex HSA/FSA payments API: products (recorded catalog corpus), checkout sessions in payment, subscription, off-session and setup modes, subscriptions, customers, setup intents, refunds, the hosted checkout page, and Svix-signed webhooks. | | [Junction](packages/service/junction) | Health & labs | [`@crvouga/mockingbird-service-junction`](https://www.npmjs.com/package/@crvouga/mockingbird-service-junction) | Stateful mock of the Junction (Vital) user API driven by its OpenAPI contract and verified by differential property tests against the Junction sandbox. | | [Medplum](packages/service/medplum) | Health & labs | [`@crvouga/mockingbird-service-medplum`](https://www.npmjs.com/package/@crvouga/mockingbird-service-medplum) | Stateful, portable mock of the self-hosted Medplum server (FHIR R4 REST, OAuth2 and admin API) that runs anywhere JavaScript runs, proven at parity with a real self-hosted Medplum used as the oracle. | | [OAuth & Social Login](packages/service/oauth) | Identity | [`@crvouga/mockingbird-service-oauth`](https://www.npmjs.com/package/@crvouga/mockingbird-service-oauth) | Portable social-login mock with Google, Apple, Microsoft, GitHub and generic OIDC profiles, private relay identities, reproducible edge cases, signed tokens and an accessible UI. | | [PostgreSQL](packages/service/postgres) | Databases | [`@crvouga/mockingbird-service-postgres`](https://www.npmjs.com/package/@crvouga/mockingbird-service-postgres) | Pure TypeScript in-memory PostgreSQL implementation with zero WASM/native dependencies | | [SQLite](packages/service/sqlite) | Databases | [`@crvouga/mockingbird-service-sqlite`](https://www.npmjs.com/package/@crvouga/mockingbird-service-sqlite) | Pure TypeScript in-memory SQLite implementation with zero WASM/native dependencies | | [Stripe](packages/service/stripe) | Payments | [`@crvouga/mockingbird-service-stripe`](https://www.npmjs.com/package/@crvouga/mockingbird-service-stripe) | Stateful mock of the Stripe API (accounts by key, customers, payments, subscriptions with renewals, invoices, checkout with a hosted page, a Stripe.js stand-in, signed webhooks) at API versions 2024-06-20 and 2025-02-24.acacia, verified by differential property tests against Stripe test mode. | ### Work in progress | Service | Category | Package | What it mocks | | --- | --- | --- | --- | | [Amazon Textract](packages/service/textract) | AI & speech | [`@crvouga/mockingbird-service-textract`](https://www.npmjs.com/package/@crvouga/mockingbird-service-textract) | Stateful Amazon Textract mock with document analysis jobs, graph blocks, pagination, and deterministic notifications. | | [AWS Bedrock](packages/service/bedrock) | AI & speech | [`@crvouga/mockingbird-service-bedrock`](https://www.npmjs.com/package/@crvouga/mockingbird-service-bedrock) | Stateful, scriptable mock of AWS Bedrock Runtime (Converse, ConverseStream, InvokeModel incl. Titan embeddings, Nova Sonic bidirectional streams over h2c) and AgentCore InvokeHarness, with exact event-stream framing. | | [AWS Polly & Transcribe](packages/service/aws-speech) | AI & speech | [`@crvouga/mockingbird-service-aws-speech`](https://www.npmjs.com/package/@crvouga/mockingbird-service-aws-speech) | Stateful mock of AWS Polly (SynthesizeSpeech, StartSpeechSynthesisStream) and Transcribe (streaming over h2c, batch jobs), with exact event-stream framing and scripted transcripts. | | [LlamaCloud](packages/service/llamacloud) | AI & speech | [`@crvouga/mockingbird-service-llamacloud`](https://www.npmjs.com/package/@crvouga/mockingbird-service-llamacloud) | Stateful mock of the LlamaCloud platform API: project and pipeline lookup, pipeline documents, and deterministic (scripted or term-overlap) retrieval, verified against the official llama_cloud_services SDK. | | [Amazon SQS](packages/service/sqs) | Communication | [`@crvouga/mockingbird-service-sqs`](https://www.npmjs.com/package/@crvouga/mockingbird-service-sqs) | Stateful Amazon SQS mock with visibility, FIFO ordering, deduplication, batches, and redrive. | | [AWS Elemental MediaConvert](packages/service/mediaconvert) | Communication | [`@crvouga/mockingbird-service-mediaconvert`](https://www.npmjs.com/package/@crvouga/mockingbird-service-mediaconvert) | Stateful AWS Elemental MediaConvert mock with endpoint discovery, async jobs, EventBridge events, and deterministic S3 outputs. | | [Daily](packages/service/daily) | Communication | [`@crvouga/mockingbird-service-daily`](https://www.npmjs.com/package/@crvouga/mockingbird-service-daily) | Stateful mock of the Daily.co REST API: rooms, presence, eject, meeting tokens (minted and self-signed HS256, verified and decodable), and transcription/recording webhooks with transcripts written to S3. | | [Intercom](packages/service/intercom) | Communication | [`@crvouga/mockingbird-service-intercom`](https://www.npmjs.com/package/@crvouga/mockingbird-service-intercom) | Stateful mock of the Intercom REST API 2.11: contacts (search, create with 409 on duplicates, update, get), conversations (create with Idempotency-Key, reply as JSON or multipart, close/open, get, cursor search), admins, and X-Hub-Signature-signed admin reply/close/open webhooks. | | [LiveKit](packages/service/livekit) | Communication | [`@crvouga/mockingbird-service-livekit`](https://www.npmjs.com/package/@crvouga/mockingbird-service-livekit) | Stateful LiveKit mock with Twirp room APIs, JWT grants, participants, data, SIP/egress controls, and signed webhooks. | | [Mailosaur](packages/service/mailosaur) | Communication | [`@crvouga/mockingbird-service-mailosaur`](https://www.npmjs.com/package/@crvouga/mockingbird-service-mailosaur) | Stateful mock of the Mailosaur email/SMS testing API (messages search, get, delete, long-poll) with an HTTP ingest so other mocks can drop mail in (Mockingbird service contract). | | [Resend](packages/service/resend) | Communication | [`@crvouga/mockingbird-service-resend`](https://www.npmjs.com/package/@crvouga/mockingbird-service-resend) | Stateful mock of the Resend email API (send with idempotency, received emails, attachments) with an outbox and Svix-signed inbound webhooks (Mockingbird service contract). | | [Slack](packages/service/slack) | Communication | [`@crvouga/mockingbird-service-slack`](https://www.npmjs.com/package/@crvouga/mockingbird-service-slack) | Stateful mock of Slack incoming webhooks and the Web API (chat.postMessage and friends) with an outbox of every alert the app sent. | | [Twilio](packages/service/twilio) | Communication | [`@crvouga/mockingbird-service-twilio`](https://www.npmjs.com/package/@crvouga/mockingbird-service-twilio) | Stateful mock of Twilio Verify, Lookup v2, Messaging and Recordings on one port, with signed inbound SMS and voice webhooks (Mockingbird service contract). | | [Amazon DynamoDB](packages/service/dynamodb) | Databases | [`@crvouga/mockingbird-service-dynamodb`](https://www.npmjs.com/package/@crvouga/mockingbird-service-dynamodb) | Stateful Amazon DynamoDB mock with typed items, expressions, indexes, pagination, transactions, and streams. | | [AHA](packages/service/aha) | Health & labs | [`@crvouga/mockingbird-service-aha`](https://www.npmjs.com/package/@crvouga/mockingbird-service-aha) | Stateful AHA phlebotomy mock with signed HTTP orders, status webhooks, and a real deterministic SSH/SFTP result server. | | [CareTalk](packages/service/caretalk) | Health & labs | [`@crvouga/mockingbird-service-caretalk`](https://www.npmjs.com/package/@crvouga/mockingbird-service-caretalk) | Stateful mock of CareTalk's external API: client-login tokens, GetForm definitions, SavePatientForm rounds, patient search/insert, states, free slots and appointments. | | [Edamam](packages/service/edamam) | Health & labs | [`@crvouga/mockingbird-service-edamam`](https://www.npmjs.com/package/@crvouga/mockingbird-service-edamam) | Stateful mock of the Edamam APIs our apps call: food-database parser, nutrients and image analysis, nutrition analysis, recipe search v2, meal-planner select and shopping lists, over a built-in food and recipe corpus. | | [Fullscript](packages/service/fullscript) | Health & labs | [`@crvouga/mockingbird-service-fullscript`](https://www.npmjs.com/package/@crvouga/mockingbird-service-fullscript) | Stateful mock of the Fullscript lab-ordering API: per-practitioner OAuth, clinic, session grants, forward-only lab orders with results, lab-order events, expiring result PDFs, and Fullscript-Signature webhooks. | | [Gene by Gene](packages/service/genebygene) | Health & labs | [`@crvouga/mockingbird-service-genebygene`](https://www.npmjs.com/package/@crvouga/mockingbird-service-genebygene) | Stateful mock of Gene by Gene's Nucleus API v2 and auth host: tokens with credential blocking, catalog, shipping quotes, orders, kits, demographics, three-layer cancel, results with presigned downloads and S3 writes, subscriptions, and GxG-signed webhooks. | | [Healthie](packages/service/healthie) | Health & labs | [`@crvouga/mockingbird-service-healthie`](https://www.npmjs.com/package/@crvouga/mockingbird-service-healthie) | Stateful mock of the Healthie GraphQL API (legacy surface): signIn, users, currentUser, updateUser/updateClient (incl. multipart avatar), locations, documents and folders with served downloads, form answers, offerings, billing items, and the IP-allowlisted status webhooks. | | [Makor CPG](packages/service/makor-cpg) | Health & labs | [`@crvouga/mockingbird-service-makor-cpg`](https://www.npmjs.com/package/@crvouga/mockingbird-service-makor-cpg) | Stateful mock of the legacy Makor AI (CPG) API: care plans, plus-user, bloodwork webhook, subscriptions, Wholescripts orders, AI patient summaries and async-review scripts (processing → complete on the mock clock), with permissive CORS for browser-direct calls. | | [Optimal DX](packages/service/odx) | Health & labs | [`@crvouga/mockingbird-service-odx`](https://www.npmjs.com/package/@crvouga/mockingbird-service-odx) | Stateful mock of the (retired) Optimal DX partner API: patients, partner links, HL7 and structured lab imports, Functional Health Reports (JSON/PDF), webhook registrations, and signed PatientTest webhooks. | | [Prism Labs](packages/service/prism) | Health & labs | [`@crvouga/mockingbird-service-prism`](https://www.npmjs.com/package/@crvouga/mockingbird-service-prism) | Stateful mock of the Prism Labs body-scan API: subjects, scans, presigned capture upload, processing stages to READY, and deterministic body-composition, measurement, health-report and asset results. | | [Amazon Cognito](packages/service/cognito) | Identity | [`@crvouga/mockingbird-service-cognito`](https://www.npmjs.com/package/@crvouga/mockingbird-service-cognito) | Stateful Amazon Cognito User Pools mock for AWS SDK and browser authentication tests. | | [AWS Secrets Manager & SSM](packages/service/aws-secrets) | Identity | [`@crvouga/mockingbird-service-aws-secrets`](https://www.npmjs.com/package/@crvouga/mockingbird-service-aws-secrets) | Stateful AWS Secrets Manager and SSM Parameter Store mock with versions, stages, rotation, and redacted controls. | | [Persona](packages/service/persona) | Identity | [`@crvouga/mockingbird-service-persona`](https://www.npmjs.com/package/@crvouga/mockingbird-service-persona) | Stateful mock of the Persona identity-verification API: inquiry create, list (reusable lookup), get, a hosted flow page, admin lifecycle transitions, and Persona-Signature webhooks. | | [EasyPost](packages/service/easypost) | Maps & logistics | [`@crvouga/mockingbird-service-easypost`](https://www.npmjs.com/package/@crvouga/mockingbird-service-easypost) | Stateful mock of the EasyPost trackers API: create/re-use trackers, EasyPost's test tracking codes, admin status transitions and EasyPost's error envelope. | | [Google Maps](packages/service/google-maps) | Maps & logistics | [`@crvouga/mockingbird-service-google-maps`](https://www.npmjs.com/package/@crvouga/mockingbird-service-google-maps) | Mock of Google Places Autocomplete / Details / Find Place, the Geocoding API and a Maps JavaScript (places) shim, over a QA address corpus, with Google's status codes and fault presets. | | [Customer.io](packages/service/customerio) | Marketing | [`@crvouga/mockingbird-service-customerio`](https://www.npmjs.com/package/@crvouga/mockingbird-service-customerio) | Stateful mock of Customer.io: Segment-compatible CDP (identify/track/batch, SDK drop-in), App API transactional email/SMS/inbox sends with an outbox, message catalog, link-click tracking, and signed reporting webhooks. | | [FirstPromoter](packages/service/firstpromoter) | Marketing | [`@crvouga/mockingbird-service-firstpromoter`](https://www.npmjs.com/package/@crvouga/mockingbird-service-firstpromoter) | Stateful mock of the FirstPromoter v2 API: promoters (adopt-before-create by cust_id), signup tracking by tid / promoter_id / ref token, iframe login, archive, and Basic-auth lead_becomes_referral webhooks. | | [Klaviyo](packages/service/klaviyo) | Marketing | [`@crvouga/mockingbird-service-klaviyo`](https://www.npmjs.com/package/@crvouga/mockingbird-service-klaviyo) | Stateful mock of the Klaviyo events API: JSON:API event create (Ordered Product, Placed Order), event reads, unique_id dedupe, JSON:API errors and an outbox. | | [OpenTelemetry](packages/service/otel) | Observability | [`@crvouga/mockingbird-service-otel`](https://www.npmjs.com/package/@crvouga/mockingbird-service-otel) | Stateful mock of an OTLP/HTTP collector (JSON and protobuf traces and logs) and the OpenObserve search API over the same store. | | [PostHog](packages/service/posthog) | Observability | [`@crvouga/mockingbird-service-posthog`](https://www.npmjs.com/package/@crvouga/mockingbird-service-posthog) | Stateful mock of PostHog: /flags v2 and legacy /decide evaluation with per-test flag, variant and payload control, remote config, gzip/base64 capture (/batch/, /e/, /i/v0/e/), recordings intake, and the feature-flag management and HogQL API slice. | | [Kill Bill](packages/service/kill-bill) | Payments | [`@crvouga/mockingbird-service-kill-bill`](https://www.npmjs.com/package/@crvouga/mockingbird-service-kill-bill) | Stateful Kill Bill billing mock with accounts, subscriptions, invoices, payments, credits, retries, catalog, and clock controls. | | [Pharmetika](packages/service/pharmetika) | Pharmacy | [`@crvouga/mockingbird-service-pharmetika`](https://www.npmjs.com/package/@crvouga/mockingbird-service-pharmetika) | Stateful mock of the Pharmetika compounding-pharmacy provider portal: clinics, patients, medication-order validate / EPCS prepare / submit / lookup, the v7 cancel, the medication-template catalog, and status webhooks. | | [Portal Agent](packages/service/portal-agent) | Pharmacy | [`@crvouga/mockingbird-service-portal-agent`](https://www.npmjs.com/package/@crvouga/mockingbird-service-portal-agent) | Stateful mock of our eRx portal agent (LifeFile/VPI browser runner): the fulfilment job endpoint with strict response rules, a job store, fault presets, and x-internal-key callbacks. | | [RxVortex](packages/service/rxvortex) | Pharmacy | [`@crvouga/mockingbird-service-rxvortex`](https://www.npmjs.com/package/@crvouga/mockingbird-service-rxvortex) | Stateful mock of the RxVortex (Strive) pharmacy API: OAuth token, order submit, status, cancel, recovery by sender order id, preset catalog, and signed status webhooks. | | [VPI](packages/service/vpi) | Pharmacy | [`@crvouga/mockingbird-service-vpi`](https://www.npmjs.com/package/@crvouga/mockingbird-service-vpi) | Stateful mock of the VPI compounding pharmacy API: JWT authentication, products, clinic, patients, providers, saveNewPrescription drafts and the three paged prescription status lists. | | [Wholescripts](packages/service/wholescripts) | Pharmacy | [`@crvouga/mockingbird-service-wholescripts`](https://www.npmjs.com/package/@crvouga/mockingbird-service-wholescripts) | Stateful mock of the Wholescripts supplement fulfilment API: product and private-label catalogs, order submit, status polling and cancel, with admin status transitions. | | [AWS Step Functions](packages/service/step-functions) | Productivity | [`@crvouga/mockingbird-service-step-functions`](https://www.npmjs.com/package/@crvouga/mockingbird-service-step-functions) | Stateful AWS Step Functions mock with idempotent executions, callbacks, deterministic transitions, and history. | | [Formbricks](packages/service/formbricks) | Productivity | [`@crvouga/mockingbird-service-formbricks`](https://www.npmjs.com/package/@crvouga/mockingbird-service-formbricks) | Stateful mock of Formbricks (Geviti fork): client environment state seeded from our production survey clone, response creation with the fork's validation errors, the v1 management API, the widget script, and responseFinished webhooks. | | [Google Calendar](packages/service/google-calendar) | Productivity | [`@crvouga/mockingbird-service-google-calendar`](https://www.npmjs.com/package/@crvouga/mockingbird-service-google-calendar) | Stateful mock of the Google Calendar v3 API and Google OAuth our EMR calls: events list/insert/update/delete/watch, channels.stop, calendarList/calendars, token exchange/refresh/revoke and userinfo, with signed-by-header push notifications. | | [Payload CMS](packages/service/payload-cms) | Productivity | [`@crvouga/mockingbird-service-payload-cms`](https://www.npmjs.com/package/@crvouga/mockingbird-service-payload-cms) | Stateful mock of the Payload CMS collection REST API: paginated finds with a where-query subset, find by id, a seeded marketing collection and admin-editable documents. | | [Plane](packages/service/plane) | Productivity | [`@crvouga/mockingbird-service-plane`](https://www.npmjs.com/package/@crvouga/mockingbird-service-plane) | Stateful mock of the Plane REST API v1: cursor-paginated work items, comments, links, states and labels, with Plane's rate limit and error shapes. | | [Amazon S3](packages/service/s3) | Storage | [`@crvouga/mockingbird-service-s3`](https://www.npmjs.com/package/@crvouga/mockingbird-service-s3) | Stateful Amazon S3 mock with binary objects, listing, copies, multipart uploads, presigned URLs, and canonical XML errors. | Operation coverage per service is in each package's `SUPPORT.md` (or `COMPATIBILITY.md` for the SQL engines), and on the docs site's coverage page. ## One contract for every HTTP service Every HTTP service ships an in-process `fetch`, a Node server and a CLI, and all answer the same control surface, so a stack learns it once. ```bash npx mockingbird-junction serve --port 8787 # one service npx mockingbird-junction serve --config mockingbird.json # every service in the config ``` | Surface | What it gives you | | --- | --- | | `createRuntime()` · `createServer()` (`./server`) · `mockingbird- serve` | The mock as one runtime-neutral `fetch`, or a listening server from Node or the CLI | | `GET /health` | Unauthenticated readiness probe, outside the vendor's auth gate | | `/__admin/*` (`x-mockingbird-admin-key` optional) | Reset, snapshot and restore, clock control, fault injection, a request journal, metrics with unmatched-route counts, plus service-specific routes | | `x-mockingbird-namespace` | Per-request isolation: parallel workers share one process without sharing data | | `--seed`, clock control | Seeded randomness and an injectable clock, so a run replays exactly | | `--log json` | One structured line per request: operation id, status, duration, namespace, fault | ```json { "services": { "junction": { "port": 8787, "options": { "corpus": "./test/junction-corpus.json" } }, "stripe": { "port": 12111 } } } ``` `mockingbird.json` names services by their package suffix and takes each one's `serve` flags; any installed service's CLI can serve all of them. The database engines are not HTTP APIs, so they are outside this contract. ## For coding agents Every service README doubles as its integration guide and ships inside the npm tarball (`node_modules//README.md`). [`llms.txt`](llms.txt) indexes them by tier, and the docs site publishes the same content as markdown and JSON, rebuilt from the packages on every build. When a mock diverges from the real API, lacks a feature you call, or the vendor you need is not in the catalog, file an issue: [the filing guide](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md) gives the title format, templates and the behavior spec for feature and service requests. ## Contributing ```bash git clone https://github.com/crvouga/mockingbird.git && cd mockingbird bun run setup # install, build every package, create .env.local bun test ``` Building, testing and `bun run check` need no secrets and no accounts. Live parity against the real provider sandboxes runs on GitHub Actions with the repo's secrets, so anyone with write access runs it without holding a key: `bun run parity:remote -- `. See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) and [docs/SECRETS.md](docs/SECRETS.md). ## Guides | Guide | | | --- | --- | | [Why Mockingbird](docs/WHY.md) | Your tests are only as honest as the fakes they run against. Most suites that touch Stripe, Twilio or a lab partner either call a shared sandbox or stub the client. Both fail in ways that are expensive to notice. Mockingbird is a third option. | | [Testing and parity](docs/TESTING.md) | How every mock is proven to behave like its vendor: differential contracts, property-based walks, and live parity against real sandboxes. | | [Authoring a Mockingbird service](docs/AUTHORING_A_SERVICE.md) | How to add a vendor mock to this repo. The reference implementation is [`packages/service/rxvortex`](../packages/service/rxvortex): copy its layout and patterns. | | [Service catalog coverage](docs/CATALOG_COVERAGE.md) | Where each section of the geviti "Mockingbird wish list — service catalog" (2026-09-20) lives in this repo, how it is proven, and what the proof turned up. Every package follows [AUTHORING_A_SERVICE.md](AUTHORING_A_SERVICE.md) and ships the same evidence: | | [Developing Mockingbird](docs/DEVELOPMENT.md) | Working on this repo: requirements, how the packages are layered, and the quality gates every change passes. | | [Reporting issues](docs/REPORTING_ISSUES.md) | How coding agents in other projects file a GitHub issue when a mock diverges from its oracle, lacks a feature they call, or breaks, or when they need a service mocked that the catalog does not have yet. Agents in this repository pick the issues up and resolve them. | | [Releasing](docs/RELEASING.md) | How packages get from `main` to npm. Once the `NPM_TOKEN` repo secret is set, releases run automatically. | | [Secrets runbook](docs/SECRETS.md) | Where every credential lives, who needs it, and how to run live parity without ever holding a sandbox key: GitHub Actions repo secrets are the only secret store. | ## License MIT. --- _Source: https://npm.io/package/@crvouga/mockingbird-service-intercom · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._