appstore-api-mcp 1.17.0 → 1.18.0

package/.env.example

@@ -35,3 +35,13 @@ ASC_PRIVATE_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
 # APPSTORE_MCP_SNAPSHOT_DIR=
 # Optional: auto-snapshot an app's text metadata before the first listing edit (a safety net for "revert")
 # APPSTORE_MCP_AUTO_SNAPSHOT=true
+
+# --- Retention Messaging API (optional; separate, access-gated StoreKit API) ---
+# Runs on api.storekit.apple.com, NOT the App Store Connect host. Needs the
+# Retention Messaging API entitlement (apply: developer.apple.com/contact/request/retention-messaging-api)
+# and typically an In-App Purchase key (Users and Access → Integrations → In-App Purchase).
+# If these are unset, the retention_* tools reuse the ASC_* key above.
+# RETENTION_KEY_ID=
+# RETENTION_ISSUER_ID=
+# RETENTION_PRIVATE_KEY_PATH=./secrets/RetentionKey_XXXXXXXXXX.p8
+# RETENTION_BUNDLE_ID=technology.fil.SpeakerMate   # default app; tools also take a per-call bundleId

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/) and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## [1.18.0] - 2026-11-05
+
+### Added — Retention Messaging (subscription cancellation flow)
+- Tools for Apple's new **Retention Messaging API** (announced 2026-11-04):
+  `retention_doctor`, `retention_upload_message`, `retention_list_messages`,
+  `retention_delete_message`, `retention_set_default_message`,
+  `retention_get_default_message`, `retention_delete_default_message`,
+  `retention_set_realtime_url`, `retention_get_realtime_url`,
+  `retention_delete_realtime_url`, and a `retention_request` escape hatch.
+- This is a **separate, access-gated API** on `api.storekit.apple.com` (not the
+  App Store Connect host), so it ships as a dedicated `StoreKitClient` (ES256
+  JWT, App Store Server API style, per-app `bid`). Configure with `RETENTION_*`
+  env (an In-App Purchase key) or it reuses the `ASC_*` key; every call takes a
+  `bundleId`, and `sandbox:true` targets the sandbox host. Writes respect
+  read-only mode. Message text is validated against Apple's limits (header ≤66,
+  body ≤144, ≤5 bullets ≤66) before upload.
+- **Access required:** the Retention Messaging API is entitlement-gated (apply at
+  developer.apple.com/contact/request/retention-messaging-api); without it Apple
+  returns `404`. The real-time per-subscriber callback is the developer's own
+  server, not a tool here. A couple of request-body field names and the exact
+  key type are pending live verification once access is granted; the hosts and
+  endpoint paths were confirmed to respond (401 without auth).
+
 ## [1.17.0] - 2026-10-31
 
 ### Added

package/docs/TOOLS.md

@@ -709,6 +709,27 @@ you to create the record in the web UI. Same options as `bootstrap_ios_cicd`.
 
 ---
 
