@anthusai/papyrus 5.20.0 → 5.21.0

package/amplify/functions/content-actions/handler.py

@@ -27,6 +27,7 @@ from papyrus_content.story_reporting import save_story_version
 from papyrus_content.publication import ensure_publication_from_environment
 from papyrus_content.editorial_checks import GraphQLEditorialStore, ensure_default_policies
 from papyrus_content.reference_intake import IntakeError, intake_references
+from papyrus_content.publish_alerts import PUBLISHED_TASK_KEY, announce_published
 from papyrus_content.publishing import (
     ItemFields,
     PublishError,
@@ -119,11 +120,17 @@ def projection_context(client):
     return context
 
 
-def project_item_action(client, item_id: str, *, unpublished: bool) -> dict:
+def project_item_action(client, item_id: str, *, unpublished: bool, published_item_id: str | None = None) -> dict:
+    """Project one item. ``published_item_id`` is passed only for a real publish: the alert is announced once the page
+    is live, here when the projection succeeds, or by the scheduled retry (which carries the same marker) when it did not."""
     if not projection_configured():
+        if published_item_id:
+            announce_published(item_id, published_item_id)
         return {}
     liveness = {} if unpublished else {"live": False}
     task = {"task": "item", "itemId": item_id, "unpublished": unpublished}
+    if published_item_id:
+        task[PUBLISHED_TASK_KEY] = {"publishedItemId": published_item_id}
     try:
         report = project(projection_context(client), item_id, unpublished=unpublished)
     except Exception as error:  # noqa: BLE001 - a projection failure never fails the save
@@ -145,6 +152,8 @@ def project_item_action(client, item_id: str, *, unpublished: bool) -> dict:
         schedule_unpurged_invalidation(report.unpurged)
     if report.follow_up_item_pages:
         schedule_projection_task({"task": "item-pages", "exceptItemId": item_id}, "follow-up")
+    if report.ok and published_item_id:
+        announce_published(item_id, published_item_id)
     return response
 
 
@@ -201,6 +210,10 @@ def run_projection_task(task: dict) -> dict:
         schedule_unpurged_invalidation(report.unpurged)
     if not report.ok:
         raise ProjectionTaskFailed("; ".join(report.errors))
+    published = task.get(PUBLISHED_TASK_KEY)
+    if task.get("task") == "item" and not task.get("unpublished") and isinstance(published, dict):
+        # A real publish (the CLI marks it, as does the newsroom's retry): the page is live, so tell the newsletter.
+        announce_published(task["itemId"], published.get("publishedItemId"))
     return {"ok": True, "paths": [*report.written, *report.deleted]}
 
 
@@ -286,7 +299,9 @@ def publish_item_action(arguments: dict, actor: str) -> dict:
     }
     if result.changed:
         response.update(site_triggers_for(client, arguments["id"]))
-    response.update(project_item_action(client, arguments["id"], unpublished=False))
+    response.update(
+        project_item_action(client, arguments["id"], unpublished=False, published_item_id=result.published_item_id if result.changed else None)
+    )
     return response
 
 

package/amplify/plugins/newsletter/config.js

