fix(sdk): correct blocked-message docs (drop non-existent blockedReason field)

[tuyakhov]

Why

Scheduled review of senderkit-app main since the last SDK sync (PR #44, which covered app PRs through #198) — this run covers app PRs #199 → #211.

Almost the entire window is internal abuse-module refactors, operator-only tooling, server-side config, and UI work that does not touch the SDK/CLI/MCP outbound contract. The one change that does affect the SDK is app #211, and it's a correction of something PR #44 got wrong.

The one SDK-affecting change — app #211

App #211 ("keep spam-detection detail out of customer-visible surfaces") makes explicit and enforces that the abuse-scan detail is operator-only. The public message read surface (GET /api/v1/messages list/get — what messages.list / messages.get call, plus the SSE tail) projects a lean messageColumns set that has never included blocked_reason (confirmed against the app code: lib/services/messages.ts — getMessage/listMessages both .select(messageColumns), and no serializer re-adds it). The detailed reason lives only on the operator alert, the workspace flagged/suspended reason, and the admin abuse-review page.

PR #44 added Message.blockedReason?: string | null on the assumption it was readable by API clients. It never was — the field is always undefined over the wire. #211 confirms this is intentional and permanent.

What changed

SDK types (packages/sdk/src/types.ts)

• Removed Message.blockedReason — the API never populates it.
• Reworded the Message.status doc: a blocked message is identified by its blocked status plus a generic entry on its timeline; the detailed trigger is operator-only.

MCP / CLI (packages/sdk/src/mcp-schemas.ts)

• Dropped the MESSAGE_STATUSES comment claiming the trigger is on blockedReason; it now states the detail is operator-only.

Changeset

• @senderkit/sdk: patch.

Non-breaking: the field was always undefined, and Message keeps its [key: string]: unknown index signature. blocked stays in MESSAGE_STATUSES (unchanged) — so MCP/CLI status: "blocked" filtering still works exactly as shipped in #44.

Reviewed and intentionally not changed

App PR	Summary	Why no SDK/CLI/MCP change
#199, #201	Abuse refactors (pipeline.ts extraction, classifier dedupe)	Pure internal refactors, no behavior change.
#200	Retune managed-SES shared-sender reputation caps (Starter 1.5k, Pro 15k)	Server-side config; SDK doesn't model plans/quota. Existing quota/error behavior unchanged.
#202	Escape attacker-controlled reason in operator alert email	Operator-internal email rendering.
#203	Logs: load-older history under the live tail	Explicitly no new API — reuses the existing GET /api/v1/messages?cursor=&limit= endpoint the SDK already models (cursor / nextCursor).
#205	De-dupe operator alert emails per workspace incident	Operator-internal notification behavior.
#206	Don't flag loopback/private-IP links as raw-IP phishing	Detection heuristic tuning — changes when a send is blocked, not the contract.
#207	Onboarding: toggle checklist by clicking the title	Pure UI.
#208 / #209	Admin abuse review: account link, scroll fix, email preview (+ new messages.rendered_version, workspaces.flagged_message_id columns)	Admin/operator-only UI; new columns are not on the public API.
#210	Spec + plan for agent-driven Supabase wiring (MCP)	Docs only, no code. Per the spec, the planned tools are app-only management tools defined in-repo — the public @senderkit/sdk is explicitly untouched. Nothing to do until/unless it ships.

Verification

pnpm build and pnpm test pass — sdk 58, cli 80, react-email 29. No remaining blockedReason references in packages/.

🤖 Generated with Claude Code

https://claude.ai/code/session_019CX1MwgJt4TBjL8RnG9hax

---

Generated by Claude Code