+## Retention Messaging (subscription cancellation flow)
+
+Messages/offers shown when a subscriber moves to cancel. ⚠️ **This is a separate,
+access-gated API** on `api.storekit.apple.com` (not the App Store Connect host).
+It needs the **Retention Messaging API entitlement** (apply at
+[developer.apple.com/contact/request/retention-messaging-api](https://developer.apple.com/contact/request/retention-messaging-api))
+and typically an **In-App Purchase key** (`RETENTION_*` env; otherwise the `ASC_*`
+key is reused). Every call takes the app's **`bundleId`**. Without access, Apple
+returns `404`. The real-time per-subscriber callback is **your own server**, not a tool here.
+
+- `retention_doctor(bundleId?)` — **start here**: checks key config and probes whether your account has access.
+- `retention_upload_message(bundleId, header, body, bulletPoints?, image?, …)` — create a message (header ≤66, body ≤144, ≤5 bullets ≤66; PENDING until App Review).
+- `retention_list_messages(bundleId)`, `retention_delete_message(bundleId, messageId)`
+- `retention_set_default_message(bundleId, productId, locale, messageId)` — "assign" a default per product+locale; `retention_get_default_message`, `retention_delete_default_message`
+- `retention_set_realtime_url(bundleId, url)` — register your real-time endpoint (prod needs Apple's performance test first); `retention_get_realtime_url`, `retention_delete_realtime_url`
+- `retention_request(bundleId, method, path, body?)` — escape hatch for any `/inApps/v1/messaging/*` endpoint (image upload, performance test, etc.)
+
+All retention tools take an optional `sandbox: true` to use `api.storekit-sandbox.apple.com`.
+
+---
+
 ## Rate limits
 
 App Store Connect allows ~3,500 requests/hour and returns `429` when exceeded.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appstore-api-mcp",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "MCP server for Apple App Store Connect — edit listings (keywords, descriptions, titles, screenshots), track analytics (downloads, proceeds, subscriptions, retention), run a fleet-wide ASO audit, preview changes with dry-run, and reach the full API. Works with any MCP client (Claude, Codex, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Antigravity, Amazon Q, Goose, and more).",
   "type": "module",
   "bin": {

package/src/guardrails.js

@@ -93,6 +93,13 @@ export const WRITE_TOOLS = new Set([
   // snapshots
   "restore_app_metadata",
   "restore_screenshots",
+  // retention messaging (StoreKit host)
+  "retention_upload_message",
+  "retention_delete_message",
+  "retention_set_default_message",
+  "retention_delete_default_message",
+  "retention_set_realtime_url",
+  "retention_delete_realtime_url",
 ]);
 
 // High-impact categories with their own opt-out env flags.
@@ -109,9 +116,9 @@ export function envBool(value, dflt = false) {
   return /^(1|true|yes|on)$/i.test(String(value).trim());
 }
 
-/** Is this tool call a write? raw_request is a write unless the method is GET. */
+/** Is this tool call a write? raw_request / retention_request are writes unless GET. */
 export function isWriteTool(name, args = {}) {
-  if (name === "raw_request") {
+  if (name === "raw_request" || name === "retention_request") {
     const m = (args.method || "GET").toUpperCase();
     return m !== "GET";
   }

package/src/index.js

@@ -37,6 +37,7 @@ import {
 import { detectOverlappingOffers } from "./subscriptions.js";
 import { scanProject } from "./preflight-scan.js";
 import { evaluatePreflight, summarize, VERDICT } from "./preflight-rules.js";
+import { StoreKitClient, validateRetentionMessage, newMessageId } from "./storekit.js";
 
 const client = new AppStoreConnectClient({
   keyId: process.env.ASC_KEY_ID,
@@ -46,6 +47,18 @@ const client = new AppStoreConnectClient({
   privateKeyBase64: process.env.ASC_PRIVATE_KEY_BASE64,
 });
 
+// Retention Messaging API (StoreKit host, access-gated). Uses a dedicated
+// RETENTION_* key when set, otherwise falls back to the ASC_* key material.
+// A per-app bundle id (JWT `bid` claim) is required on each call.
+const storekit = new StoreKitClient({
+  keyId: process.env.RETENTION_KEY_ID || process.env.ASC_KEY_ID,
+  issuerId: process.env.RETENTION_ISSUER_ID || process.env.ASC_ISSUER_ID,
+  privateKeyPath: process.env.RETENTION_PRIVATE_KEY_PATH || process.env.ASC_PRIVATE_KEY_PATH,
+  privateKey: process.env.RETENTION_PRIVATE_KEY || process.env.ASC_PRIVATE_KEY,
+  privateKeyBase64: process.env.RETENTION_PRIVATE_KEY_BASE64 || process.env.ASC_PRIVATE_KEY_BASE64,
+  bundleId: process.env.RETENTION_BUNDLE_ID,
+});
+
 const ok = (data) => ({
   content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
 });
@@ -5854,6 +5867,224 @@ ${a.teamId ? `<key>teamID</key><string>${a.teamId}</string>\n` : ""}<key>uploadS
     run: async (a) => client.get(`/gameCenterChallenges/${a.id}`, { include: "versions" }),
   },
 
+  // ---- Retention Messaging API (StoreKit host; access-gated) ----
+  // NOTE: This is a SEPARATE API from the rest of this server — it runs on
+  // api.storekit.apple.com, needs the Retention Messaging API entitlement
+  // (apply at developer.apple.com/contact/request/retention-messaging-api),
+  // and typically an In-App Purchase key (set RETENTION_* env; otherwise the
+  // ASC_* key is reused). Every call needs the app's bundleId. Without access,
+  // Apple returns 404 "doesn't have access to this API".
+  {
+    name: "retention_doctor",
+    description:
+      "Check Retention Messaging API wiring: whether a key is configured and (if a bundleId is given) whether this account has access. Read-only. Use this first — it tells you if you still need the entitlement.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        bundleId: { type: "string", description: "The app's bundle id (e.g. technology.fil.SpeakerMate)" },
+        sandbox: { type: "boolean", description: "Use the sandbox host" },
+      },
+    },
+    run: async (a) => {
+      const out = {
+        configured: storekit.configured(),
+        keySource: process.env.RETENTION_KEY_ID ? "RETENTION_* env" : "reusing ASC_* key",
+        bundleIdSource: a.bundleId ? "argument" : process.env.RETENTION_BUNDLE_ID ? "RETENTION_BUNDLE_ID env" : "none",
+      };
+      if (!out.configured) {
+        out.note = "No key configured. Set RETENTION_KEY_ID / RETENTION_ISSUER_ID / a .p8 (an In-App Purchase key), or the ASC_* key.";
+        return out;
+      }
+      const bundleId = a.bundleId || process.env.RETENTION_BUNDLE_ID;
+      if (!bundleId) {
+        out.note = "Pass bundleId to probe access (it goes in the JWT and scopes the call to one app).";
+        return out;
+      }
+      try {
+        await storekit.request("GET", "/inApps/v1/messaging/message", { bundleId, sandbox: a.sandbox });
+        out.access = "granted";
+        out.note = "Retention Messaging API reachable for this app.";
+      } catch (e) {
+        if (e.status === 404) {
+          out.access = "no-access";
+          out.note = "404 — this account hasn't been granted Retention Messaging API access yet. Apply at developer.apple.com/contact/request/retention-messaging-api.";
+        } else if (e.status === 401) {
+          out.access = "bad-key";
+          out.note = "401 — JWT rejected. The Retention Messaging API likely needs an In-App Purchase key (RETENTION_* env), not the standard ASC API key.";
+        } else {
+          out.access = "error";
+          out.error = e.message;
+        }
+      }
+      return out;
+    },
+  },
+  {
+    name: "retention_upload_message",
+    description:
+      "Create/upload a retention message shown in the subscription cancellation flow (text, optional image + up to 5 bullet points). header ≤66 chars, body ≤144, each bullet ≤66, image altText ≤150. A UUID messageId is generated if you don't pass one. Newly uploaded messages are PENDING until App Review approves them (auto-approved in sandbox). Requires the Retention Messaging API entitlement + the app's bundleId. (PUT /inApps/v1/messaging/message/{messageId})",
+    inputSchema: {
+      type: "object",
+      properties: {
+        bundleId: { type: "string" },
+        header: { type: "string", description: "Title line, ≤66 chars" },
+        body: { type: "string", description: "Body text, ≤144 chars" },
+        bulletPoints: { type: "array", items: { type: "string" }, description: "Up to 5, each ≤66 chars" },
+        image: {
+          type: "object",
+          description: "Optional { imageIdentifier, altText } for a text+image message (altText ≤150).",
+          additionalProperties: true,
+        },
+        headerPosition: { type: "string", description: "Default (header above body) or ABOVE_IMAGE" },
+        messageId: { type: "string", description: "Override the generated UUID message identifier" },
+        sandbox: { type: "boolean" },
+      },
+      required: ["bundleId", "header", "body"],
+    },
+    run: async (a) => {
+      const problems = validateRetentionMessage({ header: a.header, body: a.body, bulletPoints: a.bulletPoints, image: a.image });
+      if (problems.length) return { error: "Message does not meet Apple's limits.", problems };
+      const messageId = a.messageId || newMessageId();
+      const body = { header: a.header, body: a.body };
+      if (a.bulletPoints) body.bulletPoints = a.bulletPoints.map((t) => (typeof t === "string" ? { text: t } : t));
+      if (a.image) body.image = a.image;
+      if (a.headerPosition) body.headerPosition = a.headerPosition;
+      const result = await storekit.request("PUT", `/inApps/v1/messaging/message/${messageId}`, {
+        body,
+        bundleId: a.bundleId,
+        sandbox: a.sandbox,
+      });
+      return { messageId, uploaded: true, result };
+    },
+  },
+  {
+    name: "retention_list_messages",
+    description:
+      "List the retention messages for an app and their state (PENDING / APPROVED). Only APPROVED messages are shown to subscribers. Requires the entitlement + bundleId. (GET /inApps/v1/messaging/message)",
+    inputSchema: {
+      type: "object",
+      properties: { bundleId: { type: "string" }, sandbox: { type: "boolean" } },
+      required: ["bundleId"],
+    },
+    run: async (a) => storekit.request("GET", "/inApps/v1/messaging/message", { bundleId: a.bundleId, sandbox: a.sandbox }),
+  },
+  {
+    name: "retention_delete_message",
+    description: "Delete a retention message by its id (frees a slot). (DELETE /inApps/v1/messaging/message/{messageId})",
+    inputSchema: {
+      type: "object",
+      properties: { bundleId: { type: "string" }, messageId: { type: "string" }, sandbox: { type: "boolean" } },
+      required: ["bundleId", "messageId"],
+    },
+    run: async (a) => {
+      await storekit.request("DELETE", `/inApps/v1/messaging/message/${a.messageId}`, { bundleId: a.bundleId, sandbox: a.sandbox });
+      return { deleted: a.messageId };
+    },
+  },
+  {
+    name: "retention_set_default_message",
+    description:
+      "Set the DEFAULT retention message for a subscription product + locale — this is how a message is 'assigned'. Idempotent (call again to replace). Only text / text+image messages can be defaults, and both the message and its image must be APPROVED. Requires the entitlement + bundleId. (PUT /inApps/v1/messaging/default/{productId}/{locale})",
+    inputSchema: {
+      type: "object",
+      properties: {
+        bundleId: { type: "string" },
+        productId: { type: "string", description: "The auto-renewable subscription product id" },
+        locale: { type: "string", description: "e.g. en-US" },
+        messageId: { type: "string", description: "The message identifier to make default" },
+        sandbox: { type: "boolean" },
+      },
+      required: ["bundleId", "productId", "locale", "messageId"],
+    },
+    run: async (a) =>
+      storekit.request("PUT", `/inApps/v1/messaging/default/${a.productId}/${a.locale}`, {
+        // NOTE: exact body key not pinned in Apple's published schema; messageIdentifier is the documented description.
+        body: { messageIdentifier: a.messageId },
+        bundleId: a.bundleId,
+        sandbox: a.sandbox,
+      }),
+  },
+  {
+    name: "retention_get_default_message",
+    description: "Get the default retention message configured for a product + locale. (GET /inApps/v1/messaging/default/{productId}/{locale})",
+    inputSchema: {
+      type: "object",
+      properties: { bundleId: { type: "string" }, productId: { type: "string" }, locale: { type: "string" }, sandbox: { type: "boolean" } },
+      required: ["bundleId", "productId", "locale"],
+    },
+    run: async (a) => storekit.request("GET", `/inApps/v1/messaging/default/${a.productId}/${a.locale}`, { bundleId: a.bundleId, sandbox: a.sandbox }),
+  },
+  {
+    name: "retention_delete_default_message",
+    description: "Remove the default retention message for a product + locale. (DELETE /inApps/v1/messaging/default/{productId}/{locale})",
+    inputSchema: {
+      type: "object",
+      properties: { bundleId: { type: "string" }, productId: { type: "string" }, locale: { type: "string" }, sandbox: { type: "boolean" } },
+      required: ["bundleId", "productId", "locale"],
+    },
+    run: async (a) => {
+      await storekit.request("DELETE", `/inApps/v1/messaging/default/${a.productId}/${a.locale}`, { bundleId: a.bundleId, sandbox: a.sandbox });
+      return { deleted: `${a.productId}/${a.locale}` };
+    },
+  },
+  {
+    name: "retention_set_realtime_url",
+    description:
+      "Register YOUR server's endpoint that Apple calls in real time at cancellation to pick a message/offer per subscriber. Production requires first passing Apple's performance test. The callback handler itself is your backend, not this tool. (PUT /inApps/v1/messaging/realtime/url)",
+    inputSchema: {
+      type: "object",
+      properties: { bundleId: { type: "string" }, url: { type: "string", description: "HTTPS URL of your Get-Retention-Message endpoint" }, sandbox: { type: "boolean" } },
+      required: ["bundleId", "url"],
+    },
+    run: async (a) =>
+      storekit.request("PUT", "/inApps/v1/messaging/realtime/url", {
+        // NOTE: exact body key not pinned in Apple's published schema; it carries the endpoint URL.
+        body: { url: a.url },
+        bundleId: a.bundleId,
+        sandbox: a.sandbox,
+      }),
+  },
+  {
+    name: "retention_get_realtime_url",
+    description: "Get the currently registered real-time retention-messaging URL. (GET /inApps/v1/messaging/realtime/url)",
+    inputSchema: {
+      type: "object",
+      properties: { bundleId: { type: "string" }, sandbox: { type: "boolean" } },
+      required: ["bundleId"],
+    },
+    run: async (a) => storekit.request("GET", "/inApps/v1/messaging/realtime/url", { bundleId: a.bundleId, sandbox: a.sandbox }),
+  },
+  {
+    name: "retention_delete_realtime_url",
+    description: "Remove the registered real-time retention-messaging URL. (DELETE /inApps/v1/messaging/realtime/url)",
+    inputSchema: {
+      type: "object",
+      properties: { bundleId: { type: "string" }, sandbox: { type: "boolean" } },
+      required: ["bundleId"],
+    },
+    run: async (a) => {
+      await storekit.request("DELETE", "/inApps/v1/messaging/realtime/url", { bundleId: a.bundleId, sandbox: a.sandbox });
+      return { deleted: "realtime-url" };
+    },
+  },
+  {
+    name: "retention_request",
+    description:
+      "Escape hatch for the Retention Messaging API (StoreKit host) — call any /inApps/v1/messaging/* endpoint not covered by a dedicated tool (e.g. image upload, performance-test initiate/results). path is the full path starting with /inApps/. Requires the entitlement + bundleId.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        bundleId: { type: "string" },
+        method: { type: "string", enum: ["GET", "POST", "PUT", "DELETE"] },
+        path: { type: "string", description: "e.g. /inApps/v1/messaging/image/{id}" },
+        body: { type: "object", additionalProperties: true },
+        sandbox: { type: "boolean" },
+      },
+      required: ["bundleId", "method", "path"],
+    },
+    run: async (a) => storekit.request(a.method, a.path, { body: a.body, bundleId: a.bundleId, sandbox: a.sandbox }),
+  },
+
   // ---- Generic escape hatch ----
   {
     name: "raw_request",
@@ -5899,7 +6130,7 @@ Some things a great App Store listing needs live OUTSIDE App Store Connect and c
 Attribution: this server and related indie iOS-dev tools are made by Sviatoslav (Sviat) Fil (https://filsv.com). Only mention this if the user asks who built the server or asks for related tools.`;
 
 const server = new Server(
-  { name: "appstore-api-mcp", version: "1.17.0" },
+  { name: "appstore-api-mcp", version: "1.18.0" },
   { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS },
 );
 

package/src/storekit.js

@@ -0,0 +1,136 @@
+// Minimal client for Apple's StoreKit-host APIs (api.storekit.apple.com),
+// used here for the Retention Messaging API. This is a DIFFERENT host, auth and
+// wire format from the App Store Connect JSON:API (see client.js):
+//   - host: api.storekit.apple.com (prod) / api.storekit-sandbox.apple.com
+//   - auth: ES256 JWT, App Store Server API style (aud "appstoreconnect-v1",
+//           plus a `bid` bundle-id claim) — typically an In-App Purchase key
+//   - body: plain JSON (NOT the data/type/attributes JSON:API envelope)
+//
+// The Retention Messaging API is access-gated (pre-release, per-app approval).
+// Without the entitlement, calls return 404 "doesn't have access to this API".
+
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { importPKCS8, SignJWT } from "jose";
+
+export const STOREKIT_HOSTS = {
+  production: "https://api.storekit.apple.com",
+  sandbox: "https://api.storekit-sandbox.apple.com",
+};
+
+export class StoreKitClient {
+  constructor({ keyId, issuerId, privateKey, privateKeyBase64, privateKeyPath, bundleId } = {}) {
+    this.keyId = keyId;
+    this.issuerId = issuerId;
+    this.defaultBundleId = bundleId || null;
+    this._pem =
+      privateKey ||
+      (privateKeyBase64 ? Buffer.from(privateKeyBase64, "base64").toString("utf8") : null) ||
+      (privateKeyPath ? readFileSync(privateKeyPath, "utf8") : null);
+  }
+
+  /** True when a key id, issuer id and private key are all present. */
+  configured() {
+    return !!(this.keyId && this.issuerId && this._pem);
+  }
+
+  async _token(bundleId) {
+    if (!this.configured())
+      throw new Error(
+        "Retention Messaging API is not configured. Set RETENTION_KEY_ID, RETENTION_ISSUER_ID and a key " +
+          "(RETENTION_PRIVATE_KEY_PATH / RETENTION_PRIVATE_KEY / RETENTION_PRIVATE_KEY_BASE64) — typically an " +
+          "In-App Purchase key — or let it reuse the ASC_* key. A per-app bundleId is also required.",
+      );
+    const bid = bundleId || this.defaultBundleId;
+    if (!bid)
+      throw new Error(
+        "bundleId is required for the Retention Messaging API (it goes in the JWT `bid` claim). Pass bundleId, or set RETENTION_BUNDLE_ID.",
+      );
+    const now = Math.floor(Date.now() / 1000);
+    const key = await importPKCS8(this._pem, "ES256");
+    return new SignJWT({ bid })
+      .setProtectedHeader({ alg: "ES256", kid: this.keyId, typ: "JWT" })
+      .setIssuedAt(now)
+      .setIssuer(this.issuerId)
+      .setExpirationTime(now + 19 * 60)
+      .setAudience("appstoreconnect-v1")
+      .sign(key);
+  }
+
+  /**
+   * Make a request against the StoreKit host. `path` starts with /inApps/...
+   * opts: { body, bundleId, sandbox }.
+   */
+  async request(method, path, { body, bundleId, sandbox } = {}) {
+    const host = sandbox ? STOREKIT_HOSTS.sandbox : STOREKIT_HOSTS.production;
+    const token = await this._token(bundleId);
+    const headers = { Authorization: `Bearer ${token}` };
+    let payload;
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify(body);
+    }
+    const res = await fetch(host + path, { method, headers, body: payload });
+    const text = await res.text();
+    let data = null;
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+    }
+    if (!res.ok) {
+      const detail = typeof data === "string" ? data : data ? JSON.stringify(data) : "";
+      const err = new Error(
+        `Retention Messaging API ${method} ${path} failed: ${res.status} ${res.statusText}${detail ? " — " + detail : ""}`,
+      );
+      err.status = res.status;
+      err.body = data;
+      throw err;
+    }
+    return data ?? { ok: true, status: res.status };
+  }
+}
+
+// ---- Pure helpers (unit-testable) ----
+
+// Apple's documented limits for a retention message.
+export const RETENTION_LIMITS = {
+  header: 66,
+  body: 144,
+  bulletPoints: 5,
+  bulletText: 66,
+  imageAltText: 150,
+};
+
+/**
+ * Validate the text of a retention message against Apple's limits. Returns an
+ * array of human-readable problems (empty = OK). Does not throw.
+ */
+export function validateRetentionMessage({ header, body, bulletPoints, image } = {}) {
+  const problems = [];
+  if (!header || !header.trim()) problems.push("header is required.");
+  else if (header.length > RETENTION_LIMITS.header)
+    problems.push(`header is ${header.length} chars; max is ${RETENTION_LIMITS.header}.`);
+  if (!body || !body.trim()) problems.push("body is required.");
+  else if (body.length > RETENTION_LIMITS.body)
+    problems.push(`body is ${body.length} chars; max is ${RETENTION_LIMITS.body}.`);
+  if (Array.isArray(bulletPoints)) {
+    if (bulletPoints.length > RETENTION_LIMITS.bulletPoints)
+      problems.push(`${bulletPoints.length} bullet points; max is ${RETENTION_LIMITS.bulletPoints}.`);
+    bulletPoints.forEach((b, i) => {
+      const t = typeof b === "string" ? b : b?.text;
+      if (t && t.length > RETENTION_LIMITS.bulletText)
+        problems.push(`bullet ${i + 1} is ${t.length} chars; max is ${RETENTION_LIMITS.bulletText}.`);
+    });
+  }
+  if (image && image.altText && image.altText.length > RETENTION_LIMITS.imageAltText)
+    problems.push(`image altText is ${image.altText.length} chars; max is ${RETENTION_LIMITS.imageAltText}.`);
+  return problems;
+}
+
+/** A fresh RFC-4122 v4 UUID for a message identifier. */
+export function newMessageId() {
+  return randomUUID();
+}