@crvouga/mockingbird-service-customerio 3.2.0 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,15 +1,21 @@
1
1
  # Changelog — @crvouga/mockingbird-service-customerio
2
2
 
3
- ## 3.2.0 (2026-10-09)
3
+ ## 3.3.0 (2026-10-12)
4
4
 
5
5
  ### Features
6
6
 
7
- - match Emulate provider coverage ([16b65ce](https://github.com/crvouga/mockingbird/commit/16b65ce791fa216f28ec1521df636f57771d9c5e))
7
+ - unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
8
8
 
9
9
  ### Dependencies
10
10
 
11
11
  - `@crvouga/mockingbird-service-sqlite`
12
12
 
13
+ ## 3.2.0 (2026-10-08)
14
+
15
+ ### Features
16
+
17
+ - match Emulate provider coverage ([16b65ce](https://github.com/crvouga/mockingbird/commit/16b65ce791fa216f28ec1521df636f57771d9c5e))
18
+
13
19
  ## 3.1.0 (2026-10-08)
14
20
 
15
21
  ### Features
package/DISCOVERY.md CHANGED
@@ -35,6 +35,7 @@ repository; live parity is an additional oracle check, not a substitute for the
35
35
 
36
36
  - `GET /__admin/health`
37
37
  - `GET /__admin`
38
+ - `GET /__admin/controls`
38
39
  - `GET /__admin/state`
39
40
  - `GET /__admin/requests`
40
41
  - `GET /__admin/metrics`
@@ -45,6 +46,28 @@ For HTTP services, use `x-mockingbird-namespace` (or the documented credential/p
45
46
  parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
46
47
  designed for assertions and diagnosis by consuming test suites.
47
48
 
49
+ ## Admin controls
50
+
51
+ Every HTTP emulator takes the same controls, and each means the same thing at boot
52
+ (`createRuntime({ adminControls })`, `serve --admin-controls`), over `/__admin`, and in a request header:
53
+
54
+ | Control | Admin API | Request header | Interface |
55
+ | --- | --- | --- | --- |
56
+ | Isolate state by key | `GET /__admin/namespaces` | `x-mockingbird-namespace: <key>` | [Namespaces](https://mockingbird.chrisvouga.dev/docs/admin-controls/namespaces) |
57
+ | Reset to boot | `POST /__admin/reset` | `x-mockingbird-reset: true` | [Reset](https://mockingbird.chrisvouga.dev/docs/admin-controls/reset) |
58
+ | Snapshot and restore | `POST /__admin/snapshots`, `POST /__admin/snapshots/<id>/restore` | `x-mockingbird-snapshot: <name>`, `x-mockingbird-restore: <name>` | [Snapshot and restore](https://mockingbird.chrisvouga.dev/docs/admin-controls/snapshot-and-restore) |
59
+ | Move the clock | `POST /__admin/clock` | `x-mockingbird-time: <instant>`, `x-mockingbird-advance: <duration>` | [Clock](https://mockingbird.chrisvouga.dev/docs/admin-controls/clock) |
60
+ | Read or branch from old state | `GET /__admin/timeline` | `x-mockingbird-at: <checkpoint>`, `x-mockingbird-branch: <name>` | [Checkpoints and branches](https://mockingbird.chrisvouga.dev/docs/admin-controls/checkpoints-and-branches) |
61
+ | Inject a fault | `POST /__admin/faults` | `x-mockingbird-fault: <fault>` | [Faults](https://mockingbird.chrisvouga.dev/docs/admin-controls/faults) |
62
+ | Latency and timeouts | `PUT /__admin/latency` | `x-mockingbird-delay: <duration>`, `x-mockingbird-timeout: <duration>` | [Latency and timeouts](https://mockingbird.chrisvouga.dev/docs/admin-controls/latency-and-timeouts) |
63
+ | Replay from a seed | `PUT /__admin/controls` | `x-mockingbird-seed: <seed>` | [Seed and determinism](https://mockingbird.chrisvouga.dev/docs/admin-controls/seed-and-determinism) |
64
+ | See what happened | `GET /__admin/requests`, `GET /__admin/state` | | [Journal, metrics and state](https://mockingbird.chrisvouga.dev/docs/admin-controls/journal-and-state) |
65
+
66
+ `GET /__admin` lists every route and header with a one-line summary, and `GET /__admin/controls`
67
+ is the namespace's current control document. The same seed and the same requests give the same
68
+ bytes. Setting controls as an emulator starts is [Boot](https://mockingbird.chrisvouga.dev/docs/admin-controls/boot); every route and header is in
69
+ the [Reference](https://mockingbird.chrisvouga.dev/docs/admin-controls/reference). The full guide: <https://mockingbird.chrisvouga.dev/docs/admin-controls>.
70
+
48
71
  ## Report a mismatch or missing capability
49
72
 
50
73
  Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
package/README.md CHANGED
@@ -37,36 +37,48 @@ npx mockingbird-customerio serve --port 8810 \
37
37
  --webhook-secret "$CUSTOMERIO_REPORTING_WEBHOOK_SIGNING_KEY"
38
38
  ```
39
39
 
40
- ```js
40
+ ```ts
41
41
  import { Analytics } from "@customerio/cdp-analytics-node"
42
42
  import { createServer } from "@crvouga/mockingbird-service-customerio/server"
43
43
 
44
44
  const cio = await createServer({
45
45
  webhooks: { url: "http://127.0.0.1:3000/v1/customer-io/reporting-webhook", secret: "k".repeat(32) },
46
46
  })
47
+
48
+ // The application's CDP client. Only its host changes.
47
49
  const analytics = new Analytics({ writeKey: "wk", host: cio.url, maxEventsInBatch: 1 })
48
50
  analytics.identify({ userId: "42", traits: { email: "ada@example.com" } })
49
51
  await analytics.closeAndFlush()
50
52
 
51
- // The member unsubscribes in Customer.io: the signed reporting event reaches the backend.
53
+ // Test control. The member unsubscribes in Customer.io: the signed reporting event reaches the backend.
52
54
  await fetch(`${cio.url}/__admin/reporting-events`, {
53
55
  method: "POST",
54
56
  headers: { "content-type": "application/json" },
55
57
  body: JSON.stringify({ metric: "unsubscribed", userId: "42", objectType: "customer" }),
56
58
  })
59
+ await cio.close()
57
60
  ```
58
61
 
59
- Without the SDK, drive the emulator directly and read back what the app sent:
62
+ Transactional sends go through the App API client (`customerio-node`), pointed at the same
63
+ emulator. The test then reads back what the app sent:
60
64
 
61
65
  ```ts
66
+ import { Analytics } from "@customerio/cdp-analytics-node"
67
+ import { APIClient, SendEmailRequest } from "customerio-node"
62
68
  import { createServer } from "@crvouga/mockingbird-service-customerio/server"
63
69
 
64
70
  const cio = await createServer()
65
- await fetch(`${cio.url}/v1/identify`, {
66
- method: "POST",
67
- headers: { "content-type": "application/json", authorization: `Basic ${btoa("wk:")}` },
68
- body: JSON.stringify({ userId: "42", traits: { email: "ada@example.com" } }),
69
- })
71
+
72
+ // The application's clients. Only the CDP host and the App API url change.
73
+ const analytics = new Analytics({ writeKey: "wk", host: cio.url, maxEventsInBatch: 1 })
74
+ const api = new APIClient("app-key", { url: `${cio.url}/v1` })
75
+ analytics.identify({ userId: "42", traits: { email: "ada@example.com" } })
76
+ await analytics.closeAndFlush()
77
+ await api.sendEmail(
78
+ new SendEmailRequest({ transactional_message_id: 1, identifiers: { id: "42" }, to: "ada@example.com" }),
79
+ )
80
+
81
+ // Test assertions read the emulator's state.
70
82
  const profiles = await (await fetch(`${cio.url}/__admin/profiles`)).json()
71
83
  const deliveries = await (await fetch(`${cio.url}/__admin/outbox?userId=42`)).json()
72
84
  await cio.close()