@anthusai/papyrus 2.0.0-next.41 → 2.0.0-next.43

package/amplify/functions/assignment-action/data-access.js

@@ -9,6 +9,8 @@ export const ASSIGNMENT_DATA_FIELDS = [
     "Query/fields/getProcedureDefinition",
     "Query/fields/getModelAttachment",
     "Query/fields/getNewsroomSection",
+    "Query/fields/listNewsroomSections",
+    "Query/fields/listNewsroomSectionsByTenantAndSortOrder",
     "Query/fields/getKnowledgeCorpus",
     "Query/fields/getKnowledgeImportRun",
     "Query/fields/getReference",

package/amplify/functions/assignment-action/data-access.ts

@@ -11,6 +11,8 @@ export const ASSIGNMENT_DATA_FIELDS = [
   "Query/fields/getProcedureDefinition",
   "Query/fields/getModelAttachment",
   "Query/fields/getNewsroomSection",
+  "Query/fields/listNewsroomSections",
+  "Query/fields/listNewsroomSectionsByTenantAndSortOrder",
   "Query/fields/getKnowledgeCorpus",
   "Query/fields/getKnowledgeImportRun",
   "Query/fields/getReference",

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

@@ -189,7 +189,7 @@ def run_projection_task(task: dict) -> dict:
     elif task.get("task") == "deploy-render":
         return run_deploy_render_task(client)
     elif task.get("task") == READER_SNAPSHOT_TASK:
-        return run_reader_snapshot(projection_context(client), client).to_dict()
+        return run_reader_snapshot(projection_context(client), client, poll_retirements=task.get("retirementPoll") is True).to_dict()
     elif task.get("task") == "invalidate":
         invalidate = projection_context(client).invalidate
         if invalidate is None:

package/amplify/functions/shared/editorial-context.ts

@@ -13,8 +13,9 @@ export type EditorialOptions = {
   storyLineageId?: string | null;
   assignmentId?: string | null;
   maxCharacters?: number | null;
-  /** A publication without a current mission or policy record yields missingPublicationDoctrine instead of an error.
-   * Only the editorial check asks for this (its rule lane needs no doctrine); more than one current record is still an error. */
+  /** A publication without a current mission or policy record yields missingPublicationDoctrine instead of an error, and a
+   * section value that matches no NewsroomSection yields missingSectionConfiguration instead of an error.
+   * Only the editorial check asks for this (its rule lane needs neither); more than one current record is still an error. */
   optionalPublicationDoctrine?: boolean | null;
   readAttachment: (attachment: EditorialRecord) => Promise<string>;
 };
@@ -41,6 +42,47 @@ async function get(client: EditorialClient, model: string, id: string) {
   return row;
 }
 
+const slugOf = (value: string) => value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+const localPart = (id: string) => id.split("#").at(-1) ?? id;
+
+async function allSections(client: EditorialClient) {
+  const rows: EditorialRecord[] = [];
+  let nextToken: string | null | undefined;
+  do {
+    const response = checked(await client.models.NewsroomSection.list({ limit: 100, nextToken }), "read NewsroomSection list");
+    rows.push(...(response.data as EditorialRecord[] ?? []));
+    nextToken = response.nextToken;
+  } while (nextToken);
+  return rows;
+}
+
+/** An item stores its section as an id, a slug or a name; find the NewsroomSection of this publication it means.
+ * Order: id (as given, then tenant-scoped), then slug (the id's local part), then name (title or short title).
+ * Returns null when nothing matches; two sections matching at the same step is an error. */
+async function findSection(client: EditorialClient, value: string, tenantId?: string) {
+  const direct = checked(await client.models.NewsroomSection.get({ id: value }), "read NewsroomSection").data as EditorialRecord | null;
+  if (direct) return direct;
+  if (tenantId) {
+    const scoped = checked(await client.models.NewsroomSection.get({ id: tenantScopedValue(tenantId, value) }), "read NewsroomSection").data as EditorialRecord | null;
+    if (scoped) return scoped;
+  }
+  const all = tenantId
+    ? await pages(client, "NewsroomSection", "listNewsroomSectionsByTenantAndSortOrder", { tenantId })
+    : (await allSections(client)).filter(row => !row.tenantId);
+  const wanted = slugOf(value);
+  const steps: ((row: EditorialRecord) => boolean)[] = [
+    row => slugOf(localPart(String(row.id ?? ""))) === wanted,
+    row => [row.title, row.shortTitle].some(name => typeof name === "string" && name.trim().toLowerCase() === value.trim().toLowerCase()),
+    row => [row.title, row.shortTitle].some(name => typeof name === "string" && slugOf(name) === wanted),
+  ];
+  for (const step of steps) {
+    const matches = all.filter(step);
+    if (matches.length > 1) throw new Error(`Section "${value}" is ambiguous: ${matches.map(row => row.id).join(", ")}.`);
+    if (matches.length === 1) return matches[0];
+  }
+  return null;
+}
+
 function tenant(row: EditorialRecord, tenantId?: string) {
   if ((row.tenantId || null) !== (tenantId || null)) throw new Error("Editorial record tenant does not match the configured authoring scope.");
 }
@@ -58,7 +100,7 @@ function entry(scope: string, kind: string, text: string, record: EditorialRecor
   } };
 }
 
