@anthusai/papyrus 2.0.0-next.8 → 2.0.0-next.80

package/lib/newsletter-api.ts

@@ -0,0 +1,418 @@
+import { isIP } from "node:net";
+import { NextResponse, type NextRequest } from "next/server";
+import { readAmplifyOutputsFile } from "./amplify-outputs-path";
+import { PROSPECTUS_SESSION_COOKIE, loadProspectusSessionSealingSecret } from "./prospectus-session";
+import { signedInProspectusSession } from "./prospectus-sign-in-routes";
+import { readerSubject } from "./reader-subject";
+import { SiteOriginNotConfiguredError, publicSiteOrigin, siteOriginNotConfiguredResponse } from "./site-origin";
+
+export const NEWSLETTER_FUNCTION_ENV = "PAPYRUS_NEWSLETTER_FUNCTION";
+export const NEWSLETTER_SUBSCRIBE_MAXIMUM_BODY_BYTES = 8192;
+export const NEWSLETTER_CONFIRM_MAXIMUM_BODY_BYTES = 4096;
+export const NEWSLETTER_USER_AGENT_CHARACTERS = 300;
+export const NEWSLETTER_TOKEN = /^[A-Za-z0-9._-]{1,2048}$/;
+const MAXIMUM_LISTS = 20;
+const LIST_ID = /^[a-z][a-z0-9-]{0,39}$/;
+
+export type NewsletterEvent = { action: string } & Record<string, unknown>;
+export interface NewsletterResult {
+  statusCode: number;
+  body: Record<string, unknown>;
+}
+export type NewsletterInvoker = (functionName: string, event: NewsletterEvent) => Promise<NewsletterResult>;
+
+export interface NewsletterApiOptions {
+  environment?: Record<string, string | undefined>;
+  invoke?: NewsletterInvoker;
+  /** The parsed `amplify_outputs.json`; read from disk when absent. */
+  outputs?: Record<string, unknown> | null;
+  loadSealingSecret?: () => Promise<string | null>;
+  nowInSeconds?: number;
+}
+
+const NO_STORE = { "cache-control": "no-store" };
+
+function failure(status: number, error: string, message: string): NextResponse {
+  return NextResponse.json({ error, message }, { status, headers: NO_STORE });
+}
+
+export async function invokeNewsletterLambda(functionName: string, event: NewsletterEvent): Promise<NewsletterResult> {
+  const { InvokeCommand, LambdaClient } = await import("@aws-sdk/client-lambda");
+  const response = await new LambdaClient({}).send(
+    new InvokeCommand({ FunctionName: functionName, InvocationType: "RequestResponse", Payload: Buffer.from(JSON.stringify(event)) }),
+  );
+  if (response.FunctionError || !response.Payload) throw new Error("newsletter failed");
+  const result = JSON.parse(Buffer.from(response.Payload).toString("utf8")) as Partial<NewsletterResult>;
+  if (typeof result.statusCode !== "number" || typeof result.body !== "object" || result.body === null) {
+    throw new Error("newsletter returned an unexpected shape");
+  }
+  return { statusCode: result.statusCode, body: result.body as Record<string, unknown> };
+}
+
+type Enabled = { settings: Record<string, unknown>; functionName: string | null };
+
+function enabledPlugin(options: NewsletterApiOptions, environment: Record<string, string | undefined>): Enabled | null {
+  let outputs: Record<string, unknown> | null;
+  try {
+    outputs = options.outputs !== undefined ? options.outputs : readAmplifyOutputsFile();
+  } catch {
+    return null;
+  }
+  const custom = (outputs as { custom?: { papyrusPlugins?: Record<string, unknown>; newsletter?: { actionsFunction?: unknown } } } | null)?.custom;
+  const settings = custom?.papyrusPlugins?.newsletter;
+  if (typeof settings !== "object" || settings === null) return null;
+  const fromEnvironment = (environment[NEWSLETTER_FUNCTION_ENV] ?? "").trim();
+  const fromOutputs = custom?.newsletter?.actionsFunction;
+  const functionName = fromEnvironment || (typeof fromOutputs === "string" && fromOutputs.trim() ? fromOutputs.trim() : null);
+  return { settings: settings as Record<string, unknown>, functionName };
+}
+
+function notFoundJson(): NextResponse {
+  return failure(404, "not_found", "Not found.");
+}
+
+function notFoundPage(): NextResponse {
+  return new NextResponse("Not found", { status: 404, headers: { ...NO_STORE, "content-type": "text/plain; charset=utf-8" } });
+}
+
+/** The visitor's address from CloudFront's `ip:port` header (IPv6 may be bracketed), else the first x-forwarded-for entry. */
+export function clientAddress(headers: Pick<Headers, "get">): string {
+  const viewer = (headers.get("cloudfront-viewer-address") ?? "").trim();
+  if (viewer) {
+    let candidate: string;
+    if (viewer.startsWith("[")) candidate = viewer.slice(1, Math.max(viewer.indexOf("]"), 1));
+    else if (isIP(viewer) === 4) candidate = viewer;
+    else candidate = viewer.slice(0, Math.max(viewer.lastIndexOf(":"), 0));
+    if (isIP(candidate)) return candidate;
+  }
+  const forwarded = (headers.get("x-forwarded-for") ?? "").split(",")[0]?.trim() ?? "";
+  return isIP(forwarded) ? forwarded : "unknown";
+}
+
+async function readBody(request: NextRequest, maximum: number, contentTypes: string[] | null): Promise<{ text: string } | { response: NextResponse }> {
+  const contentType = (request.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+  if (contentTypes !== null && !contentTypes.includes(contentType)) return { response: failure(415, "unsupported_media_type", `Send ${(contentTypes ?? []).join(" or ")}.`) };
+  const declared = Number(request.headers.get("content-length") ?? "0");
+  if (Number.isFinite(declared) && declared > maximum) return { response: failure(413, "payload_too_large", "The request body is too large.") };
+  const text = await request.text();
+  if (Buffer.byteLength(text, "utf8") > maximum) return { response: failure(413, "payload_too_large", "The request body is too large.") };
+  return { text };
+}
+
+function listIds(raw: unknown): string[] {
+  const entries = typeof raw === "string" ? raw.slice(0, 1000).split(",") : Array.isArray(raw) ? raw : [];
+  return entries
+    .filter((entry): entry is string => typeof entry === "string")
+    .map((entry) => entry.trim())
+    .filter((entry) => LIST_ID.test(entry))
+    .slice(0, MAXIMUM_LISTS);
+}
+
+function limited(value: unknown, maximum: number): string {
+  return typeof value === "string" ? value.slice(0, maximum) : "";
+}
+
+/** The reader's pairwise site subject when they happen to be signed in; never required, never logged, never an error. */
+async function optionalSiteSubject(request: NextRequest, options: NewsletterApiOptions, environment: Record<string, string | undefined>): Promise<string | undefined> {
+  if (!request.cookies.has(PROSPECTUS_SESSION_COOKIE)) return undefined;
+  try {
+    const sealingSecret = await (options.loadSealingSecret ?? (() => loadProspectusSessionSealingSecret({ environment })))();
+    if (!sealingSecret) return undefined;
+    const session = signedInProspectusSession(request, sealingSecret, options.nowInSeconds);
+    return readerSubject(session, environment) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function siteOriginOrResponse(request: NextRequest, environment: Record<string, string | undefined>): { origin: string } | { response: NextResponse } {
+  try {
+    return { origin: publicSiteOrigin(request, environment) };
+  } catch (error) {
+    if (error instanceof SiteOriginNotConfiguredError) return { response: siteOriginNotConfiguredResponse(error) };
+    throw error;
+  }
+}
+
+/**
+ * Whether a state-changing request came from the site's own pages: its `Origin` is the public site origin or, when the browser
+ * sent none, its `Referer` is on it. `Origin: null` (what a browser sends when the page said `Referrer-Policy: no-referrer`,
+ * and what a sandboxed or cross-origin redirect chain produces) is never accepted.
+ */
+export function isSameSiteRequest(headers: Pick<Headers, "get">, siteOrigin: string): boolean {
+  const origin = headers.get("origin");
+  if (origin !== null) return origin === siteOrigin;
+  const referer = headers.get("referer");
+  if (!referer) return false;
+  try {
+    return new URL(referer).origin === siteOrigin;
+  } catch {
+    return false;
+  }
+}
+
+/** The edge turns an origin answer of 403 or 404 into the site's 404 page, so failures here answer 400. */
+const CROSS_SITE = { status: 400 } as const;
+
+/** POST /api/newsletter/subscribe */
+export async function handleNewsletterSubscribe(request: NextRequest, options: NewsletterApiOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  const plugin = enabledPlugin(options, environment);
+  if (!plugin) return notFoundJson();
+  const site = siteOriginOrResponse(request, environment);
+  if ("response" in site) return site.response;
+  if (!isSameSiteRequest(request.headers, site.origin)) return failure(CROSS_SITE.status, "origin_mismatch", "This request did not come from this site.");
+  const body = await readBody(request, NEWSLETTER_SUBSCRIBE_MAXIMUM_BODY_BYTES, ["application/json"]);
+  if ("response" in body) return body.response;
+  let payload: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(body.text) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("not an object");
+    payload = parsed as Record<string, unknown>;
+  } catch {
+    return failure(400, "invalid_json", "The request body is not a JSON object.");
+  }
+  if (!plugin.functionName) return failure(503, "newsletter_unavailable", "Newsletter signup is not available right now.");
+
+  const siteSubject = await optionalSiteSubject(request, options, environment);
+  const event: NewsletterEvent = {
+    action: "subscribe",
+    email: limited(payload.email, 320),
+    lists: listIds(payload.lists),
+    page: limited(payload.page, 500),
+    consent: limited(payload.consent, 500),
+    formId: limited(payload.formId, 100),
+    honeypot: limited(payload.website, 200),
+    renderedAt: typeof payload.renderedAt === "number" || typeof payload.renderedAt === "string" ? payload.renderedAt : null,
+    ip: clientAddress(request.headers),
+    userAgent: limited(request.headers.get("user-agent"), NEWSLETTER_USER_AGENT_CHARACTERS),
+    ...(siteSubject ? { siteSubject } : {}),
+  };
+  try {
+    const result = await (options.invoke ?? invokeNewsletterLambda)(plugin.functionName, event);
+    const status = typeof result.body.status === "string" ? result.body.status : "error";
+    return NextResponse.json({ status }, { status: result.statusCode, headers: NO_STORE });
+  } catch (error) {
+    console.error(`Newsletter subscribe failed (${error instanceof Error ? error.name : "error"}).`);
+    return failure(502, "newsletter_unavailable", "Newsletter signup could not be reached.");
+  }
+}
+
+/** The site's `urls.basePath` as a path with a leading slash ("/posts"), or "" for a site at the root. Anything unusable counts as no base path. */
+function basePathOf(plugin: Enabled): string {
+  const raw = plugin.settings.basePath;
+  return typeof raw === "string" && /^[a-z0-9][a-z0-9_-]*(\/[a-z0-9][a-z0-9_-]*){0,2}$/.test(raw) ? `/${raw}` : "";
+}
+
+export type NewsletterPage = "confirm" | "confirmed" | "preferences" | "unsubscribe" | "unsubscribed" | "expired";
+
+/**
+ * People never land on /api. Every answer a person's browser can follow is a redirect to one of the plugin's projected pages,
+ * `<base>/newsletter/<page>/` (the directory form, whatever the site's `urls.style`), which the site serves statically.
+ */
+function redirector(request: NextRequest, environment: Record<string, string | undefined>, plugin: Enabled): { origin: string; go: (page: NewsletterPage, query?: Record<string, string>, status?: 302 | 303) => NextResponse } | { response: NextResponse } {
+  const site = siteOriginOrResponse(request, environment);
+  if ("response" in site) return site;
+  const base = basePathOf(plugin);
+  return {
+    origin: site.origin,
+    go: (page, query = {}, status = 303) => {
+      const search = new URLSearchParams(query).toString();
+      return NextResponse.redirect(new URL(`${base}/newsletter/${page}/${search ? `?${search}` : ""}`, site.origin), {
+        status,
+        headers: { ...NO_STORE, "referrer-policy": "no-referrer" },
+      });
+    },
+  };
+}
+
+function configuredLists(plugin: Enabled, ids: string[]): Array<{ id: string; name: string }> {
+  const known = Array.isArray(plugin.settings.lists) ? (plugin.settings.lists as Array<{ id?: unknown; name?: unknown }>) : [];
+  return ids.flatMap((id) => {
+    const match = known.find((entry) => entry.id === id);
+    return typeof match?.name === "string" ? [{ id, name: match.name }] : [];
+  });
+}
+
+function call(options: NewsletterApiOptions, functionName: string, event: NewsletterEvent): Promise<NewsletterResult> {
+  return (options.invoke ?? invokeNewsletterLambda)(functionName, event);
+}
+
+/**
+ * Next answers HEAD by running the route's GET export, but leaves `request.method` as "HEAD". A check for `=== "GET"` therefore
+ * sends a mail scanner's HEAD down the POST path. Every read-only branch asks this instead, so HEAD redirects exactly like GET.
+ */
+function isReadRequest(request: Pick<NextRequest, "method">): boolean {
+  return request.method === "GET" || request.method === "HEAD";
+}
+
+function textResponse(body: string, status: number): NextResponse {
+  return new NextResponse(body, { status, headers: { ...NO_STORE, "content-type": "text/plain; charset=utf-8" } });
+}
+
+function manageTokenFrom(...values: Array<string | null>): string {
+  const found = values.find((value) => value !== null && value !== "") ?? "";
+  return NEWSLETTER_TOKEN.test(found) ? found : "";
+}
+
+function listParameter(value: string | null): string {
+  return value !== null && LIST_ID.test(value) ? value : "";
+}
+
+function idsOf(lists: unknown): string[] {
+  return (Array.isArray(lists) ? (lists as Array<{ id?: unknown }>) : []).flatMap((entry) => (typeof entry.id === "string" && LIST_ID.test(entry.id) ? [entry.id] : []));
+}
+
+/**
+ * /api/newsletter/confirm. POST (form field `t`, from the confirm page) confirms and answers 303 to the confirmed page, or to the
+ * expired page. GET is only for confirmation emails sent before the pages moved: it answers 302 to `<base>/newsletter/confirm/?token=`
+ * and changes nothing.
+ */
+export async function handleNewsletterConfirm(request: NextRequest, options: NewsletterApiOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  const plugin = enabledPlugin(options, environment);
+  if (!plugin) return notFoundPage();
+  const to = redirector(request, environment, plugin);
+  if ("response" in to) return to.response;
+  if (isReadRequest(request)) {
+    const token = manageTokenFrom(request.nextUrl.searchParams.get("t"));
+    return token ? to.go("confirm", { token }, 302) : to.go("expired", {}, 302);
+  }
+  if (!isSameSiteRequest(request.headers, to.origin)) return to.go("expired");
+  const body = await readBody(request, NEWSLETTER_CONFIRM_MAXIMUM_BODY_BYTES, ["application/x-www-form-urlencoded"]);
+  if ("response" in body) return body.response;
+  const token = manageTokenFrom(new URLSearchParams(body.text).get("t"));
+  if (!token || !plugin.functionName) return to.go("expired");
+  try {
+    const result = await call(options, plugin.functionName, {
+      action: "confirm",
+      token,
+      ip: clientAddress(request.headers),
+      userAgent: limited(request.headers.get("user-agent"), NEWSLETTER_USER_AGENT_CHARACTERS),
+    });
+    if (result.body.status !== "confirmed") return to.go("expired");
+    const manage = typeof result.body.manageToken === "string" ? manageTokenFrom(result.body.manageToken) : "";
+    return to.go("confirmed", { lists: idsOf(result.body.lists).join(","), ...(manage ? { token: manage } : {}) });
+  } catch (error) {
+    console.error(`Newsletter confirm failed (${error instanceof Error ? error.name : "error"}).`);
+    return to.go("expired");
+  }
+}
+
+/**
+ * /api/newsletter/unsubscribe. RFC 8058 one-click: mail providers POST `List-Unsubscribe=One-Click` to the link in the message header
+ * from their own servers, with no Origin, so there is no same-origin check; the answer is plain text, never a redirect. A POST from
+ * the unsubscribe page carries `page=1` and gets a 303 to the unsubscribed page. GET (an old email's footer link) answers 302 to
+ * `<base>/newsletter/unsubscribe/?token=&list=` and changes nothing.
+ */
+export async function handleNewsletterUnsubscribe(request: NextRequest, options: NewsletterApiOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  const plugin = enabledPlugin(options, environment);
+  if (!plugin) return notFoundPage();
+  const to = redirector(request, environment, plugin);
+  if ("response" in to) return to.response;
+  const query = request.nextUrl.searchParams;
+  if (isReadRequest(request)) {
+    const token = manageTokenFrom(query.get("t"));
+    const listId = listParameter(query.get("l"));
+    return token ? to.go("unsubscribe", { token, ...(listId ? { list: listId } : {}) }, 302) : to.go("expired", {}, 302);
+  }
+  const body = await readBody(request, NEWSLETTER_CONFIRM_MAXIMUM_BODY_BYTES, null);
+  if ("response" in body) return body.response;
+  const form = new URLSearchParams(body.text);
+  const oneClick = form.get("List-Unsubscribe") === "One-Click";
+  const fromPage = form.get("page") === "1";
+  if (!oneClick && !fromPage) return textResponse("Send List-Unsubscribe=One-Click.", 400);
+  const token = manageTokenFrom(query.get("t"), form.get("t"));
+  const listId = listParameter(query.get("l") ?? form.get("l"));
+  const rejected = () => (fromPage ? to.go("expired") : textResponse("Invalid link.", 400));
+  if (!token) return rejected();
+  if (!plugin.functionName) return fromPage ? to.go("expired") : textResponse("Unavailable.", 503);
+  try {
+    const result = await call(options, plugin.functionName, { action: "unsubscribe", token, ...(listId ? { list: listId } : {}) });
+    if (result.body.status !== "unsubscribed") return rejected();
+    if (!fromPage) return textResponse("Unsubscribed.", 200);
+    return to.go("unsubscribed", { lists: idsOf(result.body.lists).join(","), token });
+  } catch (error) {
+    console.error(`Newsletter unsubscribe failed (${error instanceof Error ? error.name : "error"}).`);
+    return fromPage ? to.go("expired") : textResponse("Try again later.", 502);
+  }
+}
+
+const PREFERENCE_MESSAGES = new Set(["saved", "unsubscribed"]);
+
+/**
+ * /api/newsletter/preferences. POST (same-origin form from the preferences page) saves, unsubscribes from everything, or deletes
+ * after a confirm step, and answers 303 to the preferences page with `msg=saved|unsubscribed|deleted` or `step=delete`. GET (an old
+ * email's manage link) answers 302 to `<base>/newsletter/preferences/?token=`.
+ */
+export async function handleNewsletterPreferences(request: NextRequest, options: NewsletterApiOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  const plugin = enabledPlugin(options, environment);
+  if (!plugin) return notFoundPage();
+  const to = redirector(request, environment, plugin);
+  if ("response" in to) return to.response;
+  if (isReadRequest(request)) {
+    const token = manageTokenFrom(request.nextUrl.searchParams.get("t"));
+    return token ? to.go("preferences", { token }, 302) : to.go("expired", {}, 302);
+  }
+  if (!isSameSiteRequest(request.headers, to.origin)) return to.go("expired");
+  const body = await readBody(request, NEWSLETTER_CONFIRM_MAXIMUM_BODY_BYTES, ["application/x-www-form-urlencoded"]);
+  if ("response" in body) return body.response;
+  const form = new URLSearchParams(body.text);
+  const token = manageTokenFrom(form.get("t"));
+  if (!token || !plugin.functionName) return to.go("expired");
+  const action = form.get("action");
+  if (action === "delete" && form.get("confirm") !== "1") return to.go("preferences", { token, step: "delete" });
+  const operation =
+    action === "save"
+      ? { action: "update_preferences", token, lists: form.getAll("l").slice(0, MAXIMUM_LISTS).filter((id) => LIST_ID.test(id)) }
+      : action === "unsubscribe_all"
+        ? { action: "unsubscribe", token }
+        : action === "delete"
+          ? { action: "delete_subscriber", token }
+          : null;
+  if (!operation) return failure(400, "invalid_action", "Choose save, unsubscribe from everything, or delete.");
+  try {
+    const status = (await call(options, plugin.functionName, operation)).body.status;
+    if (status === "deleted") return to.go("preferences", { msg: "deleted" });
+    if (typeof status !== "string" || !PREFERENCE_MESSAGES.has(status)) return to.go("expired");
+    return to.go("preferences", { token, msg: status });
+  } catch (error) {
+    console.error(`Newsletter preferences save failed (${error instanceof Error ? error.name : "error"}).`);
+    return to.go("expired");
+  }
+}
+
+/**
+ * GET /api/newsletter/state: JSON for the projected pages' script, never HTML. `kind=confirm&t=` and `kind=preferences&t=` ask the
+ * function (read only); `kind=lists&lists=a,b` names lists from the site's own settings. Failures answer 400 or 502 with a status
+ * word, since the edge turns an origin 403 or 404 into the site's 404 page.
+ */
+export async function handleNewsletterState(request: NextRequest, options: NewsletterApiOptions = {}): Promise<NextResponse> {
+  const environment = options.environment ?? process.env;
+  const plugin = enabledPlugin(options, environment);
+  if (!plugin) return notFoundJson();
+  const params = request.nextUrl.searchParams;
+  const kind = params.get("kind");
+  const json = (status: number, body: Record<string, unknown>) => NextResponse.json(body, { status, headers: NO_STORE });
+  if (kind === "lists") return json(200, { status: "ready", lists: configuredLists(plugin, listIds(params.get("lists") ?? "")) });
+  if (kind !== "confirm" && kind !== "preferences") return json(400, { status: "invalid" });
+  const token = manageTokenFrom(params.get("t"));
+  if (!token) return json(400, { status: "invalid" });
+  if (!plugin.functionName) return json(503, { status: "unavailable" });
+  try {
+    const result = await call(options, plugin.functionName, { action: kind === "confirm" ? "confirm_page_state" : "preferences_state", token });
+    if (result.body.status !== "ready") return json(400, { status: "invalid" });
+    const lists = Array.isArray(result.body.lists) ? (result.body.lists as Array<Record<string, unknown>>) : [];
+    if (kind === "confirm") return json(200, { status: "ready", lists: lists.flatMap((entry) => (typeof entry.name === "string" ? [{ name: entry.name }] : [])) });
+    return json(200, {
+      status: "ready",
+      email: typeof result.body.email === "string" ? result.body.email : "",
+      lists: lists.map((entry) => ({ id: entry.id, name: entry.name, description: entry.description ?? "", subscribed: entry.subscribed === true })),
+    });
+  } catch (error) {
+    console.error(`Newsletter state failed (${error instanceof Error ? error.name : "error"}).`);
+    return json(502, { status: "unavailable" });
+  }
+}

package/lib/newsletter-client.ts

@@ -0,0 +1,46 @@
+"use client";
+
+import { generateClient } from "aws-amplify/data";
+import type { NewsletterFailure } from "./newsletter-model";
+
+/** The operations the newsroom Newsletter panel calls. All take and return AWSJSON; the function behind them checks the role again. */
+export const NEWSLETTER_QUERY_OPERATIONS = [
+  "newsletterOverview", "newsletterIssues", "newsletterIssue", "newsletterPreview", "newsletterIssueDeliveries", "newsletterSubscribers", "newsletterExport",
+] as const;
+export const NEWSLETTER_MUTATION_OPERATIONS = [
+  "newsletterApproveIssue", "newsletterCancelIssue", "newsletterStopIssue", "newsletterTestSend", "newsletterCreateDraft", "newsletterErase", "newsletterResume",
+] as const;
+export type NewsletterOperation = (typeof NEWSLETTER_QUERY_OPERATIONS)[number] | (typeof NEWSLETTER_MUTATION_OPERATIONS)[number];
+
+type GraphQLResult = { data?: Record<string, unknown>; errors?: { message?: string; errorType?: string }[] };
+
+export type NewsletterApi = <T extends object = Record<string, unknown>>(operation: NewsletterOperation, input?: Record<string, unknown>) => Promise<({ ok: true } & T) | NewsletterFailure>;
+
+export function newsletterOperationDocument(operation: NewsletterOperation): string {
+  const kind = (NEWSLETTER_MUTATION_OPERATIONS as readonly string[]).includes(operation) ? "mutation" : "query";
+  const title = operation.charAt(0).toUpperCase() + operation.slice(1);
+  return `${kind} ${title}($input: AWSJSON) { ${operation}(input: $input) }`;
+}
+
+/** Calls one operation through the site's authenticated API (user pool). The browser holds no table name, key or address list. */
+export const callNewsletter: NewsletterApi = async (operation, input = {}) => {
+  const client = generateClient({ authMode: "userPool" });
+  let result: GraphQLResult;
+  try {
+    result = (await client.graphql({ query: newsletterOperationDocument(operation), variables: { input: JSON.stringify(input) } })) as GraphQLResult;
+  } catch (error) {
+    // Amplify throws the response when AppSync returns errors.
+    result = (error && typeof error === "object" && "errors" in error ? error : { errors: [{ message: "failed" }] }) as GraphQLResult;
+  }
+  if (result.errors?.some((entry) => /unauthorized|not authorized|forbidden/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`))) {
+    return { ok: false, error: "forbidden" };
+  }
+  const raw = result.data?.[operation];
+  if (result.errors?.length || raw === undefined || raw === null) return { ok: false, error: "unavailable" };
+  try {
+    const parsed = (typeof raw === "string" ? JSON.parse(raw) : raw) as { ok?: boolean };
+    return parsed && typeof parsed === "object" && "ok" in parsed ? (parsed as never) : { ok: false, error: "unavailable" };
+  } catch {
+    return { ok: false, error: "unavailable" };
+  }
+};

package/lib/newsletter-fixture.ts

@@ -0,0 +1,184 @@
+/**
+ * A pretend Newsletter service for `?demo=1` and the tests: the same operations and answers as the functions, held in memory.
+ * Placeholders only (reader addresses are @example.com); nothing here is a real subscriber, issue or postal address.
+ */
+import type { NewsletterApi, NewsletterOperation } from "./newsletter-client";
+import type {
+  NewsletterDelivery,
+  NewsletterEvent,
+  NewsletterExportRow,
+  NewsletterIssue,
+  NewsletterList,
+  NewsletterSubscriber,
+} from "./newsletter-model";
+
+export const FIXTURE_TIME_ZONE = "America/New_York";
+
+const LISTS: NewsletterList[] = [
+  { id: "weekly", name: "Weekly roundup", kind: "roundup", confirmed: 412, pending: 17, unsubscribed: 38, timezone: FIXTURE_TIME_ZONE },
+  { id: "alerts-security", name: "Security alerts", kind: "alert", confirmed: 96, pending: 4, unsubscribed: 9 },
+];
+
+export function fixtureIssues(): NewsletterIssue[] {
+  const counts = { queued: 0, sent: 0, failed: 0, suppressed: 0, skipped: 0, delivered: 0, bounced: 0, complained: 0, softBounced: 0 };
+  return [
+    {
+      issueId: "a1", listId: "weekly", listName: "Weekly roundup", kind: "roundup", itemId: "item-weekly-0122", status: "draft",
+      subject: "Weekly roundup: Jan 15 to Jan 22, 2027", counts,
+    },
+    {
+      issueId: "a2", listId: "alerts-security", listName: "Security alerts", kind: "alert", itemId: "item-alert-1", status: "awaiting_approval",
+      subject: "A critical patch is out for the build tool", counts,
+    },
+    {
+      issueId: "a3", listId: "weekly", listName: "Weekly roundup", kind: "roundup", itemId: "item-weekly-0115", status: "scheduled",
+      subject: "Weekly roundup: Jan 8 to Jan 15, 2027", sendAt: "2027-01-15T14:00:00Z", approvedBy: "admin-user", approvedAt: "2027-01-14T18:30:00Z",
+      counts, editedSinceApproval: true,
+    },
+    {
+      issueId: "a4", listId: "weekly", listName: "Weekly roundup", kind: "roundup", itemId: "item-weekly-0108", status: "blocked",
+      subject: "Weekly roundup: Jan 1 to Jan 8, 2027", sendAt: "2027-01-08T14:00:00Z", note: "postal address missing", counts,
+    },
+    {
+      issueId: "a5", listId: "weekly", listName: "Weekly roundup", kind: "roundup", itemId: "item-weekly-0101", status: "sending",
+      subject: "Weekly roundup: Dec 25 to Jan 1, 2027", sendAt: "2027-01-01T14:00:00Z", approvedBy: "admin-user",
+      counts: { ...counts, queued: 429, sent: 240, delivered: 188 },
+    },
+    {
+      issueId: "a6", listId: "weekly", listName: "Weekly roundup", kind: "roundup", itemId: "item-weekly-1225", status: "sent",
+      subject: "Weekly roundup: Dec 18 to Dec 25, 2026", sendAt: "2026-12-25T14:00:00Z", sentAt: "2026-12-25T14:09:40Z", approvedBy: "admin-user",
+      archiveUrl: "https://news.example.com/roundup/2026-12-25.html",
+      counts: { ...counts, queued: 421, sent: 418, delivered: 409, bounced: 3, complained: 1, failed: 1, suppressed: 2, softBounced: 2 },
+    },
+    {
+      issueId: "a7", listId: "alerts-security", listName: "Security alerts", kind: "alert", itemId: "item-alert-0", status: "quarantined",
+      subject: "An alert with a status this panel does not know", counts,
+    },
+  ];
+}
+
+function deliveriesFor(issueId: string, full: boolean): NewsletterDelivery[] {
+  const address = (index: number) => (full ? `reader${index}@example.com` : `r***@example.com`);
+  const rows: NewsletterDelivery[] = [
+    { address: address(1), status: "delivered", at: "2026-12-25T14:00:04Z", eventAt: "2026-12-25T14:00:09Z" },
+    { address: address(2), status: "delivered", at: "2026-12-25T14:00:05Z", eventAt: "2026-12-25T14:00:12Z" },
+    { address: address(3), status: "bounced", at: "2026-12-25T14:00:06Z", eventAt: "2026-12-25T14:00:20Z" },
+    { address: address(4), status: "complained", at: "2026-12-25T14:00:07Z", eventAt: "2026-12-25T14:02:31Z" },
+    { address: address(5), status: "failed", at: "2026-12-25T14:00:08Z", error: "MessageRejected" },
+    { address: "(erased)", status: "sent", at: "2026-12-25T14:00:09Z" },
+  ];
+  return issueId === "a6" || issueId === "a5" ? rows : [];
+}
+
+const SUBSCRIBERS: NewsletterSubscriber[] = [
+  { email: "reader1@example.com", status: "confirmed", lists: [{ id: "weekly", status: "subscribed" }, { id: "alerts-security", status: "subscribed" }], createdAt: "2026-11-02T10:11:00Z", confirmedAt: "2026-11-02T10:13:00Z" },
+  { email: "reader2@example.com", status: "confirmed", lists: [{ id: "weekly", status: "subscribed" }], createdAt: "2026-11-09T08:00:00Z", confirmedAt: "2026-11-09T08:02:00Z" },
+  { email: "reader3@example.com", status: "pending", lists: [{ id: "alerts-security", status: "pending" }], createdAt: "2026-12-30T21:45:00Z" },
+  { email: "=reader4@example.com", status: "unsubscribed", lists: [{ id: "weekly", status: "unsubscribed" }], createdAt: "2026-10-01T09:00:00Z", confirmedAt: "2026-10-01T09:05:00Z" },
+];
+
+const EVENTS: NewsletterEvent[] = [
+  { type: "Complaint", at: "2026-12-25T14:02:31Z", issue: "a6", list: "weekly" },
+  { type: "Bounce", at: "2026-12-25T14:00:20Z", issue: "a6", list: "weekly", detail: "Permanent" },
+  { type: "Delivery", at: "2026-12-25T14:00:12Z", issue: "a6", list: "weekly" },
+  { type: "Delivery", at: "2026-12-25T14:00:09Z", issue: "a6", list: "weekly" },
+  { type: "Bounce", at: "2026-12-25T13:59:50Z", issue: "a5", list: "weekly", detail: "Transient" },
+];
+
+const SAMPLE_HTML = `<!doctype html><html><body style="margin:0;font-family:Georgia,serif;color:#111"><div style="max-width:560px;margin:0 auto;padding:24px"><h1 style="font-size:24px;margin:0 0 12px">Weekly roundup</h1><p>A short introduction goes here.</p><h2 style="font-size:18px">Security</h2><ul><li><a href="#preview">A critical patch is out</a>: update today.</li></ul><hr><p style="font-size:12px;color:#555">You get this because you subscribed. <a href="#preview">Manage</a> &middot; <a href="#preview">Unsubscribe</a><br>1 Example Street, Example City</p></div></body></html>`;
+
+export type FixtureOptions = { postalAddress?: boolean; admin?: boolean };
+
+/** One fixture service per mounted panel, so a demo session keeps its changes until reload. */
+export function createFixtureApi(options: FixtureOptions = {}): NewsletterApi {
+  const full = options.admin !== false;
+  const issues = fixtureIssues();
+  const subscribers = [...SUBSCRIBERS];
+  const paused = { paused: true, reason: "papyrus-newsletter-example-bounce-rate: bounce rate above 4%", pausedAt: "2026-12-26T09:12:00Z" } as { paused: boolean; reason?: string; pausedAt?: string };
+  const findIssue = (input: Record<string, unknown>) => issues.find((issue) => issue.issueId === input.issueId);
+  const failure = (error: string, message = "") => ({ ok: false as const, error, message });
+
+  const handlers: Record<NewsletterOperation, (input: Record<string, unknown>) => object> = {
+    newsletterOverview: () => ({
+      ok: true,
+      lists: LISTS,
+      totals: { confirmed: 488, pending: 20, unsubscribed: 45 },
+      suppressed: 12,
+      paused: { ...paused },
+      events: EVENTS,
+    }),
+    newsletterIssues: (input) => ({
+      ok: true,
+      issues: issues.filter((issue) => (!input.status || issue.status === input.status) && (!input.listId || issue.listId === input.listId)).map(({ editedSinceApproval: _edited, ...rest }) => rest),
+    }),
+    newsletterIssue: (input) => {
+      const issue = findIssue(input);
+      return issue ? { ok: true, issue } : failure("not_found");
+    },
+    newsletterPreview: (input) => {
+      const issue = findIssue(input);
+      if (!issue) return failure("not_found");
+      return { ok: true, subject: issue.subject, html: SAMPLE_HTML, text: `${issue.subject}\n\nA short introduction goes here.\n\nSecurity\n- A critical patch is out: update today.\n\nYou get this because you subscribed.`, bytes: SAMPLE_HTML.length, postalAddress: options.postalAddress !== false };
+    },
+    newsletterIssueDeliveries: (input) => (findIssue(input) ? { ok: true, deliveries: deliveriesFor(String(input.issueId), full) } : failure("not_found")),
+    newsletterSubscribers: (input) => ({
+      ok: true,
+      subscribers: subscribers.filter((row) => (!input.status || row.status === input.status) && (!input.listId || row.lists.some((entry) => entry.id === input.listId))),
+    }),
+    newsletterExport: () => ({
+      ok: true,
+      rows: subscribers.filter((row) => row.status !== "unsubscribed").map((row): NewsletterExportRow => ({
+        email: row.email, status: row.status, lists: row.lists.map((entry) => `${entry.id}:${entry.status}`).join(";"), createdAt: row.createdAt,
+        consentRequestedAt: row.createdAt, consentConfirmedAt: row.confirmedAt ?? "", consentFormId: "newsletter",
+        consentPageUrl: "https://news.example.com/roundup/", consentWording: "Send me the weekly email.",
+      })),
+    }),
+    newsletterApproveIssue: (input) => {
+      const issue = findIssue(input);
+      if (!issue) return failure("not_found");
+      if (!["draft", "awaiting_approval", "scheduled", "blocked"].includes(issue.status)) return failure("invalid_state");
+      issue.status = "scheduled";
+      issue.sendAt = String(input.sendAt);
+      issue.approvedBy = "admin-user";
+      delete issue.note;
+      delete issue.editedSinceApproval;
+      return { ok: true, issue, adjusted: false, warnings: options.postalAddress === false ? ["postal address missing: the send will be blocked until an operator sets it"] : [] };
+    },
+    newsletterCancelIssue: (input) => {
+      const issue = findIssue(input);
+      if (!issue) return failure("not_found");
+      if (issue.status !== "scheduled") return failure("invalid_state");
+      issue.status = "draft";
+      issue.note = "cancelled by admin-user";
+      delete issue.sendAt;
+      delete issue.editedSinceApproval;
+      return { ok: true, issue };
+    },
+    newsletterStopIssue: (input) => {
+      const issue = findIssue(input);
+      if (!issue) return failure("not_found");
+      if (issue.status !== "sending") return failure("invalid_state");
+      issue.status = "stopped";
+      issue.note = "stopped by admin-user";
+      return { ok: true, issue };
+    },
+    newsletterTestSend: (input) => (findIssue(input) ? { ok: true } : failure("not_found")),
+    newsletterCreateDraft: (input) => (input.listId === "weekly" ? { ok: true, status: "exists", issueId: "a1", itemId: "item-weekly-0122" } : failure("bad_request")),
+    newsletterErase: (input) => {
+      const at = subscribers.findIndex((row) => row.email === input.email);
+      if (at >= 0) subscribers.splice(at, 1);
+      return { ok: true, removed: at >= 0 ? 3 : 2 };
+    },
+    newsletterResume: () => {
+      paused.paused = false;
+      paused.reason = undefined;
+      return { ok: true, paused: false };
+    },
+  };
+
+  return (async (operation: NewsletterOperation, input: Record<string, unknown> = {}) => {
+    const admin = ["newsletterApproveIssue", "newsletterCancelIssue", "newsletterStopIssue", "newsletterSubscribers", "newsletterExport", "newsletterErase", "newsletterResume"];
+    if (options.admin === false && admin.includes(operation)) return { ok: false, error: "forbidden" };
+    return handlers[operation](input);
+  }) as NewsletterApi;
+}