@graph8/sdk 0.370.0 → 0.374.0

package/blocks/documents/lib/documents-types.ts

@@ -0,0 +1,252 @@
+"use client";
+
+/**
+ * Shapes, vocabularies and helpers the documents block shares.
+ *
+ * The documents responses are OPEN in the contract (`DocumentPayload` / `DocumentListPayload`), so every field here is
+ * optional and read defensively: a missing value is shown as a dash, never replaced by a guess. A list read always carries
+ * its rows under `items` (the contract's promise), whichever key the app used underneath.
+ *
+ * SDK operations: none.
+ */
+
+import type { Tone } from "@/g8/components/screen/status-pill";
+
+export type Rec = Record<string, unknown>;
+
+/** The Library root; a folder's `parent_path` for a top-level folder. */
+export const ROOT = "Library";
+/** Largest file the /api/g8 proxy forwards by default (5 MiB). The app itself accepts 50 MB: raise `maxBodyBytes` in the proxy route first. */
+export const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+/** Bytes a multipart body adds around its files: the boundary lines and headers (about 200 per file) plus the other fields. */
+export const BASE_OVERHEAD = 4096;
+export const FILE_OVERHEAD = 512;
+/** The largest single file that fits one request under the proxy's body cap (`maxBytes`). */
+export const fileLimit = (maxBytes: number): number => maxBytes - BASE_OVERHEAD - FILE_OVERHEAD;
+/** The extensions the Library accepts (contract text of uploadLibraryDocument). */
+export const LIBRARY_EXTENSIONS = ["pdf", "docx", "doc", "txt", "md", "mdx", "csv", "json", "png", "jpg", "jpeg", "xls", "xlsx", "ppt", "pptx"] as const;
+/** Security questionnaires are read from a spreadsheet or a PDF. */
+export const QUESTIONNAIRE_EXTENSIONS = ["xlsx", "pdf"] as const;
+/** The types whose text the Library can extract again. */
+export const REEXTRACT_TYPES = ["pdf", "docx"] as const;
+
+export const CORRESPONDENCE_CHANNELS = [
+  { value: "email", label: "Email" },
+  { value: "linkedin", label: "LinkedIn" },
+  { value: "call_notes", label: "Call notes" },
+] as const;
+export const DIRECTIONS = [
+  { value: "inbound", label: "Inbound" },
+  { value: "outbound", label: "Outbound" },
+] as const;
+
+export interface LibraryDoc {
+  id: string;
+  folder_path: string;
+  file_name?: string | null;
+  display_name?: string | null;
+  file_type?: string | null;
+  content?: string | null;
+  has_file_data?: boolean;
+  file_size_bytes?: number | null;
+  mime_type?: string | null;
+  priority?: string | null;
+  source?: string | null;
+  indexed_at?: string | null;
+  deleted_at?: string | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+  created_by?: string | null;
+  owner_name?: string | null;
+  current_version?: number | null;
+  meta_data?: Rec | null;
+}
+
+export interface LibraryFolder {
+  id: string;
+  name: string;
+  parent_path: string;
+  full_path: string;
+  created_at?: string | null;
+}
+
+export interface Questionnaire {
+  id: string;
+  account_id?: string | null;
+  original_file_name?: string | null;
+  original_file_type?: string | null;
+  display_name?: string | null;
+  status?: string | null;
+  total_questions?: number | null;
+  answered_questions?: number | null;
+  escalated_questions?: number | null;
+  error_message?: string | null;
+  created_at?: string | null;
+  completed_at?: string | null;
+  questions?: Question[] | null;
+}
+
+export interface Question {
+  id: string;
+  question_text?: string | null;
+  question_topic?: string | null;
+  cell_reference?: string | null;
+  sheet_name?: string | null;
+  answer_text?: string | null;
+  final_answer?: string | null;
+  confidence?: string | null;
+  status?: string | null;
+  review_status?: string | null;
+  escalation_notes?: string | null;
+  guardrail_warnings?: string[] | null;
+  citations?: Rec[] | null;
+}
+
+export interface QuestionnaireProgress {
+  id?: string;
+  status?: string | null;
+  total_questions?: number | null;
+  answered_questions?: number | null;
+  escalated_questions?: number | null;
+  error_message?: string | null;
+  progress?: number | null;
+}
+
+export interface Correspondence {
+  id: string;
+  account_id?: string | null;
+  stakeholder_id?: string | null;
+  channel?: string | null;
+  direction?: string | null;
+  subject?: string | null;
+  content?: string | null;
+  source?: string | null;
+  external_id?: string | null;
+  correspondence_date?: string | null;
+  indexed_in_rag?: boolean;
+  created_at?: string | null;
+}
+
+export interface ImportResult {
+  imported?: number;
+  skipped?: number;
+  errors?: string[];
+}
+
+/** The rows of an open list payload: its `items` array (the contract always sends it). */
+export function rowsOf<T>(data: unknown): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const items = (data as { items?: unknown } | null | undefined)?.items;
+  return Array.isArray(items) ? (items as T[]) : [];
+}
+
+/** The `total` an open list payload may carry, or null when it sends none. */
+export function totalOf(data: unknown): number | null {
+  const t = (data as { total?: unknown } | null | undefined)?.total;
+  return typeof t === "number" ? t : null;
+}
+
+export const extOf = (name: string): string => (name.includes(".") ? name.slice(name.lastIndexOf(".") + 1).toLowerCase() : "");
+
+/** "12 KB", "1.4 MB"; an empty string when the size is unknown (callers show a dash). */
+export function fmtSize(bytes: number | null | undefined): string {
+  if (typeof bytes !== "number" || !Number.isFinite(bytes) || bytes < 0) return "";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024).toLocaleString("en-US")} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export const when = (v: string | null | undefined): string => {
+  if (!v) return "";
+  const d = new Date(v);
+  return Number.isNaN(d.getTime()) ? "" : d.toLocaleString();
+};
+
+/** Keep the files that may go up and say why the others cannot. The same files are counted in the confirm and sent. */
+export function checkFiles(files: readonly File[], allowed: readonly string[], maxBytes: number): { ok: File[]; problems: string[] } {
+  const ok: File[] = [];
+  const problems: string[] = [];
+  for (const f of files) {
+    if (!allowed.includes(extOf(f.name))) problems.push(`${f.name}: only ${allowed.join(", ")} files can be added.`);
+    else if (f.size === 0) problems.push(`${f.name}: the file is empty.`);
+    else if (f.size > maxBytes) problems.push(`${f.name}: ${fmtSize(f.size)} is over the ${fmtSize(maxBytes)} limit.`);
+    else ok.push(f);
+  }
+  return { ok, problems };
+}
+
+/** The API's folder-name rule (letters, digits, spaces, hyphens, underscores; at most 50) and its three-level depth limit. */
+export function folderNameProblem(name: string, parentPath: string): string | null {
+  const n = name.trim();
+  if (!n) return "Give the folder a name.";
+  if (n.length > 50) return "A folder name is at most 50 characters.";
+  if (!/^[\w\s-]+$/.test(n)) return "Use letters, numbers, spaces, hyphens and underscores only.";
+  if (`${parentPath}/${n}`.split("/").length > 3) return "Folders go three levels deep at most.";
+  return null;
+}
+
+/** A stored file name proposed from a title: lower case, hyphens, `.md`. The person can edit it. */
+export function fileNameFor(title: string): string {
+  const base = title.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return base ? `${base}.md` : "";
+}
+
+export const docName = (d: Pick<LibraryDoc, "display_name" | "file_name">): string => d.display_name || d.file_name || "Untitled document";
+export const folderLabel = (path: string): string => (path === ROOT ? "Library" : path.replace(/^Library\//, ""));
+
+export const QUESTIONNAIRE_STATUS: Record<string, { label: string; tone: Tone }> = {
+  pending: { label: "Waiting", tone: "neutral" },
+  processing: { label: "Answering", tone: "info" },
+  completed: { label: "Completed", tone: "positive" },
+  needs_review: { label: "Needs review", tone: "warning" },
+  failed: { label: "Failed", tone: "negative" },
+};
+export const statusInfo = (s: string | null | undefined): { label: string; tone: Tone } =>
+  QUESTIONNAIRE_STATUS[s ?? ""] ?? { label: s ? s.replace(/_/g, " ") : "Unknown", tone: "neutral" };
+/** The filled workbook is only available in these states (the API refuses earlier). */
+export const canDownload = (s: string | null | undefined): boolean => s === "completed" || s === "needs_review";
+export const isWorking = (s: string | null | undefined): boolean => s === "pending" || s === "processing";
+
+/** What a person should read as the state of one question. */
+export function reviewState(q: Question): { label: string; tone: Tone } {
+  if (q.review_status === "skip") return { label: "Not applicable", tone: "neutral" };
+  if (q.review_status === "wrong") return { label: "Marked wrong", tone: "negative" };
+  if (q.status === "escalated") return { label: "Escalated", tone: "warning" };
+  if (q.status === "approved" || q.confidence === "confirmed") return { label: "Approved", tone: "positive" };
+  if (q.final_answer) return { label: "Edited", tone: "info" };
+  if (q.answer_text) return { label: "Answered", tone: "neutral" };
+  return { label: "No answer", tone: "warning" };
+}
+
+/** The answer the filled workbook carries: the person's edit when there is one, else the AI's. */
+export const answerOf = (q: Question): string => q.final_answer || q.answer_text || "";
+
+/** Whole-number percent, or null when there is nothing to divide. */
+export function percentOf(done: number | null | undefined, total: number | null | undefined): number | null {
+  if (typeof done !== "number" || typeof total !== "number" || total <= 0) return null;
+  return Math.min(100, Math.round((done / total) * 100));
+}
+
+/** One piece of correspondence as the import call takes it, or the reason it cannot be sent. */
+export function parseImportItems(text: string): { items: Rec[]; problem: string | null } {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { items: [], problem: "That is not valid JSON." };
+  }
+  const list = Array.isArray(parsed) ? parsed : (parsed as { items?: unknown } | null)?.items;
+  if (!Array.isArray(list) || list.length === 0) return { items: [], problem: "Paste a JSON array with at least one message." };
+  const channels = CORRESPONDENCE_CHANNELS.map((c) => c.value as string);
+  const directions = DIRECTIONS.map((d) => d.value as string);
+  for (const [i, raw] of list.entries()) {
+    const it = raw as Rec;
+    const at = `Message ${i + 1}`;
+    if (!it || typeof it !== "object") return { items: [], problem: `${at} is not an object.` };
+    if (typeof it.content !== "string" || !it.content.trim()) return { items: [], problem: `${at} needs content.` };
+    if (typeof it.channel !== "string" || !channels.includes(it.channel)) return { items: [], problem: `${at}: channel must be ${channels.join(", ")}.` };
+    if (typeof it.direction !== "string" || !directions.includes(it.direction)) return { items: [], problem: `${at}: direction must be inbound or outbound.` };
+    if (typeof it.correspondence_date !== "string" || Number.isNaN(Date.parse(it.correspondence_date))) return { items: [], problem: `${at}: correspondence_date must be a date and time, for example 2026-09-30T14:00:00Z.` };
+  }
+  return { items: list as Rec[], problem: null };
+}

package/blocks/documents/lib/download.ts

@@ -0,0 +1,64 @@
+"use client";
+
+/**
+ * Save a file the API returns as raw bytes (a Library document in its original format, a filled questionnaire workbook).
+ * These two routes are NOT the JSON envelope, so `g8Get` (which parses JSON) cannot read them; this goes through the same
+ * /api/g8 proxy and keeps the key on the server.
+ *
+ * SDK operations: none directly. The callers declare downloadLibraryDocument / downloadSecurityQuestionnaire.
+ */
+
+import { G8Error } from "@graph8/sdk/errors";
+import { buildG8Url, transport } from "@/g8/lib/g8-client";
+
+/** @internal Swappable in tests (jsdom has no object URLs). */
+export const saver = {
+  save(blob: Blob, name: string): void {
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = name;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+  },
+};
+
+/** The file name a Content-Disposition header names (RFC 5987 `filename*` first), or null. */
+export function nameFromDisposition(header: string | null): string | null {
+  if (!header) return null;
+  const star = /filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/.exec(header);
+  if (star) {
+    try {
+      return decodeURIComponent(star[1].trim());
+    } catch {
+      /* fall through to the plain form */
+    }
+  }
+  const plain = /filename\s*=\s*"?([^";]+)"?/.exec(header);
+  return plain ? plain[1].trim() : null;
+}
+
+/** Fetch `path` (relative to /api/v1) and hand the bytes to the browser as a download. Throws `G8Error` on any failure. */
+export async function downloadFile(path: string, fallbackName: string): Promise<string> {
+  let resp: Response;
+  try {
+    resp = await transport.fetch(buildG8Url(path), { method: "GET", credentials: "same-origin" });
+  } catch (err) {
+    throw new G8Error({ message: `Network error: ${(err as Error)?.message ?? "request failed"}`, status: 0, type: "network_error", retryable: true });
+  }
+  if (!resp.ok) {
+    let message = `Request failed with status ${resp.status}`;
+    try {
+      const env = JSON.parse(await resp.text()) as { message?: string; detail?: unknown };
+      message = env.message || (typeof env.detail === "string" ? env.detail : message);
+    } catch {
+      /* keep the status line */
+    }
+    throw new G8Error({ message, status: resp.status, type: "api_error", code: String(resp.status), retryable: resp.status === 429 || resp.status >= 500 });
+  }
+  const name = nameFromDisposition(resp.headers.get("content-disposition")) || fallbackName;
+  saver.save(await resp.blob(), name);
+  return name;
+}

