@graph8/sdk 0.373.0 → 0.374.0

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

package/blocks/email-signatures/components/signature-template-details.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+/**
+ * SignatureTemplateDetails: one template's facts and its two consequential actions: make it the organisation default,
+ * and archive it.
+ *
+ * SDK operations, in order (policy, member and mailbox reads come from the shared hooks):
+ *   1. setDefaultSignatureTemplate (POST /signatures/templates/{template_id}/set-default)   write       sends the POLICY version (not the template's);
+ *      it changes the signature of every mailbox that follows the organisation default, so ConfirmSpendDialog (external) first, sized from those mailboxes.
+ *   2. archiveSignatureTemplate (DELETE /signatures/templates/{template_id}?version)         destructive hides the template from the library; ConfirmSpendDialog (destructive) first.
+ *      The API refuses (409) while the template is the default, a department default or assigned to a mailbox, so the button
+ *      is disabled with that reason when the screen can already see it; already-installed signatures are untouched.
+ * Both send the version that was read, and a stale one answers 409 (shown, with the lists refreshed).
+ */
+
+import { useState } from "react";
+import { Archive, Star } from "lucide-react";
+import { Button } 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 { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Delete, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { plural } from "@/g8/lib/plural";
+import { useSignatureDeployments, useSignatureMembers, useSignaturePolicy } from "../hooks/use-signatures-data";
+import { BLOCK_KINDS, BRAND_SOURCES, LAYOUTS, isConflict, isManaged, templateName } from "../lib/signatures-types";
+import type { SignatureTemplate } from "../lib/signatures-types";
+
+export interface SignatureTemplateDetailsProps {
+  template: SignatureTemplate;
+  /** Called after the template was archived, so the screen can close it. */
+  onArchived?: () => void;
+}
+
+export function SignatureTemplateDetails({ template, onArchived }: SignatureTemplateDetailsProps) {
+  const policy = useSignaturePolicy();
+  const members = useSignatureMembers();
+  const deployments = useSignatureDeployments();
+  const [dialog, setDialog] = useState<"default" | "archive" | null>(null);
+  const name = templateName(template);
+  const settings = policy.data?.data;
+  const isDefault = settings?.default_template_id === template.id;
+  const departments = Object.entries(settings?.department_templates ?? {}).filter(([, id]) => id === template.id).map(([d]) => d);
+  const rows = (deployments.data ?? []).filter((d) => isManaged(d));
+  const assignedTo = rows.filter((d) => d.assignment?.template_id === template.id).length;
+  const followsDefault = rows.filter((d) => {
+    if (d.assignment?.template_id) return false;
+    const dept = members.data?.find((m) => m.id === d.assignment?.member_id)?.department;
+    return !(dept && settings?.department_templates?.[dept]);
+  }).length;
+  const blockedBy = isDefault ? "It is the organisation default." : departments.length > 0 ? `It is the default for ${departments.join(", ")}.` : assignedTo > 0 ? `${plural(assignedTo, "mailbox")} use it.` : "";
+
+  const setDefault = useG8Mutation(async (): Promise<unknown> => (await g8Post(`/signatures/templates/${encodeURIComponent(template.id)}/set-default`, { version: policy.data?.version ?? 0 })).data, {
+    onSuccess: () => setDialog(null),
+    onError: () => { setDialog(null); if (policy.data) void policy.refetch(); },
+    invalidates: [["signatures", "policy"], ["signatures", "deployments"]],
+  });
+  const archive = useG8Mutation(async (): Promise<unknown> => (await g8Delete(`/signatures/templates/${encodeURIComponent(template.id)}`, { query: { version: template.version } })).data, {
+    onSuccess: () => { setDialog(null); onArchived?.(); },
+    onError: () => setDialog(null),
+    invalidates: [["signatures", "templates"], ["signatures", "template", template.id]],
+  });
+
+  return (
+    <div className="grid gap-4">
+      <KeyValueList columns={2} items={[
+        { label: "Name", value: name },
+        { label: "Layout", value: LAYOUTS.find((l) => l.value === template.data.layout)?.label ?? "" },
+        { label: "Font", value: template.data.font ?? "" },
+        { label: "Text colour", value: template.data.primary_color ?? "", mono: true },
+        { label: "Colour and font", value: BRAND_SOURCES.find((b) => b.value === template.data.brand_source)?.label ?? "", wide: true },
+        { label: "Blocks", value: (template.data.blocks ?? []).map((b) => BLOCK_KINDS.find((k) => k.value === b.kind)?.label ?? b.kind).join(", "), wide: true },
+        { label: "Version", value: String(template.version) },
+        { label: "Used by", value: `${plural(assignedTo, "mailbox")} directly` },
+      ]} />
+      <div className="flex flex-wrap items-center gap-2">
+        {isDefault ? <StatusPill tone="positive">Organisation default</StatusPill> : null}
+        {departments.map((d) => <StatusPill key={d} tone="info">Default for {d}</StatusPill>)}
+      </div>
+      {setDefault.error ? (isConflict(setDefault.error) ? <ApiError error={setDefault.error} title="The policy changed since you opened it. It was refreshed: try again" /> : <ApiError error={setDefault.error} title="Could not set the default" />) : null}
+      {archive.error ? (isConflict(archive.error) ? <ApiError error={archive.error} title="This template cannot be archived right now" /> : <ApiError error={archive.error} title="Could not archive the template" />) : null}
+      <div className="flex flex-wrap gap-2">
+        <Button type="button" variant="outline" disabled={isDefault || !policy.data} onClick={() => setDialog("default")}><Star className="size-4" />{isDefault ? "Already the default" : "Make organisation default"}</Button>
+        <Button type="button" variant="outline" disabled={blockedBy !== ""} onClick={() => setDialog("archive")}><Archive className="size-4" />Archive</Button>
+      </div>
+      {blockedBy ? <p className="text-muted-foreground text-xs">Archive is unavailable: {blockedBy} Give those mailboxes another template first.</p> : null}
+      <ConfirmSpendDialog
+        open={dialog === "default"}
+        tier="external"
+        title={`Make ${name} the organisation default?`}
+        affected={followsDefault}
+        description={<p>{plural(followsDefault, "mailbox")} that follow the organisation default will send this signature. Mailboxes with their own template, or a department default, are not changed.</p>}
+        confirmLabel="Make default"
+        confirming={setDefault.loading}
+        onCancel={() => setDialog(null)}
+        onConfirm={() => void setDefault.mutate(undefined)}
+      />
+      <ConfirmSpendDialog
+        open={dialog === "archive"}
+        tier="destructive"
+        title={`Archive ${name}?`}
+        affected={1}
+        description="The template leaves the library. Signatures already installed from it are not changed."
+        confirmLabel="Archive"
+        confirming={archive.loading}
+        onCancel={() => setDialog(null)}
+        onConfirm={() => void archive.mutate(undefined)}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,109 @@
+"use client";
+
+/**
+ * SignatureTemplateForm: create a signature template or edit one, with a live preview of the draft.
+ *
+ * SDK operations, in order:
+ *   1. getSignatureTemplate (GET /signatures/templates/{template_id})   read    edit only: the FULL record is read before the form shows
+ *   2. createSignatureTemplate (POST /signatures/templates)            write   a template library entry; nothing reaches a mailbox until it is assigned
+ *   3. updateSignatureTemplate (PATCH /signatures/templates/{template_id}) write REPLACES the template with the draft and sends the version that was read
+ * The update replaces the whole template, so the draft is built from the loaded record (known keys only, because the API
+ * refuses any other) and a field the person clears is sent empty. A save with no change sends nothing. A 409 means someone else
+ * saved first: the person reloads and edits the newer version. After a save the template list and the template's own cache
+ * entry are refreshed, so reopening the form shows what was saved. The live preview (TemplatePreview) only renders.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useSignatureTemplate } from "../hooks/use-signatures-data";
+import { BRAND_SOURCES, FONTS, LAYOUTS, blankTemplate, draftFromTemplate, isConflict, sameTemplate, templateProblems } from "../lib/signatures-types";
+import type { BrandSource, SignatureFont, SignatureLayout, SignatureTemplate, TemplateData } from "../lib/signatures-types";
+import { SignatureBlockEditor } from "./signature-block-editor";
+import { TemplatePreview } from "./signature-preview";
+
+export interface SignatureTemplateFormProps {
+  /** Edit this template; omit to create a new one. */
+  template?: SignatureTemplate;
+  onSaved: (template: SignatureTemplate) => void;
+  onCancel?: () => void;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm disabled:opacity-50";
+
+/** Edit mode reads the full template first: saving a form seeded from a list row or a half-loaded record would overwrite real values. */
+export function SignatureTemplateForm({ template, onSaved, onCancel }: SignatureTemplateFormProps) {
+  const full = useSignatureTemplate(template?.id);
+  if (!template) return <TemplateFields onSaved={onSaved} onCancel={onCancel} />;
+  if (full.error && !full.data) return <ApiError error={full.error} title="Could not load this template" onRetry={() => void full.refetch()} />;
+  if (!full.data || full.data.id !== template.id) return <Skeleton className="h-40 w-full" aria-label="Loading template" />;
+  return <TemplateFields key={`${full.data.id}:${full.data.version}`} template={full.data} onSaved={onSaved} onCancel={onCancel} onReload={() => void full.refetch()} />;
+}
+
+function TemplateFields({ template, onSaved, onCancel, onReload }: SignatureTemplateFormProps & { onReload?: () => void }) {
+  const original = template ? draftFromTemplate(template) : blankTemplate();
+  const [draft, setDraft] = useState<TemplateData>(original);
+  const problems = templateProblems(draft);
+  const changed = !sameTemplate(draft, original);
+  const set = (change: Partial<TemplateData>): void => setDraft({ ...draft, ...change });
+
+  const save = useG8Mutation(async (): Promise<SignatureTemplate> => {
+    if (template) {
+      if (!changed) return template;
+      return (await g8Patch<SignatureTemplate>(`/signatures/templates/${encodeURIComponent(template.id)}`, { version: template.version, data: draft })).data;
+    }
+    return (await g8Post<SignatureTemplate>("/signatures/templates", { data: draft })).data;
+  }, { onSuccess: onSaved, invalidates: (saved) => [["signatures", "templates"], ["signatures", "template", saved.id]] });
+
+  return (
+    <form className="grid gap-4" onSubmit={(e) => { e.preventDefault(); if (problems.length === 0) void save.mutate(undefined); }}>
+      <div><Label htmlFor="g8-sig-name" className="mb-1">Template name</Label><Input id="g8-sig-name" value={draft.name} placeholder="Sales team" onChange={(e) => set({ name: e.target.value })} /></div>
+      <div className="grid gap-3 sm:grid-cols-3">
+        <div>
+          <Label htmlFor="g8-sig-layout" className="mb-1">Layout</Label>
+          <select id="g8-sig-layout" className={SELECT} value={draft.layout} onChange={(e) => set({ layout: e.target.value as SignatureLayout })}>
+            {LAYOUTS.map((l) => <option key={l.value} value={l.value}>{l.label}</option>)}
+          </select>
+        </div>
+        <div>
+          <Label htmlFor="g8-sig-font" className="mb-1">Font</Label>
+          <select id="g8-sig-font" className={SELECT} value={draft.font} onChange={(e) => set({ font: e.target.value as SignatureFont })}>
+            {FONTS.map((f) => <option key={f} value={f}>{f}</option>)}
+          </select>
+        </div>
+        <div>
+          <Label htmlFor="g8-sig-color" className="mb-1">Text colour</Label>
+          <input id="g8-sig-color" type="color" className="border-input h-9 w-full cursor-pointer rounded-md border bg-transparent p-1" value={draft.primary_color} onChange={(e) => set({ primary_color: e.target.value })} />
+        </div>
+      </div>
+      <div>
+        <Label htmlFor="g8-sig-brand" className="mb-1">Colour and font source</Label>
+        <select id="g8-sig-brand" className={SELECT} value={draft.brand_source} onChange={(e) => set({ brand_source: e.target.value as BrandSource })}>
+          {BRAND_SOURCES.map((b) => <option key={b.value} value={b.value}>{b.label}</option>)}
+        </select>
+      </div>
+      <section aria-label="Blocks" className="grid gap-2">
+        <h3 className="text-sm font-medium">Blocks</h3>
+        <p className="text-muted-foreground text-xs">Placeholders such as {"{{member.name}}"} are filled from each employee. Add a fallback after a bar, {"{{member.title|Team}}"}, so a missing value never fails the signature.</p>
+        <SignatureBlockEditor blocks={draft.blocks} onChange={(blocks) => set({ blocks })} />
+      </section>
+      <section aria-label="Preview" className="grid gap-2">
+        <h3 className="text-sm font-medium">Preview</h3>
+        <TemplatePreview draft={draft} draftValid={problems.length === 0} />
+      </section>
+      {problems.length > 0 ? <ul role="alert" className="text-error list-disc pl-5 text-xs">{problems.map((p) => <li key={p}>{p}</li>)}</ul> : null}
+      {save.error && isConflict(save.error) ? (
+        <div className="grid gap-2">
+          <ApiError error={save.error} title="Someone else changed this template" />
+          {onReload ? <div><Button type="button" variant="outline" size="sm" onClick={onReload}>Load the newer version</Button></div> : null}
+        </div>
+      ) : save.error ? <ApiError error={save.error} title="Could not save the template" /> : null}
+      <div className="flex gap-2">
+        <Button type="submit" loading={save.loading} disabled={problems.length > 0 || (Boolean(template) && !changed)}>{template ? "Save changes" : "Create template"}</Button>
+        {onCancel ? <Button type="button" variant="outline" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+    </form>
+  );
+}

package/blocks/email-signatures/hooks/use-signatures-data.ts

@@ -0,0 +1,93 @@
+"use client";
+
+/**
+ * Shared reads for the email-signatures block. Every screen part asks through these hooks, so one request serves them all
+ * (the cache key names the input) and a write refreshes every part that shows the record by invalidating the same key.
+ *
+ * SDK operations, all reads:
+ *   listSignatureTemplates   GET /signatures/templates     every template; the API does not page it, so the UI says "All N"
+ *   getSignatureTemplate     GET /signatures/templates/{template_id}   the FULL record an edit form is seeded from
+ *   listSignatureMembers     GET /signatures/members       the directory employees a signature can be assigned to
+ *   listSignatureDeployments GET /signatures/mailboxes    each mailbox's assignment, status and revision
+ *   getSignatureSettings     GET /signatures/settings      the policy and the version a policy write must send back
+ *   listSignatureCampaigns   GET /signatures/campaigns     banner campaigns and the revision to edit one
+ *   listMailboxes            GET /mailboxes?limit=500      the mailboxes a signature can be assigned to (the API caps one read at 500)
+ *
+ * The signature lists take no paging parameters and return everything. The mailbox list is read once with the API's
+ * largest limit: a screen that renders it must show the foundation FirstNotice ("Showing the first 500 mailboxes") when
+ * `truncated` is true, so a long list never ends silently.
+ */
+
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { mergeMailboxes } from "../lib/signatures-types";
+import type { Deployment, MailboxRecord, SignatureCampaign, SignatureMailbox, SignatureMember, SignaturePolicy, SignatureTemplate } from "../lib/signatures-types";
+
+export const MAILBOX_LIMIT = 500;
+
+function rows<T>(envelope: { data?: unknown } | null | undefined): T[] {
+  const data = envelope?.data;
+  if (Array.isArray(data)) return data as T[];
+  const items = (data as { items?: unknown } | null | undefined)?.items;
+  return Array.isArray(items) ? (items as T[]) : [];
+}
+
+export function useSignatureTemplates() {
+  return useG8Query((signal) => g8Get("/signatures/templates", {}, { signal }).then((r) => rows<SignatureTemplate>(r)), [], { key: ["signatures", "templates"] });
+}
+
+/** The full template. `enabled` false holds the read until an id is known. */
+export function useSignatureTemplate(id: string | undefined) {
+  return useG8Query(
+    (signal) => g8Get<SignatureTemplate>(`/signatures/templates/${encodeURIComponent(id ?? "")}`, {}, { signal }).then((r) => r.data),
+    [id],
+    { enabled: Boolean(id), key: ["signatures", "template", id ?? ""] },
+  );
+}
+
+export function useSignatureMembers() {
+  return useG8Query((signal) => g8Get("/signatures/members", {}, { signal }).then((r) => rows<SignatureMember>(r)), [], { key: ["signatures", "members"] });
+}
+
+export function useSignatureDeployments() {
+  return useG8Query((signal) => g8Get("/signatures/mailboxes", {}, { signal }).then((r) => rows<Deployment>(r)), [], { key: ["signatures", "deployments"] });
+}
+
+export function useSignaturePolicy() {
+  return useG8Query((signal) => g8Get<SignaturePolicy>("/signatures/settings", {}, { signal }).then((r) => r.data), [], { key: ["signatures", "policy"] });
+}
+
+export function useSignatureCampaigns() {
+  return useG8Query((signal) => g8Get("/signatures/campaigns", {}, { signal }).then((r) => rows<SignatureCampaign>(r)), [], { key: ["signatures", "campaigns"] });
+}
+
+export interface SignatureMailboxes {
+  mailboxes: SignatureMailbox[];
+  loading: boolean;
+  /** Set when the deployments read failed (nothing can be shown). */
+  error: unknown;
+  /** Set when only the mailbox list failed (for example a key without mailbox access): mailboxes that already have a signature still show. */
+  mailboxesError: unknown;
+  /** The mailbox read came back full (500): there may be more mailboxes than are listed. */
+  truncated: boolean;
+  refetch: () => void;
+}
+
+/** Every mailbox with its signature deployment: the list of mailboxes, merged with the deployments by mailbox id. */
+export function useSignatureMailboxes(): SignatureMailboxes {
+  const deployments = useSignatureDeployments();
+  const list = useG8Query(
+    (signal) => g8Get("/mailboxes", { limit: MAILBOX_LIMIT }, { signal }).then((r) => rows<MailboxRecord>(r)),
+    [],
+    { key: ["signatures", "mailbox-list"] },
+  );
+  const records = list.data ?? [];
+  return {
+    mailboxes: mergeMailboxes(records, deployments.data ?? []),
+    loading: (deployments.loading && !deployments.data) || (list.loading && !list.data && !list.error),
+    error: deployments.error && !deployments.data ? deployments.error : undefined,
+    mailboxesError: list.error && !list.data ? list.error : undefined,
+    truncated: records.length >= MAILBOX_LIMIT,
+    refetch: () => { void deployments.refetch(); void list.refetch(); },
+  };
+}