@crvouga/mockingbird-service-customerio 1.5.1 → 1.6.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 +11 -4
- package/README.md +31 -19
- package/dist/{chunk-VVKQ5YMB.js → chunk-LKYGOY6Z.js} +365 -56
- package/dist/{chunk-VVKQ5YMB.js.map → chunk-LKYGOY6Z.js.map} +2 -2
- package/dist/{chunk-24PW46BB.js → chunk-YH4VUBB3.js} +4 -3
- package/dist/chunk-YH4VUBB3.js.map +7 -0
- package/dist/cli.js +2 -2
- package/dist/index.d.ts +75 -10
- package/dist/index.js +5 -1
- package/dist/server.d.ts +78 -13
- package/dist/server.js +2 -2
- package/package.json +1 -1
- package/dist/chunk-24PW46BB.js.map +0 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,14 +1,21 @@
|
|
|
1
1
|
# Changelog — @crvouga/mockingbird-service-customerio
|
|
2
2
|
|
|
3
|
-
## 1.
|
|
3
|
+
## 1.6.0 (2026-09-30)
|
|
4
|
+
|
|
5
|
+
### Features
|
|
6
|
+
|
|
7
|
+
- boot Bolt over Socket Mode ([01322df](https://github.com/crvouga/mockingbird/commit/01322df315c66b1f2f5b53094cbbeeeef6d3ae6c))
|
|
8
|
+
- complete the notification contract ([98c3b33](https://github.com/crvouga/mockingbird/commit/98c3b333a8bc983d20493b94e1d1e74afa998328))
|
|
4
9
|
|
|
5
10
|
### Fixes and improvements
|
|
6
11
|
|
|
7
|
-
-
|
|
12
|
+
- list delivery state exports in the API section ([3d7eba5](https://github.com/crvouga/mockingbird/commit/3d7eba5ae1d15a6f563fc6ee2245a8d74a29b7b1))
|
|
8
13
|
|
|
9
|
-
|
|
14
|
+
## 1.5.1 (2026-09-29)
|
|
10
15
|
|
|
11
|
-
|
|
16
|
+
### Fixes and improvements
|
|
17
|
+
|
|
18
|
+
- keep hosted pages inside narrow hosts and popups ([6512323](https://github.com/crvouga/mockingbird/commit/6512323198cb00b99005f3d2cfa5b9f1e6e321a7))
|
|
12
19
|
|
|
13
20
|
## 1.5.0 (2026-09-29)
|
|
14
21
|
|
package/README.md
CHANGED
|
@@ -5,10 +5,10 @@
|
|
|
5
5
|
Stateful mock of **Customer.io** for test suites, serving all three hosts our code talks to from
|
|
6
6
|
one process: the Segment-compatible **CDP** (`identify`, `track`, `batch`, exactly as
|
|
7
7
|
`@customerio/cdp-analytics-node` posts them), the **App API** transactional sends (email, SMS,
|
|
8
|
-
inbox message)
|
|
9
|
-
outbox a suite asserts on (and reads links out
|
|
10
|
-
`subscribed`, `spammed`, subscription preferences,
|
|
11
|
-
signed the way Customer.io signs them.
|
|
8
|
+
inbox message), message catalog, profile attribute reads, and delivery-status reads, and the
|
|
9
|
+
**link-tracking** click endpoint. Sends land in an outbox a suite asserts on (and reads links out
|
|
10
|
+
of); reporting events (`unsubscribed`, `subscribed`, `spammed`, subscription preferences,
|
|
11
|
+
`clicked`) are posted to our reporting webhook, signed the way Customer.io signs them.
|
|
12
12
|
|
|
13
13
|
- Operation coverage: [SUPPORT.md](https://github.com/crvouga/mockingbird/blob/main/packages/service/customerio/SUPPORT.md)
|
|
14
14
|
- The contract (`openapi.yaml`) is hand-authored from Customer.io's CDP (Segment spec) and App API
|
|
@@ -76,10 +76,12 @@ await cio.close()
|
|
|
76
76
|
|
|
77
77
|
| Route | Behaviour |
|
|
78
78
|
| --- | --- |
|
|
79
|
-
| `POST /v1/identify`, `/v1/track`, `/v1/batch` | CDP, `Authorization: Basic base64(<write key>:)` (else 401 `{error}`). Segment events (`batch` of `identify` / `track`); each needs `userId` or `anonymousId` (else 400 `{error}`, which the SDK does not retry). → `{success: true}`. Identify merges traits
|
|
80
|
-
| `POST /v1/send/email`, `/v1/send/sms`, `/v1/send/inbox_message` | App API, `Authorization: Bearer <app key>` (else 401 `{meta: {error}}`). `{transactional_message_id (id or trigger name), identifiers:
|
|
81
|
-
| `GET /v1/transactional` | `{messages: [{id, name, trigger_name, description, send_to_unsubscribed, link_tracking, …}]}`, no pagination. Seeded with `acme_<key>` for every legacy email key the consumer app has, plus `acme_inbox_message` and `acme_playground_notification` (ids 1–21). |
|
|
82
|
-
| `GET /v1/transactional/{id}` | `{message: {...}}` by id or trigger name, or 404. |
|
|
79
|
+
| `POST /v1/identify`, `/v1/track`, `/v1/batch` | CDP, `Authorization: Basic base64(<write key>:)` (else 401 `{error}`). Segment events (`batch` of `identify` / `track`); each needs `userId` or `anonymousId` (else 400 `{error}`, which the SDK does not retry). A batch is validated before any entry is applied. → `{success: true}`. Identify shallow-merges traits; `cio_subscription_preferences.channels` / `.topics` merge one level so omitted keys and explicit `false` remain. Concurrent identifies on one profile are serialized. A repeated `messageId` is recorded as a duplicate and not applied. |
|
|
80
|
+
| `POST /v1/send/email`, `/v1/send/sms`, `/v1/send/inbox_message` | App API, `Authorization: Bearer <app key>` (else 401 `{meta: {error}}`). `{transactional_message_id (id or trigger name, case-insensitive), identifiers: exactly one of id \| email \| cio_id, to?, from?, subject?, message_data?, send_to_unsubscribed?, tracked?, disable_message_retention?, headers?, attachments?}` → `{delivery_id, queued_at}`. Validation errors are 400 `{meta: {error}}`. SMS `to`, when present, must be E.164. With `strictMessages`, an unknown id is 400 `{meta: {error: "transactional_message_id not found"}}`. An `identifiers.id` with no profile creates a minimal one; `to` stays the literal recipient. Accepted sends start `pending` (not delivered). A profile that unsubscribed, or whose email/SMS channel is `false`, gets `suppressed` unless `send_to_unsubscribed` (inbox follows only the unsubscribed flag). `disable_message_retention` drops `message_data` from the outbox unless `retainMessageDataForTests`. `tracked: true` rewrites every URL to `<trackingBase>/click/<linkId>`. There is no send idempotency: a repeat creates another delivery. |
|
|
81
|
+
| `GET /v1/transactional` | `{messages: [{id, name, trigger_name, description, send_to_unsubscribed, link_tracking, …}]}`, no pagination (the whole catalog, including hundreds of rows). Seeded with `acme_<key>` for every legacy email key the consumer app has, plus `acme_inbox_message` and `acme_playground_notification` (ids 1–21). `transactionalListKey: "transactional"` renames the array key. |
|
|
82
|
+
| `GET /v1/transactional/{id}` | `{message: {...}}` by id or trigger name (case-insensitive), or 404. |
|
|
83
|
+
| `GET /v1/customers/{customer_id}/attributes?id_type=id\|email\|cio_id` | `{customer: {identifiers: {id, email?, cio_id}, attributes, devices}}`. Unknown `id_type` is 400; an unknown customer is 404. Attributes spread stored traits, then `id`, `cio_id`, `email`, and `unsubscribed` win. |
|
|
84
|
+
| `GET /v1/messages/{delivery_id}` | `{message: {id, type, recipient, customer_id, created, state, status, metrics}}`. `type` is `in_app` for inbox. No `message_data`. 404 when the id is missing or still inside `statusVisibleAfterMs`. Failure states add `failure_message`, `rejection_reason`, and `error`. |
|
|
83
85
|
| `POST /click/{linkId}` | Our backend's click report (unauthenticated) → 200, counts the click and posts a `clicked` reporting event. Unknown link: plain-text 404. |
|
|
84
86
|
| `GET /click/{linkId}` | A browser following a tracked link → 302 to the original URL. |
|
|
85
87
|
|
|
@@ -97,21 +99,29 @@ is the JSON string of subscription preferences. `timestamp` never runs ahead of
|
|
|
97
99
|
|
|
98
100
|
| Route | Effect |
|
|
99
101
|
| --- | --- |
|
|
100
|
-
| `GET /__admin/outbox?to=&since=&channel=&transactional_message_id=&userId=` | Transactional deliveries, oldest first (`GET /__admin/outbox/:id` for one): `channel`, `to`, `identifiers`, `subject`, `messageData`, `links`, `tracked`, `state` (`
|
|
102
|
+
| `GET /__admin/outbox?to=&recipient=&since=&channel=&transactional_message_id=&userId=&deliveryId=` | Transactional deliveries, oldest first (`GET /__admin/outbox/:id` for one): `channel`, `to`, `identifiers`, `subject`, `messageData`, `links`, `originalLinks`, `tracked`, `state` (`pending` until transitioned, or `suppressed`), `reason`, `metrics`, `clicks`, `attachments` (filenames). `recipient` matches `to`. The journal records method, path, and status, never the body, the API key, or message content. |
|
|
101
103
|
| `POST /__admin/reporting-events` | `{metric, userId? \| email? \| deliveryId?, objectType?, preferences?: {topics?, channels?}}`: apply it to the profile (`unsubscribed`, `subscribed`, `spammed`, `cio_subscription_preferences_changed`) and post the signed event. Any other metric (`delivered`, `opened`, `bounced`, …) is posted as-is. |
|
|
102
104
|
| `GET /__admin/cdp/events?userId=&type=&event=` | CDP calls received (with `duplicate`). |
|
|
103
|
-
| `GET /__admin/profiles`, `GET /__admin/profiles/:id` | Profiles (traits, `unsubscribed`, `channelsOff`). |
|
|
105
|
+
| `GET /__admin/profiles`, `GET /__admin/profiles/:id`, `PUT /__admin/profiles/:id` | Profiles (traits, `cioId`, `unsubscribed`, `channelsOff`, `preferences`). PUT merges `{traits?, email?, unsubscribed?, preferences?}`. |
|
|
106
|
+
| `POST /__admin/deliveries/:id` | `{"state": "pending"\|"sent"\|"delivered"\|"bounced"\|"dropped"\|"failed"\|"spammed"\|"undeliverable"\|"suppressed"}`. Stamps `metrics[state]` with unix seconds on the namespace clock. `delivered` is success; the failure states are terminal. |
|
|
107
|
+
| `POST /__admin/namespace-clock` | `{"advance": <ms>}` adds to this namespace's clock offset only. |
|
|
104
108
|
| `GET\|PUT /__admin/transactional` | Read or replace the workspace's transactional messages (`[{id?, name?, trigger_name, link_tracking?, send_to_unsubscribed?}]`). |
|
|
105
|
-
| `GET\|PUT /__admin/settings` | `{strictMessages?, trackingBase?, keys?}` (`keys` restricts accepted write / App API keys). |
|
|
109
|
+
| `GET\|PUT /__admin/settings` | `{strictMessages?, trackingBase?, keys?, statusVisibleAfterMs?, clockOffsetMs?, retainMessageDataForTests?, transactionalListKey?}` (`keys` restricts accepted write / App API keys). |
|
|
106
110
|
|
|
107
111
|
Fault presets (`POST /__admin/faults {"preset": "<name>", "count"?: n}`; `GET /__admin/faults/presets`):
|
|
108
|
-
`transactional_message_missing` (400 meta.error: `trigger_name_missing`, then fallback),
|
|
109
|
-
`transactional_404`, `request_timeout_408` (
|
|
110
|
-
(500, ambiguous), `accepted_but_500` (queued, then 500), `rate_limited`
|
|
111
|
-
`
|
|
112
|
-
|
|
113
|
-
`
|
|
114
|
-
`
|
|
112
|
+
`transactional_message_missing` (400 meta.error: `trigger_name_missing`, then fallback; no delivery),
|
|
113
|
+
`transactional_404`, `request_timeout_408` (408 before enqueue, no delivery, ambiguous), `server_error`
|
|
114
|
+
(500 before enqueue, no delivery, ambiguous), `accepted_but_500` (queued, then 500), `rate_limited`
|
|
115
|
+
(429 with numeric `Retry-After`, definite, no delivery), `invalid_app_key`, `send_drop` and
|
|
116
|
+
`send_drop_before_accept` (socket closes before enqueue: ambiguous, no delivery),
|
|
117
|
+
`send_drop_after_accept` (delivery recorded, then the socket closes: ambiguous, one delivery),
|
|
118
|
+
`cdp_unavailable` (503; the SDK retries), `cdp_bad_request` (400; no retry), `cdp_slow` (15 s, past
|
|
119
|
+
the 10 s delivery timeout), `transactional_list_unavailable`, `omit_trigger_names` (omit every
|
|
120
|
+
`trigger_name`, or only `params.ids`), `webhook_duplicate`, `webhook_drop`, `webhook_reorder`.
|
|
121
|
+
A manual fault can inject 403 or 503, or a 429 whose `Retry-After` is an HTTP-date. ECONNREFUSED
|
|
122
|
+
(a definite failure) is a stopped mock, not a preset. 401 is `{error}` on the CDP and
|
|
123
|
+
`{meta: {error}}` on the App API. Keys mapped to the same namespace share profiles and deliveries;
|
|
124
|
+
two namespaces do not, including faults and clock offsets. Resetting one namespace leaves the other.
|
|
115
125
|
|
|
116
126
|
### Namespaces
|
|
117
127
|
|
|
@@ -134,7 +144,7 @@ username) or the App API key (Bearer) through `PUT /__admin/credentials {"creden
|
|
|
134
144
|
|
|
135
145
|
| Export | Kind | Description |
|
|
136
146
|
| --- | --- | --- |
|
|
137
|
-
| `CustomerIoAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `report(input)`, `profiles()`, `state`. Options: `sqlite`, `now`, `wallClock`, `namespace`, `messages`, `settings`, `onReport`. |
|
|
147
|
+
| `CustomerIoAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `report(input)`, `profiles()`, `mergeProfile(id, patch)`, `transitionDelivery(id, state)`, `advanceClock(ms)`, `state`. Options: `sqlite`, `now`, `wallClock`, `namespace`, `messages`, `settings`, `onReport`. |
|
|
138
148
|
| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, outbox, reporting webhooks). Options: `webhooks: {url, secret, retryDelaysMs?, fetch?}`, `messages`, `settings`, `clock`, `wallClock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
|
|
139
149
|
| `CUSTOMERIO_PRESETS` | object | Every named fault preset. |
|
|
140
150
|
| `CUSTOMERIO_NAMESPACE` | string | The service name, `"customerio"`. |
|
|
@@ -142,6 +152,8 @@ username) or the App API key (Bearer) through `PUT /__admin/credentials {"creden
|
|
|
142
152
|
| `signReporting` | function | `(secret, timestampSeconds, body)` → the hex `x-cio-signature`. |
|
|
143
153
|
| `customerIoCredential` | function | The write key or App API key a request carries. |
|
|
144
154
|
| `DEFAULT_TRANSACTIONAL_MESSAGES`, `DEFAULT_SETTINGS`, `TRANSACTIONAL_EMAIL_KEYS` | values | The seeded catalog, settings, and our backend's legacy email keys. |
|
|
155
|
+
| `DELIVERY_STATES` | values | Delivery lifecycle states. An accepted send starts at `pending`. |
|
|
156
|
+
| `FAILURE_STATES` | values | Terminal failure states: `bounced`, `dropped`, `failed`, `spammed`, `undeliverable`, `suppressed`. `delivered` is success; `sent` stays open. |
|
|
145
157
|
| `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
|
|
146
158
|
| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target; port 8810. |
|
|
147
159
|
|