@anthusai/papyrus 2.0.0-next.11 → 2.0.0-next.110

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;
+}

package/lib/newsletter-model.ts

@@ -0,0 +1,202 @@
+/** Shapes and wording for the newsroom Newsletter panel. `src/papyrus_content/newsletter/` (panel.py, issues.py) produces them. */
+import { getNewsroomNavHref } from "./newsroom-nav";
+import { csvCell } from "./signup-csv";
+
+export type NewsletterCounts = Partial<Record<"queued" | "sent" | "failed" | "suppressed" | "skipped" | "delivered" | "bounced" | "complained" | "softBounced", number>>;
+
+export type NewsletterList = { id: string; name: string; kind: string; confirmed: number; pending: number; unsubscribed: number; timezone?: string };
+
+export type NewsletterEvent = { type: string; at: string; issue?: string; list?: string; detail?: string };
+
+export type NewsletterOverview = {
+  lists: NewsletterList[];
+  totals: { confirmed: number; pending: number; unsubscribed: number };
+  suppressed: number;
+  paused: { paused: boolean; reason?: string; pausedAt?: string; resumedAt?: string };
+  events: NewsletterEvent[];
+};
+
+export type NewsletterIssue = {
+  issueId: string;
+  listId: string;
+  listName?: string;
+  kind: string;
+  itemId?: string;
+  subject: string;
+  status: string;
+  sendAt?: string;
+  approvedBy?: string;
+  approvedAt?: string;
+  sentAt?: string;
+  counts: NewsletterCounts;
+  note?: string;
+  archiveUrl?: string;
+  editedSinceApproval?: boolean;
+};
+
+export type NewsletterPreview = { subject: string; html: string; text: string; bytes: number; postalAddress: boolean };
+
+export type NewsletterDelivery = { address: string; status: string; at: string; eventAt?: string; error?: string };
+
+export type NewsletterSubscriber = { email: string; status: string; lists: { id: string; status: string }[]; createdAt: string; confirmedAt?: string };
+
+export type NewsletterExportRow = {
+  email: string;
+  status: string;
+  lists: string;
+  createdAt: string;
+  consentRequestedAt: string;
+  consentConfirmedAt: string;
+  consentFormId: string;
+  consentPageUrl: string;
+  consentWording: string;
+};
+
+export type NewsletterFailure = { ok: false; error: string; message?: string };
+
+/** The newsroom words for the statuses the functions write. A status this panel does not know is shown as written, never hidden. */
+const STATUS_LABELS: Record<string, string> = {
+  draft: "Draft",
+  awaiting_approval: "Awaiting approval",
+  scheduled: "Scheduled",
+  sending: "Sending",
+  sent: "Sent",
+  stopped: "Stopped",
+  cancelled: "Cancelled",
+  blocked: "Blocked",
+};
+/** A mark beside the word, so no status relies on colour alone. */
+const STATUS_MARKS: Record<string, string> = { draft: "✎", awaiting_approval: "?", scheduled: "◷", sending: "▶", sent: "✓", stopped: "■", cancelled: "–", blocked: "!" };
+
+export function statusLabel(status: string): string {
+  if (STATUS_LABELS[status]) return STATUS_LABELS[status];
+  const words = status.replace(/_/g, " ").trim();
+  return words ? words.charAt(0).toUpperCase() + words.slice(1) : "Unknown";
+}
+
+export function statusMark(status: string): string {
+  return STATUS_MARKS[status] ?? "·";
+}
+
+export const ISSUE_STATUS_FILTERS = ["draft", "awaiting_approval", "scheduled", "sending", "sent", "blocked", "stopped", "cancelled"] as const;
+
+/** Approval accepts a draft, an alert awaiting approval, a scheduled issue (a new time) and a blocked one (cause fixed). */
+export function canApprove(status: string): boolean {
+  return status === "draft" || status === "awaiting_approval" || status === "scheduled" || status === "blocked";
+}
+export const canCancel = (status: string): boolean => status === "scheduled";
+export const canStop = (status: string): boolean => status === "sending";
+
+export function issueEditorHref(itemId: string, demo?: boolean): string {
+  return getNewsroomNavHref(`/newsroom/articles/${encodeURIComponent(itemId)}`, demo);
+}
+
+const ERROR_WORDS: Record<string, string> = {
+  forbidden: "Your role cannot do this.",
+  not_found: "That issue no longer exists.",
+  invalid_state: "The issue changed state. Refresh and try again.",
+  item_missing: "The issue's item no longer exists.",
+  render_failed: "The issue cannot be rendered. Open it in the editor and fix the body.",
+  bad_request: "The request was not understood.",
+  no_address: "Your account has no email address to send a test to.",
+  unavailable: "The newsletter service could not be reached. Try again in a minute.",
+};
+
+/** One sentence for a failed operation. A missing postal address is an operator task, so the panel says where it is set. */
+export function failureText(failure: NewsletterFailure): string {
+  if (failure.error === "postal_address_missing") {
+    return "This site has no postal address for the email footer, and mail law requires one. An operator sets it in the site's AWS configuration (an SSM parameter); it cannot be set from the newsroom.";
+  }
+  return ERROR_WORDS[failure.error] ?? failure.message ?? "The request failed.";
+}
+
+// -- times ---------------------------------------------------------------------------------------------------------------
+
+export function formatUtc(iso: string | null | undefined): string {
+  if (!iso) return "never";
+  const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(iso);
+  return match ? `${match[1]} ${match[2]} UTC` : iso;
+}
+
+export function validTimeZone(zone: string | null | undefined): string | null {
+  if (!zone) return null;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: zone });
+    return zone;
+  } catch {
+    return null;
+  }
+}
+
+function wallParts(instant: Date, zone: string): { year: number; month: number; day: number; hour: number; minute: number } {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: zone, hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit",
+  }).formatToParts(instant);
+  const pick = (type: string) => Number(parts.find((part) => part.type === type)?.value ?? "0");
+  return { year: pick("year"), month: pick("month"), day: pick("day"), hour: pick("hour") % 24, minute: pick("minute") };
+}
+
+/** Minutes the zone is ahead of UTC at that instant. */
+function offsetMinutes(instant: Date, zone: string): number {
+  const wall = wallParts(instant, zone);
+  const asUtc = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute);
+  return Math.round((asUtc - Math.floor(instant.getTime() / 60000) * 60000) / 60000);
+}
+
+const pad = (value: number) => String(value).padStart(2, "0");
+
+/** Local wall time `YYYY-MM-DDTHH:mm` (a datetime-local value) as an ISO instant, for the given zone. */
+export function zonedInputToIso(local: string, zone: string): string | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/.exec(local);
+  if (!match) return null;
+  const [, year, month, day, hour, minute] = match.map(Number) as unknown as number[];
+  const wallAsUtc = Date.UTC(year, month - 1, day, hour, minute);
+  let guess = wallAsUtc - offsetMinutes(new Date(wallAsUtc), zone) * 60000;
+  guess = wallAsUtc - offsetMinutes(new Date(guess), zone) * 60000; // once more: the offset can differ across a clock change
+  const instant = new Date(guess);
+  return Number.isNaN(instant.getTime()) ? null : instant.toISOString().replace(".000Z", "Z");
+}
+
+/** The next whole hour on the zone's clock, as a datetime-local value. */
+export function nextWholeHourInput(now: Date, zone: string): string {
+  const wall = wallParts(now, zone);
+  const next = new Date(Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour + 1, 0));
+  return `${next.getUTCFullYear()}-${pad(next.getUTCMonth() + 1)}-${pad(next.getUTCDate())}T${pad(next.getUTCHours())}:00`;
+}
+
+/** An ISO instant as a datetime-local value in the zone. */
+export function isoToZonedInput(iso: string, zone: string): string {
+  const wall = wallParts(new Date(iso), zone);
+  return `${wall.year}-${pad(wall.month)}-${pad(wall.day)}T${pad(wall.hour)}:${pad(wall.minute)}`;
+}
+
+/** `2027-01-15 09:00 EST` in the zone. */
+export function formatInZone(iso: string | null | undefined, zone: string): string {
+  if (!iso) return "not set";
+  const instant = new Date(iso);
+  if (Number.isNaN(instant.getTime())) return iso;
+  const label = new Intl.DateTimeFormat("en-US", { timeZone: zone, timeZoneName: "short" }).formatToParts(instant).find((part) => part.type === "timeZoneName")?.value ?? zone;
+  return `${isoToZonedInput(iso, zone).replace("T", " ")} ${label}`;
+}
+
+// -- counts and CSV ------------------------------------------------------------------------------------------------------
+
+/** "12 sent, 2 delivered, 1 bounced"; only counters above zero, in reading order. */
+export function countsText(counts: NewsletterCounts): string {
+  const order: [keyof NewsletterCounts, string][] = [
+    ["queued", "queued"], ["sent", "sent"], ["delivered", "delivered"], ["bounced", "bounced"], ["complained", "complained"],
+    ["failed", "failed"], ["suppressed", "suppressed"], ["skipped", "skipped"], ["softBounced", "soft bounced"],
+  ];
+  const parts = order.filter(([name]) => (counts[name] ?? 0) > 0).map(([name, label]) => `${counts[name]} ${label}`);
+  return parts.length ? parts.join(", ") : "nothing sent yet";
+}
+
+export const NEWSLETTER_CSV_HEADER = [
+  "email", "status", "lists", "createdAt", "consentRequestedAt", "consentConfirmedAt", "consentFormId", "consentPageUrl", "consentWording",
+] as const;
+
+/** Every cell goes through the formula neutraliser: addresses and consent wording are text people typed. */
+export function subscribersToCsv(rows: NewsletterExportRow[]): string {
+  const lines = rows.map((row) => NEWSLETTER_CSV_HEADER.map((column) => csvCell(String(row[column] ?? ""))).join(","));
+  return `${[NEWSLETTER_CSV_HEADER.join(","), ...lines].join("\r\n")}\r\n`;
+}

