@crvouga/mockingbird-service-customerio 1.5.1 → 1.6.1

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,14 +1,29 @@
1
1
  # Changelog — @crvouga/mockingbird-service-customerio
2
2
 
3
- ## 1.5.1 (2026-09-30)
3
+ ## 1.6.1 (2026-09-30)
4
4
 
5
5
  ### Fixes and improvements
6
6
 
7
- - keep hosted pages inside narrow hosts and popups ([6512323](https://github.com/crvouga/mockingbird/commit/6512323198cb00b99005f3d2cfa5b9f1e6e321a7))
7
+ - keep admin buttons pressed until the action finishes ([0aabfcb](https://github.com/crvouga/mockingbird/commit/0aabfcb5f392aa51e193f9c3f817d5877d92bc6a))
8
+ - size admin select fields like the text inputs beside them ([0fb3ef2](https://github.com/crvouga/mockingbird/commit/0fb3ef2ddbf43376c93a2ae6d87c6c9bf890dafc))
9
+ - keep admin section tabs wired when boot is renamed ([4eda25e](https://github.com/crvouga/mockingbird/commit/4eda25eacd59da048d196f7cc8369d7a02b47bfc))
10
+
11
+ ## 1.6.0 (2026-09-29)
12
+
13
+ ### Features
14
+
15
+ - boot Bolt over Socket Mode ([01322df](https://github.com/crvouga/mockingbird/commit/01322df315c66b1f2f5b53094cbbeeeef6d3ae6c))
16
+ - complete the notification contract ([98c3b33](https://github.com/crvouga/mockingbird/commit/98c3b333a8bc983d20493b94e1d1e74afa998328))
8
17
 
9
- ### Dependencies
18
+ ### Fixes and improvements
10
19
 
11
- - `@crvouga/mockingbird-service-sqlite`
20
+ - list delivery state exports in the API section ([3d7eba5](https://github.com/crvouga/mockingbird/commit/3d7eba5ae1d15a6f563fc6ee2245a8d74a29b7b1))
21
+
22
+ ## 1.5.1 (2026-09-29)
23
+
24
+ ### Fixes and improvements
25
+
26
+ - keep hosted pages inside narrow hosts and popups ([6512323](https://github.com/crvouga/mockingbird/commit/6512323198cb00b99005f3d2cfa5b9f1e6e321a7))
12
27
 
13
28
  ## 1.5.0 (2026-09-29)
14
29
 
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) and message catalog, and the **link-tracking** click endpoint. Sends land in an
9
- outbox a suite asserts on (and reads links out of); reporting events (`unsubscribed`,
10
- `subscribed`, `spammed`, subscription preferences, `clicked`) are posted to our reporting webhook,
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 into the profile (`email`, `unsubscribed`); 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), identifiers: {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}}`. With `strictMessages`, an id that is neither a catalog id nor a trigger name is 400 `{meta: {error: "transactional_message_id not found"}}`. A profile that unsubscribed (or switched the channel off) gets a `suppressed` delivery unless `send_to_unsubscribed`. `disable_message_retention` keeps no `message_data` in the outbox. `tracked: true` rewrites every URL in `message_data` to `<trackingBase>/click/<linkId>`. `to` defaults to the profile's email (email) or `phone` trait (SMS). |
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` (`sent` / `suppressed`), `clicks`, `attachments` (filenames). |
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` (ambiguous: the reservation is kept), `server_error`
110
- (500, ambiguous), `accepted_but_500` (queued, then 500), `rate_limited` (429, definite),
111
- `invalid_app_key`, `send_drop` (socket closes mid-request: ambiguous), `cdp_unavailable` (503;
112
- the SDK retries), `cdp_bad_request` (400; no retry), `cdp_slow` (15 s), `transactional_list_unavailable`,
113
- `omit_trigger_names` (the validator falls back to per-id reads), `webhook_duplicate`,
114
- `webhook_drop`. ECONNREFUSED (a definite failure) is a stopped mock, not a preset.
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