@emulates/brevo 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog — @emulates/brevo
+
+## 0.1.1 (2026-10-06)
+
+Initial release.
+
+### Dependencies
+
+- `@emulates/sqlite`

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @emulates/brevo discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@emulates/brevo/`; 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: **Contact identity and CRUD**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- brevo`.
+- 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/emulators/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: `brevo`.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @emulates/brevo
 
-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/emulators): high-fidelity, in-process emulators for APIs and databases.
+
+WIP Brevo v3 contact lifecycle, based on the official contact reference. No messages are sent.
+
+## Install
+
+```sh
+bun add @emulates/brevo
+```
+
+## Usage
+
+```ts
+import { createRuntime } from "@emulates/brevo"
+
+const brevo = createRuntime()
+const response = await brevo.fetch(new Request("http://brevo.test/v3/contacts", {
+  method: "POST",
+  headers: { "content-type": "application/json", "api-key": "mock_brevo_key" },
+  body: JSON.stringify({ email: "synthetic@example.invalid", ext_id: "mock-contact", listIds: [1], updateEnabled: false }),
+}))
+console.log(await response.json()) // { id: 1 }
+```
+
+Run `emulates-brevo serve --port 12124` for a separate application process. Replace
+the client's `https://api.brevo.com` origin with `http://localhost:12124`; the consumer must
+make its 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-emulates-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`.

package/SUPPORT.md

@@ -0,0 +1,14 @@
+# Brevo contacts subset — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **4**
+- supported by the emulator: **4**
+- parity enabled: **4**
+
+| operationId | route | emulator | parity | notes |
+| --- | --- | --- | --- | --- |
+| `CreateContact` | `POST /v3/contacts` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `GetContact` | `GET /v3/contacts/{identifier}` | ✅ supported | ✅ |  |
+| `UpdateContact` | `PUT /v3/contacts/{identifier}` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `DeleteContact` | `DELETE /v3/contacts/{identifier}` | ✅ supported | ⚠️ unsafe (opt-in) |  |