@graph8/sdk 0.373.0 → 0.374.0

package/blocks/email-signatures/components/signature-identity-form.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+/**
+ * SignatureIdentityForm: give one mailbox a managed signature by binding it to an employee (and, optionally, a template).
+ *
+ * SDK operations, in order:
+ *   1. previewSignatureSetup (POST /signatures/setup-preview)     write*   "Check setup": a dry run against the mail provider. Confirms the
+ *      employee account and the send-as address resolve and shows the signature installed there today. Changes nothing.
+ *   2. assignSignatureIdentity (POST /signatures/assignments)     write    a TAKEOVER: the mailbox's current signature is captured for
+ *      restore and replaced, and the first install is queued. ConfirmSpendDialog (external) first, naming the mailbox.
+ * *A POST, so the contract tiers it as a write.
+ * The API requires the employee account to be the employee's own directory email and the send-as address to be the mailbox
+ * address, so both are shown read-only and derived from the two choices: nothing is typed or guessed. The mailbox's current
+ * revision (0 when it has no assignment yet) is sent so a stale screen cannot overwrite a newer change (409). When the mailbox
+ * is already assigned, its template, workspace integration, employee overrides and native-install request are carried over
+ * unchanged unless the person edits them here. A provider refusal (422) shows its state and reason.
+ */
+
+import { useState } from "react";
+import { Button, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useSignatureDeployments, useSignatureMembers, useSignatureTemplates } from "../hooks/use-signatures-data";
+import { isConflict, memberLabel, templateName } from "../lib/signatures-types";
+import type { Assignment, SignatureMailbox } from "../lib/signatures-types";
+
+export interface SignatureIdentityFormProps {
+  mailbox: SignatureMailbox;
+  onDone: () => void;
+  onCancel?: () => void;
+}
+
+interface SetupCheck { html?: string; plain?: string; identity_verified?: boolean; write_verified?: boolean; message?: string }
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+
+export function SignatureIdentityForm({ mailbox, onDone, onCancel }: SignatureIdentityFormProps) {
+  const members = useSignatureMembers();
+  const templates = useSignatureTemplates();
+  const deployments = useSignatureDeployments();
+  const current = mailbox.deployment?.assignment;
+  const [memberId, setMemberId] = useState(current?.member_id ?? "");
+  const [templateId, setTemplateId] = useState(current?.template_id ?? "");
+  const [native, setNative] = useState(Boolean(current?.native_requested));
+  const [confirm, setConfirm] = useState(false);
+  const member = members.data?.find((m) => m.id === memberId);
+  const usable = Boolean(member?.email);
+
+  const assignment = (): Assignment => ({
+    member_id: memberId,
+    ...(templateId ? { template_id: templateId } : {}),
+    account_subject: member?.email ?? "",
+    send_as_email: mailbox.email,
+    ...(current?.integration_id ? { integration_id: current.integration_id } : {}),
+    overrides: current?.overrides ?? {},
+    native_requested: native,
+  });
+
+  const check = useG8Mutation(async (): Promise<SetupCheck> => (await g8Post<SetupCheck>("/signatures/setup-preview", { mailbox_id: mailbox.id, data: assignment() })).data);
+  const assign = useG8Mutation(async (): Promise<unknown> => (
+    await g8Post("/signatures/assignments", {
+      mailbox_ids: [mailbox.id],
+      expected_revisions: { [mailbox.id]: mailbox.deployment?.revision ?? 0 },
+      confirm_takeover: true,
+      data: assignment(),
+    })
+  ).data, {
+    onSuccess: () => { setConfirm(false); onDone(); },
+    onError: () => setConfirm(false),
+    invalidates: [["signatures", "deployments"]],
+  });
+
+  const err = assign.error;
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (usable) setConfirm(true); }}>
+      <p className="text-muted-foreground text-sm">Mailbox: <span className="text-foreground font-medium">{mailbox.email}</span></p>
+      <div>
+        <Label htmlFor="g8-sig-employee" className="mb-1">Employee</Label>
+        <select id="g8-sig-employee" className={SELECT} value={memberId} onChange={(e) => { setMemberId(e.target.value); check.reset(); }}>
+          <option value="">Choose an employee</option>
+          {(members.data ?? []).map((m) => <option key={m.id} value={m.id}>{memberLabel(m)}{m.department ? ` (${m.department})` : ""}</option>)}
+        </select>
+        {memberId !== "" && !usable ? <p role="alert" className="text-error mt-1 text-xs">This employee has no directory email, so a signature cannot be assigned to them.</p> : null}
+      </div>
+      <div>
+        <Label htmlFor="g8-sig-template" className="mb-1">Template</Label>
+        <select id="g8-sig-template" className={SELECT} value={templateId} onChange={(e) => setTemplateId(e.target.value)}>
+          <option value="">The department or organisation default</option>
+          {(templates.data ?? []).map((t) => <option key={t.id} value={t.id}>{templateName(t)}</option>)}
+        </select>
+      </div>
+      <KeyValueList columns={2} items={[
+        { label: "Employee account", value: member?.email ?? "" },
+        { label: "Send-as address", value: mailbox.email },
+      ]} />
+      <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={native} onChange={(e) => setNative(e.target.checked)} />Also install it inside the mail account when the policy allows native installation</label>
+      {check.data ? (
+        <div role="status" className="grid gap-1 rounded-md border p-3 text-sm">
+          <p>{check.data.message ?? "Checked."}</p>
+          {check.data.plain ? <p className="text-muted-foreground text-xs">Signature there today: {check.data.plain}</p> : null}
+        </div>
+      ) : null}
+      {check.error ? <ApiError error={check.error} title="The mail account could not be checked" /> : null}
+      {err && isConflict(err) ? (
+        <div className="grid gap-2">
+          <ApiError error={err} title="This mailbox changed since you opened it" />
+          <div><Button type="button" size="sm" variant="outline" onClick={() => { void deployments.refetch(); onCancel?.(); }}>Reload and start again</Button></div>
+        </div>
+      ) : err ? <ApiError error={err} title="Could not assign the signature" /> : null}
+      <div className="flex flex-wrap gap-2">
+        <Button type="button" variant="outline" disabled={!usable} loading={check.loading} onClick={() => void check.mutate(undefined)}>Check setup</Button>
+        <Button type="submit" disabled={!usable} loading={assign.loading}>{mailbox.deployment ? "Update assignment" : "Assign signature"}</Button>
+        {onCancel ? <Button type="button" variant="ghost" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+      <ConfirmSpendDialog
+        open={confirm}
+        tier="external"
+        title={`Take over the signature of ${mailbox.email}?`}
+        affected={1}
+        description={<p>The signature this mailbox sends today is saved so it can be restored, then replaced by {templateId ? templateName(templates.data?.find((t) => t.id === templateId)) : "the default template"} for {memberLabel(member)}. New emails from this mailbox carry it.</p>}
+        confirmLabel="Take over signature"
+        confirming={assign.loading}
+        onCancel={() => setConfirm(false)}
+        onConfirm={() => void assign.mutate(undefined)}
+      />
+    </form>
+  );
+}