@@ -0,0 +1,195 @@
+export const NEWSLETTER_SITE_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+export const NEWSLETTER_LIST_ID = /^[a-z][a-z0-9-]{0,39}$/;
+export const COMPUTE_ROLE_ARN = /^arn:aws:iam::[0-9]{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
+const HOSTNAME = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/;
+const LOCAL_PART = /^[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*$/;
+const SES_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const ISSUE_TYPE = /^[a-z][a-z0-9_]{0,59}$/;
+/** One path segment: it is the Item section of the archive and the `urls.sections` key of the site's projection.json. */
+const ARCHIVE_PATH = /^\/[a-z0-9][a-z0-9_-]*\/$/;
+const SCHEDULER_CRON = /^cron\(\S+ \S+ \S+ \S+ \S+ \S+\)$/;
+const UNSAFE_CSS = /[<>{};"\\`]|url\(|expression\(|@import/i;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+export const ITEM_URL_STYLES = ["html", "directory", "clean"];
+const KNOWN_KEYS = new Set([
+    "name", "siteId", "siteOrigin", "computeRoleArn", "sendingDomain", "fromAddress", "fromName", "instantAlerts", "theme", "lists",
+    "configurationSet", "eventTopicName", "itemUrlStyle",
+]);
+const LIST_KEYS = {
+    roundup: ["id", "name", "description", "kind", "schedule", "issueType", "archivePath"],
+    alert: ["id", "name", "description", "kind", "rule", "approval"],
+};
+function fail(message) {
+    throw new Error(`newsletter plugin ${message}`);
+}
+function record(raw, label, known) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        fail(`${label} must be an object`);
+    const unknown = Object.keys(raw).filter((key) => !known.includes(key));
+    if (unknown.length > 0)
+        fail(`${label} has unknown settings: ${unknown.join(", ")}`);
+    return raw;
+}
+function text(raw, label, maximum, options = {}) {
+    const value = raw === undefined ? options.fallback : raw;
+    if (value === undefined)
+        fail(`${label} is required`);
+    if (typeof value !== "string" || CONTROL_CHARACTERS.test(value) || value.trim() !== value) {
+        fail(`${label} must be text on one line with no leading or trailing spaces`);
+    }
+    if (value.length === 0 && !options.optional)
+        fail(`${label} is required`);
+    if (value.length > maximum)
+        fail(`${label} must be at most ${maximum} characters`);
+    return value;
+}
+function matching(raw, label, pattern, description, fallback) {
+    const value = raw === undefined ? fallback : raw;
+    if (typeof value !== "string" || !pattern.test(value))
+        fail(`${label} must be ${description}`);
+    return value;
+}
+function timeZone(raw, label) {
+    const value = text(raw, label, 64);
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: value });
+    }
+    catch {
+        fail(`${label} must be an IANA time zone such as America/New_York`);
+    }
+    return value;
+}
+function origin(raw) {
+    const value = text(raw, "siteOrigin", 200);
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (!parsed || parsed.protocol !== "https:" || parsed.origin !== value)
+        fail("siteOrigin must be an https origin such as https://example.com with no path");
+    return value;
+}
+function stringList(raw, label) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > 50)
+        fail(`${label} must be a list of 1 to 50 names`);
+    return [...new Set(raw.map((entry, index) => text(entry, `${label}[${index}]`, 80)))];
+}
+function itemUrlStyle(raw) {
+    if (raw === undefined)
+        return "html";
+    if (typeof raw !== "string" || !ITEM_URL_STYLES.includes(raw))
+        fail(`itemUrlStyle must be one of ${ITEM_URL_STYLES.join(", ")}`);
+    return raw;
+}
+function resolveTheme(raw) {
+    const theme = record(raw, "theme", ["accent", "text", "background", "surface", "muted", "fontFamily", "logoUrl"]);
+    const resolved = {
+        accent: text(theme.accent, "theme.accent", 80),
+        text: text(theme.text, "theme.text", 80),
+        background: text(theme.background, "theme.background", 80),
+    };
+    for (const key of ["surface", "muted", "fontFamily"]) {
+        if (theme[key] !== undefined)
+            resolved[key] = text(theme[key], `theme.${key}`, 200);
+    }
+    for (const [key, value] of Object.entries(resolved)) {
+        if (UNSAFE_CSS.test(value))
+            fail(`theme.${key} contains characters that are not allowed in a style value`);
+    }
+    if (theme.logoUrl !== undefined) {
+        const logoUrl = text(theme.logoUrl, "theme.logoUrl", 500);
+        if (!/^https:\/\//.test(logoUrl))
+            fail("theme.logoUrl must be an https URL");
+        resolved.logoUrl = logoUrl;
+    }
+    return resolved;
+}
+function resolveRule(raw, label) {
+    if (raw === undefined)
+        return {};
+    const rule = record(raw, label, ["sections", "tags", "types"]);
+    return {
+        ...(rule.sections === undefined ? {} : { sections: stringList(rule.sections, `${label}.sections`) }),
+        ...(rule.tags === undefined ? {} : { tags: stringList(rule.tags, `${label}.tags`) }),
+        ...(rule.types === undefined ? {} : { types: stringList(rule.types, `${label}.types`) }),
+    };
+}
+function resolveList(raw, index, instantAlerts) {
+    const label = `lists[${index}]`;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        fail(`${label} must be an object`);
+    const kind = raw.kind;
+    if (kind !== "roundup" && kind !== "alert")
+        fail(`${label}.kind must be "roundup" or "alert"`);
+    const list = record(raw, label, LIST_KEYS[kind]);
+    const base = {
+        id: matching(list.id, `${label}.id`, NEWSLETTER_LIST_ID, "lowercase letters, digits and hyphens, starting with a letter (at most 40 characters)"),
+        name: text(list.name, `${label}.name`, 80),
+        description: text(list.description, `${label}.description`, 300, { optional: true, fallback: "" }),
+    };
+    if (kind === "roundup") {
+        const schedule = record(list.schedule, `${label}.schedule`, ["draft", "timezone"]);
+        return {
+            ...base,
+            kind,
+            schedule: {
+                draft: matching(schedule.draft, `${label}.schedule.draft`, SCHEDULER_CRON, 'an EventBridge Scheduler cron such as "cron(0 13 ? * FRI *)"'),
+                timezone: timeZone(schedule.timezone, `${label}.schedule.timezone`),
+            },
+            issueType: matching(list.issueType, `${label}.issueType`, ISSUE_TYPE, "a lowercase item type name", "newsletter_issue"),
+            archivePath: matching(list.archivePath, `${label}.archivePath`, ARCHIVE_PATH, 'a path that starts and ends with "/", such as /roundup/'),
+        };
+    }
+    const approval = list.approval === undefined ? "admin" : list.approval;
+    if (approval !== "admin" && approval !== "none")
+        fail(`${label}.approval must be "admin" or "none"`);
+    if (approval === "none" && !instantAlerts) {
+        fail(`${label}.approval "none" sends alerts without an admin approving them: set instantAlerts: true on the plugin first`);
+    }
+    return { ...base, kind, rule: resolveRule(list.rule, `${label}.rule`), approval };
+}
+export function resolveNewsletterConfig(request) {
+    const raw = record(typeof request === "string" ? { name: request } : request, "settings", [...KNOWN_KEYS]);
+    const siteId = matching(raw.siteId, "siteId", NEWSLETTER_SITE_ID, "a lowercase site id (letters, digits, hyphens), the SiteId of the sending stack");
+    const computeRoleArn = raw.computeRoleArn;
+    if (typeof computeRoleArn !== "string" || !COMPUTE_ROLE_ARN.test(computeRoleArn)) {
+        fail("computeRoleArn must be the IAM role ARN of the CMS app's compute role (the CmsComputeRoleArn output)");
+    }
+    const sendingDomain = matching(raw.sendingDomain, "sendingDomain", HOSTNAME, "a lowercase domain name such as news.example.com");
+    const fromAddress = text(raw.fromAddress, "fromAddress", 254);
+    const [local, domain, ...extra] = fromAddress.split("@");
+    if (extra.length > 0 || !local || local.length > 64 || !LOCAL_PART.test(local) || domain !== sendingDomain) {
+        fail(`fromAddress must be an address on ${sendingDomain} (lowercase, such as newsletter@${sendingDomain})`);
+    }
+    if (raw.instantAlerts !== undefined && typeof raw.instantAlerts !== "boolean")
+        fail("instantAlerts must be a boolean");
+    const instantAlerts = raw.instantAlerts === true;
+    if (!Array.isArray(raw.lists) || raw.lists.length === 0 || raw.lists.length > 20)
+        fail("lists must be a list of 1 to 20 lists");
+    const lists = raw.lists.map((entry, index) => resolveList(entry, index, instantAlerts));
+    const duplicates = lists.map((list) => list.id).filter((id, index, ids) => ids.indexOf(id) !== index);
+    if (duplicates.length > 0)
+        fail(`lists has duplicate ids: ${[...new Set(duplicates)].join(", ")}`);
+    const roundups = lists.filter((list) => list.kind === "roundup");
+    if (new Set(roundups.map((list) => list.archivePath)).size !== roundups.length)
+        fail("roundup lists need different archivePath values");
+    return {
+        siteId,
+        siteOrigin: origin(raw.siteOrigin),
+        computeRoleArn,
+        sendingDomain,
+        fromAddress,
+        fromName: text(raw.fromName, "fromName", 80),
+        instantAlerts,
+        theme: resolveTheme(raw.theme),
+        lists,
+        itemUrlStyle: itemUrlStyle(raw.itemUrlStyle),
+        configurationSet: matching(raw.configurationSet, "configurationSet", SES_NAME, "an SES configuration set name", `papyrus-${siteId}`),
+        eventTopicName: matching(raw.eventTopicName, "eventTopicName", SES_NAME, "an SNS topic name", `papyrus-newsletter-events-${siteId}`),
+    };
+}

package/amplify/plugins/newsletter/config.ts

@@ -0,0 +1,240 @@
+import type { PluginRequest } from "../types";
+
+export const NEWSLETTER_SITE_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+export const NEWSLETTER_LIST_ID = /^[a-z][a-z0-9-]{0,39}$/;
+export const COMPUTE_ROLE_ARN = /^arn:aws:iam::[0-9]{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
+const HOSTNAME = /^(?=.{1,253}$)[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/;
+const LOCAL_PART = /^[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*$/;
+const SES_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const ISSUE_TYPE = /^[a-z][a-z0-9_]{0,59}$/;
+/** One path segment: it is the Item section of the archive and the `urls.sections` key of the site's projection.json. */
+const ARCHIVE_PATH = /^\/[a-z0-9][a-z0-9_-]*\/$/;
+const SCHEDULER_CRON = /^cron\(\S+ \S+ \S+ \S+ \S+ \S+\)$/;
+const UNSAFE_CSS = /[<>{};"\\`]|url\(|expression\(|@import/i;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+
+export const ITEM_URL_STYLES = ["html", "directory", "clean"] as const;
+export type ItemUrlStyle = (typeof ITEM_URL_STYLES)[number];
+
+export type NewsletterTheme = {
+  accent: string;
+  text: string;
+  background: string;
+  surface?: string;
+  muted?: string;
+  fontFamily?: string;
+  logoUrl?: string;
+};
+
+export type NewsletterRule = { sections?: string[]; tags?: string[]; types?: string[] };
+
+type ListBase = { id: string; name: string; description: string };
+export type RoundupList = ListBase & {
+  kind: "roundup";
+  /** EventBridge Scheduler cron for assembling the draft, and the IANA time zone it runs in. */
+  schedule: { draft: string; timezone: string };
+  /** The CMS item type of an issue. */
+  issueType: string;
+  /** Where the sent issue is archived, such as `/roundup/`: one path segment, also the section the issue Items are filed under. */
+  archivePath: string;
+};
+export type AlertList = ListBase & {
+  kind: "alert";
+  /** Which published items raise an alert. Absent or empty: every published item (an admin still approves it). */
+  rule: NewsletterRule;
+  approval: "admin" | "none";
+};
+export type NewsletterList = RoundupList | AlertList;
+
+export type NewsletterConfig = {
+  /** The site id: names the key parameter, the configuration set and the event topic. Must match the sending stack's SiteId. */
+  siteId: string;
+  /** The site's public https origin: confirmation links point at `<siteOrigin>/api/newsletter/confirm`. */
+  siteOrigin: string;
+  /** The IAM role of the CMS app's server runtime (the `CmsComputeRoleArn` output of the app-shell stack): the only caller of the function. */
+  computeRoleArn: string;
+  sendingDomain: string;
+  fromAddress: string;
+  fromName: string;
+  /** A site must set this to true before any list may send without approval. */
+  instantAlerts: boolean;
+  theme: NewsletterTheme;
+  lists: NewsletterList[];
+  /** How the site addresses its item pages (`urls.style` in projection.json): roundup drafts link to published items with it. */
+  itemUrlStyle: ItemUrlStyle;
+  /** `papyrus-<siteId>` unless overridden. */
+  configurationSet: string;
+  /** `papyrus-newsletter-events-<siteId>` unless overridden. */
+  eventTopicName: string;
+};
+
+const KNOWN_KEYS = new Set([
+  "name", "siteId", "siteOrigin", "computeRoleArn", "sendingDomain", "fromAddress", "fromName", "instantAlerts", "theme", "lists",
+  "configurationSet", "eventTopicName", "itemUrlStyle",
+]);
+const LIST_KEYS = {
+  roundup: ["id", "name", "description", "kind", "schedule", "issueType", "archivePath"],
+  alert: ["id", "name", "description", "kind", "rule", "approval"],
+};
+
+function fail(message: string): never {
+  throw new Error(`newsletter plugin ${message}`);
+}
+
+function record(raw: unknown, label: string, known: string[]): Record<string, unknown> {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) fail(`${label} must be an object`);
+  const unknown = Object.keys(raw).filter((key) => !known.includes(key));
+  if (unknown.length > 0) fail(`${label} has unknown settings: ${unknown.join(", ")}`);
+  return raw as Record<string, unknown>;
+}
+
+function text(raw: unknown, label: string, maximum: number, options: { optional?: boolean; fallback?: string } = {}): string {
+  const value = raw === undefined ? options.fallback : raw;
+  if (value === undefined) fail(`${label} is required`);
+  if (typeof value !== "string" || CONTROL_CHARACTERS.test(value) || value.trim() !== value) {
+    fail(`${label} must be text on one line with no leading or trailing spaces`);
+  }
+  if (value.length === 0 && !options.optional) fail(`${label} is required`);
+  if (value.length > maximum) fail(`${label} must be at most ${maximum} characters`);
+  return value;
+}
+
+function matching(raw: unknown, label: string, pattern: RegExp, description: string, fallback?: string): string {
+  const value = raw === undefined ? fallback : raw;
+  if (typeof value !== "string" || !pattern.test(value)) fail(`${label} must be ${description}`);
+  return value;
+}
+
+function timeZone(raw: unknown, label: string): string {
+  const value = text(raw, label, 64);
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: value });
+  } catch {
+    fail(`${label} must be an IANA time zone such as America/New_York`);
+  }
+  return value;
+}
+
+function origin(raw: unknown): string {
+  const value = text(raw, "siteOrigin", 200);
+  let parsed: URL | undefined;
+  try {
+    parsed = new URL(value);
+  } catch {
+    parsed = undefined;
+  }
+  if (!parsed || parsed.protocol !== "https:" || parsed.origin !== value) fail("siteOrigin must be an https origin such as https://example.com with no path");
+  return value;
+}
+
+function stringList(raw: unknown, label: string): string[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw) || raw.length === 0 || raw.length > 50) fail(`${label} must be a list of 1 to 50 names`);
+  return [...new Set(raw.map((entry, index) => text(entry, `${label}[${index}]`, 80)))];
+}
+
+function itemUrlStyle(raw: unknown): ItemUrlStyle {
+  if (raw === undefined) return "html";
+  if (typeof raw !== "string" || !(ITEM_URL_STYLES as readonly string[]).includes(raw)) fail(`itemUrlStyle must be one of ${ITEM_URL_STYLES.join(", ")}`);
+  return raw as ItemUrlStyle;
+}
+
+function resolveTheme(raw: unknown): NewsletterTheme {
+  const theme = record(raw, "theme", ["accent", "text", "background", "surface", "muted", "fontFamily", "logoUrl"]);
+  const resolved: NewsletterTheme = {
+    accent: text(theme.accent, "theme.accent", 80),
+    text: text(theme.text, "theme.text", 80),
+    background: text(theme.background, "theme.background", 80),
+  };
+  for (const key of ["surface", "muted", "fontFamily"] as const) {
+    if (theme[key] !== undefined) resolved[key] = text(theme[key], `theme.${key}`, 200);
+  }
+  for (const [key, value] of Object.entries(resolved)) {
+    if (UNSAFE_CSS.test(value)) fail(`theme.${key} contains characters that are not allowed in a style value`);
+  }
+  if (theme.logoUrl !== undefined) {
+    const logoUrl = text(theme.logoUrl, "theme.logoUrl", 500);
+    if (!/^https:\/\//.test(logoUrl)) fail("theme.logoUrl must be an https URL");
+    resolved.logoUrl = logoUrl;
+  }
+  return resolved;
+}
+
+function resolveRule(raw: unknown, label: string): NewsletterRule {
+  if (raw === undefined) return {};
+  const rule = record(raw, label, ["sections", "tags", "types"]);
+  return {
+    ...(rule.sections === undefined ? {} : { sections: stringList(rule.sections, `${label}.sections`) }),
+    ...(rule.tags === undefined ? {} : { tags: stringList(rule.tags, `${label}.tags`) }),
+    ...(rule.types === undefined ? {} : { types: stringList(rule.types, `${label}.types`) }),
+  };
+}
+
+function resolveList(raw: unknown, index: number, instantAlerts: boolean): NewsletterList {
+  const label = `lists[${index}]`;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) fail(`${label} must be an object`);
+  const kind = (raw as Record<string, unknown>).kind;
+  if (kind !== "roundup" && kind !== "alert") fail(`${label}.kind must be "roundup" or "alert"`);
+  const list = record(raw, label, LIST_KEYS[kind]);
+  const base = {
+    id: matching(list.id, `${label}.id`, NEWSLETTER_LIST_ID, "lowercase letters, digits and hyphens, starting with a letter (at most 40 characters)"),
+    name: text(list.name, `${label}.name`, 80),
+    description: text(list.description, `${label}.description`, 300, { optional: true, fallback: "" }),
+  };
+  if (kind === "roundup") {
+    const schedule = record(list.schedule, `${label}.schedule`, ["draft", "timezone"]);
+    return {
+      ...base,
+      kind,
+      schedule: {
+        draft: matching(schedule.draft, `${label}.schedule.draft`, SCHEDULER_CRON, 'an EventBridge Scheduler cron such as "cron(0 13 ? * FRI *)"'),
+        timezone: timeZone(schedule.timezone, `${label}.schedule.timezone`),
+      },
+      issueType: matching(list.issueType, `${label}.issueType`, ISSUE_TYPE, "a lowercase item type name", "newsletter_issue"),
+      archivePath: matching(list.archivePath, `${label}.archivePath`, ARCHIVE_PATH, 'a path that starts and ends with "/", such as /roundup/'),
+    };
+  }
+  const approval = list.approval === undefined ? "admin" : list.approval;
+  if (approval !== "admin" && approval !== "none") fail(`${label}.approval must be "admin" or "none"`);
+  if (approval === "none" && !instantAlerts) {
+    fail(`${label}.approval "none" sends alerts without an admin approving them: set instantAlerts: true on the plugin first`);
+  }
+  return { ...base, kind, rule: resolveRule(list.rule, `${label}.rule`), approval };
+}
+
+export function resolveNewsletterConfig(request: PluginRequest): NewsletterConfig {
+  const raw = record(typeof request === "string" ? { name: request } : request, "settings", [...KNOWN_KEYS]);
+  const siteId = matching(raw.siteId, "siteId", NEWSLETTER_SITE_ID, "a lowercase site id (letters, digits, hyphens), the SiteId of the sending stack");
+  const computeRoleArn = raw.computeRoleArn;
+  if (typeof computeRoleArn !== "string" || !COMPUTE_ROLE_ARN.test(computeRoleArn)) {
+    fail("computeRoleArn must be the IAM role ARN of the CMS app's compute role (the CmsComputeRoleArn output)");
+  }
+  const sendingDomain = matching(raw.sendingDomain, "sendingDomain", HOSTNAME, "a lowercase domain name such as news.example.com");
+  const fromAddress = text(raw.fromAddress, "fromAddress", 254);
+  const [local, domain, ...extra] = fromAddress.split("@");
+  if (extra.length > 0 || !local || local.length > 64 || !LOCAL_PART.test(local) || domain !== sendingDomain) {
+    fail(`fromAddress must be an address on ${sendingDomain} (lowercase, such as newsletter@${sendingDomain})`);
+  }
+  if (raw.instantAlerts !== undefined && typeof raw.instantAlerts !== "boolean") fail("instantAlerts must be a boolean");
+  const instantAlerts = raw.instantAlerts === true;
+  if (!Array.isArray(raw.lists) || raw.lists.length === 0 || raw.lists.length > 20) fail("lists must be a list of 1 to 20 lists");
+  const lists = raw.lists.map((entry, index) => resolveList(entry, index, instantAlerts));
+  const duplicates = lists.map((list) => list.id).filter((id, index, ids) => ids.indexOf(id) !== index);
+  if (duplicates.length > 0) fail(`lists has duplicate ids: ${[...new Set(duplicates)].join(", ")}`);
+  const roundups = lists.filter((list) => list.kind === "roundup");
+  if (new Set(roundups.map((list) => (list as RoundupList).archivePath)).size !== roundups.length) fail("roundup lists need different archivePath values");
+  return {
+    siteId,
+    siteOrigin: origin(raw.siteOrigin),
+    computeRoleArn,
+    sendingDomain,
+    fromAddress,
+    fromName: text(raw.fromName, "fromName", 80),
+    instantAlerts,
+    theme: resolveTheme(raw.theme),
+    lists,
+    itemUrlStyle: itemUrlStyle(raw.itemUrlStyle),
+    configurationSet: matching(raw.configurationSet, "configurationSet", SES_NAME, "an SES configuration set name", `papyrus-${siteId}`),
+    eventTopicName: matching(raw.eventTopicName, "eventTopicName", SES_NAME, "an SNS topic name", `papyrus-newsletter-events-${siteId}`),
+  };
+}

