@graph8/sdk 0.370.0 → 0.374.0

package/blocks/documents/components/correspondence-import.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+/**
+ * CorrespondenceImport: bring existing correspondence in, as a batch or as one file.
+ *
+ * SDK operations, in order:
+ *   1. importAccountCorrespondence (POST /accounts/{account_id}/correspondence/import)  write  a JSON array of messages; PARTIAL SUCCESS is normal (the status is 200 even when rows failed), so the imported, skipped and error counts are shown
+ *   2. uploadAccountCorrespondence (POST /accounts/{account_id}/correspondence/upload)  write  one text or .eml file becomes one record (multipart)
+ * A message with an `external_id` that is already stored is SKIPPED, which makes a re-run safe; messages without one are
+ * added again on every import, and the form says how many of those the batch holds. An uploaded file is dated NOW (the API
+ * has no date for it): to date a message when it happened, record it with CorrespondenceForm instead. Files are read as text,
+ * so only text types are offered. Nothing here is billable, external or destructive.
+ */
+
+import { useState } from "react";
+import { Button, Label, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { plural } from "@/g8/lib/plural";
+import { CORRESPONDENCE_CHANNELS, DEFAULT_MAX_BYTES, DIRECTIONS, checkFiles, fileLimit, fmtSize, parseImportItems } from "../lib/documents-types";
+import type { ImportResult, Rec } from "../lib/documents-types";
+
+export interface CorrespondenceImportProps {
+  accountId: number;
+  maxBytes?: number;
+  onImported?: () => void;
+  onDone?: () => void;
+}
+
+const TEXT_TYPES = ["eml", "txt", "md", "csv", "json"] as const;
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+const EXAMPLE = '[{"channel":"email","direction":"inbound","subject":"Re: pricing","content":"Thanks for the call...","correspondence_date":"2026-09-30T14:00:00Z","external_id":"msg-1001"}]';
+
+export function CorrespondenceImport({ accountId, maxBytes = DEFAULT_MAX_BYTES, onImported, onDone }: CorrespondenceImportProps) {
+  const [mode, setMode] = useState<"batch" | "file">("batch");
+  const [text, setText] = useState("");
+  const [file, setFile] = useState<File | null>(null);
+  const [channel, setChannel] = useState("");
+  const [direction, setDirection] = useState("");
+  const [result, setResult] = useState<ImportResult | null>(null);
+  const [saved, setSaved] = useState(false);
+  const base = `/accounts/${encodeURIComponent(String(accountId))}/correspondence`;
+  const parsed = text.trim() ? parseImportItems(text) : null;
+  const noId = parsed && !parsed.problem ? parsed.items.filter((i) => !i.external_id).length : 0;
+  const fileCheck = file ? checkFiles([file], TEXT_TYPES, fileLimit(maxBytes)) : null;
+
+  const importBatch = useG8Mutation(async (items: Rec[]): Promise<ImportResult> => (await g8Post<ImportResult>(`${base}/import`, { items })).data ?? {}, {
+    onSuccess: (r) => { setResult(r); onImported?.(); },
+    invalidates: [["documents", "correspondence"]],
+  });
+  const uploadOne = useG8Mutation(
+    async (): Promise<Rec> => {
+      const form = new FormData();
+      form.append("file", file!);
+      form.append("channel", channel);
+      form.append("direction", direction);
+      return (await g8Post<Rec>(`${base}/upload`, form)).data;
+    },
+    { onSuccess: () => { setSaved(true); setFile(null); onImported?.(); }, invalidates: [["documents", "correspondence"]] },
+  );
+
+  const err = importBatch.error ?? uploadOne.error;
+  return (
+    <div className="grid gap-3">
+      <div role="group" aria-label="How to bring messages in" className="flex gap-1">
+        <Button size="sm" variant={mode === "batch" ? "default" : "outline"} aria-pressed={mode === "batch"} onClick={() => setMode("batch")}>Paste a batch</Button>
+        <Button size="sm" variant={mode === "file" ? "default" : "outline"} aria-pressed={mode === "file"} onClick={() => setMode("file")}>Upload a file</Button>
+      </div>
+      {mode === "batch" ? (
+        <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (parsed && !parsed.problem) void importBatch.mutate(parsed.items); }}>
+          <div>
+            <Label htmlFor="g8-ci-json" className="mb-1">Messages as JSON</Label>
+            <Textarea id="g8-ci-json" rows={10} value={text} onChange={(e) => { setText(e.target.value); setResult(null); }} placeholder={EXAMPLE} className="font-mono text-xs" />
+            <p className="text-muted-foreground mt-1 text-xs">Each message needs channel (email, linkedin or call_notes), direction (inbound or outbound), content and correspondence_date. Add external_id to make a re-run skip what is already there.</p>
+          </div>
+          {parsed?.problem ? <p role="alert" className="text-error text-xs">{parsed.problem}</p> : null}
+          {parsed && !parsed.problem ? <p className="text-xs">{plural(parsed.items.length, "message")} ready.{noId > 0 ? ` ${plural(noId, "message")} ${noId === 1 ? "has" : "have"} no external_id and would be added again if you import this twice.` : ""}</p> : null}
+          {result ? (
+            <div role="status" className="grid gap-1 rounded-md border p-3 text-sm">
+              <p className="font-medium">{result.imported ?? 0} imported, {result.skipped ?? 0} skipped{(result.errors ?? []).length > 0 ? `, ${(result.errors ?? []).length} failed` : ""}.</p>
+              {(result.errors ?? []).map((m) => <p key={m} className="text-error text-xs">{m}</p>)}
+            </div>
+          ) : null}
+          <div className="flex gap-2"><Button type="submit" loading={importBatch.loading} disabled={!parsed || Boolean(parsed.problem)}>Import messages</Button>{onDone ? <Button type="button" variant="outline" onClick={onDone}>Close</Button> : null}</div>
+        </form>
+      ) : (
+        <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (file && fileCheck?.ok.length === 1 && channel && direction) void uploadOne.mutate(undefined); }}>
+          <div>
+            <Label htmlFor="g8-ci-file" className="mb-1">File</Label>
+            <input id="g8-ci-file" type="file" accept={TEXT_TYPES.map((x) => `.${x}`).join(",")} className="border-input bg-background w-full rounded-md border p-2 text-sm" onChange={(e) => { setFile(e.target.files?.[0] ?? null); setSaved(false); }} />
+            <p className="text-muted-foreground mt-1 text-xs">A forwarded .eml or an exported thread, as text ({TEXT_TYPES.join(", ")}), up to {fmtSize(fileLimit(maxBytes))}. It is recorded with today&apos;s date; to date it when it happened, record the message instead.</p>
+          </div>
+          {fileCheck?.problems.length ? <ul role="alert" className="text-error list-disc pl-5 text-xs">{fileCheck.problems.map((p) => <li key={p}>{p}</li>)}</ul> : null}
+          <div className="grid gap-3 sm:grid-cols-2">
+            <div><Label htmlFor="g8-ci-channel" className="mb-1">Channel</Label><select id="g8-ci-channel" className={SELECT} value={channel} onChange={(e) => setChannel(e.target.value)}><option value="">Choose a channel</option>{CORRESPONDENCE_CHANNELS.map((c) => <option key={c.value} value={c.value}>{c.label}</option>)}</select></div>
+            <div><Label htmlFor="g8-ci-direction" className="mb-1">Direction</Label><select id="g8-ci-direction" className={SELECT} value={direction} onChange={(e) => setDirection(e.target.value)}><option value="">Choose a direction</option>{DIRECTIONS.map((d) => <option key={d.value} value={d.value}>{d.label}</option>)}</select></div>
+          </div>
+          {saved ? <p role="status" className="text-sm">The file was recorded.</p> : null}
+          <div className="flex gap-2"><Button type="submit" loading={uploadOne.loading} disabled={!file || fileCheck?.ok.length !== 1 || !channel || !direction}>Record file</Button>{onDone ? <Button type="button" variant="outline" onClick={onDone}>Close</Button> : null}</div>
+        </form>
+      )}
+      {err ? <ApiError error={err} title="Could not bring the messages in" /> : null}
+    </div>
+  );
+}

