@graph8/sdk 0.373.0 → 0.374.0

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

@@ -0,0 +1,95 @@
+"use client";
+
+/**
+ * CorrespondenceForm: record ONE message, call or note against an account.
+ *
+ * SDK operations, in order:
+ *   1. listContacts, through ContactPicker                                          read   find the person at the account (optional)
+ *   2. createAccountCorrespondence (POST /accounts/{account_id}/correspondence)     write  stores the record and indexes it so generated documents can read it
+ * `correspondence_date` is when it HAPPENED, not when it was recorded: generated documents read it as the relationship's
+ * timeline, so it is required and sent as the exact moment (never as a date alone). Channel and direction have no default:
+ * a wrong guess would put the message on the wrong side of the timeline. Nothing here is billable, external or destructive.
+ */
+
+import { useState } from "react";
+import { Button, Input, 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 { ContactPicker } from "@/g8/pickers/components/contact-picker";
+import type { ContactOption } from "@/g8/pickers/components/contact-picker";
+import { CORRESPONDENCE_CHANNELS, DIRECTIONS } from "../lib/documents-types";
+import type { Correspondence } from "../lib/documents-types";
+
+export interface CorrespondenceFormProps {
+  accountId: number;
+  /** Pre-select the person (for example from a contact page). */
+  stakeholder?: ContactOption | null;
+  onSaved: (record: Correspondence) => void;
+  onCancel?: () => void;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+
+export function CorrespondenceForm({ accountId, stakeholder, onSaved, onCancel }: CorrespondenceFormProps) {
+  const [channel, setChannel] = useState("");
+  const [direction, setDirection] = useState("");
+  const [when, setWhen] = useState("");
+  const [subject, setSubject] = useState("");
+  const [content, setContent] = useState("");
+  const [person, setPerson] = useState<ContactOption | null>(stakeholder ?? null);
+  const [externalId, setExternalId] = useState("");
+  const date = when ? new Date(when) : null;
+  const valid = channel !== "" && direction !== "" && content.trim() !== "" && date !== null && !Number.isNaN(date.getTime());
+
+  const save = useG8Mutation(
+    async (): Promise<Correspondence> => {
+      const body: Record<string, unknown> = { channel, direction, content: content.trim(), correspondence_date: date!.toISOString() };
+      if (subject.trim()) body.subject = subject.trim();
+      if (person) body.stakeholder_id = String(person.id);
+      if (externalId.trim()) body.external_id = externalId.trim();
+      return (await g8Post<Correspondence>(`/accounts/${encodeURIComponent(String(accountId))}/correspondence`, body)).data;
+    },
+    { onSuccess: onSaved, invalidates: [["documents", "correspondence"]] },
+  );
+
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (valid) void save.mutate(undefined); }}>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div>
+          <Label htmlFor="g8-dc-channel" className="mb-1">Channel</Label>
+          <select id="g8-dc-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-dc-direction" className="mb-1">Direction</Label>
+          <select id="g8-dc-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>
+      <div>
+        <Label htmlFor="g8-dc-when" className="mb-1">When it happened</Label>
+        <Input id="g8-dc-when" type="datetime-local" value={when} onChange={(e) => setWhen(e.target.value)} />
+      </div>
+      <div><Label htmlFor="g8-dc-subject" className="mb-1">Subject (optional)</Label><Input id="g8-dc-subject" value={subject} onChange={(e) => setSubject(e.target.value)} /></div>
+      <div><Label htmlFor="g8-dc-content" className="mb-1">What was said</Label><Textarea id="g8-dc-content" rows={8} value={content} onChange={(e) => setContent(e.target.value)} /></div>
+      <div>
+        <Label htmlFor="g8-dc-person" className="mb-1">Person at the account (optional)</Label>
+        <div className="flex items-center gap-2">
+          <ContactPicker id="g8-dc-person" label="Person" value={person} onChange={setPerson} />
+          {person ? <Button type="button" variant="ghost" size="sm" onClick={() => setPerson(null)}>Clear</Button> : null}
+        </div>
+      </div>
+      <div><Label htmlFor="g8-dc-ext" className="mb-1">Your id for it (optional)</Label><Input id="g8-dc-ext" value={externalId} onChange={(e) => setExternalId(e.target.value)} /></div>
+      {save.error ? <ApiError error={save.error} title="Could not record the message" /> : null}
+      <div className="flex gap-2">
+        <Button type="submit" loading={save.loading} disabled={!valid}>Record message</Button>
+        {onCancel ? <Button type="button" variant="outline" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+    </form>
+  );
+}

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