package/blocks/email-signatures/components/signature-mailboxes.tsx

@@ -0,0 +1,195 @@
+"use client";
+
+/**
+ * SignatureMailboxes: every mailbox with the signature it sends, its status, and the actions on it.
+ *
+ * SDK operations (the lists come from the shared hooks: listMailboxes + listSignatureDeployments, listSignatureTemplates,
+ * listSignatureMembers, getSignatureSettings):
+ *   1. pushSignature (POST /signatures/mailboxes/{mailbox_id}/push)         write  queue a re-compile and re-install of one mailbox
+ *   2. pushSignatures (POST /signatures/mailboxes/push)                     write  the same for the selected mailboxes; all or none (422)
+ *   3. restoreSignature (POST /signatures/mailboxes/{mailbox_id}/restore)   write  put back the signature the mailbox had before takeover
+ *   4. changeSignatureSource (POST /signatures/mailboxes/{mailbox_id}/source) write what the mailbox sends: org default, a template, or its own
+ * Every one of them changes the signature a mailbox SENDS, so each goes through one ConfirmSpendDialog (external) that names
+ * the real number of mailboxes. Per-mailbox writes send the revision that was read (409 on a stale screen, then a refresh).
+ * Assigning an employee to a mailbox (the first step) opens SignatureIdentityForm in a sheet. Selection only holds mailboxes that
+ * still exist and are managed, and is cleared after a bulk push. Mailboxes with no signature yet are listed too; a key that
+ * cannot read mailboxes still sees the ones that have one, with a note. A deployment waiting for the mail admin's signature
+ * permission (needs_admin_grant) shows a link-out to the platform app, whose name and address come from useBrand.
+ */
+
+import { useState } from "react";
+import { RefreshCw, RotateCcw, UserPlus } from "lucide-react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { FirstNotice } from "@/g8/components/paging-notices";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { StatusPill, humanizeStatus } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { g8Post } from "@/g8/lib/g8-client";
+import { brandUrl, useBrand } from "@/g8/hooks/use-brand";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { plural } from "@/g8/lib/plural";
+import { MAILBOX_LIMIT, useSignatureMailboxes, useSignatureMembers, useSignaturePolicy, useSignatureTemplates } from "../hooks/use-signatures-data";
+import { SOURCE_CHOICES, formatWhen, isConflict, isManaged, memberLabel, statusTone, templateName } from "../lib/signatures-types";
+import type { SignatureMailbox, SourceChoice } from "../lib/signatures-types";
+import { SignatureIdentityForm } from "./signature-identity-form";
+
+type Pending =
+  | { kind: "push"; mailbox: SignatureMailbox }
+  | { kind: "restore"; mailbox: SignatureMailbox }
+  | { kind: "bulk"; mailboxes: SignatureMailbox[] }
+  | { kind: "source"; mailbox: SignatureMailbox; source: SourceChoice; templateId: string };
+
+interface Outcome { status?: string; message?: string | null }
+
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+const FILTERS = [{ value: "", label: "All mailboxes" }, { value: "attention", label: "Needs attention" }, { value: "managed", label: "Managed" }, { value: "unmanaged", label: "Not managed" }];
+
+export function SignatureMailboxes() {
+  const brand = useBrand();
+  const box = useSignatureMailboxes();
+  const templates = useSignatureTemplates();
+  const members = useSignatureMembers();
+  const policy = useSignaturePolicy();
+  const [search, setSearch] = useState("");
+  const [filter, setFilter] = useState("");
+  const [picked, setPicked] = useState<number[]>([]);
+  const [assigning, setAssigning] = useState<SignatureMailbox | null>(null);
+  const [sourcing, setSourcing] = useState<SignatureMailbox | null>(null);
+  const [srcChoice, setSrcChoice] = useState<SourceChoice>("org");
+  const [srcTemplate, setSrcTemplate] = useState("");
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [outcome, setOutcome] = useState<string | null>(null);
+
+  const run = useG8Mutation(async (p: Pending): Promise<Outcome> => {
+    if (p.kind === "bulk") return (await g8Post<Outcome>("/signatures/mailboxes/push", { mailbox_ids: p.mailboxes.map((m) => m.id) })).data;
+    const base = `/signatures/mailboxes/${p.mailbox.id}`;
+    const version = p.mailbox.deployment?.revision ?? 0;
+    if (p.kind === "push") return (await g8Post<Outcome>(`${base}/push`, { version })).data;
+    if (p.kind === "restore") return (await g8Post<Outcome>(`${base}/restore`, { version })).data;
+    return (await g8Post<Outcome>(`${base}/source`, { version, source: p.source, ...(p.source === "template" ? { template_id: p.templateId } : {}) })).data;
+  }, {
+    onSuccess: (r, p) => {
+      setPending(null);
+      setSourcing(null);
+      setPicked([]);
+      setOutcome(r.message ? `${r.status ?? "Done"}: ${r.message}` : `Queued: ${p.kind === "bulk" ? plural(p.mailboxes.length, "mailbox") : p.mailbox.email}.`);
+    },
+    onError: (e) => { setPending(null); if (isConflict(e)) box.refetch(); },
+    invalidates: [["signatures", "deployments"]],
+  });
+
+  const q = search.trim().toLowerCase();
+  const memberName = (id: string | undefined): string => (id ? memberLabel(members.data?.find((m) => m.id === id)) : "");
+  const shown = box.mailboxes.filter((m) => {
+    const d = m.deployment;
+    const okFilter = filter === "" || (filter === "attention" && Boolean(d?.alert)) || (filter === "managed" && isManaged(d)) || (filter === "unmanaged" && !isManaged(d));
+    return okFilter && (!q || `${m.email} ${memberName(d?.assignment?.member_id)}`.toLowerCase().includes(q));
+  });
+  const selectable = shown.filter((m) => isManaged(m.deployment));
+  const selected = box.mailboxes.filter((m) => picked.includes(m.id) && isManaged(m.deployment));
+  const where = (m: SignatureMailbox): string => {
+    const a = m.deployment?.assignment;
+    if (!isManaged(m.deployment)) return "Its own signature";
+    const named = (id: string | null | undefined): string => templateName(templates.data?.find((t) => t.id === id));
+    if (a?.template_id) return templates.data ? named(a.template_id) : "";
+    const dept = members.data?.find((x) => x.id === a?.member_id)?.department;
+    const deptTemplate = dept ? policy.data?.data.department_templates?.[dept] : undefined;
+    if (deptTemplate) return `${named(deptTemplate)} (department default)`;
+    return policy.data?.data.default_template_id ? `${named(policy.data.data.default_template_id)} (organisation default)` : "No default template is set";
+  };
+
+  const confirmText = (p: Pending): { title: string; body: string; count: number; label: string } => {
+    if (p.kind === "bulk") return { title: `Push the signature to ${plural(p.mailboxes.length, "mailbox")}?`, body: "Each mailbox is recompiled and its signature installed again.", count: p.mailboxes.length, label: "Push signatures" };
+    if (p.kind === "push") return { title: `Push the signature to ${p.mailbox.email}?`, body: "The mailbox is recompiled and its signature installed again.", count: 1, label: "Push signature" };
+    if (p.kind === "restore") return { title: `Restore the old signature of ${p.mailbox.email}?`, body: "The signature this mailbox had before takeover is put back and it is no longer managed. If it was edited elsewhere since, nothing is overwritten. Refused while the policy is enforced.", count: 1, label: "Restore signature" };
+    const what = p.source === "template" ? templateName(templates.data?.find((t) => t.id === p.templateId)) : p.source === "org" ? "the organisation or department default" : "its own signature";
+    return { title: `Make ${p.mailbox.email} send ${what}?`, body: "New emails from this mailbox carry the change.", count: 1, label: "Change signature" };
+  };
+  const text = pending ? confirmText(pending) : null;
+
+  const body = box.error ? <ApiError error={box.error} title="Could not load mailboxes" onRetry={box.refetch} /> : box.loading ? (
+    <div aria-busy="true" className="grid gap-2"><Skeleton className="h-10 w-full" /><Skeleton className="h-10 w-full" /><Skeleton className="h-10 w-full" /></div>
+  ) : shown.length === 0 ? (
+    <EmptyState title={box.mailboxes.length === 0 ? "No mailboxes yet" : "No mailboxes match"} description={box.mailboxes.length === 0 ? "Connect or buy a mailbox first, then give it a managed signature here." : "Try another search or filter."} />
+  ) : (
+    <>
+      <p role="status" className="text-muted-foreground mb-2 text-xs">{shown.length === box.mailboxes.length ? `All ${plural(box.mailboxes.length, "mailbox")}` : `${shown.length.toLocaleString()} of ${plural(box.mailboxes.length, "mailbox")}`}</p>
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead className="w-8"><input type="checkbox" aria-label="Select all shown mailboxes" checked={selectable.length > 0 && selectable.every((m) => picked.includes(m.id))} onChange={(e) => setPicked(e.target.checked ? selectable.map((m) => m.id) : [])} /></TableHead>
+            <TableHead>Mailbox</TableHead><TableHead>Employee</TableHead><TableHead>Signature from</TableHead><TableHead>Status</TableHead><TableHead className="text-right">Actions</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {shown.map((m) => {
+            const d = m.deployment;
+            const managed = isManaged(d);
+            return (
+              <TableRow key={m.id}>
+                <TableCell><input type="checkbox" aria-label={`Select ${m.email}`} disabled={!managed} checked={picked.includes(m.id)} onChange={(e) => setPicked(e.target.checked ? [...picked, m.id] : picked.filter((id) => id !== m.id))} /></TableCell>
+                <TableCell><span className="font-medium">{m.email}</span>{m.display_name ? <span className="text-muted-foreground block text-xs">{m.display_name}</span> : null}</TableCell>
+                <TableCell>{memberName(d?.assignment?.member_id) || <span className="text-muted-foreground">None</span>}</TableCell>
+                <TableCell>{where(m)}</TableCell>
+                <TableCell>
+                  {d ? <StatusPill tone={statusTone(d)} title={d.error ?? undefined}>{humanizeStatus(d.status)}</StatusPill> : <StatusPill tone="neutral">Not managed</StatusPill>}
+                  {d?.updated_at ? <span className="text-muted-foreground block text-xs">{formatWhen(d.updated_at)}</span> : null}
+                </TableCell>
+                <TableCell className="text-right">
+                  <div className="flex flex-wrap justify-end gap-1">
+                    <Button size="sm" variant="outline" aria-label={`${d ? "Change employee for" : "Assign a signature to"} ${m.email}`} onClick={() => setAssigning(m)}><UserPlus className="size-4" />{d ? "Employee" : "Assign"}</Button>
+                    {managed ? <Button size="sm" variant="outline" aria-label={`Push signature to ${m.email}`} onClick={() => setPending({ kind: "push", mailbox: m })}><RefreshCw className="size-4" />Push</Button> : null}
+                    {managed ? <Button size="sm" variant="ghost" aria-label={`Change source for ${m.email}`} onClick={() => { setSourcing(m); setSrcChoice("org"); setSrcTemplate(""); }}>Source</Button> : null}
+                    {managed ? <Button size="sm" variant="ghost" aria-label={`Restore the old signature of ${m.email}`} onClick={() => setPending({ kind: "restore", mailbox: m })}><RotateCcw className="size-4" />Restore</Button> : null}
+                  </div>
+                </TableCell>
+              </TableRow>
+            );
+          })}
+        </TableBody>
+      </Table>
+    </>
+  );
+
+  return (
+    <div className="grid gap-3">
+      <Toolbar
+        search={{ value: search, onChange: setSearch, placeholder: "Search mailboxes" }}
+        filters={<select aria-label="Filter mailboxes" className={SELECT} value={filter} onChange={(e) => setFilter(e.target.value)}>{FILTERS.map((f) => <option key={f.value} value={f.value}>{f.label}</option>)}</select>}
+        actions={<Button size="sm" disabled={selected.length === 0} onClick={() => setPending({ kind: "bulk", mailboxes: selected })}>Push to {plural(selected.length, "selected mailbox", "selected mailboxes")}</Button>}
+      />
+      {box.mailboxesError ? <ApiError compact error={box.mailboxesError} title="Mailboxes without a signature are not listed" onRetry={box.refetch} /> : null}
+      {box.mailboxes.some((m) => m.deployment?.status === "needs_admin_grant") ? (
+        <p role="note" className="rounded-md border p-3 text-sm">
+          Some mailboxes cannot be updated until a mail admin grants signature access. Do it in the <a className="underline" href={brandUrl(brand, "/studio/settings?tab=integrations")} target="_blank" rel="noreferrer">{brand.linkLabel} integrations settings</a>, then push them again.
+        </p>
+      ) : null}
+      {outcome ? <p role="status" className="text-sm">{outcome}</p> : null}
+      {run.error ? (isConflict(run.error) ? <ApiError error={run.error} title="This mailbox changed since the page loaded. It was refreshed: try again" /> : <ApiError error={run.error} title="Could not change the signature" />) : null}
+      {body}
+      <FirstNotice shown={box.mailboxes.length} limit={MAILBOX_LIMIT} noun="mailboxes" force={box.truncated} />
+      <FormSheet open={assigning !== null} onOpenChange={(o) => !o && setAssigning(null)} title={assigning?.deployment ? "Change the employee" : "Assign a signature"} description="Bind an employee to this mailbox. Their details fill the template.">
+        {assigning ? <SignatureIdentityForm key={assigning.id} mailbox={assigning} onDone={() => { setAssigning(null); setOutcome(`Queued the first install for ${assigning.email}.`); }} onCancel={() => setAssigning(null)} /> : null}
+      </FormSheet>
+      <FormSheet open={sourcing !== null} onOpenChange={(o) => !o && setSourcing(null)} title={`What ${sourcing?.email ?? "this mailbox"} sends`} description="Choose where this mailbox gets its signature."
+        footer={<><Button variant="outline" onClick={() => setSourcing(null)}>Cancel</Button><Button disabled={srcChoice === "template" && srcTemplate === ""} onClick={() => sourcing && setPending({ kind: "source", mailbox: sourcing, source: srcChoice, templateId: srcTemplate })}>Continue</Button></>}>
+        <select aria-label="Signature source" className={`${SELECT} w-full`} value={srcChoice} onChange={(e) => setSrcChoice(e.target.value as SourceChoice)}>{SOURCE_CHOICES.map((s) => <option key={s.value} value={s.value}>{s.label}</option>)}</select>
+        {srcChoice === "template" ? <select aria-label="Template" className={`${SELECT} w-full`} value={srcTemplate} onChange={(e) => setSrcTemplate(e.target.value)}><option value="">Choose a template</option>{(templates.data ?? []).map((t) => <option key={t.id} value={t.id}>{templateName(t)}</option>)}</select> : null}
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={pending !== null}
+        tier="external"
+        title={text?.title ?? ""}
+        affected={text?.count}
+        description={text?.body}
+        confirmLabel={text?.label}
+        confirming={run.loading}
+        onCancel={() => setPending(null)}
+        onConfirm={() => { if (pending) void run.mutate(pending); }}
+      />
+    </div>
+  );
+}

