@crvouga/mockingbird-service-intercom 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,15 +1,17 @@
 # Changelog — @crvouga/mockingbird-service-intercom
 
+## 1.1.0 (2026-09-25)
+
+### Features
+
+- metadata-only outbox, opt-in member webhook topics, and promote to ready ([4d635e9](https://github.com/crvouga/mockingbird/commit/4d635e90e1938dd5814ac33c10c92c768321a15b))
+
 ## 1.0.0 (2026-09-24)
 
 ### ⚠️ Breaking changes
 
 - vendor branding for every service; purge internal mocks and consumer names ([f689534](https://github.com/crvouga/mockingbird/commit/f6895343543550dafcb7d76b426cae7635e03226))
 
-### Dependencies
-
-- `@crvouga/mockingbird-service-sqlite`
-
 ## 0.2.0 (2026-09-23)
 
 ### Features

package/README.md

@@ -9,7 +9,8 @@ our backend makes:
   `?display_as=plaintext`, and cursor-paginated search;
 - **identity:** `/admins` and `/me`.
 
-Admin replies and close/open send Intercom's `notification_event` webhooks, signed with
+Admin replies and close/open (and, for a receiver that subscribes to them, member messages and
+replies) send Intercom's `notification_event` webhooks, signed with
 `X-Hub-Signature: sha1=<hex HMAC-SHA1>`, to both of our receivers: the backend's
 `POST /messaging/webhook` and the EMR's `POST /v1/webhooks/intercom`.
 
@@ -36,6 +37,10 @@ npx mockingbird-intercom serve --port 8807 \
   --webhook-secret "$INTERCOM_WEBHOOK_SECRET"
 ```
 
+Add `--webhook-events conversation.user.created,conversation.user.replied,conversation.admin.replied,conversation.admin.closed,conversation.admin.opened`
+to subscribe `--webhook-url` to the member topics too; `--emr-webhook-url` keeps the admin-only
+default.
+
 | Consumer | Setting |
 | --- | --- |
 | Member messaging adapter (`intercom-messaging.adapter.ts`) | `INTERCOM_API_BASE_URL=http://127.0.0.1:8807` (already read), `INTERCOM_ACCESS_TOKEN=<any>` |
@@ -124,11 +129,14 @@ The mock sends webhooks for these events:
 | Close (`/parts` or `POST /__admin/conversations/:id/close`) | `conversation.admin.closed` |
 | Open (`/parts` or `POST /__admin/conversations/:id/open`) | `conversation.admin.opened` |
 | Admin-initiated conversation (`POST /__admin/conversations`) | `conversation.admin.single.created` |
+| Member starts a conversation (`POST /conversations`) | `conversation.user.created` (opt-in) |
+| Member reply (`/reply` with `type: "user"`) | `conversation.user.replied` (opt-in) |
 
-Snooze and assignment publish `conversation.admin.snoozed` and `.assigned`, but the default
-endpoints do not subscribe to them. Member messages and notes send nothing: the EMR treats every
-`notification_event` it receives as an admin event, so a real subscription must not include
-member topics either.
+An endpoint receives the four admin topics above unless it lists its own `events`. The member
+topics, `conversation.admin.snoozed` and `.assigned` are published but opt-in: subscribe with
+`--webhook-events`, `webhooks.urls: [{url, events}]` or `PUT /__admin/webhook-endpoints`. The EMR
+treats every `notification_event` it receives as an admin event, so its subscription must not
+include member topics. Notes send nothing.
 
 Each delivery is a JSON body posted with `X-Hub-Signature: sha1=<hex HMAC-SHA1(secret, rawBody)>`:
 
@@ -156,7 +164,8 @@ Each delivery is a JSON body posted with `X-Hub-Signature: sha1=<hex HMAC-SHA1(s
 
 | Route | Effect |
 | --- | --- |
-| `POST /__admin/conversations/:id/admin-reply` | `{adminId? (default: first admin), body, messageType?: "comment" \| "note"}` appends an admin part and fires the webhook. |
+| `POST /__admin/conversations/:id/admin-reply` | `{adminId? \| admin_id? (default: first admin), body, messageType?: "comment" \| "note"}` appends an admin part ("the care team replied") and fires the webhook. |
+| `GET /__admin/outbox?since=&to=&limit=`, `GET /__admin/outbox/:id` | What the client sent through `POST /conversations` and `/reply`, oldest first: `{id, operation, conversationId, contactId, partId, partType ("source" for the opening message), authorType, authorId, hasBody, bodyLength, attachmentCount, at, createdAt}`. **Metadata only**: the body is never stored. `to=` matches the conversation or contact id; `since=` takes epoch ms or ISO-8601 on the mock clock. The admin plane's own replies are not listed. |
 | `POST /__admin/conversations/:id/close`, `…/open` | `{adminId?}` closes or reopens as an admin and fires the webhook. |
 | `POST /__admin/conversations` | `{contactId \| externalId, adminId?, body}` creates an admin-initiated conversation. The EMR then looks the member up by `contacts[0].external_id`. |
 | `GET /__admin/conversations`, `GET /__admin/contacts` | The namespace's records. |
@@ -205,14 +214,14 @@ never records message bodies or contact details.
 | --- | --- | --- |
 | `IntercomAPI` | class | The in-process mock: `fetch(request)`, `reset()`, `appendPart(…)`, `manage(…)`, `startAdminConversation(…)`, `conversations()`, `contacts()`, `conversationBody(…)`, `contactBody(…)`, `error(…)`, `state`. Options: `sqlite`, `now`, `wallClock`, `namespace`, `admins`, `settings`, `onWebhook`. |
 | `IntercomError` | class | A vendor error (status, code, message) raised by the admin-facing methods. |
-| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, webhooks). Options: `webhooks: {urls, secret?, events?, retryDelaysMs?, fetch?}`, `admins`, `settings`, `clock`, `wallClock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
+| `createRuntime` | function | The mock with the full service contract (health, admin, namespaces, credentials, presets, webhooks). Options: `webhooks: {urls, secret?, events?, retryDelaysMs?, fetch?}` (a `urls` entry may be `{url, events}` to override `events` for that URL), `admins`, `settings`, `clock`, `wallClock`, `seed`, `adminKey`, `onLog`, `sqlite`. |
 | `INTERCOM_PRESETS` | object | Every named fault preset. |
 | `INTERCOM_NAMESPACE` | string | The service name, `"intercom"`. |
-| `INTERCOM_TOPICS` | array | Every webhook topic the mock can send. |
+| `INTERCOM_TOPICS` | array | Every webhook topic the mock can send, including the opt-in member topics. |
 | `HUB_SIGNATURE_HEADER`, `signHub` | values | `X-Hub-Signature` and the `sha1=<hex>` signer, for your own receivers. |
 | `DEFAULT_ADMINS`, `DEFAULT_SETTINGS` | values | The seeded admins and default settings. |
 | `toHtml`, `toPlaintext`, `encodeCursor`, `decodeCursor` | functions | Body rendering and the search cursor format. |
 | `document`, `operationIds`, `supportedOperationIds` | values | The vendored OpenAPI contract and its operation ids. |
-| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--webhook-url`, `--emr-webhook-url`, `--webhook-secret`, `--access-token`); port 8807. |
+| `createServer`, `serveTarget`, `DEFAULT_PORT` (`./server`) | Node | Serve over `node:http`; the `serve` CLI target (`--webhook-url`, `--webhook-events`, `--emr-webhook-url`, `--webhook-secret`, `--access-token`); port 8807. |
 
 Part of [mockingbird](https://github.com/crvouga/mockingbird).

package/dist/{chunk-OSBG2XJ7.js → chunk-DOY3BICO.js}

@@ -1149,6 +1149,73 @@ var createMetrics = () => {
   };
 };
 
+// ../core/dist/outbox.js
+var OutboxStore = class {
+  items;
+  constructor(sqlite, namespace, name = "outbox") {
+    this.items = new Collection(sqlite, namespace, name);
+  }
+  record(item) {
+    this.items.insert(item.id, item);
+    return item;
+  }
+  get(id) {
+    return this.items.get(id);
+  }
+  update(id, item) {
+    this.items.update(id, item);
+  }
+  /** Oldest first, so a suite reads messages in the order they were sent. */
+  list(query = {}) {
+    const to = query.to?.toLowerCase();
+    const matched = this.items.list({ order: "oldest" }).map((row) => row.value).filter((item) => {
+      if (to !== void 0) {
+        const recipients = Array.isArray(item.to) ? item.to : [item.to];
+        if (!recipients.some((r) => r.toLowerCase() === to))
+          return false;
+      }
+      if (query.since !== void 0 && Date.parse(item.createdAt) < query.since)
+        return false;
+      if (query.where && !query.where(item))
+        return false;
+      return true;
+    });
+    return query.limit !== void 0 ? matched.slice(-Math.max(0, query.limit)) : matched;
+  }
+};
+var json2 = (status, body) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+var parseSince = (value) => {
+  if (value === null)
+    return void 0;
+  const parsed = /^\d+$/.test(value) ? Number(value) : Date.parse(value);
+  return Number.isNaN(parsed) ? null : parsed;
+};
+var outboxAdminRoutes = (runtime, pick, filter) => ({
+  "GET /outbox": ({ url, namespace }) => {
+    const since = parseSince(url.searchParams.get("since"));
+    if (since === null) {
+      return json2(400, {
+        error: { type: "mockingbird_admin", message: "since: expected epoch ms or ISO-8601" }
+      });
+    }
+    const limit = url.searchParams.get("limit");
+    const where = filter?.(url.searchParams);
+    const to = url.searchParams.get("to");
+    return json2(200, {
+      messages: pick(runtime.instance(namespace)).list({
+        ...to !== null ? { to } : {},
+        ...since !== void 0 ? { since } : {},
+        ...where ? { where } : {},
+        ...limit !== null && /^\d+$/.test(limit) ? { limit: Number(limit) } : {}
+      })
+    });
+  },
+  "GET /outbox/:id": ({ params, namespace }) => {
+    const item = pick(runtime.instance(namespace)).get(params.id);
+    return item ? json2(200, item) : json2(404, { error: { type: "mockingbird_admin", message: `no message ${params.id}` } });
+  }
+});
+
 // ../../core/dist/timeline.js
 var BRANCH_PATTERN = /^[A-Za-z0-9_.-]{1,64}$/;
 var Timeline = class {
@@ -1531,7 +1598,7 @@ var restoreNamespace = (sqlite, namespace, snapshot) => {
 };
 
 // ../core/dist/version.js
-var PACKAGE_VERSION = true ? "1.0.0" : UNRELEASED_VERSION;
+var PACKAGE_VERSION = true ? "1.1.0" : UNRELEASED_VERSION;
 
 // ../core/dist/signing.js
 var encoder = new TextEncoder();
@@ -1854,8 +1921,8 @@ var createWebhookHub = (options) => {
   };
   return hub;
 };
-var json2 = (status, body) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
-var adminError2 = (status, message) => json2(status, { error: { type: "mockingbird_admin", message } });
+var json3 = (status, body) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+var adminError2 = (status, message) => json3(status, { error: { type: "mockingbird_admin", message } });
 var isRecord3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var parseEndpoint = (value) => {
   if (!isRecord3(value) || typeof value.url !== "string")
@@ -1886,7 +1953,7 @@ var parseEndpoint = (value) => {
   return endpoint;
 };
 var webhookAdminRoutes = (hub) => ({
-  "GET /webhooks": ({ url, namespace }) => json2(200, {
+  "GET /webhooks": ({ url, namespace }) => json3(200, {
     deliveries: hub.deliveries(url.searchParams.get("all") === "1" ? void 0 : namespace).filter((d) => {
       const type = url.searchParams.get("type");
       return type === null || d.type === type;
@@ -1894,17 +1961,17 @@ var webhookAdminRoutes = (hub) => ({
   }),
   "GET /webhooks/events": ({ url, namespace }) => {
     const type = url.searchParams.get("type");
-    return json2(200, {
+    return json3(200, {
       events: hub.messages(url.searchParams.get("all") === "1" ? void 0 : namespace).filter((m) => type === null || m.type === type).map((m) => ({ ...m, payload: parsePayload(m) }))
     });
   },
   "POST /webhooks/:id/replay": async ({ params }) => {
     const replayed = await hub.replay(params.id);
-    return replayed ? json2(200, replayed) : adminError2(404, `no delivery ${params.id}`);
+    return replayed ? json3(200, replayed) : adminError2(404, `no delivery ${params.id}`);
   },
   "POST /webhooks/flush": async () => {
     await hub.flush();
-    return json2(200, { status: "ok" });
+    return json3(200, { status: "ok" });
   },
   "POST /webhooks/faults": ({ body, namespace }) => {
     if (!isRecord3(body) || !["duplicate", "reorder", "drop"].includes(String(body.mode))) {
@@ -1914,9 +1981,9 @@ var webhookAdminRoutes = (hub) => ({
     if (typeof body.count === "number")
       fault.count = body.count;
     hub.fault(namespace, fault);
-    return json2(201, { namespace, ...fault });
+    return json3(201, { namespace, ...fault });
   },
-  "GET /webhook-endpoints": ({ namespace }) => json2(200, {
+  "GET /webhook-endpoints": ({ namespace }) => json3(200, {
     endpoints: hub.endpoints(namespace).map(({ secret, ...rest }) => ({
       ...rest,
       secret: secret ? "(set)" : null
@@ -1934,11 +2001,11 @@ var webhookAdminRoutes = (hub) => ({
       parsed.push(endpoint);
     }
     const set = hub.setEndpoints(namespace, parsed);
-    return json2(200, { endpoints: set.map((e) => ({ ...e, secret: e.secret ? "(set)" : null })) });
+    return json3(200, { endpoints: set.map((e) => ({ ...e, secret: e.secret ? "(set)" : null })) });
   },
   "DELETE /webhook-endpoints": ({ namespace }) => {
     hub.setEndpoints(namespace, []);
-    return json2(200, { status: "ok" });
+    return json3(200, { status: "ok" });
   }
 });
 var parsePayload = (message) => {
@@ -2683,6 +2750,7 @@ var IntercomState = class {
     this.admins = new Collection(sqlite, namespace, "admins");
     this.settings = new Collection(sqlite, namespace, "settings");
     this.counters = new Collection(sqlite, namespace, "counters");
+    this.outbox = new OutboxStore(sqlite, namespace, "outbox");
     this.workspaceId = "mockapp";
     this.ensureSeeded();
   }
@@ -2693,6 +2761,7 @@ var IntercomState = class {
   admins;
   settings;
   counters;
+  outbox;
   workspaceId;
   ensureSeeded() {
     if (this.admins.count() === 0) {
@@ -2810,8 +2879,8 @@ var INTERCOM_PRESETS = {
     webhook: { mode: "drop" }
   }
 };
-var json3 = (status, body) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
-var adminError3 = (status, message) => json3(status, { error: { type: "mockingbird_admin", message } });
+var json4 = (status, body) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+var adminError3 = (status, message) => json4(status, { error: { type: "mockingbird_admin", message } });
 var isRecord5 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var guard = (run) => {
   try {
@@ -2826,8 +2895,9 @@ var adminRoutes = (runtime) => {
   const conversation = (namespace, id) => api(namespace).state.conversations.get(id);
   const defaultAdmin = (namespace) => api(namespace).state.admins.list({ order: "oldest" }).at(0)?.value.id ?? "";
   return {
-    "GET /contacts": ({ namespace }) => json3(200, { contacts: api(namespace).contacts() }),
-    "GET /conversations": ({ namespace }) => json3(200, { conversations: api(namespace).conversations() }),
+    ...outboxAdminRoutes(runtime, (instance) => instance.state.outbox),
+    "GET /contacts": ({ namespace }) => json4(200, { contacts: api(namespace).contacts() }),
+    "GET /conversations": ({ namespace }) => json4(200, { conversations: api(namespace).conversations() }),
     "POST /conversations": ({ body, namespace }) => guard(() => {
       if (!isRecord5(body) || typeof body.body !== "string") {
         return adminError3(400, 'expected {"contactId" | "externalId", "adminId"?, "body"}');
@@ -2840,7 +2910,7 @@ var adminRoutes = (runtime) => {
         adminId: typeof body.adminId === "string" ? body.adminId : defaultAdmin(namespace),
         body: body.body
       });
-      return json3(201, created);
+      return json4(201, created);
     }),
     "POST /conversations/:id/admin-reply": ({ params, body, namespace }) => guard(() => {
       const found = conversation(namespace, params.id);
@@ -2848,32 +2918,33 @@ var adminRoutes = (runtime) => {
       if (!isRecord5(body) || typeof body.body !== "string") {
         return adminError3(
           400,
-          'expected {"adminId"?, "body", "messageType"?: "comment" | "note"}'
+          'expected {"adminId" | "admin_id"?, "body", "messageType"?: "comment" | "note"}'
         );
       }
       const instance = api(namespace);
+      const requested = body.adminId ?? body.admin_id;
       const author = instance.state.admins.get(
-        typeof body.adminId === "string" ? body.adminId : defaultAdmin(namespace)
+        typeof requested === "string" ? requested : defaultAdmin(namespace)
       );
-      if (!author) return adminError3(404, `no admin ${String(body.adminId)}`);
+      if (!author) return adminError3(404, `no admin ${String(requested)}`);
       const next = instance.appendPart(found, {
         partType: body.messageType === "note" ? "note" : "comment",
         author: { type: "admin", id: author.id, name: author.name, email: author.email },
         body: toHtml(body.body)
       });
-      return json3(200, next);
+      return json4(200, next);
     }),
     "POST /conversations/:id/close": ({ params, body, namespace }) => guard(() => {
       const found = conversation(namespace, params.id);
       if (!found) return adminError3(404, `no conversation ${params.id}`);
       const adminId = isRecord5(body) && typeof body.adminId === "string" ? body.adminId : defaultAdmin(namespace);
-      return json3(200, api(namespace).manage(found, { action: "close", adminId }));
+      return json4(200, api(namespace).manage(found, { action: "close", adminId }));
     }),
     "POST /conversations/:id/open": ({ params, body, namespace }) => guard(() => {
       const found = conversation(namespace, params.id);
       if (!found) return adminError3(404, `no conversation ${params.id}`);
       const adminId = isRecord5(body) && typeof body.adminId === "string" ? body.adminId : defaultAdmin(namespace);
-      return json3(200, api(namespace).manage(found, { action: "open", adminId }));
+      return json4(200, api(namespace).manage(found, { action: "open", adminId }));
     }),
     "PUT /admins": ({ body, namespace }) => {
       const list = Array.isArray(body) ? body : isRecord5(body) ? body.admins : void 0;
@@ -2895,9 +2966,9 @@ var adminRoutes = (runtime) => {
           team_ids: []
         });
       }
-      return json3(200, { admins: state.admins.list({ order: "oldest" }).map((row) => row.value) });
+      return json4(200, { admins: state.admins.list({ order: "oldest" }).map((row) => row.value) });
     },
-    "GET /settings": ({ namespace }) => json3(200, api(namespace).state.current()),
+    "GET /settings": ({ namespace }) => json4(200, api(namespace).state.current()),
     "PUT /settings": ({ body, namespace }) => {
       if (!isRecord5(body)) return adminError3(400, "expected a JSON object");
       const patch = {};
@@ -2911,7 +2982,7 @@ var adminRoutes = (runtime) => {
         }
         patch.customAttributes = body.customAttributes === null ? null : body.customAttributes.map(String);
       }
-      return json3(200, api(namespace).state.update(patch));
+      return json4(200, api(namespace).state.update(patch));
     }
   };
 };
@@ -2924,14 +2995,15 @@ var createRuntime2 = (options = {}) => {
     ...hooks?.retryDelaysMs ? { retryDelaysMs: hooks.retryDelaysMs } : {},
     ...hooks?.fetch ? { fetch: hooks.fetch } : {},
     ...options.wallClock ? { now: options.wallClock } : {},
-    endpoints: (hooks?.urls ?? []).map(
-      (url, index) => ({
+    endpoints: (hooks?.urls ?? []).map((entry, index) => {
+      const target = typeof entry === "string" ? { url: entry } : entry;
+      return {
         id: `we_intercom_${index}`,
-        url,
+        url: target.url,
         ...hooks?.secret ? { secret: hooks.secret } : {},
-        events: [...hooks?.events ?? DEFAULT_TOPICS]
-      })
-    )
+        events: [...target.events ?? hooks?.events ?? DEFAULT_TOPICS]
+      };
+    })
   });
   const runtime = createRuntime({
     name: INTERCOM_NAMESPACE,
@@ -2972,7 +3044,9 @@ var INTERCOM_TOPICS = [
   "conversation.admin.opened",
   "conversation.admin.snoozed",
   "conversation.admin.assigned",
-  "conversation.admin.single.created"
+  "conversation.admin.single.created",
+  "conversation.user.created",
+  "conversation.user.replied"
 ];
 var CONTACT_FIELDS = [
   "id",
@@ -3407,6 +3481,17 @@ var IntercomAPI = class {
         parts: []
       };
       this.state.conversations.insert(conversation.id, conversation);
+      const text2 = String(body.body);
+      this.recordSent({
+        operation: "CreateConversation",
+        conversation,
+        partId: null,
+        partType: "source",
+        author: conversation.source.author,
+        bodyLength: text2.length,
+        attachmentCount: 0
+      });
+      this.notify("conversation.user.created", conversation, []);
       return annotateResponse(
         jsonRes(200, {
           type: "user_message",
@@ -3577,6 +3662,15 @@ var IntercomAPI = class {
       body: body === void 0 ? null : toHtml(body),
       attachments: stored
     });
+    this.recordSent({
+      operation: "ReplyConversation",
+      conversation: next,
+      partId,
+      partType: messageType,
+      author,
+      bodyLength: body?.length ?? 0,
+      attachmentCount: stored.length
+    });
     return annotateResponse(jsonRes(200, this.conversationBody(next, { parts: next.parts })), {
       ids: { conversationId: next.id, partId }
     });
@@ -3611,8 +3705,29 @@ var IntercomAPI = class {
     };
     this.state.conversations.update(conversation.id, next);
     if (byAdmin && visible) this.notify("conversation.admin.replied", next, [part]);
+    if (input.author.type === "user") this.notify("conversation.user.replied", next, [part]);
     return next;
   }
+  /** Record what the API client sent, for `GET /__admin/outbox`: metadata only, never the body. */
+  recordSent(input) {
+    const at = new Date(this.now()).toISOString();
+    this.state.outbox.record({
+      id: `sent_${this.state.next("sent")}`,
+      to: [input.conversation.id, input.conversation.contactId],
+      createdAt: at,
+      at,
+      operation: input.operation,
+      conversationId: input.conversation.id,
+      contactId: input.conversation.contactId,
+      partId: input.partId,
+      partType: input.partType,
+      authorType: input.author.type === "admin" ? "admin" : "user",
+      authorId: input.author.id,
+      hasBody: input.bodyLength > 0,
+      bodyLength: input.bodyLength,
+      attachmentCount: input.attachmentCount
+    });
+  }
   manageConversation(context) {
     return this.withConversation(context, (conversation) => {
       const body = this.json(context);
@@ -3832,4 +3947,4 @@ export {
   IntercomError,
   IntercomAPI
 };
-//# sourceMappingURL=chunk-OSBG2XJ7.js.map
+//# sourceMappingURL=chunk-DOY3BICO.js.map