package/amplify/plugins/newsletter/function/handler.py

@@ -0,0 +1,6 @@
+"""Bundle entry kept for the shared Python bundler, which copies ``handler.py`` to the asset root.
+
+The Lambda's handler is ``papyrus_content.newsletter.handler.handler`` (src/papyrus_content/newsletter/handler.py).
+"""
+
+from papyrus_content.newsletter.handler import handler  # noqa: F401

package/amplify/plugins/newsletter/function/requirements.txt

@@ -0,0 +1,5 @@
+PyYAML>=6.0.2,<7
+citeproc-py>=0.8.2,<1
+anthus-markus==0.7.0
+Pillow>=11.3,<12
+boto3>=1.35.8,<2

package/amplify/plugins/newsletter/ops/handler.py

@@ -0,0 +1,12 @@
+"""Bundle entry for the newsroom's newsletter operations (AppSync): forwards to the ``newsletter`` function.
+
+The logic is ``papyrus_content.newsletter.ops_proxy`` (src/papyrus_content/newsletter/ops_proxy.py).
+"""
+
+from typing import Any
+
+from papyrus_content.newsletter.ops_proxy import handle
+
+
+def handler(event: dict[str, Any], _context: Any = None) -> Any:
+    return handle(event)

package/amplify/plugins/newsletter/ops/resource.js

