@crvouga/mockingbird-service-brevo

Local emulators. Real API contracts. Part of Mockingbird.

WIP Brevo v3 contact lifecycle, based on the official contact reference. No messages are sent.

Install

bun add @crvouga/mockingbird-service-brevo

Usage

import { BrevoClient } from "@getbrevo/brevo"
import { createRuntime } from "@crvouga/mockingbird-service-brevo"

// The Brevo SDK your application already uses. Only its fetch changes: requests reach the
// emulator in this process instead of api.brevo.com.
const emulator = createRuntime()
const brevo = new BrevoClient({
  apiKey: "mock_brevo_key",
  fetch: ((url: RequestInfo | URL, init?: RequestInit) =>
    emulator.fetch(new Request(url, init))) as typeof fetch,
})

const created = await brevo.contacts.createContact({
  email: "[email protected]",
  ext_id: "mock-contact",
  listIds: [1],
  updateEnabled: false,
})
console.log(created) // { id: 1 }

Run mockingbird-brevo serve --port 12124 for a separate application process and set the SDK's baseUrl to http://localhost:12124/v3 (@getbrevo/brevo; a raw HTTP client replaces its https://api.brevo.com origin). The consumer must make that base URL injectable (the vendor does not define a standard environment variable). Use the synthetic api-key: mock_brevo_key, or configure apiKeys in createRuntime.

Routes

• POST /v3/contacts: creates a contact with a numeric id (201). Duplicate email or external id with updateEnabled: false returns 400 duplicate_parameter without mutation. updateEnabled: true updates the existing contact (204).
• PUT /v3/contacts/{identifier}?identifierType=ext_id: updates attributes, including attributes.EMAIL, without changing the contact's numeric id or existing list memberships (204). listIds adds memberships; unlinkListIds removes them.
• DELETE /v3/contacts/{encoded-email}?identifierType=email_id: deletes that contact (204).
• GET /v3/contacts/{identifier}: reads the contact. Explicit identifierType supports email_id, contact_id, and ext_id; the default recognizes an email or numeric id.

Missing contacts return 404 document_not_found. Invalid identifiers, malformed bodies, invalid emails and conflicting updates return 400; missing or invalid API keys return 401. Errors use {code, message}. There are no webhooks for this surface.

Controls and verification

Pass synthetic contacts to seed the emulator; reset restores those fixtures. Shared admin routes include /__admin/state/contacts for inspection/seeding, /__admin/reset, Timeline checkpoints, /__admin/clock, /__admin/requests and /__admin/faults. Requests are journaled as metadata, never contact bodies or API keys. Set adminPrefix to relocate this tree.

Namespace carriers are x-mockingbird-namespace, /__admin/ns/{namespace}, or API keys mapped through PUT /__admin/credentials. Each namespace has independent contacts and ids. Fault presets: unauthorized, rate_limited (429 with Retry-After), server_error (503), and connection_drop. Generic fault rules also support deterministic latency.

Acceptance tests exercise the raw-fetch requests from issue #280, namespace/reset behavior, faults and served HTTP. Property tests cover every operation and detect deliberate divergence. bun scripts/parity.ts needs BREVO_API_KEY and safely compares the missing-contact envelope; it does not create, update or delete real contacts. Live write parity has not been verified.

Deliberately not modelled

Email/SMS sending, campaigns, lists management, bulk import/export, SMS/WhatsApp identifiers, forceMerge, attribute-definition catalogs, contact statistics and account-level quotas. Only email and external-id creation are supported. No real customer fixtures or outbound events.

API

• BrevoAPI: in-process FetchAPI with fetch, reset, contacts and counters collections.
• BREVO_NAMESPACE: service name (brevo).
• createRuntime: shared admin, namespace, clock, fault and journal surface; accepts apiKeys and contacts in addition to shared runtime options.
• BREVO_PRESETS: named fault presets.
• document, operationIds, supportedOperationIds: generated OpenAPI contract metadata.
• createServer, serveTarget, DEFAULT_PORT from ./server: Node HTTP server and CLI target (default port 12124).

Public types include Contact, BrevoAPIOptions, OperationId and SupportedOperationId.