@graph8/sdk 0.370.0 → 0.374.0

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

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

@@ -0,0 +1,77 @@
+"use client";
+
+/**
+ * SignatureReport: signature and campaign engagement: how many impressions and clicks each mailbox and each campaign got.
+ *
+ * SDK operations:
+ *   1. getSignatureReport (GET /signatures/reports)   read   counts by event kind, mailbox, campaign and source, plus the limits of the numbers
+ * Mailbox and campaign names come from the shared hooks. The numbers are only what the API can see: it says when click
+ * tracking is not configured, and lists its own limitations (for example that a natively installed signature reports no
+ * impressions); the screen shows them instead of presenting a zero as a measurement. Events are kept for the number of days
+ * the report states.
+ */
+
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { humanizeStatus as humanize } from "@/g8/components/screen/status-pill";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useSignatureCampaigns, useSignatureMailboxes } from "../hooks/use-signatures-data";
+import type { ReportMetric, SignatureReport as Report } from "../lib/signatures-types";
+
+function totals(metrics: ReportMetric[], by: (m: ReportMetric) => string): [string, Map<string, number>][] {
+  const out = new Map<string, Map<string, number>>();
+  for (const m of metrics) {
+    const key = by(m);
+    const row = out.get(key) ?? new Map<string, number>();
+    row.set(m.kind, (row.get(m.kind) ?? 0) + m.count);
+    out.set(key, row);
+  }
+  return [...out].sort((a, b) => a[0].localeCompare(b[0]));
+}
+
+export function SignatureReport() {
+  const report = useG8Query((signal) => g8Get<Report>("/signatures/reports", {}, { signal }).then((r) => r.data), [], { key: ["signatures", "report"] });
+  const box = useSignatureMailboxes();
+  const campaigns = useSignatureCampaigns();
+  if (report.error && !report.data) return <ApiError error={report.error} title="Could not load the report" onRetry={() => void report.refetch()} />;
+  if (!report.data) return <Skeleton className="h-40 w-full" aria-label="Loading the report" />;
+
+  const r = report.data;
+  const metrics = r.metrics ?? [];
+  const kinds = [...new Set(metrics.map((m) => m.kind))].sort();
+  const email = (id: number | null | undefined): string => (id == null ? "No mailbox" : box.mailboxes.find((m) => m.id === id)?.email || "A mailbox that is no longer listed");
+  const campaign = (id: string | null | undefined): string => (id ? campaigns.data?.find((c) => c.id === id)?.data.name || "A campaign that is no longer listed" : "No campaign");
+  const byMailbox = totals(metrics, (m) => email(m.mailbox_id));
+  const byCampaign = totals(metrics.filter((m) => m.campaign_id), (m) => campaign(m.campaign_id));
+  const grid = (rows: [string, Map<string, number>][], first: string) => (
+    <table className="w-full text-sm">
+      <thead><tr className="text-muted-foreground text-left text-xs"><th className="py-1 font-normal">{first}</th>{kinds.map((k) => <th key={k} className="py-1 text-right font-normal">{humanize(k)}</th>)}</tr></thead>
+      <tbody>{rows.map(([name, counts]) => <tr key={name} className="border-t"><td className="py-1.5">{name}</td>{kinds.map((k) => <td key={k} className="py-1.5 text-right tabular-nums">{(counts.get(k) ?? 0).toLocaleString()}</td>)}</tr>)}</tbody>
+    </table>
+  );
+
+  return (
+    <div className="grid gap-4">
+      {!r.tracking_available ? <p role="note" className="rounded-md border p-3 text-sm">Click tracking is not set up for this workspace, so clicks are not counted. Impressions that the API can see still are.</p> : null}
+      {metrics.length === 0 ? (
+        <EmptyState title="No signature activity yet" description={`Impressions and clicks appear once managed signatures go out. Events are kept for ${r.retention_days ?? "a limited number of"} days.`} />
+      ) : (
+        <>
+          <StatStrip items={kinds.map((k) => ({ label: humanize(k), value: metrics.filter((m) => m.kind === k).reduce((n, m) => n + m.count, 0).toLocaleString() }))} />
+          <SectionCard title="By mailbox">{grid(byMailbox, "Mailbox")}</SectionCard>
+          {byCampaign.length > 0 ? <SectionCard title="By campaign">{grid(byCampaign, "Campaign")}</SectionCard> : null}
+        </>
+      )}
+      {(r.limitations ?? []).length > 0 ? (
+        <SectionCard title="How to read these numbers">
+          <ul className="text-muted-foreground list-disc space-y-1 pl-5 text-sm">{(r.limitations ?? []).map((l) => <li key={l}>{l}</li>)}</ul>
+          {r.retention_days ? <p className="text-muted-foreground mt-2 text-xs">Events are kept for {r.retention_days} days.</p> : null}
+        </SectionCard>
+      ) : null}
+    </div>
+  );
+}