@@ -0,0 +1,27 @@
+import { defineFunction } from "@aws-amplify/backend";
+import { Duration } from "aws-cdk-lib";
+import { Architecture, Function, Runtime } from "aws-cdk-lib/aws-lambda";
+import { pythonLambdaCode } from "../../../functions/shared/python-bundle.js";
+/** AppSync gives a resolver 30 seconds; this function only forwards to `newsletter`, which answers in a few. */
+export const NEWSLETTER_OPS_TIMEOUT_SECONDS = 25;
+/**
+ * The newsroom's newsletter operations enter here because an Amplify custom operation needs an Amplify-defined function and
+ * the `newsletter` function itself lives in the plugin stack. It holds no data access: it may invoke that one function.
+ */
+export const newsletterOps = defineFunction((scope) => new Function(scope, "papyrus-newsletter-ops", {
+    runtime: Runtime.PYTHON_3_12,
+    architecture: Architecture.ARM_64,
+    handler: "handler.handler",
+    timeout: Duration.seconds(NEWSLETTER_OPS_TIMEOUT_SECONDS),
+    memorySize: 256,
+    code: pythonLambdaCode({ functionDir: "../plugins/newsletter/ops", modules: ["papyrus_content"], noDeps: true }, [
+        "bash",
+        "-c",
+        [
+            "set -euo pipefail",
+            "mkdir -p /asset-output/papyrus_content",
+            "cp amplify/plugins/newsletter/ops/handler.py /asset-output/handler.py",
+            "cp -R src/papyrus_content/. /asset-output/papyrus_content/",
+        ].join(" && "),
+    ]),
+}), { resourceGroupName: "data" });