-export function buildEditorialContext(publication: EditorialRecord, scope: EditorialRecord, entries: EditorialRecord[], warnings: string[], maxCharacters = 0, missingPublicationDoctrine: string[] = []) {
+export function buildEditorialContext(publication: EditorialRecord, scope: EditorialRecord, entries: EditorialRecord[], warnings: string[], maxCharacters = 0, missingPublicationDoctrine: string[] = [], missingSectionConfiguration: string[] = []) {
   const lines = [`Editorial context: ${publication.key}`, "Source: cloud",
     "Precedence: publication > section > assignment. Surface conflicts; narrower instructions do not silently override publication policy.",
     "Private operating guidance; not evidence or reader-facing copy."];
@@ -69,7 +111,8 @@ export function buildEditorialContext(publication: EditorialRecord, scope: Edito
   if (maxCharacters && totalCharacters > maxCharacters) throw new Error(`Editorial context budget ${maxCharacters} cannot hold ${totalCharacters} required characters; policy was not truncated.`);
   const payload = { schemaVersion: 1, rendererVersion: "editorial-context/v1", publication, scope, sourceMode: "cloud",
     precedence: ["publication", "section", "assignment"], entries, sources: entries.map(value => value.source), warnings, text, totalCharacters,
-    ...(missingPublicationDoctrine.length ? { missingPublicationDoctrine } : {}) };
+    ...(missingPublicationDoctrine.length ? { missingPublicationDoctrine } : {}),
+    ...(missingSectionConfiguration.length ? { missingSectionConfiguration } : {}) };
   return { ...payload, contextHash: digest(JSON.stringify(canonical(payload))), resolvedAt: new Date().toISOString() };
 }
 
@@ -89,6 +132,8 @@ export async function resolveEditorialContext(client: EditorialClient, options:
   const warnings: string[] = [];
   const missingPublicationDoctrine: string[] = [];
   let sectionId = options.sectionId || null;
+  let requestedSection: string | null = null;
+  const missingSectionConfiguration: string[] = [];
   let storyLineageId = options.storyLineageId || null;
   const assignmentId = options.assignmentId || null;
   let assignment: EditorialRecord | undefined;
@@ -124,13 +169,19 @@ export async function resolveEditorialContext(client: EditorialClient, options:
     entries.push(entry("publication", kind, text, record));
   }
   if (sectionId) {
-    const section = await get(client, "NewsroomSection", sectionId);
+    const section = await findSection(client, sectionId, options.tenantId);
+    if (!section && !options.optionalPublicationDoctrine) throw new Error(`NewsroomSection not found: ${sectionId}`);
+    if (!section) { missingSectionConfiguration.push(sectionId); requestedSection = sectionId; sectionId = null; }
+    else {
     tenant(section, options.tenantId);
+    if (section.id !== sectionId) requestedSection = sectionId;
+    sectionId = section.id;
     for (const [kind, key] of [["mission", "editorialMission"], ["policy", "editorialPolicy"], ["guidance", "assignmentGuidance"], ["kill criteria", "killCriteria"]]) {
       const text = String(section[key] || "").trim();
       if (text) entries.push(entry("section", kind, text, section));
       else if (kind === "mission" || kind === "policy") warnings.push(`Section ${section.id} intentionally has an empty ${kind} slot; publication doctrine still applies.`);
     }
+    }
   }
   if (assignment) {
     if (options.tenantId && !storyLineageId && !sectionId) throw new Error("A tenant assignment needs a scoped story or section to establish its publication.");
@@ -153,7 +204,9 @@ export async function resolveEditorialContext(client: EditorialClient, options:
       warnings.push("No assignment brief attachment exists; the Assignment summary is supplied as its brief.");
     }
   }
-  return buildEditorialContext(publication, { sectionId, storyLineageId, assignmentId }, entries, warnings, options.maxCharacters ?? 0, missingPublicationDoctrine);
+  // requestedSection: the value the caller asked for when it was not the section's id (a slug or name, or nothing matched).
+  const scope = { sectionId, storyLineageId, assignmentId, ...(requestedSection ? { requestedSection } : {}) };
+  return buildEditorialContext(publication, scope, entries, warnings, options.maxCharacters ?? 0, missingPublicationDoctrine, missingSectionConfiguration);
 }
 
 export function assignmentDoctrine(pack: Awaited<ReturnType<typeof resolveEditorialContext>>) {

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