package/blocks/documents/components/correspondence-panel.tsx

@@ -0,0 +1,191 @@
+"use client";
+
+/**
+ * CorrespondencePanel: what has been said to one account, across channels, as a finished page: the list with a channel and
+ * person filter, the selected message, record one, bring a batch in, delete.
+ *
+ * SDK operations, in order:
+ *   1. listAccountCorrespondence (GET /accounts/{account_id}/correspondence)                    read         newest first, paged 50 at a time with Load more; filtered by channel and person on the server
+ *   2. deleteAccountCorrespondence (DELETE .../correspondence/{correspondence_id})              DESTRUCTIVE  removes the record; documents already generated from it are NOT rewritten; behind ConfirmSpendDialog
+ * Recording one message (CorrespondenceForm) and importing (CorrespondenceImport) are the composed parts. Pass `accountId`
+ * (a company id); without one the panel asks for an account.
+ * URL: `?cid=` the open message, `&view=full` as a page.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Mail, MessagesSquare, Plus, Trash2, Upload } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { LoadMore } from "@/g8/components/paging-notices";
+import { useLoadMoreList } from "@/g8/hooks/use-load-more-list";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { byOffset } from "@/g8/lib/paging";
+import { g8Delete, g8Get } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ContactPicker } from "@/g8/pickers/components/contact-picker";
+import type { ContactOption } from "@/g8/pickers/components/contact-picker";
+import { CORRESPONDENCE_CHANNELS, DEFAULT_MAX_BYTES, rowsOf, totalOf, when } from "../lib/documents-types";
+import type { Correspondence, Rec } from "../lib/documents-types";
+import { CorrespondenceForm } from "./correspondence-form";
+import { CorrespondenceImport } from "./correspondence-import";
+
+export interface CorrespondencePanelProps {
+  accountId: number | null;
+  renderRowActions?: (c: Correspondence) => ReactNode;
+  toolbarActions?: ReactNode;
+  maxBytes?: number;
+}
+
+const PAGE = 50;
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+const label = (list: readonly { value: string; label: string }[], v: string | null | undefined): string => list.find((x) => x.value === v)?.label ?? (v ? v.replace(/_/g, " ") : "");
+const headline = (c: Correspondence): string => c.subject || (c.content ? `${c.content.slice(0, 80)}${c.content.length > 80 ? "..." : ""}` : "No subject");
+
+export function CorrespondencePanel({ accountId, renderRowActions, toolbarActions, maxBytes = DEFAULT_MAX_BYTES }: CorrespondencePanelProps) {
+  const brand = useBrand();
+  const [cid, setCid] = useUrlState("cid", "");
+  const [view, setView] = useUrlState("view", "");
+  const [search, setSearch] = useState("");
+  const [channel, setChannel] = useState("");
+  const [person, setPerson] = useState<ContactOption | null>(null);
+  const [sheet, setSheet] = useState<null | "record" | "import">(null);
+  const [toDelete, setToDelete] = useState<Correspondence | null>(null);
+
+  const list = useLoadMoreList<Correspondence>(
+    byOffset(PAGE, async (offset, signal) => {
+      if (accountId == null) return { rows: [], hasNext: false };
+      const env = await g8Get<Rec>(`/accounts/${encodeURIComponent(String(accountId))}/correspondence`, { channel: channel || undefined, stakeholder_id: person ? String(person.id) : undefined, limit: PAGE, offset }, { signal });
+      const rows = rowsOf<Correspondence>(env.data);
+      const total = totalOf(env.data);
+      return { rows, hasNext: total != null ? offset + rows.length < total : rows.length >= PAGE };
+    }),
+    [accountId, channel, person?.id],
+  );
+
+  const remove = useG8Mutation(
+    (c: Correspondence) => g8Delete(`/accounts/${encodeURIComponent(String(accountId))}/correspondence/${encodeURIComponent(c.id)}`),
+    { onSuccess: (_r, c) => { setToDelete(null); if (c.id === cid) { setCid(null); setView(null); } void list.refetch(); }, invalidates: [["documents", "correspondence"]] },
+  );
+
+  const rows = list.data ?? [];
+  const q = search.trim().toLowerCase();
+  const shown = rows.filter((r) => !q || `${r.subject ?? ""} ${r.content ?? ""}`.toLowerCase().includes(q));
+  const selected = rows.find((r) => r.id === cid) ?? null;
+  const closeDetail = (): void => { setCid(null); setView(null); };
+  const n = (f: (r: Correspondence) => boolean): string => (list.data ? `${rows.filter(f).length.toLocaleString()}${list.hasMore ? "+" : ""}` : "...");
+
+  if (accountId == null) {
+    return <EmptyState icon={<MessagesSquare className="size-8" />} title="Choose an account" description="Pick a company above to see what has been said to it, or to record a message." />;
+  }
+
+  const body = list.error ? <ApiError error={list.error} title="Could not load correspondence" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? (
+    <div aria-busy="true" className="grid gap-2"><Skeleton className="h-14 w-full" /><Skeleton className="h-14 w-full" /></div>
+  ) : shown.length === 0 ? (
+    <EmptyState icon={<Mail className="size-8" />} title={rows.length === 0 && !channel && !person ? "Nothing recorded yet" : "No messages match"} description={rows.length === 0 && !channel && !person ? `Record the emails, LinkedIn messages and call notes that happened off ${brand.name}, so every generated document knows the relationship.` : "Try another search or filter."} action={rows.length === 0 && !channel && !person ? <Button onClick={() => setSheet("record")}>Record a message</Button> : undefined} />
+  ) : (
+    <>
+      <ul className="grid gap-2">
+        {shown.map((r) => (
+          <li key={r.id} className={`flex flex-wrap items-center justify-between gap-2 rounded-md border p-3 ${r.id === cid ? "bg-muted" : ""}`}>
+            <button type="button" className="min-w-0 flex-1 text-left" onClick={() => setCid(r.id)}>
+              <span className="block truncate font-medium">{headline(r)}</span>
+              <span className="text-muted-foreground block truncate text-xs">{label(CORRESPONDENCE_CHANNELS, r.channel) || "-"} · {when(r.correspondence_date) || "-"}</span>
+            </button>
+            {r.direction ? <StatusPill tone={r.direction === "inbound" ? "info" : "neutral"}>{label([{ value: "inbound", label: "Inbound" }, { value: "outbound", label: "Outbound" }], r.direction)}</StatusPill> : null}
+            {renderRowActions?.(r)}
+          </li>
+        ))}
+      </ul>
+      <LoadMore shown={rows.length} noun="messages" hasMore={list.hasMore} loading={list.loadingMore} onLoadMore={list.loadMore} />
+    </>
+  );
+
+  return (
+    <div className="grid gap-4">
+      <StatStrip items={[
+        { label: "Messages", value: list.data ? `${rows.length.toLocaleString()}${list.hasMore ? "+" : ""}` : "..." },
+        { label: "Inbound", value: n((r) => r.direction === "inbound") },
+        { label: "Outbound", value: n((r) => r.direction === "outbound") },
+        { label: "Latest", value: rows[0]?.correspondence_date ? new Date(rows[0].correspondence_date).toLocaleDateString() : "-", hint: "The newest message loaded." },
+      ]} />
+      <SplitView
+        list={(
+          <div className="grid gap-3">
+            <Toolbar
+              search={{ value: search, onChange: setSearch, placeholder: "Search messages" }}
+              filters={(
+                <>
+                  <select aria-label="Filter by channel" className={SELECT} value={channel} onChange={(e) => { setChannel(e.target.value); closeDetail(); }}><option value="">All channels</option>{CORRESPONDENCE_CHANNELS.map((c) => <option key={c.value} value={c.value}>{c.label}</option>)}</select>
+                  <span className="flex items-center gap-1"><ContactPicker label="Person" value={person} onChange={(p) => { setPerson(p); closeDetail(); }} />{person ? <Button size="sm" variant="ghost" onClick={() => { setPerson(null); closeDetail(); }}>Clear person</Button> : null}</span>
+                </>
+              )}
+              actions={<>{toolbarActions}<Button size="sm" variant="outline" onClick={() => setSheet("import")}><Upload className="size-4" />Import</Button><Button size="sm" onClick={() => setSheet("record")}><Plus className="size-4" />Record message</Button></>}
+            />
+            {body}
+          </div>
+        )}
+        detail={selected ? (
+          <DetailPanel
+            key={selected.id}
+            title={headline(selected)}
+            subtitle={`${label(CORRESPONDENCE_CHANNELS, selected.channel)} · ${when(selected.correspondence_date)}`}
+            badges={selected.direction ? <StatusPill tone={selected.direction === "inbound" ? "info" : "neutral"}>{selected.direction === "inbound" ? "Inbound" : "Outbound"}</StatusPill> : undefined}
+            actions={<Button size="sm" variant="outline" onClick={() => setToDelete(selected)}><Trash2 className="size-4" />Delete</Button>}
+            onClose={closeDetail}
+            onExpand={() => setView("full")}
+            onCollapse={view === "full" ? () => setView(null) : undefined}
+            tabs={[
+              { id: "message", label: "Message", content: selected.content ? <pre aria-label="Message text" className="bg-muted max-h-[28rem] overflow-auto whitespace-pre-wrap rounded-md p-3 text-sm">{selected.content}</pre> : <EmptyState compact title="No text" /> },
+              { id: "details", label: "Details", content: (
+                <KeyValueList columns={2} items={[
+                  { label: "Channel", value: label(CORRESPONDENCE_CHANNELS, selected.channel) },
+                  { label: "Direction", value: selected.direction ? (selected.direction === "inbound" ? "Inbound" : "Outbound") : "" },
+                  { label: "Happened", value: when(selected.correspondence_date) },
+                  { label: "Recorded", value: when(selected.created_at) },
+                  { label: "Source", value: selected.source },
+                  { label: "Read by the AI", value: selected.indexed_in_rag == null ? "" : selected.indexed_in_rag ? "Yes" : "Not yet" },
+                  { label: "Person id", value: selected.stakeholder_id, mono: true },
+                  { label: "Your id", value: selected.external_id, mono: true },
+                  { label: "Record id", value: selected.id, mono: true },
+                ]} />
+              ) },
+            ]}
+          />
+        ) : null}
+        detailOpen={Boolean(selected)}
+        onCloseDetail={closeDetail}
+        expanded={view === "full"}
+        onExpandedChange={(e) => setView(e ? "full" : null)}
+        detailWidth="xl"
+      />
+      <FormSheet open={sheet === "record"} onOpenChange={(o) => setSheet(o ? "record" : null)} title="Record a message" description={`An email, LinkedIn message or call note that happened off ${brand.name}.`} width="lg">
+        {sheet === "record" ? <CorrespondenceForm accountId={accountId} stakeholder={person} onCancel={() => setSheet(null)} onSaved={(r) => { setSheet(null); void list.refetch(); setCid(r.id); }} /> : null}
+      </FormSheet>
+      <FormSheet open={sheet === "import"} onOpenChange={(o) => setSheet(o ? "import" : null)} title="Import messages" description="Bring a batch or a file in." width="lg">
+        {sheet === "import" ? <CorrespondenceImport accountId={accountId} maxBytes={maxBytes} onImported={() => void list.refetch()} onDone={() => setSheet(null)} /> : null}
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={toDelete !== null}
+        tier="destructive"
+        title="Delete this message?"
+        affected={1}
+        description={<><p>The record is removed. Documents already generated from it are not rewritten.</p>{remove.error ? <ApiError error={remove.error} title="Could not delete the message" /> : null}</>}
+        confirmLabel="Delete"
+        confirming={remove.loading}
+        onCancel={() => setToDelete(null)}
+        onConfirm={() => { if (toDelete) void remove.mutate(toDelete); }}
+      />
+    </div>
+  );
+}

package/blocks/documents/components/documents-screen.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+/**
+ * DocumentsScreen: the finished documents workspace. No props needed.
+ *
+ * Composes: ScreenLayout (title, tabs), LibraryPanel (the organization's document Library), AccountBar + QuestionnairesPanel
+ * (an account's security questionnaires and their review) and AccountBar + CorrespondencePanel (what has been said to an account).
+ *
+ * Tabs (`?tab=`): Library, Security questionnaires, Correspondence. The two account tabs share one account (`?account=<company id>`),
+ * so a link opens straight to a company's paperwork.
+ *
+ * User flows: browse the Library by folder; search and filter it; open a document to read its text, its facts, download the
+ * original, edit it, read a PDF or Word file's text again, restore a removed one, or delete it (confirmed); make, rename and
+ * delete folders; write a text document; upload one or many files (checked against the Library's types and the proxy's size
+ * limit first). For an account: upload a buyer's questionnaire (confirmed, billable), follow it while it is answered, review every
+ * answer (edit, approve, escalate, mark not applicable, mark wrong, save to the answer library), download the filled workbook,
+ * rename or delete it (confirmed); record a message, import a batch or a file, filter by channel and person, delete (confirmed).
+ *
+ * SDK operations: none directly; every call lives in the composed parts, which confirm each billable and destructive action.
+ */
+
+import { FileText } from "lucide-react";
+import type { ReactNode } from "react";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { DEFAULT_MAX_BYTES } from "../lib/documents-types";
+import type { LibraryDoc } from "../lib/documents-types";
+import { AccountBar } from "./account-bar";
+import { CorrespondencePanel } from "./correspondence-panel";
+import { LibraryPanel } from "./library-panel";
+import { QuestionnairesPanel } from "./questionnaires-panel";
+
+export interface DocumentsScreenProps {
+  renderRowActions?: (doc: LibraryDoc) => ReactNode;
+  renderDetailActions?: (doc: LibraryDoc) => ReactNode;
+  extraDetailTabs?: { id: string; label: string; render: (doc: LibraryDoc) => ReactNode }[];
+  toolbarActions?: ReactNode;
+  /** Largest upload in bytes. Default 5 MiB, the /api/g8 proxy's body limit; raise `maxBodyBytes` in the proxy route first. */
+  maxBytes?: number;
+  className?: string;
+}
+
+type Tab = "library" | "questionnaires" | "correspondence";
+const TABS: Tab[] = ["library", "questionnaires", "correspondence"];
+
+export function DocumentsScreen({ renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions, maxBytes = DEFAULT_MAX_BYTES, className }: DocumentsScreenProps) {
+  const [tabParam, setTabParam] = useUrlState("tab", "library");
+  const [account, setAccount] = useUrlState("account", "");
+  const [, setId] = useUrlState("id", "");
+  const [, setView] = useUrlState("view", "");
+  const [, setQid] = useUrlState("qid", "");
+  const [, setCid] = useUrlState("cid", "");
+  const tab = (TABS.includes(tabParam as Tab) ? tabParam : "library") as Tab;
+  const accountId = account && Number.isInteger(Number(account)) && Number(account) > 0 ? Number(account) : null;
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Documents"
+      description="Your document library, the security questionnaires buyers send, and the correspondence behind each account."
+      icon={<FileText className="size-5" />}
+      tabs={[{ id: "library", label: "Library" }, { id: "questionnaires", label: "Security questionnaires" }, { id: "correspondence", label: "Correspondence" }]}
+      activeTab={tab}
+      onTabChange={(next) => { setTabParam(next === "library" ? null : next); setId(null); setQid(null); setCid(null); setView(null); }}
+    >
+      {tab === "library" ? (
+        <LibraryPanel renderRowActions={renderRowActions} renderDetailActions={renderDetailActions} extraDetailTabs={extraDetailTabs} toolbarActions={toolbarActions} maxBytes={maxBytes} />
+      ) : (
+        <div className="grid gap-4">
+          <AccountBar className="max-w-sm" accountId={accountId} onChange={(id) => { setAccount(String(id)); setQid(null); setCid(null); setView(null); }} />
+          {tab === "questionnaires" ? <QuestionnairesPanel accountId={accountId} toolbarActions={toolbarActions} maxBytes={maxBytes} /> : <CorrespondencePanel accountId={accountId} toolbarActions={toolbarActions} maxBytes={maxBytes} />}
+        </div>
+      )}
+    </ScreenLayout>
+  );
+}

