@anthusai/papyrus 2.0.0-next.7 → 2.0.0-next.70

package/amplify/plugins/newsletter/config.ts

@@ -0,0 +1,305 @@
+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;
+  /** Branding, all optional: a plain theme keeps the plain layout. Colours are CSS values; the border is 1.5px when set. */
+  headerBand?: string;
+  headerText?: string;
+  buttonFill?: string;
+  buttonText?: string;
+  buttonBorder?: string;
+  footerBand?: string;
+  footerText?: string;
+  /** An absolute https image, drawn with alt text and explicit pixel size (web fonts do not load in email). */
+  wordmarkImageUrl?: string;
+  wordmarkAlt?: string;
+  wordmarkWidth?: number;
+  wordmarkHeight?: number;
+  /** Draws the footer's wordmark at this width in pixels (1 to 400), smaller than the header's; the height keeps the aspect ratio. */
+  footerWordmarkWidth?: number;
+  labelFont?: string;
+};
+
+const THEME_STYLE_KEYS = [
+  "surface", "muted", "fontFamily", "headerBand", "headerText", "buttonFill", "buttonText", "buttonBorder", "footerBand",
+  "footerText", "labelFont",
+] as const;
+const THEME_KEYS = [
+  "accent", "text", "background", ...THEME_STYLE_KEYS, "logoUrl", "wordmarkImageUrl", "wordmarkAlt", "wordmarkWidth", "wordmarkHeight",
+  "footerWordmarkWidth",
+];
+
+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. The plugin's pages are at `<siteOrigin><basePath>/newsletter/...`. */
+  siteOrigin: string;
+  /** The site's `urls.basePath` from projection.json, as a path without slashes at either end ("" for a site at the root, "posts" for dataparade.io/posts). */
+  basePath: 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", "basePath", "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;
+}
+
+/** `urls.basePath` as projection.json writes it ("/posts" or "posts"): lowercase path segments, no dots, at most 3 deep. */
+const BASE_PATH = /^[a-z0-9][a-z0-9_-]*(\/[a-z0-9][a-z0-9_-]*){0,2}$/;
+
+function basePath(raw: unknown): string {
+  if (raw === undefined) return "";
+  const value = typeof raw === "string" ? raw.replace(/^\/+|\/+$/g, "") : null;
+  if (value === null || (value !== "" && !BASE_PATH.test(value))) fail('basePath must be the site\'s urls.basePath, a lowercase path such as "/posts"');
+  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", THEME_KEYS);
+  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 THEME_STYLE_KEYS) {
+    if (theme[key] !== undefined) resolved[key] = text(theme[key], `theme.${key}`, 200);
+  }
+  for (const [key, value] of Object.entries(resolved)) {
+    if (typeof value === "string" && 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;
+  }
+  if (theme.wordmarkImageUrl !== undefined) {
+    const url = text(theme.wordmarkImageUrl, "theme.wordmarkImageUrl", 500);
+    if (!/^https:\/\/[^\s"'<>\\`]+$/.test(url)) fail("theme.wordmarkImageUrl must be an absolute https URL");
+    resolved.wordmarkImageUrl = url;
+    for (const key of ["wordmarkWidth", "wordmarkHeight"] as const) {
+      const value = theme[key];
+      if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 2000) {
+        fail(`theme.${key} is required with theme.wordmarkImageUrl and must be a whole number of pixels from 1 to 2000`);
+      }
+      resolved[key] = value;
+    }
+  } else if (theme.wordmarkWidth !== undefined || theme.wordmarkHeight !== undefined) {
+    fail("theme.wordmarkWidth and theme.wordmarkHeight need theme.wordmarkImageUrl");
+  }
+  if (theme.footerWordmarkWidth !== undefined) {
+    if (theme.wordmarkImageUrl === undefined) fail("theme.footerWordmarkWidth needs theme.wordmarkImageUrl");
+    const width = theme.footerWordmarkWidth;
+    if (typeof width !== "number" || !Number.isInteger(width) || width < 1 || width > 400) {
+      fail("theme.footerWordmarkWidth must be a whole number of pixels from 1 to 400");
+    }
+    resolved.footerWordmarkWidth = width;
+  }
+  if (theme.wordmarkAlt !== undefined) {
+    const alt = text(theme.wordmarkAlt, "theme.wordmarkAlt", 200);
+    if (/[\u0000-\u001f\u007f]/.test(alt)) fail("theme.wordmarkAlt must not contain control characters");
+    resolved.wordmarkAlt = alt;
+  }
+  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),
+    basePath: basePath(raw.basePath),
+    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" },
+);

package/amplify/plugins/newsletter/papyrus.plugin.js

