@anthusai/papyrus 2.0.0-next.40 → 2.0.0-next.42

package/amplify/data/resource.js

@@ -856,6 +856,7 @@ const schema = a.schema({
         storyLineageId: a.id(),
         assignmentId: a.id(),
         maxCharacters: a.integer(),
+        optionalPublicationDoctrine: a.boolean(),
     })
         .returns(a.json().required())
         .authorization((allow) => [allow.groups(categoryWriteGroups)])

package/amplify/data/resource.ts

@@ -931,6 +931,7 @@ const schema = a.schema({
       storyLineageId: a.id(),
       assignmentId: a.id(),
       maxCharacters: a.integer(),
+      optionalPublicationDoctrine: a.boolean(),
     })
     .returns(a.json().required())
     .authorization((allow) => [allow.groups(categoryWriteGroups)])

package/amplify/data/schema.js

@@ -781,6 +781,7 @@ function buildBaseDefinitions(includeEditions) {
             storyLineageId: a.id(),
             assignmentId: a.id(),
             maxCharacters: a.integer(),
+            optionalPublicationDoctrine: a.boolean(),
         })
             .returns(a.json().required())
             .authorization((allow) => [allow.groups(categoryWriteGroups)])

package/amplify/data/schema.ts

@@ -854,6 +854,7 @@ const definitions = {
       storyLineageId: a.id(),
       assignmentId: a.id(),
       maxCharacters: a.integer(),
+      optionalPublicationDoctrine: a.boolean(),
     })
     .returns(a.json().required())
     .authorization((allow) => [allow.groups(categoryWriteGroups)])

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/assignment-action/handler.ts

@@ -316,7 +316,7 @@ async function listAssignmentsForObject(event: Parameters<Schema["listAssignment
   return contexts;
 }
 
-async function editorialContext(client: DataClient, scope: { publicationKey?: string; sectionId?: string | null; storyLineageId?: string | null; assignmentId?: string | null; maxCharacters?: number | null }) {
+async function editorialContext(client: DataClient, scope: { publicationKey?: string; sectionId?: string | null; storyLineageId?: string | null; assignmentId?: string | null; maxCharacters?: number | null; optionalPublicationDoctrine?: boolean | null }) {
   if (!editorialEndpoint) throw new Error("Editorial context requires the configured backend endpoint.");
   return resolveEditorialContext(client as unknown as EditorialClient, {
     ...scope, endpoint: editorialEndpoint, tenantId: tenantIdFromEnvironment(), readAttachment: readEditorialAttachment,

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

@@ -9,6 +9,7 @@ from papyrus_content.graphql_authoring import create_authoring_client
 from papyrus_content.markus_renderer.derive import derive_body
 from papyrus_content.projection.deploy_render import deploy_render, drift_metric_line
 from papyrus_content.projection.engine import project, project_all, project_item_pages
+from papyrus_content.reader_steering.task import TASK_NAME as READER_SNAPSHOT_TASK, run_reader_snapshot
 from papyrus_content.projection.runtime import (
     DEAD_LETTER_QUEUE_ENV,
     context_from_environment,
@@ -187,6 +188,8 @@ def run_projection_task(task: dict) -> dict:
         report = project_all(projection_context(client))
     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, 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,6 +13,10 @@ 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, 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>;
 };
 
@@ -38,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.");
 }
@@ -55,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) {
+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."];
@@ -65,7 +110,9 @@ export function buildEditorialContext(publication: EditorialRecord, scope: Edito
   if (!Number.isInteger(maxCharacters) || maxCharacters < 0) throw new Error("Editorial context budget must be nonnegative.");
   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 };
+    precedence: ["publication", "section", "assignment"], entries, sources: entries.map(value => value.source), warnings, text, totalCharacters,
+    ...(missingPublicationDoctrine.length ? { missingPublicationDoctrine } : {}),
+    ...(missingSectionConfiguration.length ? { missingSectionConfiguration } : {}) };
   return { ...payload, contextHash: digest(JSON.stringify(canonical(payload))), resolvedAt: new Date().toISOString() };
 }
 
@@ -83,7 +130,10 @@ export async function resolveEditorialContext(client: EditorialClient, options:
     corpusId: corpora[0].id, tenantId: options.tenantId ?? null, endpoint: options.endpoint };
   const entries: EditorialRecord[] = [];
   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;
@@ -110,6 +160,7 @@ export async function resolveEditorialContext(client: EditorialClient, options:
     const rows = await pages(client, "Item", options.tenantId ? "itemByTenantSlug" : "itemBySlug",
       options.tenantId ? { tenantSlug: tenantScopedValue(options.tenantId, slug) } : { slug });
     const current = rows.filter(row => row.type === "doctrine" && row.status === "private" && row.versionState === "current");
+    if (current.length === 0 && options.optionalPublicationDoctrine) { missingPublicationDoctrine.push(kind); continue; }
     if (current.length !== 1) throw new Error(`Publication ${kind}: expected exactly one current record, found ${current.length}.`);
     const record = current[0];
     tenant(record, options.tenantId);
@@ -118,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.");
@@ -147,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);
+  // 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