package/blocks/documents/components/library-document-detail.tsx

@@ -0,0 +1,175 @@
+"use client";
+
+/**
+ * LibraryDocumentDetail: one Library document with its text, its facts and every action on it.
+ *
+ * SDK operations, in order:
+ *   1. getLibraryDocument (GET /library/documents/{document_id})                 read         the full record, with its extracted text
+ *   2. downloadLibraryDocument (GET /library/documents/{document_id}/download)  read         the ORIGINAL bytes (not the JSON envelope), saved as a file
+ *   3. updateLibraryDocument, through LibraryDocumentForm                         write        rename, move or change the text
+ *   4. reextractLibraryDocument (POST .../reextract)                             write        read a PDF or DOCX's text again; replaces the stored text, never the file
+ *   5. refreshLibraryDocument (POST .../refresh)                                 write        re-fetch a SCRAPED page (the API may answer that it cannot yet; its message is shown as is)
+ *   6. restoreLibraryDocument (POST .../restore)                                 write        bring back a removed document
+ *   7. deleteLibraryDocument (DELETE .../{document_id})                          DESTRUCTIVE  removes the row AND its bytes for good; behind ConfirmSpendDialog
+ * Only the owner or an admin can delete (the API says 403 otherwise and the reason is shown). Nothing here is billable or external.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Download, FileText, Pencil, RefreshCw, RotateCcw, ScanText, Trash2 } from "lucide-react";
+import { Button, Skeleton } 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 { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { downloadFile } from "../lib/download";
+import { REEXTRACT_TYPES, docName, fmtSize, folderLabel, when } from "../lib/documents-types";
+import type { LibraryDoc, LibraryFolder, Rec } from "../lib/documents-types";
+import { LibraryDocumentForm } from "./library-document-form";
+
+export interface LibraryDocumentDetailProps {
+  doc: LibraryDoc;
+  folders: LibraryFolder[];
+  onClose: () => void;
+  onDeleted?: (doc: LibraryDoc) => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  renderActions?: (doc: LibraryDoc) => ReactNode;
+  extraTabs?: { id: string; label: string; render: (doc: LibraryDoc) => ReactNode }[];
+}
+
+const sourceLabel = (s: string | null | undefined): string => (s ? s.charAt(0).toUpperCase() + s.slice(1) : "");
+
+export function LibraryDocumentDetail({ doc, folders, onClose, onDeleted, onExpand, onCollapse, renderActions, extraTabs }: LibraryDocumentDetailProps) {
+  const [editing, setEditing] = useState(false);
+  const [deleting, setDeleting] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
+  const [downloadError, setDownloadError] = useState<unknown>(undefined);
+  const [downloading, setDownloading] = useState(false);
+
+  const full = useG8Query(
+    (signal) => g8Get<LibraryDoc>(`/library/documents/${encodeURIComponent(doc.id)}`, {}, { signal }).then((r) => r.data),
+    [doc.id],
+    { key: ["documents", "doc", doc.id], placeholderData: doc },
+  );
+  const d = full.data && full.data.id === doc.id ? full.data : doc;
+  const removed = Boolean(d.deleted_at);
+  const type = (d.file_type ?? "").toLowerCase();
+  const canReextract = (REEXTRACT_TYPES as readonly string[]).includes(type) && d.has_file_data === true && !removed;
+
+  const reextract = useG8Mutation(() => g8Post<Rec>(`/library/documents/${encodeURIComponent(doc.id)}/reextract`), {
+    onSuccess: (r) => { const n = (r.data as Rec | null)?.content_length; setNotice(typeof n === "number" ? `Text read again: ${n.toLocaleString()} characters.` : "Text read again."); },
+    invalidates: [["documents"]],
+  });
+  const refresh = useG8Mutation(() => g8Post<Rec>(`/library/documents/${encodeURIComponent(doc.id)}/refresh`), {
+    onSuccess: (r) => { const m = (r.data as Rec | null)?.message; setNotice(typeof m === "string" && m ? m : "Refresh requested."); },
+    invalidates: [["documents"]],
+  });
+  const restore = useG8Mutation(() => g8Post<LibraryDoc>(`/library/documents/${encodeURIComponent(doc.id)}/restore`), { onSuccess: () => setNotice("Document restored."), invalidates: [["documents"]] });
+  const remove = useG8Mutation(() => g8Delete(`/library/documents/${encodeURIComponent(doc.id)}`), {
+    onSuccess: () => { setDeleting(false); onDeleted?.(doc); },
+    invalidates: [["documents"]],
+  });
+
+  const save = async (): Promise<void> => {
+    setDownloading(true);
+    setDownloadError(undefined);
+    try {
+      await downloadFile(`/library/documents/${encodeURIComponent(doc.id)}/download`, d.file_name || docName(d));
+    } catch (err) {
+      setDownloadError(err);
+    } finally {
+      setDownloading(false);
+    }
+  };
+
+  const preview = full.error && !full.data ? <ApiError error={full.error} title="Could not load this document" onRetry={() => void full.refetch()} /> : full.isPlaceholderData ? (
+    <Skeleton className="h-32 w-full" aria-label="Loading text" />
+  ) : d.content ? (
+    <pre aria-label="Document text" className="bg-muted max-h-[28rem] overflow-auto whitespace-pre-wrap rounded-md p-3 text-sm">{d.content}</pre>
+  ) : (
+    <EmptyState compact icon={<FileText className="size-8" />} title="No text to show" description={type === "png" || type === "jpg" || type === "jpeg" ? "Images are stored as files. Download it to see it." : d.has_file_data ? "No text was read from this file. Download the original, or read it again." : "This document has no text."} />
+  );
+
+  const actions = (
+    <>
+      {renderActions?.(d)}
+      {removed ? (
+        <Button size="sm" variant="outline" loading={restore.loading} onClick={() => void restore.mutate(undefined)}><RotateCcw className="size-4" />Restore</Button>
+      ) : (
+        <Button size="sm" variant="outline" disabled={full.isPlaceholderData} onClick={() => setEditing(true)}><Pencil className="size-4" />Edit</Button>
+      )}
+      <Button size="sm" variant="outline" loading={downloading} onClick={() => void save()}><Download className="size-4" />Download</Button>
+      {canReextract ? <Button size="sm" variant="outline" loading={reextract.loading} onClick={() => void reextract.mutate(undefined)}><ScanText className="size-4" />Read text again</Button> : null}
+      {d.source === "scrape" && !removed ? <Button size="sm" variant="outline" loading={refresh.loading} onClick={() => void refresh.mutate(undefined)}><RefreshCw className="size-4" />Refresh from source</Button> : null}
+      <Button size="sm" variant="outline" onClick={() => setDeleting(true)}><Trash2 className="size-4" />Delete</Button>
+    </>
+  );
+
+  return (
+    <>
+      <DetailPanel
+        title={docName(d)}
+        subtitle={`${folderLabel(d.folder_path)}${d.file_name && d.file_name !== d.display_name ? ` · ${d.file_name}` : ""}`}
+        badges={<>{type ? <StatusPill tone="info">{type.toUpperCase()}</StatusPill> : null}{removed ? <StatusPill tone="warning">Removed</StatusPill> : null}</>}
+        actions={actions}
+        onClose={onClose}
+        onExpand={onExpand}
+        onCollapse={onCollapse}
+        summary={notice || reextract.error || refresh.error || restore.error || downloadError ? (
+          <div className="grid gap-2 px-4 pt-3">
+            {notice ? <p role="status" className="text-sm">{notice}</p> : null}
+            {reextract.error ? <ApiError error={reextract.error} title="Could not read the text again" compact /> : null}
+            {refresh.error ? <ApiError error={refresh.error} title="Could not refresh the document" compact /> : null}
+            {restore.error ? <ApiError error={restore.error} title="Could not restore the document" compact /> : null}
+            {downloadError ? <ApiError error={downloadError} title="Could not download the file" compact /> : null}
+          </div>
+        ) : undefined}
+        tabs={[
+          { id: "text", label: "Text", content: preview },
+          {
+            id: "details",
+            label: "Details",
+            content: (
+              <KeyValueList columns={2} items={[
+                { label: "Title", value: d.display_name },
+                { label: "File name", value: d.file_name },
+                { label: "Type", value: type ? type.toUpperCase() : "" },
+                { label: "Folder", value: folderLabel(d.folder_path) },
+                { label: "Size", value: fmtSize(d.file_size_bytes) },
+                { label: "Source", value: sourceLabel(d.source) },
+                { label: "Added by", value: d.owner_name },
+                { label: "Added", value: when(d.created_at) },
+                { label: "Updated", value: when(d.updated_at) },
+                { label: "Searchable by the AI", value: d.indexed_at ? `Since ${when(d.indexed_at)}` : "Not yet" },
+                { label: "Version", value: d.current_version != null ? String(d.current_version) : "" },
+                { label: "Document id", value: d.id, mono: true },
+              ]} />
+            ),
+          },
+          ...(extraTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(d) })),
+        ]}
+      />
+      <FormSheet open={editing} onOpenChange={setEditing} title="Edit document" description="Only what you change is saved." width="lg">
+        {editing ? <LibraryDocumentForm document={doc} folders={folders} onCancel={() => setEditing(false)} onSaved={() => { setEditing(false); setNotice("Saved."); }} /> : null}
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={deleting}
+        tier="destructive"
+        title={`Delete ${docName(d)}?`}
+        affected={1}
+        description={<><p>The document and its stored file are removed for good. It cannot be restored. Only its owner or an admin can delete it.</p>{remove.error ? <ApiError error={remove.error} title="Could not delete the document" /> : null}</>}
+        confirmLabel="Delete"
+        confirming={remove.loading}
+        onCancel={() => setDeleting(false)}
+        onConfirm={() => void remove.mutate(undefined)}
+      />
+    </>
+  );
+}