package/blocks/email-signatures/components/signature-policy.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+/**
+ * SignaturePolicy: the organisation-wide signature policy: whether signatures are managed at all, the default template,
+ * a template per department, whether employees may change the parts you leave unlocked, which variant cold sends use, and
+ * native installation.
+ *
+ * SDK operations, in order (the policy, template and member reads come from the shared hooks):
+ *   1. getSignatureSettings (GET /signatures/settings)    read    the stored policy and its version; the form shows only once it has loaded
+ *   2. updateSignatureSettings (PUT /signatures/settings) write   REPLACES the policy and sends the version that was read (409 if someone saved first).
+ *      It changes what every managed mailbox sends, so ConfirmSpendDialog (external) comes first, sized from the managed mailboxes.
+ * The payload is the stored policy's known keys plus the fields the person changed; a field that was never stored is left out so
+ * the API applies its own default instead of one invented here. Clearing the default template sends null, clearing a department
+ * removes it from the map. Turning management on needs a default template; enforcing needs every active mailbox assigned (the API checks).
+ */
+
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { g8Put } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { plural } from "@/g8/lib/plural";
+import { useSignatureDeployments, useSignatureMembers, useSignaturePolicy, useSignatureTemplates } from "../hooks/use-signatures-data";
+import { COLD_VARIANTS, POLICY_MODES, isConflict, isManaged, knownPolicy, templateName } from "../lib/signatures-types";
+import type { PolicyData, PolicyMode, SignaturePolicy as Policy } from "../lib/signatures-types";
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm disabled:opacity-50";
+
+export function SignaturePolicy() {
+  const policy = useSignaturePolicy();
+  const [saved, setSaved] = useState(false);
+  if (policy.error && !policy.data) return <ApiError error={policy.error} title="Could not load the policy" onRetry={() => void policy.refetch()} />;
+  if (!policy.data) return <Skeleton className="h-40 w-full" aria-label="Loading the policy" />;
+  // A save changes the version, which remounts the form, so the "saved" note lives here.
+  return (
+    <div className="grid gap-2">
+      {saved ? <p role="status" className="text-sm">Policy saved.</p> : null}
+      <PolicyForm key={policy.data.version} policy={policy.data} onReload={() => void policy.refetch()} onSaved={() => setSaved(true)} />
+    </div>
+  );
+}
+
+function PolicyForm({ policy, onReload, onSaved }: { policy: Policy; onReload: () => void; onSaved: () => void }) {
+  const templates = useSignatureTemplates();
+  const members = useSignatureMembers();
+  const deployments = useSignatureDeployments();
+  const stored = knownPolicy(policy.data);
+  const [mode, setMode] = useState<PolicyMode>((stored.mode as PolicyMode) ?? "off");
+  const [defaultId, setDefaultId] = useState(stored.default_template_id ?? "");
+  const [byDept, setByDept] = useState<Record<string, string>>(stored.department_templates ?? {});
+  const [overrides, setOverrides] = useState(stored.allow_employee_overrides ?? true);
+  const [cold, setCold] = useState<"full" | "compact">(stored.cold_sends_variant ?? "compact");
+  const [native, setNative] = useState(stored.native_enabled ?? false);
+  const [confirm, setConfirm] = useState(false);
+  const managed = (deployments.data ?? []).filter((d) => isManaged(d)).length;
+  const departments = [...new Set([...(members.data ?? []).map((m) => m.department).filter((d): d is string => Boolean(d)), ...Object.keys(stored.department_templates ?? {})])].sort();
+  const needsDefault = mode !== "off" && defaultId === "";
+
+  const next: Partial<PolicyData> = {
+    ...stored,
+    ...(mode !== stored.mode ? { mode } : {}),
+    ...(defaultId !== (stored.default_template_id ?? "") ? { default_template_id: defaultId === "" ? null : defaultId } : {}),
+    ...(JSON.stringify(byDept) !== JSON.stringify(stored.department_templates ?? {}) ? { department_templates: byDept } : {}),
+    ...(overrides !== (stored.allow_employee_overrides ?? true) ? { allow_employee_overrides: overrides } : {}),
+    ...(cold !== (stored.cold_sends_variant ?? "compact") ? { cold_sends_variant: cold } : {}),
+    ...(native !== (stored.native_enabled ?? false) ? { native_enabled: native } : {}),
+  };
+  const changed = JSON.stringify(next) !== JSON.stringify(stored);
+
+  const save = useG8Mutation(async (): Promise<Policy> => (await g8Put<Policy>("/signatures/settings", { version: policy.version, data: next })).data, {
+    onSuccess: () => { setConfirm(false); onSaved(); },
+    onError: () => setConfirm(false),
+    invalidates: [["signatures", "policy"], ["signatures", "deployments"]],
+  });
+
+  const setDept = (dept: string, id: string): void => {
+    const rest = Object.fromEntries(Object.entries(byDept).filter(([k]) => k !== dept));
+    setByDept(id === "" ? rest : { ...rest, [dept]: id });
+  };
+  const options = (templates.data ?? []).map((t) => <option key={t.id} value={t.id}>{templateName(t)}</option>);
+
+  return (
+    <SectionCard title="Signature policy" description={`Applies to ${plural(managed, "managed mailbox", "managed mailboxes")}.`}>
+      <form className="grid gap-4" onSubmit={(e) => { e.preventDefault(); if (changed && !needsDefault) setConfirm(true); }}>
+        <fieldset className="grid gap-2 text-sm">
+          <legend className="mb-1 font-medium">Management</legend>
+          {POLICY_MODES.map((m) => (
+            <label key={m.value} className="flex items-start gap-2"><input type="radio" name="g8-sig-mode" className="mt-1" checked={mode === m.value} onChange={() => setMode(m.value)} /><span><span className="font-medium">{m.label}</span><span className="text-muted-foreground block text-xs">{m.hint}</span></span></label>
+          ))}
+        </fieldset>
+        <label className="grid gap-1 text-sm">Default template
+          <select aria-label="Default template" className={SELECT} value={defaultId} onChange={(e) => setDefaultId(e.target.value)}><option value="">None</option>{options}</select>
+        </label>
+        {needsDefault ? <p role="alert" className="text-error text-xs">Choose a default template before turning management on.</p> : null}
+        {departments.length > 0 ? (
+          <fieldset className="grid gap-2">
+            <legend className="mb-1 text-sm font-medium">Template by department</legend>
+            {departments.map((d) => (
+              <label key={d} className="grid grid-cols-[10rem_1fr] items-center gap-2 text-sm">{d}
+                <select aria-label={`Template for ${d}`} className={SELECT} value={byDept[d] ?? ""} onChange={(e) => setDept(d, e.target.value)}><option value="">The default template</option>{options}</select>
+              </label>
+            ))}
+          </fieldset>
+        ) : null}
+        <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={overrides} onChange={(e) => setOverrides(e.target.checked)} />Employees may change the parts of their signature that are not locked</label>
+        <label className="grid gap-1 text-sm">Cold sends use
+          <select aria-label="Cold sends variant" className={SELECT} value={cold} onChange={(e) => setCold(e.target.value as "full" | "compact")}>{COLD_VARIANTS.map((v) => <option key={v.value} value={v.value}>{v.label}</option>)}</select>
+        </label>
+        <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={native} onChange={(e) => setNative(e.target.checked)} />Allow installing signatures inside the mail account (native installation)</label>
+        {save.error && isConflict(save.error) ? (
+          <div className="grid gap-2"><ApiError error={save.error} title="The policy changed since you opened it" /><div><Button type="button" size="sm" variant="outline" onClick={onReload}>Load the newer policy</Button></div></div>
+        ) : save.error ? <ApiError error={save.error} title="Could not save the policy" /> : null}
+        <div><Button type="submit" loading={save.loading} disabled={!changed || needsDefault}>Save policy</Button></div>
+      </form>
+      <ConfirmSpendDialog
+        open={confirm}
+        tier="external"
+        title={`Save the policy for ${plural(managed, "managed mailbox", "managed mailboxes")}?`}
+        affected={managed}
+        description="The policy decides which signature each managed mailbox sends and whether employees can change it. Turning management off stops managing every one of them."
+        confirmLabel="Save policy"
+        confirming={save.loading}
+        onCancel={() => setConfirm(false)}
+        onConfirm={() => void save.mutate(undefined)}
+      />
+    </SectionCard>
+  );
+}