package/lib/newsroom-demo-dashboard.ts

@@ -237,7 +237,7 @@ export function applyPilobolusDemoDashboardContent(
         ...record,
         title: "Pilobolus Editorial Policy",
         body: [
-          "Publication doctrine is the global inclusion standard for Pilobol.us; desk doctrine sets local intake priorities for field notes and source intake.",
+          "Publication doctrine is the global inclusion standard for Pilobol.us; section doctrine sets local intake priorities for field notes and source intake.",
           "Field-notes reporting should prioritize accepted Pilobolus references and annotated intake artifacts—not the Papyrus platform knowledge base.",
           "High-risk claims about host takeover or network control require explicit uncertainty handling and accepted source linkage.",
         ],

package/lib/newsroom-nav.ts

@@ -21,7 +21,7 @@ export type NewsroomNavItem = {
 };
 
 export const NEWSROOM_OPS_NAV: NewsroomNavItem[] = [
-  { id: "overview", label: "Overview", detail: "Desk home", href: newsroomHref() },
+  { id: "overview", label: "Overview", detail: "Newsroom home", href: newsroomHref() },
   { id: "articles", label: getContentItemName().plural, detail: "Drafts & published", href: newsroomHref("articles") },
   { id: "assignments", label: "Assignments", detail: "Work queue", href: newsroomHref("assignments") },
   { id: "references", label: "References", detail: "Knowledge base", href: newsroomHref("references") },

package/lib/newsroom-organizer-nav.ts

@@ -8,6 +8,7 @@ export type OrganizerDestination = {
 };
 export const ORGANIZER_NAV_GROUPS: readonly { title: string; items: readonly OrganizerDestination[] }[] = [
   { title: "Editorial work", items: [
+    { key: "overview", label: "Overview", description: "See notifications and work needing attention.", path: "/newsroom", primary: true },
     { key: "articles", label: getContentItemName().plural, description: `Follow ${contentItemPluralLowercase} across their stages and open one to write or revise it.`, path: `/newsroom/${contentItemBoardPathSegment()}`, alsoActiveOnPaths: ["/newsroom/articles"], primary: true },
     { key: "assignments", label: "Assignments", description: "Follow research and reporting work across its statuses and claim it.", path: "/newsroom/assignments" },
     { key: "messages", label: "Messages", description: "Read and reply to newsroom conversations.", path: "/newsroom/messages", primary: true },
@@ -23,7 +24,7 @@ export const ORGANIZER_NAV_GROUPS: readonly { title: string; items: readonly Org
   ] },
 ];
 const all = ORGANIZER_NAV_GROUPS.flatMap(group => group.items);
-export const ORGANIZER_PRIMARY_NAV = ["articles", "references", "messages"].map(key => all.find(item => item.key === key)!);
+export const ORGANIZER_PRIMARY_NAV = ["overview", "articles", "references", "messages"].map(key => all.find(item => item.key === key)!);
 
 export const ORGANIZER_SETTINGS_DESTINATION = {
   label: "Settings", path: "/newsroom/settings", description: "Theme, motion and interface preferences.",

package/lib/papyrus-chat-admission.ts

@@ -0,0 +1,65 @@
+import { postChatMessage, type ChatHttpTransport, type ChatMessageSubmission, type PostMessageResponse } from "chatticus/chat-client";
+
+/** Stable author mapping supplied by the Papyrus host; never infer it from a display label or email. */
+export interface PapyrusChatAuthor {
+  hostMappedAuthorId: string;
+  addressedToBotId: string | null;
+}
+
+/** One logical send. Reuse this exact value only for an explicit retry of the same message. */
+export interface PapyrusChatAdmissionAttempt {
+  readonly submission: Readonly<ChatMessageSubmission>;
+  readonly idempotencyKey: string;
+}
+
+export interface PapyrusChatAdmissionSenderOptions {
+  /** Host-owned chat URL; no endpoint is configured or exposed by this module. */
+  url: string;
+  /** Must obtain current Papyrus auth headers on every call; token type stays a host decision. */
+  freshAuthorizationHeaders: () => Promise<Record<string, string>>;
+  fetch?: typeof globalThis.fetch;
+  /** Override only in hermetic tests. Production defaults to the platform CSPRNG. */
+  createIdempotencyKey?: () => string;
+}
+
+export interface PapyrusChatAdmissionSender {
+  createAttempt(text: string, author: PapyrusChatAuthor): PapyrusChatAdmissionAttempt;
+  send(attempt: PapyrusChatAdmissionAttempt): Promise<PostMessageResponse>;
+}
+
+/**
+ * Bind Papyrus's host-owned auth and URL to Chatticus's reusable admission
+ * transport. Each send makes one POST; there is no automatic retry or auth
+ * fallback. An explicit retry sends the same attempt and refreshes headers.
+ */
+export function createPapyrusChatAdmissionSender(options: PapyrusChatAdmissionSenderOptions): PapyrusChatAdmissionSender {
+  const transport: ChatHttpTransport = {
+    url: options.url,
+    headers: async () => {
+      const headers = await options.freshAuthorizationHeaders();
+      const authorization = Object.entries(headers).find(([name]) => name.toLowerCase() === "authorization")?.[1];
+      if (!authorization?.trim()) throw new Error("Papyrus authorization headers are required");
+      return headers;
+    },
+    ...(options.fetch ? { fetch: options.fetch } : {}),
+  };
+  const createKey = options.createIdempotencyKey ?? (() => globalThis.crypto.randomUUID());
+
+  return {
+    createAttempt(text, author) {
+      if (!text.trim() || !author.hostMappedAuthorId.trim()) throw new Error("A message and host-mapped author are required");
+      const submission: ChatMessageSubmission = {
+        author_kind: "human",
+        author_id: author.hostMappedAuthorId,
+        body: text,
+        addressed_to_bot_id: author.addressedToBotId,
+      };
+      const idempotencyKey = createKey();
+      if (!idempotencyKey.trim()) throw new Error("A stable message admission key is required");
+      return Object.freeze({ submission: Object.freeze(submission), idempotencyKey });
+    },
+    send(attempt) {
+      return postChatMessage(transport, attempt.submission, attempt.idempotencyKey);
+    },
+  };
+}