package/amplify/plugins/newsletter/ops/resource.ts

@@ -0,0 +1,37 @@
+import { defineFunction } from "@aws-amplify/backend";
+import { Duration } from "aws-cdk-lib";
+import { Architecture, Function, Runtime } from "aws-cdk-lib/aws-lambda";
+import type { Construct } from "constructs";
+import { pythonLambdaCode } from "../../../functions/shared/python-bundle";
+
+/** AppSync gives a resolver 30 seconds; this function only forwards to `newsletter`, which answers in a few. */
+export const NEWSLETTER_OPS_TIMEOUT_SECONDS = 25;
+
+/**
+ * The newsroom's newsletter operations enter here because an Amplify custom operation needs an Amplify-defined function and
+ * the `newsletter` function itself lives in the plugin stack. It holds no data access: it may invoke that one function.
+ */
+export const newsletterOps = defineFunction(
+  (scope: Construct) =>
+    new Function(scope, "papyrus-newsletter-ops", {
+      runtime: Runtime.PYTHON_3_12,
+      architecture: Architecture.ARM_64,
+      handler: "handler.handler",
+      timeout: Duration.seconds(NEWSLETTER_OPS_TIMEOUT_SECONDS),
+      memorySize: 256,
+      code: pythonLambdaCode(
+        { functionDir: "../plugins/newsletter/ops", modules: ["papyrus_content"], noDeps: true },
+        [
+          "bash",
+          "-c",
+          [
+            "set -euo pipefail",
+            "mkdir -p /asset-output/papyrus_content",
+            "cp amplify/plugins/newsletter/ops/handler.py /asset-output/handler.py",
+            "cp -R src/papyrus_content/. /asset-output/papyrus_content/",
+          ].join(" && "),
+        ],
+      ),
+    }),
+  { resourceGroupName: "data" },
+);