package/blocks/email-signatures/components/signature-preview.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+/**
+ * SafeSignatureFrame and TemplatePreview: show what a signature will look like.
+ *
+ * SafeSignatureFrame renders signature HTML (which comes from the API, and a template can carry custom markup) inside a
+ * sandboxed iframe with no scripts, no same-origin access and a content-security-policy that allows only inline styles and
+ * https or data images. The markup is never put into the page's own DOM, so it cannot run code or restyle the app.
+ *
+ * TemplatePreview renders a template with the signature renderer, read-only (nothing is saved or sent):
+ *   1. previewSignatureTemplate (POST /signatures/preview)                        write*  an UNSAVED draft; waits until the draft is valid, debounced
+ *   2. previewSavedSignatureTemplate (POST /signatures/templates/{id}/preview)    write*  a stored template
+ * *The contract tiers a preview as a write because it is a POST; it changes nothing. Pick an employee AND a mailbox to render
+ * with that person's real details; without both, the API renders sample data. Variants: full, compact (what cold sends use)
+ * and with the campaign banner, plus the plain-text version.
+ */
+
+import { useMemo, useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useDebounced } from "@/g8/lib/use-debounced-value";
+import { useSignatureMailboxes, useSignatureMembers } from "../hooks/use-signatures-data";
+import { memberLabel } from "../lib/signatures-types";
+import type { PreviewVariant, TemplateData, TemplatePreview as TemplatePreviewData } from "../lib/signatures-types";
+
+const POLICY = "default-src 'none'; img-src https: data:; style-src 'unsafe-inline'";
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+
+/** The document the frame shows: the signature's markup between fixed, trusted wrapper tags. */
+export function frameDocument(html: string): string {
+  return `<!doctype html><html><head><meta charset="utf-8"><meta http-equiv="Content-Security-Policy" content="${POLICY}"><style>body{margin:12px;font:14px/1.4 Arial,sans-serif;color:#222;background:#fff}</style></head><body>${html}</body></html>`;
+}
+
+export interface SafeSignatureFrameProps {
+  html: string;
+  title?: string;
+  className?: string;
+}
+
+export function SafeSignatureFrame({ html, title = "Signature preview", className }: SafeSignatureFrameProps) {
+  const doc = useMemo(() => frameDocument(html), [html]);
+  // sandbox="" is the strictest setting: no scripts, no forms, no popups, no same-origin. Do not add allow-* tokens.
+  return <iframe title={title} sandbox="" referrerPolicy="no-referrer" srcDoc={doc} className={className ?? "border-border h-56 w-full rounded-md border bg-white"} />;
+}
+
+const VARIANTS: { value: PreviewVariant; label: string }[] = [
+  { value: "full", label: "Full" },
+  { value: "compact", label: "Compact (cold sends)" },
+  { value: "campaign", label: "With campaign banner" },
+];
+
+export interface TemplatePreviewProps {
+  /** An unsaved draft to render. Omit to render the stored template `templateId`. */
+  draft?: TemplateData;
+  /** Hold a draft back until it passes the template rules (the API refuses an invalid one). */
+  draftValid?: boolean;
+  templateId?: string;
+  className?: string;
+}
+
+export function TemplatePreview({ draft, draftValid = true, templateId, className }: TemplatePreviewProps) {
+  const members = useSignatureMembers();
+  const mailboxes = useSignatureMailboxes();
+  const [memberId, setMemberId] = useState("");
+  const [mailboxId, setMailboxId] = useState("");
+  const [variant, setVariant] = useState<PreviewVariant>("full");
+  const [plain, setPlain] = useState(false);
+  const real = memberId !== "" && mailboxId !== "";
+  const who = real ? { mailbox_id: Number(mailboxId), member_id: memberId } : {};
+  const body = JSON.stringify(draft ? { data: draft, ...who } : who);
+  const settled = useDebounced(body, draft ? 600 : 0);
+  const ready = (draft ? draftValid : Boolean(templateId)) && settled === body;
+
+  const result = useG8Query(
+    (signal) => {
+      const payload = JSON.parse(settled) as Record<string, unknown>;
+      const path = draft ? "/signatures/preview" : `/signatures/templates/${encodeURIComponent(templateId ?? "")}/preview`;
+      return g8Post<TemplatePreviewData>(path, payload, { signal }).then((r) => r.data);
+    },
+    [settled, templateId, Boolean(draft)],
+    { enabled: ready },
+  );
+  const shown = result.data?.[variant];
+
+  return (
+    <div className={className ?? "grid gap-3"}>
+      <div className="grid gap-2 sm:grid-cols-2">
+        <label className="grid gap-1 text-xs">
+          Show it for
+          <select aria-label="Preview for employee" className={SELECT} value={memberId} onChange={(e) => setMemberId(e.target.value)}>
+            <option value="">Sample employee</option>
+            {(members.data ?? []).map((m) => <option key={m.id} value={m.id}>{memberLabel(m)}</option>)}
+          </select>
+        </label>
+        <label className="grid gap-1 text-xs">
+          From mailbox
+          <select aria-label="Preview from mailbox" className={SELECT} value={mailboxId} onChange={(e) => setMailboxId(e.target.value)}>
+            <option value="">Sample mailbox</option>
+            {mailboxes.mailboxes.map((m) => <option key={m.id} value={m.id}>{m.email}</option>)}
+          </select>
+        </label>
+      </div>
+      {(memberId === "") !== (mailboxId === "") ? <p role="note" className="text-muted-foreground text-xs">Pick both an employee and a mailbox to preview with real details; until then the sample is shown.</p> : null}
+      <div className="flex flex-wrap items-center gap-1" role="group" aria-label="Preview variant">
+        {VARIANTS.map((v) => <Button key={v.value} type="button" size="sm" variant={variant === v.value ? "default" : "outline"} aria-pressed={variant === v.value} onClick={() => setVariant(v.value)}>{v.label}</Button>)}
+        <Button type="button" size="sm" variant={plain ? "default" : "outline"} aria-pressed={plain} onClick={() => setPlain(!plain)}>Plain text</Button>
+      </div>
+      {!ready && draft && !draftValid ? <p role="note" className="text-muted-foreground text-sm">The preview appears once the template is valid.</p> : result.error ? (
+        <ApiError error={result.error} title="Could not render the preview" onRetry={() => void result.refetch()} />
+      ) : result.loading && !result.data ? (
+        <Skeleton className="h-56 w-full" aria-label="Rendering the preview" />
+      ) : shown ? (
+        plain ? <pre aria-label="Plain text signature" className="bg-muted max-h-56 overflow-auto whitespace-pre-wrap rounded-md border p-3 text-sm">{shown.plain}</pre> : <SafeSignatureFrame html={shown.html} />
+      ) : null}
+    </div>
+  );
+}