@@ -0,0 +1,263 @@
+import { Duration, RemovalPolicy, Stack } from "aws-cdk-lib";
+import { Alarm, ComparisonOperator, MathExpression, Metric, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
+import { AttributeType, BillingMode, ProjectionType, Table, TableEncryption } from "aws-cdk-lib/aws-dynamodb";
+import { ArnPrincipal, Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Key } from "aws-cdk-lib/aws-kms";
+import { Topic } from "aws-cdk-lib/aws-sns";
+import { LambdaSubscription } from "aws-cdk-lib/aws-sns-subscriptions";
+import { Architecture, Function as LambdaFunction, Runtime } from "aws-cdk-lib/aws-lambda";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { SecureStringParameter } from "./secure-string-parameter.js";
+import { pythonLambdaCode } from "../../functions/shared/python-bundle.js";
+import { resolveNewsletterConfig } from "./config.js";
+import { newsletterOps } from "./ops/resource.js";
+import { NEWSLETTER_MUTATIONS, NEWSLETTER_QUERIES, newsletterSchemaDefinitions } from "./schema.js";
+import { functionArn, newsletterFunctionName, wireSending } from "./sending.js";
+export { resolveNewsletterConfig };
+export const NEWSLETTER_OUTPUT_KEY = "newsletter";
+/** Set on the site's content-actions function: it invokes this function (`item-published`) after a real publish. Unset: no alerts. */
+export const NEWSLETTER_FUNCTION_ENV = "PAPYRUS_NEWSLETTER_FUNCTION";
+export const NEWSLETTER_HANDLER = "papyrus_content.newsletter.handler.handler";
+/** `boto3` is bundled because the runtime's copy may predate SESv2 `Simple.Headers` (List-Unsubscribe). */
+export const NEWSLETTER_REQUIREMENTS = ["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"];
+/** Relative to `amplify/functions/`, which is where the shared bundler looks for a function's `handler.py`. */
+const FUNCTION_DIRECTORY = "../plugins/newsletter/function";
+export const newsletterManifest = {
+    name: "newsletter",
+    contract: 1,
+    models: [],
+    queries: NEWSLETTER_QUERIES,
+    mutations: NEWSLETTER_MUTATIONS,
+    guest: { mutations: [] },
+    newsroomPanels: [],
+    staticAssets: ["_plugins/papyrus-newsletter@1.js", "_plugins/papyrus-newsletter-pages@1.js"],
+};
+let codeForTests;
+/** Synthesis tests swap the bundled Python asset (a pip install) for inline code. Pass nothing to restore it. */
+export function overrideNewsletterCodeForTests(code) {
+    codeForTests = code;
+}
+export function newsletterKeyParameterName(siteId) {
+    return `/papyrus/${siteId}/newsletter-key`;
+}
+/** The SES identity ARN and configuration set ARN the function may send through. */
+export function newsletterSesResources(stack, config) {
+    return [
+        `arn:${stack.partition}:ses:${stack.region}:${stack.account}:identity/${config.sendingDomain}`,
+        `arn:${stack.partition}:ses:${stack.region}:${stack.account}:configuration-set/${config.configurationSet}`,
+    ];
+}
+export const BOUNCE_RATE_THRESHOLD = 0.04;
+export const COMPLAINT_RATE_THRESHOLD = 0.0008;
+export const ALARM_MINIMUM_SENDS = 50;
+export function newsletterAlarmTopicName(siteId) {
+    return `papyrus-newsletter-alarms-${siteId}`;
+}
+/** The two alarm names; the function pauses sending only for these (python: `events.alarm_names`). */
+export function newsletterAlarmNames(siteId) {
+    return { bounce: `papyrus-newsletter-${siteId}-bounce-rate`, complaint: `papyrus-newsletter-${siteId}-complaint-rate` };
+}
+/** What the function reads from its environment. Lists carry only what it needs to name them in the email. */
+export function newsletterEnvironment(config, tableName, keyParameter) {
+    return {
+        TABLE_NAME: tableName,
+        KEY_PARAMETER: keyParameter,
+        SITE_ID: config.siteId,
+        SITE_ORIGIN: config.siteOrigin,
+        SITE_BASE_PATH: config.basePath,
+        SENDING_DOMAIN: config.sendingDomain,
+        FROM_ADDRESS: config.fromAddress,
+        FROM_NAME: config.fromName,
+        CONFIGURATION_SET: config.configurationSet,
+        ITEM_URL_STYLE: config.itemUrlStyle,
+        INSTANT_ALERTS: config.instantAlerts ? "true" : "false",
+        LISTS_JSON: JSON.stringify(config.lists.map((list) => ({
+            id: list.id,
+            name: list.name,
+            description: list.description,
+            kind: list.kind,
+            // A roundup's issue type, archive section and time zone are what drafting needs; its schedule stays in the stack.
+            ...(list.kind === "roundup" ? { issueType: list.issueType, archivePath: list.archivePath, timezone: list.schedule.timezone } : {}),
+            // An alert's rule and approval decide which published items raise an alert and whether an admin approves it.
+            ...(list.kind === "alert" ? { rule: list.rule, approval: list.approval } : {}),
+        }))),
+        THEME_JSON: JSON.stringify(config.theme),
+        ALARM_NAMES: Object.values(newsletterAlarmNames(config.siteId)).join(","),
+    };
+}
+export const newsletterPlugin = {
+    manifest: newsletterManifest,
+    resolveConfig: resolveNewsletterConfig,
+    functions: () => ({ newsletterOps }),
+    schemaDefinitions: newsletterSchemaDefinitions,
+    publicSettings: (config) => ({
+        contract: newsletterManifest.contract,
+        fromName: config.fromName,
+        // The CMS routes redirect people to the plugin's pages under the site's base path.
+        basePath: config.basePath,
+        lists: config.lists.map((list) => ({
+            id: list.id,
+            name: list.name,
+            description: list.description,
+            kind: list.kind,
+            // The panel needs the item type to open an issue in the editor and the archive path to show where it lands.
+            ...(list.kind === "roundup" ? { issueType: list.issueType, archivePath: list.archivePath } : {}),
+        })),
+        theme: config.theme,
+    }),
+    wire(backend, config, context) {
+        const stack = Stack.of(context.createStack("newsletter"));
+        const key = new Key(stack, "NewsletterKey", {
+            description: `Encrypts the ${config.siteId} newsletter subscriber table`,
+            enableKeyRotation: true,
+            removalPolicy: RemovalPolicy.RETAIN,
+        });
+        const table = new Table(stack, "NewsletterTable", {
+            partitionKey: { name: "pk", type: AttributeType.STRING },
+            sortKey: { name: "sk", type: AttributeType.STRING },
+            billingMode: BillingMode.PAY_PER_REQUEST,
+            timeToLiveAttribute: "expiresAt",
+            encryption: TableEncryption.CUSTOMER_MANAGED,
+            encryptionKey: key,
+            // Point-in-time recovery stays off so that erasing a subscriber is real erasure.
+            pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: false },
+            removalPolicy: RemovalPolicy.RETAIN,
+        });
+        table.addGlobalSecondaryIndex({
+            indexName: "byList",
+            partitionKey: { name: "gsiList", type: AttributeType.STRING },
+            sortKey: { name: "sk", type: AttributeType.STRING },
+            projectionType: ProjectionType.KEYS_ONLY,
+        });
+        // Sparse: only send-ledger rows carry `gsiHid`, so erasing a subscriber finds their rows with one query, not a scan.
+        table.addGlobalSecondaryIndex({
+            indexName: "byHid",
+            partitionKey: { name: "gsiHid", type: AttributeType.STRING },
+            projectionType: ProjectionType.KEYS_ONLY,
+        });
+        const keyParameter = new SecureStringParameter(stack, "NewsletterKeyParameter", {
+            parameterName: newsletterKeyParameterName(config.siteId),
+            description: `Root key for ${config.siteId} newsletter subscriber hashing and link signing (HKDF-derived)`,
+        });
+        const functionDirectory = path.dirname(fileURLToPath(import.meta.url));
+        // One bundle serves the `newsletter` function and the send worker; they differ in handler, timeout and IAM.
+        const code = codeForTests ?? pythonLambdaCode({
+            functionDir: FUNCTION_DIRECTORY,
+            modules: ["papyrus_content"],
+            requirements: NEWSLETTER_REQUIREMENTS,
+            noDeps: true,
+            checkoutExtras: (outputDir) => installRequirements(path.join(functionDirectory, "function", "requirements.txt"), outputDir),
+        }, [
+            "bash",
+            "-c",
+            [
+                "set -euo pipefail",
+                "mkdir -p /asset-output/papyrus_content",
+                "cp amplify/plugins/newsletter/function/handler.py /asset-output/handler.py",
+                "cp -R src/papyrus_content/. /asset-output/papyrus_content/",
+                "python3 -m pip install -r amplify/plugins/newsletter/function/requirements.txt -t /asset-output --no-cache-dir",
+            ].join(" && "),
+        ]);
+        const environment = newsletterEnvironment(config, table.tableName, keyParameter.parameterName);
+        const lambda = new LambdaFunction(stack, "NewsletterFunction", {
+            functionName: newsletterFunctionName(config.siteId),
+            runtime: Runtime.PYTHON_3_12,
+            architecture: Architecture.ARM_64,
+            handler: NEWSLETTER_HANDLER,
+            // Starting a send pages the whole list and queues it, so this is longer than a signup needs.
+            timeout: Duration.seconds(120),
+            memorySize: 512,
+            description: `Newsletter for ${config.siteId}: subscriptions, roundup drafts, approval and starting sends`,
+            environment,
+            code,
+        });
+        table.grantReadWriteData(lambda); // includes the table key's encrypt and decrypt
+        lambda.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["ssm:GetParameter"], resources: [keyParameter.parameterArn] }));
+        lambda.addToRolePolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["ses:SendEmail", "ses:SendRawEmail"],
+            resources: newsletterSesResources(stack, config),
+            conditions: { StringEquals: { "ses:FromAddress": config.fromAddress } },
+        }));
+        wireSending({
+            stack,
+            config,
+            context,
+            backend,
+            table,
+            lambda,
+            environment,
+            keyParameterArn: keyParameter.parameterArn,
+            sesResources: newsletterSesResources(stack, config),
+            code,
+        });
+        // The SES configuration set's own sending switch, for the alarm pause. Nothing else of SES is writable.
+        lambda.addToRolePolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["ses:PutConfigurationSetSendingOptions"],
+            resources: [newsletterSesResources(stack, config)[1]],
+        }));
+        // Lifting a suppression after a deliberate re-subscribe. IAM has no resource-level scope for the account list.
+        lambda.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["ses:DeleteSuppressedDestination"], resources: ["*"] }));
+        // SES delivery events: the topic belongs to the sending stack and is named literally.
+        const eventTopic = Topic.fromTopicArn(stack, "SesEventTopic", `arn:${stack.partition}:sns:${stack.region}:${stack.account}:${config.eventTopicName}`);
+        eventTopic.addSubscription(new LambdaSubscription(lambda));
+        // Bounce and complaint rate alarms over the CloudWatch event destination, 24 h period, at least 50 sends.
+        const alarmTopic = new Topic(stack, "AlarmTopic", { topicName: newsletterAlarmTopicName(config.siteId) });
+        alarmTopic.addSubscription(new LambdaSubscription(lambda));
+        const metric = (metricName) => new Metric({
+            namespace: "AWS/SES",
+            metricName,
+            dimensionsMap: { "ses:configuration-set": config.configurationSet },
+            statistic: "Sum",
+            period: Duration.hours(24),
+        });
+        const names = newsletterAlarmNames(config.siteId);
+        for (const [id, alarmName, metricName, threshold] of [
+            ["BounceRateAlarm", names.bounce, "Bounce", BOUNCE_RATE_THRESHOLD],
+            ["ComplaintRateAlarm", names.complaint, "Complaint", COMPLAINT_RATE_THRESHOLD],
+        ]) {
+            const rate = new MathExpression({
+                expression: `IF(sent >= ${ALARM_MINIMUM_SENDS}, FILL(events, 0) / sent, 0)`,
+                usingMetrics: { sent: metric("Send"), events: metric(metricName) },
+                period: Duration.hours(24),
+                label: `${metricName} rate`,
+            });
+            const alarm = new Alarm(stack, id, {
+                alarmName,
+                alarmDescription: `${metricName} rate above ${threshold * 100}% of sends in 24 hours (at least ${ALARM_MINIMUM_SENDS} sends): pauses ${config.siteId} newsletter sending`,
+                metric: rate,
+                threshold,
+                evaluationPeriods: 1,
+                comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+                treatMissingData: TreatMissingData.NOT_BREACHING,
+            });
+            alarm.addAlarmAction(new SnsAction(alarmTopic));
+        }
+        // The publish path tells this function about a real publish. The ARN is spelled out (not referenced) so the content-actions
+        // stack does not depend on this one, and the grant is for this one function only.
+        const contentActions = context.contentActionsLambda;
+        contentActions.addEnvironment(NEWSLETTER_FUNCTION_ENV, newsletterFunctionName(config.siteId));
+        contentActions.addToRolePolicy(new PolicyStatement({
+            effect: Effect.ALLOW,
+            actions: ["lambda:InvokeFunction"],
+            resources: [functionArn(Stack.of(contentActions), newsletterFunctionName(config.siteId))],
+        }));
+        lambda.addPermission("InvokeFromCmsCompute", {
+            principal: new ArnPrincipal(config.computeRoleArn),
+            action: "lambda:InvokeFunction",
+        });
+        backend.addOutput({ custom: { [NEWSLETTER_OUTPUT_KEY]: { actionsFunction: lambda.functionName } } });
+    },
+};
+function installRequirements(requirementsPath, outputDir) {
+    // Same wheels and platform as the other Python functions: a Lambda on arm64 with CPython 3.12.
+    execFileSync("python3", [
+        "-m", "pip", "install", "-r", requirementsPath, "-t", outputDir, "--no-cache-dir",
+        "--platform", "manylinux2014_aarch64", "--implementation", "cp", "--python-version", "3.12",
+        "--only-binary=:all:", "--ignore-requires-python",
+    ], { stdio: "inherit" });
+}