From 77022aab00e5575e587d333c4b9958a713b67b7c Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 20 Jun 2026 21:08:42 +0000 Subject: [PATCH] =?UTF-8?q?fix(sdk):=20correct=20blocked-message=20docs=20?= =?UTF-8?q?=E2=80=94=20blockedReason=20is=20operator-only?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit senderkit-app PR #211 codified that the outbound abuse scanner's detailed detection breakdown is operator-only and never returned by the REST API. The messages.list / messages.get projection (and the MCP tools built on it) omit blockedReason; a blocked message's customer-facing timeline carries only a generic "Blocked by automated content safety checks." entry. The previous release (0.10.0) advertised a Message.blockedReason field that the API never populated. Remove it and update the Message.status / MESSAGE_STATUSES docs to describe the generic, customer-facing block reason instead. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01U4xKXphsKiGp6AHvd7tzUf --- .changeset/fix-blocked-reason-not-returned.md | 20 +++++++++++++++++++ packages/sdk/src/mcp-schemas.ts | 3 ++- packages/sdk/src/types.ts | 7 ++++--- 3 files changed, 26 insertions(+), 4 deletions(-) create mode 100644 .changeset/fix-blocked-reason-not-returned.md diff --git a/.changeset/fix-blocked-reason-not-returned.md b/.changeset/fix-blocked-reason-not-returned.md new file mode 100644 index 0000000..9e547ec --- /dev/null +++ b/.changeset/fix-blocked-reason-not-returned.md @@ -0,0 +1,20 @@ +--- +"@senderkit/sdk": patch +--- + +Correct the `blocked` message documentation to match the API. + +The previous release advertised a `Message.blockedReason` field carrying the +"human-readable trigger" for a blocked send. senderkit-app never returned it: +the REST `messages.list` / `messages.get` projection (and the MCP tools built +on it) deliberately omit the abuse detection breakdown, which is operator-only. +The app has now codified this (the customer-facing `timeline` carries only a +generic "Blocked by automated content safety checks." entry; the detailed +reason stays in the operator-only admin abuse review). + +- Remove the never-populated `Message.blockedReason` field. Reads still expose + any extra server fields through the existing index signature, so this only + drops a misleading type/doc — no field that the API actually sent. +- Update the `Message.status` and `MESSAGE_STATUSES` docs to stop pointing at + `blockedReason` and describe the generic, customer-facing block reason + instead. diff --git a/packages/sdk/src/mcp-schemas.ts b/packages/sdk/src/mcp-schemas.ts index 0dec5e3..82f93ac 100644 --- a/packages/sdk/src/mcp-schemas.ts +++ b/packages/sdk/src/mcp-schemas.ts @@ -122,7 +122,8 @@ const emailEnvelope = { * The ten message lifecycle statuses (mirrors the app's `messageStatusEnum`). * Bounces normalize to `failed` with the reason on the message timeline. * `blocked` is a terminal state set when the outbound abuse scanner halts a - * send (the human-readable trigger is on the message's `blockedReason`). + * send. The detailed detection breakdown is operator-only and never returned by + * the API; a blocked message's `timeline` carries only a generic block entry. */ export const MESSAGE_STATUSES = [ "scheduled", diff --git a/packages/sdk/src/types.ts b/packages/sdk/src/types.ts index a3345e7..ddfb1de 100644 --- a/packages/sdk/src/types.ts +++ b/packages/sdk/src/types.ts @@ -195,15 +195,16 @@ export interface Message { publicId: string; /** * Lifecycle status (one of `MESSAGE_STATUSES`). A `blocked` message was - * halted by the outbound abuse scanner; `blockedReason` carries the trigger. + * halted by the outbound abuse scanner. The detailed detection breakdown is + * operator-only and is never returned by the API; the customer-facing + * `timeline` carries only a generic block entry ("Blocked by automated + * content safety checks."). */ status: string; channel: Channel; templateSlug: string | null; recipient: string; createdAt: string; - /** Human-readable reason a `blocked` message was halted. Absent otherwise. */ - blockedReason?: string | null; [key: string]: unknown; }