package/blocks/documents/recipes/follow-a-questionnaire.ts

@@ -0,0 +1,26 @@
+/**
+ * @title Follow a security questionnaire until it is answered and list the questions that need a person
+ * @when After a questionnaire was uploaded in the app (answering uses credits, so a person confirms the upload; upload is
+ * multipart and not part of this typed client). Poll the cheap status read, not the full detail, until the status is no longer
+ * pending or processing. This only READS: it approves nothing, because an approval is a person's judgement. The filled workbook
+ * is available only once the status is completed or needs_review.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const accountId = process.env.G8_COMPANY_ID!;
+const questionnaireId = process.env.G8_QUESTIONNAIRE_ID!;
+const path = { account_id: accountId, questionnaire_id: questionnaireId };
+
+let status = "pending";
+for (let i = 0; i < 60 && (status === "pending" || status === "processing"); i++) {
+  const s = (await g8.api.documents.getSecurityQuestionnaireStatus({ path })).data as { status?: string; answered_questions?: number; total_questions?: number };
+  status = s.status ?? "unknown";
+  console.log(status, `${s.answered_questions ?? "-"} of ${s.total_questions ?? "-"} answered`);
+  if (status === "pending" || status === "processing") await new Promise((r) => setTimeout(r, 5000));
+}
+
+const detail = (await g8.api.documents.getSecurityQuestionnaire({ path })).data as { questions?: Array<{ id: string; question_text?: string; status?: string; review_status?: string; answer_text?: string | null }> };
+const needsAPerson = (detail.questions ?? []).filter((q) => q.status !== "approved" && q.review_status !== "skip");
+console.log(`${needsAPerson.length} questions still need review`, needsAPerson.slice(0, 5).map((q) => q.question_text));

package/blocks/documents/recipes/log-account-correspondence.ts

@@ -0,0 +1,27 @@
+/**
+ * @title Import an account's messages so running it twice does not duplicate them
+ * @when Bringing emails, LinkedIn messages or call notes in from another system. Partial success is normal: the status is 200
+ * even when rows failed, so read `imported`, `skipped` and `errors`. A row whose `external_id` is already stored is SKIPPED,
+ * so send one on every row. `correspondence_date` is when the message HAPPENED, not when you import it: generated documents
+ * read it as the relationship timeline. `channel` is email, linkedin or call_notes; `direction` is inbound or outbound.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const accountId = process.env.G8_COMPANY_ID!; // a company id from g8.api.companies.listCompanies
+
+const result = await g8.api.documents.importAccountCorrespondence({
+  path: { account_id: accountId },
+  body: {
+    items: [
+      { channel: "email", direction: "inbound", subject: "Re: pricing", content: "Thanks for the call, sending the quote today.", correspondence_date: "2026-09-30T14:00:00Z", external_id: "msg-1001" },
+      { channel: "call_notes", direction: "outbound", content: "Walked through the security review.", correspondence_date: "2026-10-02T16:30:00Z", external_id: "call-2002" },
+    ],
+  },
+});
+const r = result.data as { imported?: number; skipped?: number; errors?: string[] };
+console.log(`${r.imported ?? 0} imported, ${r.skipped ?? 0} skipped, ${(r.errors ?? []).length} failed`);
+
+const recent = await g8.api.documents.listAccountCorrespondence({ path: { account_id: accountId }, query: { limit: 10 } });
+console.log((recent.data.items ?? []).length, "messages on the account");

package/blocks/documents/recipes/organize-the-library.ts

@@ -0,0 +1,25 @@
+/**
+ * @title Create a Library folder and a text document in it, then list what the folder holds
+ * @when Seeding the Library from a script. The folder must exist before a document can land in it, and a folder name is
+ * letters, numbers, spaces, hyphens and underscores (at most 50), three levels deep at most. A text document is stored exactly
+ * as sent (no extraction). Nothing here reaches anyone. To add a FILE (PDF, Word ...) the API takes multipart, which this
+ * typed client does not send: post it with `fetch` and a `FormData` to /api/v1/library/documents/upload.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const folder = await g8.api.documents.createLibraryFolder({ body: { name: "Case studies 2026", parent_path: "Library" } });
+const folderPath = String((folder.data as { full_path?: string }).full_path ?? "Library/Case studies 2026");
+
+const doc = await g8.api.documents.createLibraryDocument({
+  body: {
+    folder_path: folderPath,
+    file_name: "acme-rollout.md",
+    display_name: "Acme rollout",
+    content: "Acme moved 400 seats in six weeks.",
+  },
+});
+
+const inFolder = await g8.api.documents.listLibraryDocuments({ query: { folder_path: folderPath } });
+console.log(folderPath, (doc.data as { id?: string }).id, (inFolder.data.items ?? []).length);

package/blocks/email-signatures/README.md

@@ -0,0 +1,123 @@
+# email-signatures
+
+Managed email signatures: design **one signature for the team** and keep every mailbox on it. A *template* is the shared
+design (blocks, layout, font, colour, with placeholders such as `{{member.name}}`). A *deployment* binds one mailbox to one
+employee and a template, and the platform installs or applies it. A *policy* decides whether signatures are managed at all,
+which template is the default, and whether employees may change the unlocked parts. A *campaign* adds a banner to signatures
+for a time window. Changing what a mailbox sends is consequential, so every such action is confirmed with the real number of
+mailboxes it touches.
+
+## Screens
+
+`EmailSignaturesScreen` (`components/email-signatures-screen.tsx`) is the finished page: templates, mailboxes, campaigns,
+policy and report.
+
+```tsx
+import { EmailSignaturesScreen } from "@/g8/email-signatures/components/email-signatures-screen";
+export default function Page() { return <EmailSignaturesScreen />; }
+```
+
+Tabs (`?tab=`): **Templates**, **Mailboxes**, **Campaigns**, **Policy**, **Report**. Open a template (`?id=`) for Preview,
+Edit, Use on mailboxes and Details; `&view=full` shows it as a full page.
+
+Flows: see every template (the list is complete: the API does not page it); create one from blocks and placeholders with a
+live preview; preview a stored template as a sample or as a real employee on a real mailbox (full, compact, with the campaign
+banner, or plain text); edit it (the form opens only after the full record has loaded, and a stale save is refused with
+"Load the newer version"); apply it to chosen mailboxes, a department or every mailbox; make it the organisation default;
+archive it. On **Mailboxes**: assign an employee to a mailbox (with a setup check first), push, restore the old signature and
+change what a mailbox sends, one by one or in bulk. **Campaigns**: create and edit banner campaigns, preview the banner, and
+test which mailbox and recipients it would reach. **Policy**: off, managed or enforced, default and department templates.
+**Report**: impressions and clicks by mailbox and campaign.
+
+Parts you can mount alone: `SignatureTemplateForm`, `TemplatePreview` (and `SafeSignatureFrame`), `SignatureAssignTemplate`,
+`SignatureTemplateDetails`, `SignatureMailboxes`, `SignatureIdentityForm`, `SignaturePolicy`, `SignatureCampaigns`,
+`SignatureCampaignForm`, `SignatureReport`, `SignatureBlockEditor`.
+
+## Install
+
+```
+npx @graph8/sdk add email-signatures
+```
+
+Installs `foundation` and `mailboxes` first if missing. Everything lands under `g8/email-signatures/`. The block does not use the `pickers` block on purpose: its `MemberPicker` reports a
+user id, while a signature is assigned to a *directory employee* (`listSignatureMembers`, a different id), and the mailbox
+list is merged with each mailbox's signature status, which no generic picker knows.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| graph8 | Mailboxes connected (Google or Microsoft in the app, or the mailboxes block). A signature is bound to a mailbox. | `GET /api/v1/mailboxes` lists it. |
+| graph8 | The people who sign are team members **with an email address**. An employee without one cannot be assigned. | `GET /api/v1/signatures/members` lists them. |
+| The app | Installing a signature inside a Google account needs the Google Workspace integration with the signature permission, granted by a Workspace admin. A deployment stuck at `needs_admin_grant` is missing it. Without native installation the signature is applied when mail is sent from the platform. | A deployment leaves `needs_admin_grant`. |
+| graph8 key | `signatures:read`, `signatures:write`, `signatures:delete` (archive). `campaigns:read` lists mailboxes. | `g8.api.me.describeCurrentKey()` |
+| Your app | `allowedPrefixes` must include `signatures` and `mailboxes`. | The route file lists them. |
+
+## The flow, in order (IDs passed between steps)
+
+1. **Template**: `createSignatureTemplate({ data: { name, layout, blocks, primary_color, font, brand_source } })` -> **`template.id`** and `template.version`. Exactly one required, locked `identity` block; at most one optional `banner`; unique block ids; required blocks are locked.
+2. **Preview**: `previewSignatureTemplate({ data })` for a draft, `previewSavedSignatureTemplate(template.id, { mailbox_id, member_id })` for a stored one. Pass **both** `mailbox_id` and `member_id` to render with that employee's real details, neither for sample data. Reads only.
+3. **Policy**: `getSignatureSettings` -> **`version`** (the *policy* version). `setDefaultSignatureTemplate(template.id, { version })` makes the template the default (confirmed). `updateSignatureSettings({ version, data })` turns management off, on (`default`) or `enforced`; on needs a default template, enforced needs every active mailbox assigned.
+4. **Employee and mailbox**: `listSignatureMembers` -> **`member.id`**; the mailbox from `listMailboxes` -> **`mailbox.id`**; `listSignatureDeployments` -> the mailbox's **`revision`** (0 when it has no assignment).
+5. **Check**: `previewSignatureSetup({ mailbox_id, data })` is a dry run against the mail provider (account and send-as resolve).
+6. **Assign**: `assignSignatureIdentity({ mailbox_ids, expected_revisions: { [mailbox.id]: revision }, confirm_takeover: true, data: { member_id, account_subject, send_as_email, template_id? } })` behind a confirmation. `account_subject` must be the employee's own directory email and `send_as_email` the mailbox address.
+7. **Bulk**: `assignSignatureTemplate(template.id, { mailbox_ids } | { department } | { all_mailboxes: true })` (exactly one; every target already assigned), `pushSignatures({ mailbox_ids })`, `pushSignature(mailbox.id, { version: revision })`.
+8. **Change or undo**: `changeSignatureSource(mailbox.id, { version, source: "org" | "template" | "custom", template_id? })`; `restoreSignature(mailbox.id, { version })` puts back what the mailbox had before (refused while the policy is `enforced`; parked as `restore_conflict` if the signature was edited elsewhere since).
+9. **Campaign**: `createSignatureCampaign({ data })` (banner block, `starts_at` / `ends_at` timezone-aware, status `draft`, `scheduled` or `paused`); only a `scheduled` campaign inside its dates is added. `previewSignatureCampaign` renders it and, with a mailbox and recipients, says whether it would apply.
+10. **Read**: `getSignatureReport`.
+
+## Default decisions (do not ask the human unless marked)
+
+| Decision | Default | Ask? |
+|---|---|---|
+| New template | Classic stacked, Arial, text colour `#222222`, brand kit colour and font, one required locked identity block (the API's own defaults) | no |
+| Which mailboxes get a template | None: a person chooses the mailboxes, a department or everyone and confirms the count | **yes** |
+| Policy mode | Left as it is | **yes** |
+| Assigning an employee to a mailbox | Account = the employee's directory email, send-as = the mailbox address, after the person agrees to the takeover | **yes** |
+| Stopping a campaign | Set it to Paused (there is no delete) | no |
+| Removing a template | Archive it, after giving its mailboxes another template | no |
+| After editing a template | Push the mailboxes that use it | no |
+
+## Operation coverage (24 signatures operations, all reachable from `EmailSignaturesScreen`)
+
+| Operation | Where |
+|---|---|
+| `listSignatureTemplates`, `getSignatureTemplate` | template list; the edit form (full record) |
+| `createSignatureTemplate`, `updateSignatureTemplate` | `SignatureTemplateForm` |
+| `archiveSignatureTemplate` | `SignatureTemplateDetails` (destructive, confirmed; disabled while the template is in use) |
+| `setDefaultSignatureTemplate` | `SignatureTemplateDetails` (confirmed, sized from the mailboxes that follow the default) |
+| `assignSignatureTemplate` | `SignatureAssignTemplate` (confirmed, sized from the mailboxes the choice covers) |
+| `previewSignatureTemplate`, `previewSavedSignatureTemplate` | `TemplatePreview` |
+| `listSignatureMembers` | employee menus |
+| `listSignatureDeployments` | `SignatureMailboxes` and every count in a confirmation |
+| `assignSignatureIdentity`, `previewSignatureSetup` | `SignatureIdentityForm` (takeover confirmed; setup check first) |
+| `pushSignature`, `pushSignatures`, `restoreSignature`, `changeSignatureSource` | `SignatureMailboxes` (each confirmed) |
+| `getSignatureSettings`, `updateSignatureSettings` | `SignaturePolicy` (save confirmed) |
+| `listSignatureCampaigns`, `createSignatureCampaign`, `updateSignatureCampaign`, `previewSignatureCampaign` | `SignatureCampaigns`, `SignatureCampaignForm` |
+| `getSignatureReport` | `SignatureReport` |
+
+No operation of the namespace is skipped. The block also reads `listMailboxes` (the mailboxes to assign). Previews and the setup check are POSTs, so the contract tiers them as `write`; they change nothing.
+
+## API gaps (what is asked for that the API does not have)
+
+| Asked for | Reality | What the block does |
+|---|---|---|
+| A list of template variables | None. The renderer resolves a fixed set (`member.*`, `mailbox.*`, `company.*`, `brand.*`). | A built-in placeholder list that mirrors the renderer (`lib/signatures-types.ts`). `{{x\|fallback}}` is supported. |
+| Delete a template or a campaign | Templates can only be archived (refused while in use); campaigns cannot be removed. | Archive with the reason it is blocked; pause a campaign. |
+| Read one campaign | There is `list` only. | Edit seeds from the list row, which is the complete stored campaign, and refreshes the list after a save. |
+| Paging and filters | The template, member, deployment and campaign lists take no paging parameters and return everything. `listMailboxes` takes `limit` up to 500 and no page. | The UI says "All N"; a mailbox read that comes back full says "Showing the first 500 mailboxes". |
+| Mailboxes with no signature yet | `listSignatureDeployments` only lists mailboxes that already have a deployment. | Merged with `listMailboxes` (needs `campaigns:read`); without that scope only the assigned mailboxes show, with a note. |
+| Upload a logo or photo | Multipart uploads are not in the developer API. | Images are referenced by address. |
+| Pick audience lists for a campaign | The block has no list picker (it does not depend on the lists block). | A campaign that already targets lists keeps them on every save and can have the targeting removed; add lists through `createSignatureCampaign` / `updateSignatureCampaign` (`recipient_list_ids`). |
+| Employee self-service (`/me`) | An API key has no seat or directory identity. | Out of scope. Employee overrides are carried over unchanged when an assignment is edited. |
+| Choose the Workspace integration | The integrations used by signatures are not listed by the API. | An existing assignment's integration is carried over; a new one lets the API pick. |
+| Click-tracking redirect | Public, unauthenticated by design. | Not an API capability. |
+| Edit part of a template | `updateSignatureTemplate` and `updateSignatureSettings` replace the document. | The whole template is sent, built from the full record that was read; a cleared field is sent empty (`""`), a cleared default template as `null`; a save with no change sends nothing. |
+
+## Things that surprise people
+
+- Every write carries the version or revision that was read. A concurrent change answers **409**; the screen says so and offers the newer version. The **policy** has its own version, used by set-default and the policy save.
+- Signature HTML comes from the API and a template can carry custom markup, so the preview shows it in a **sandboxed frame** with no scripts. Never put signature HTML into your own page with `dangerouslySetInnerHTML`.
+- A required block with a placeholder that has no fallback fails to render for an employee whose directory entry lacks that value. Add `{{member.title|Team}}`.
+- Campaign targeting by audience list applies only to mail sent from a sequence. Dates are picked in the viewer's time zone and sent as timezone-aware instants.
+- Enforced mode refuses a restore and employee changes; turning management **off** stops managing every mailbox.