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; }