@graph8/sdk 0.373.0 → 0.374.0

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

@@ -0,0 +1,173 @@
+"use client";
+
+/**
+ * QuestionnairesPanel: an account's security questionnaires as a finished page: the list, upload a new one, and the
+ * selected questionnaire's review (QuestionnaireDetail).
+ *
+ * SDK operations, in order:
+ *   1. listSecurityQuestionnaires (GET /accounts/{account_id}/security-questionnaires)  read     the account's questionnaires, newest first, paged 50 at a time with Load more
+ *   2. uploadSecurityQuestionnaire (POST /accounts/{account_id}/security-questionnaires) BILLABLE  uploads an XLSX or PDF and starts answering it in the background; behind ConfirmSpendDialog
+ * Everything on one questionnaire (read, progress, review actions, workbook download, rename, delete) is QuestionnaireDetail.
+ * Answering uses credits, but the API publishes no price for it, so the confirmation names the file and says so instead of
+ * showing a made-up estimate. Pass `accountId` (a company id); without one the panel asks for an account.
+ * URL: `?qid=` the open questionnaire, `&view=full` as a page.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { FileSpreadsheet, Upload } from "lucide-react";
+import { Button, Label, 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 { FormSheet } from "@/g8/components/screen/form-sheet";
+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 { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { plural } from "@/g8/lib/plural";
+import { DEFAULT_MAX_BYTES, QUESTIONNAIRE_EXTENSIONS, QUESTIONNAIRE_STATUS, checkFiles, fileLimit, fmtSize, rowsOf, statusInfo, totalOf, when } from "../lib/documents-types";
+import type { Questionnaire, Rec } from "../lib/documents-types";
+import { QuestionnaireDetail } from "./questionnaire-detail";
+
+export interface QuestionnairesPanelProps {
+  /** The account (company id) whose questionnaires to show. */
+  accountId: number | null;
+  renderRowActions?: (q: Questionnaire) => ReactNode;
+  toolbarActions?: ReactNode;
+  /** Largest upload in bytes. Default 5 MiB, the /api/g8 proxy's body limit. */
+  maxBytes?: number;
+}
+
+const PAGE = 50;
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+const nameOf = (q: Questionnaire): string => q.display_name || q.original_file_name || "Untitled questionnaire";
+
+export function QuestionnairesPanel({ accountId, renderRowActions, toolbarActions, maxBytes = DEFAULT_MAX_BYTES }: QuestionnairesPanelProps) {
+  const brand = useBrand();
+  const [qid, setQid] = useUrlState("qid", "");
+  const [view, setView] = useUrlState("view", "");
+  const [search, setSearch] = useState("");
+  const [status, setStatus] = useState("");
+  const [uploading, setUploading] = useState(false);
+  const [file, setFile] = useState<File | null>(null);
+  const [problems, setProblems] = useState<string[]>([]);
+  const [confirming, setConfirming] = useState(false);
+
+  const list = useLoadMoreList<Questionnaire>(
+    byOffset(PAGE, async (offset, signal) => {
+      if (accountId == null) return { rows: [], hasNext: false };
+      const env = await g8Get<Rec>(`/accounts/${encodeURIComponent(String(accountId))}/security-questionnaires`, { status: status || undefined, limit: PAGE, offset }, { signal });
+      const rows = rowsOf<Questionnaire>(env.data);
+      const total = totalOf(env.data);
+      return { rows, hasNext: total != null ? offset + rows.length < total : rows.length >= PAGE };
+    }),
+    [accountId, status],
+  );
+
+  const send = useG8Mutation(
+    async (f: File): Promise<Questionnaire> => {
+      const form = new FormData();
+      form.append("file", f);
+      return (await g8Post<Questionnaire>(`/accounts/${encodeURIComponent(String(accountId))}/security-questionnaires`, form)).data;
+    },
+    {
+      onSuccess: (created) => { setConfirming(false); setUploading(false); setFile(null); void list.refetch(); setQid(created.id); },
+      invalidates: [["documents", "questionnaire"]],
+    },
+  );
+
+  const rows = list.data ?? [];
+  const q = search.trim().toLowerCase();
+  const shown = rows.filter((r) => !q || `${nameOf(r)} ${r.original_file_name ?? ""}`.toLowerCase().includes(q));
+  const selected = rows.find((r) => r.id === qid) ?? null;
+  const closeDetail = (): void => { setQid(null); setView(null); };
+  const count = (s: string): string => (list.data ? `${rows.filter((r) => r.status === s).length.toLocaleString()}${list.hasMore ? "+" : ""}` : "...");
+
+  if (accountId == null) {
+    return <EmptyState icon={<FileSpreadsheet className="size-8" />} title="Choose an account" description="Pick a company above to see the security questionnaires it sent you, or to upload a new one." />;
+  }
+
+  const body = list.error ? <ApiError error={list.error} title="Could not load questionnaires" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? (
+    <div aria-busy="true" className="grid gap-2"><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /></div>
+  ) : shown.length === 0 ? (
+    <EmptyState icon={<FileSpreadsheet className="size-8" />} title={rows.length === 0 && !status ? "No questionnaires yet" : "No questionnaires match"} description={rows.length === 0 && !status ? `Upload the spreadsheet or PDF a buyer sent. ${brand.name} answers it from your answer library and policy documents, and you review the answers here.` : "Try another search or status."} action={rows.length === 0 && !status ? <Button onClick={() => setUploading(true)}>Upload a questionnaire</Button> : undefined} />
+  ) : (
+    <>
+      <ul className="grid gap-2">
+        {shown.map((r) => {
+          const info = statusInfo(r.status);
+          return (
+            <li key={r.id} className={`flex flex-wrap items-center justify-between gap-2 rounded-md border p-3 ${r.id === qid ? "bg-muted" : ""}`}>
+              <button type="button" className="min-w-0 flex-1 text-left" onClick={() => setQid(r.id)}>
+                <span className="block truncate font-medium">{nameOf(r)}</span>
+                <span className="text-muted-foreground block truncate text-xs">{r.total_questions != null ? `${r.answered_questions ?? "-"} of ${plural(r.total_questions, "question")} answered` : "Questions not counted yet"} · {when(r.created_at) || "-"}</span>
+              </button>
+              <StatusPill tone={info.tone}>{info.label}</StatusPill>
+              {renderRowActions?.(r)}
+            </li>
+          );
+        })}
+      </ul>
+      <LoadMore shown={rows.length} noun="questionnaires" hasMore={list.hasMore} loading={list.loadingMore} onLoadMore={list.loadMore} />
+    </>
+  );
+
+  const chosen = file ? checkFiles([file], QUESTIONNAIRE_EXTENSIONS, fileLimit(maxBytes)) : null;
+  return (
+    <div className="grid gap-4">
+      <StatStrip items={[
+        { label: "Questionnaires", value: list.data ? `${rows.length.toLocaleString()}${list.hasMore ? "+" : ""}` : "..." },
+        { label: "Needs review", value: count("needs_review"), tone: "warning" },
+        { label: "Answering", value: count("processing") },
+        { label: "Completed", value: count("completed"), tone: "positive" },
+      ]} />
+      <SplitView
+        list={(
+          <div className="grid gap-3">
+            <Toolbar
+              search={{ value: search, onChange: setSearch, placeholder: "Search questionnaires" }}
+              filters={<select aria-label="Filter by status" className={SELECT} value={status} onChange={(e) => { setStatus(e.target.value); closeDetail(); }}><option value="">All statuses</option>{Object.entries(QUESTIONNAIRE_STATUS).map(([v, s]) => <option key={v} value={v}>{s.label}</option>)}</select>}
+              actions={<>{toolbarActions}<Button size="sm" onClick={() => setUploading(true)}><Upload className="size-4" />Upload questionnaire</Button></>}
+            />
+            {body}
+          </div>
+        )}
+        detail={selected ? <QuestionnaireDetail key={selected.id} accountId={accountId} questionnaire={selected} onChanged={() => void list.refetch()} onClose={closeDetail} onDeleted={closeDetail} onExpand={() => setView("full")} onCollapse={view === "full" ? () => setView(null) : undefined} /> : null}
+        detailOpen={Boolean(selected)}
+        onCloseDetail={closeDetail}
+        expanded={view === "full"}
+        onExpandedChange={(e) => setView(e ? "full" : null)}
+        detailWidth="xl"
+      />
+      <FormSheet open={uploading} onOpenChange={(o) => { setUploading(o); if (!o) { setFile(null); setProblems([]); } }} title="Upload a questionnaire" description={`${brand.name} reads the questions and answers each one in the background. Nothing is sent to the buyer.`}>
+        <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (chosen && chosen.ok.length === 1) setConfirming(true); }}>
+          <div>
+            <Label htmlFor="g8-qp-file" className="mb-1">Questionnaire file</Label>
+            <input id="g8-qp-file" type="file" accept={QUESTIONNAIRE_EXTENSIONS.map((x) => `.${x}`).join(",")} className="border-input bg-background w-full rounded-md border p-2 text-sm" onChange={(e) => { const f = e.target.files?.[0] ?? null; setFile(f); setProblems(f ? checkFiles([f], QUESTIONNAIRE_EXTENSIONS, fileLimit(maxBytes)).problems : []); }} />
+            <p className="text-muted-foreground mt-1 text-xs">{QUESTIONNAIRE_EXTENSIONS.join(" or ")}, up to {fmtSize(fileLimit(maxBytes))}. A spreadsheet keeps its layout; a PDF is answered into a new spreadsheet.</p>
+          </div>
+          {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}
+          <div className="flex gap-2"><Button type="submit" disabled={!chosen || chosen.ok.length !== 1}>Upload and answer</Button><Button type="button" variant="outline" onClick={() => setUploading(false)}>Cancel</Button></div>
+        </form>
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={confirming && file !== null}
+        tier="billable"
+        title={`Upload and answer ${file?.name ?? "this file"}?`}
+        description={<><p>{brand.name} reads every question in the file and writes an answer to each from your answer library and policy documents. Answering uses credits. The API does not publish a price for it, so no estimate is shown here.</p>{send.error ? <ApiError error={send.error} title="Could not upload the questionnaire" /> : null}</>}
+        confirmLabel="Upload and answer"
+        confirming={send.loading}
+        onCancel={() => setConfirming(false)}
+        onConfirm={() => { if (file) void send.mutate(file); }}
+      />
+    </div>
+  );
+}

package/blocks/documents/components/record-documents-tab.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+/**
+ * RecordDocumentsTab: the paperwork behind one account, on a company, contact or deal page. Use it as an `extraDetailTabs`
+ * entry of CompaniesScreen / ContactsScreen / DealsScreen:
+ *   { id: "documents", label: "Documents", render: (c) => <RecordDocumentsTab companyId={c.id} documentsPath="/documents" /> }
+ *   { id: "documents", label: "Documents", render: (c) => <RecordDocumentsTab contactId={c.id} /> }          (a contact: their company's paperwork, messages with them first)
+ *   { id: "documents", label: "Documents", render: (d) => <RecordDocumentsTab contactId={d.primary_contact?.id} scope="account" /> }  (a deal: the primary contact finds the company; all its messages show)
+ *
+ * SDK operations, in order:
+ *   1. getContact (GET /contacts/{contact_id})                                          read  only when only a contactId is given: finds the contact's company
+ *   2. listAccountCorrespondence (GET /accounts/{account_id}/correspondence)            read  the latest messages (with that person only when a contactId is given)
+ *   3. listSecurityQuestionnaires (GET /accounts/{account_id}/security-questionnaires)  read  the latest questionnaires for the account
+ * Both lists are the newest five; "Open in documents" goes to the full screen with the account chosen. Read only: recording,
+ * uploading and reviewing happen in DocumentsScreen. A contact with no company has no account to read, and the tab says so.
+ */
+
+import { Mail } from "lucide-react";
+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 { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { plural } from "@/g8/lib/plural";
+import { CORRESPONDENCE_CHANNELS, rowsOf, statusInfo, totalOf, when } from "../lib/documents-types";
+import type { Correspondence, Questionnaire, Rec } from "../lib/documents-types";
+
+export interface RecordDocumentsTabProps {
+  /** The company (account) id. */
+  companyId?: number | null;
+  /** A contact: narrows the messages to this person and, without a companyId, finds the company. */
+  contactId?: number | null;
+  /** "person" (default with a contactId) shows only the messages with that contact; "account" shows the whole account's, using the contact only to find the company (a deal page). */
+  scope?: "person" | "account";
+  /** Path of your documents screen for the links. Default "/documents". */
+  documentsPath?: string;
+  /** Route to the documents screen yourself (for example with the router) instead of a plain link. */
+  onOpenDocuments?: (href: string) => void;
+}
+
+const LIMIT = 5;
+
+export function RecordDocumentsTab({ companyId, contactId, scope = "person", documentsPath = "/documents", onOpenDocuments }: RecordDocumentsTabProps) {
+  const personal = contactId != null && scope !== "account";
+  const needContact = companyId == null && contactId != null;
+  const contact = useG8Query((signal) => g8Get<{ company_id?: number | null }>(`/contacts/${contactId}`, {}, { signal }).then((r) => r.data), [contactId], { enabled: needContact, key: ["documents", "contact-company", contactId ?? ""] });
+  const account = companyId ?? contact.data?.company_id ?? null;
+  const base = `/accounts/${account}`;
+  const mail = useG8Query(
+    (signal) => g8Get<Rec>(`${base}/correspondence`, { stakeholder_id: personal ? String(contactId) : undefined, limit: LIMIT }, { signal }).then((r) => ({ rows: rowsOf<Correspondence>(r.data), total: totalOf(r.data) })),
+    [account, personal ? contactId : null],
+    { enabled: account != null, key: ["documents", "correspondence", "tab", account ?? "", personal ? contactId ?? "" : ""] },
+  );
+  const forms = useG8Query(
+    (signal) => g8Get<Rec>(`${base}/security-questionnaires`, { limit: LIMIT }, { signal }).then((r) => ({ rows: rowsOf<Questionnaire>(r.data), total: totalOf(r.data) })),
+    [account],
+    { enabled: account != null, key: ["documents", "questionnaire", "tab", account ?? ""] },
+  );
+
+  if (companyId == null && contactId == null) return <EmptyState compact icon={<Mail className="size-8" />} title="No account to show" description="Documents are kept per company. Add a contact or a company to this record to see them." />;
+  if (needContact && contact.error) return <ApiError error={contact.error} title="Could not find this person's company" onRetry={() => void contact.refetch()} />;
+  if (needContact && contact.loading && !contact.data) return <Skeleton className="h-24 w-full" aria-label="Loading documents" />;
+  if (account == null) return <EmptyState compact icon={<Mail className="size-8" />} title="No company on this contact" description="Messages and questionnaires are kept per company, so there is nothing to show until this person has one." />;
+
+  const href = (tab: string): string => `${documentsPath}?tab=${tab}&account=${account}`;
+  const link = (tab: string, text: string) => (
+    <a href={href(tab)} className="text-sm underline" onClick={(e) => { if (!onOpenDocuments || e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return; e.preventDefault(); onOpenDocuments(href(tab)); }}>{text}</a>
+  );
+
+  return (
+    <div className="grid gap-4">
+      <SectionCard title={personal ? "Messages with this person" : "Correspondence"} actions={link("correspondence", "Open in documents")}>
+        {mail.error ? <ApiError error={mail.error} title="Could not load messages" compact onRetry={() => void mail.refetch()} /> : !mail.data ? <Skeleton className="h-16 w-full" aria-label="Loading messages" /> : mail.data.rows.length === 0 ? (
+          <EmptyState compact title="No messages recorded" description="Emails, LinkedIn messages and call notes recorded for this account show up here." />
+        ) : (
+          <ul className="divide-y rounded-md border" aria-label="Messages">
+            {mail.data.rows.map((m) => (
+              <li key={m.id} className="flex items-center justify-between gap-3 p-3 text-sm">
+                <span className="min-w-0"><span className="block truncate font-medium">{m.subject || (m.content ? m.content.slice(0, 80) : "No subject")}</span><span className="text-muted-foreground block text-xs">{CORRESPONDENCE_CHANNELS.find((c) => c.value === m.channel)?.label ?? m.channel ?? "-"} · {when(m.correspondence_date) || "-"}</span></span>
+                {m.direction ? <StatusPill tone={m.direction === "inbound" ? "info" : "neutral"}>{m.direction === "inbound" ? "Inbound" : "Outbound"}</StatusPill> : null}
+              </li>
+            ))}
+          </ul>
+        )}
+        {mail.data && mail.data.total != null && mail.data.total > mail.data.rows.length ? <p className="text-muted-foreground mt-2 text-xs">Showing the newest {mail.data.rows.length} of {plural(mail.data.total, "message")}.</p> : null}
+      </SectionCard>
+      <SectionCard title="Security questionnaires" description="Kept for the company, not the person." actions={link("questionnaires", "Open in documents")}>
+        {forms.error ? <ApiError error={forms.error} title="Could not load questionnaires" compact onRetry={() => void forms.refetch()} /> : !forms.data ? <Skeleton className="h-16 w-full" aria-label="Loading questionnaires" /> : forms.data.rows.length === 0 ? (
+          <EmptyState compact title="No questionnaires" description="Questionnaires uploaded for this account show up here." />
+        ) : (
+          <ul className="divide-y rounded-md border" aria-label="Questionnaires">
+            {forms.data.rows.map((f) => {
+              const info = statusInfo(f.status);
+              return (
+                <li key={f.id} className="flex items-center justify-between gap-3 p-3 text-sm">
+                  <span className="min-w-0"><span className="block truncate font-medium">{f.display_name || f.original_file_name || "Untitled questionnaire"}</span><span className="text-muted-foreground block text-xs">{f.total_questions != null ? `${f.answered_questions ?? "-"} of ${plural(f.total_questions, "question")} answered` : "-"}</span></span>
+                  <StatusPill tone={info.tone}>{info.label}</StatusPill>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+        {forms.data && forms.data.total != null && forms.data.total > forms.data.rows.length ? <p className="text-muted-foreground mt-2 text-xs">Showing the newest {forms.data.rows.length} of {plural(forms.data.total, "questionnaire")}.</p> : null}
+      </SectionCard>
+    </div>
+  );
+}

package/blocks/documents/lib/documents-types.ts

@@ -0,0 +1,252 @@
+"use client";
+
+/**
+ * Shapes, vocabularies and helpers the documents block shares.
+ *
+ * The documents responses are OPEN in the contract (`DocumentPayload` / `DocumentListPayload`), so every field here is
+ * optional and read defensively: a missing value is shown as a dash, never replaced by a guess. A list read always carries
+ * its rows under `items` (the contract's promise), whichever key the app used underneath.
+ *
+ * SDK operations: none.
+ */
+
+import type { Tone } from "@/g8/components/screen/status-pill";
+
+export type Rec = Record<string, unknown>;
+
+/** The Library root; a folder's `parent_path` for a top-level folder. */
+export const ROOT = "Library";
+/** Largest file the /api/g8 proxy forwards by default (5 MiB). The app itself accepts 50 MB: raise `maxBodyBytes` in the proxy route first. */
+export const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+/** Bytes a multipart body adds around its files: the boundary lines and headers (about 200 per file) plus the other fields. */
+export const BASE_OVERHEAD = 4096;
+export const FILE_OVERHEAD = 512;
+/** The largest single file that fits one request under the proxy's body cap (`maxBytes`). */
+export const fileLimit = (maxBytes: number): number => maxBytes - BASE_OVERHEAD - FILE_OVERHEAD;
+/** The extensions the Library accepts (contract text of uploadLibraryDocument). */
+export const LIBRARY_EXTENSIONS = ["pdf", "docx", "doc", "txt", "md", "mdx", "csv", "json", "png", "jpg", "jpeg", "xls", "xlsx", "ppt", "pptx"] as const;
+/** Security questionnaires are read from a spreadsheet or a PDF. */
+export const QUESTIONNAIRE_EXTENSIONS = ["xlsx", "pdf"] as const;
+/** The types whose text the Library can extract again. */
+export const REEXTRACT_TYPES = ["pdf", "docx"] as const;
+
+export const CORRESPONDENCE_CHANNELS = [
+  { value: "email", label: "Email" },
+  { value: "linkedin", label: "LinkedIn" },
+  { value: "call_notes", label: "Call notes" },
+] as const;
+export const DIRECTIONS = [
+  { value: "inbound", label: "Inbound" },
+  { value: "outbound", label: "Outbound" },
+] as const;
+
+export interface LibraryDoc {
+  id: string;
+  folder_path: string;
+  file_name?: string | null;
+  display_name?: string | null;
+  file_type?: string | null;
+  content?: string | null;
+  has_file_data?: boolean;
+  file_size_bytes?: number | null;
+  mime_type?: string | null;
+  priority?: string | null;
+  source?: string | null;
+  indexed_at?: string | null;
+  deleted_at?: string | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+  created_by?: string | null;
+  owner_name?: string | null;
+  current_version?: number | null;
+  meta_data?: Rec | null;
+}
+
+export interface LibraryFolder {
+  id: string;
+  name: string;
+  parent_path: string;
+  full_path: string;
+  created_at?: string | null;
+}
+
+export interface Questionnaire {
+  id: string;
+  account_id?: string | null;
+  original_file_name?: string | null;
+  original_file_type?: string | null;
+  display_name?: string | null;
+  status?: string | null;
+  total_questions?: number | null;
+  answered_questions?: number | null;
+  escalated_questions?: number | null;
+  error_message?: string | null;
+  created_at?: string | null;
+  completed_at?: string | null;
+  questions?: Question[] | null;
+}
+
+export interface Question {
+  id: string;
+  question_text?: string | null;
+  question_topic?: string | null;
+  cell_reference?: string | null;
+  sheet_name?: string | null;
+  answer_text?: string | null;
+  final_answer?: string | null;
+  confidence?: string | null;
+  status?: string | null;
+  review_status?: string | null;
+  escalation_notes?: string | null;
+  guardrail_warnings?: string[] | null;
+  citations?: Rec[] | null;
+}
+
+export interface QuestionnaireProgress {
+  id?: string;
+  status?: string | null;
+  total_questions?: number | null;
+  answered_questions?: number | null;
+  escalated_questions?: number | null;
+  error_message?: string | null;
+  progress?: number | null;
+}
+
+export interface Correspondence {
+  id: string;
+  account_id?: string | null;
+  stakeholder_id?: string | null;
+  channel?: string | null;
+  direction?: string | null;
+  subject?: string | null;
+  content?: string | null;
+  source?: string | null;
+  external_id?: string | null;
+  correspondence_date?: string | null;
+  indexed_in_rag?: boolean;
+  created_at?: string | null;
+}
+
+export interface ImportResult {
+  imported?: number;
+  skipped?: number;
+  errors?: string[];
+}
+
+/** The rows of an open list payload: its `items` array (the contract always sends it). */
+export function rowsOf<T>(data: unknown): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const items = (data as { items?: unknown } | null | undefined)?.items;
+  return Array.isArray(items) ? (items as T[]) : [];
+}
+
+/** The `total` an open list payload may carry, or null when it sends none. */
+export function totalOf(data: unknown): number | null {
+  const t = (data as { total?: unknown } | null | undefined)?.total;
+  return typeof t === "number" ? t : null;
+}
+
+export const extOf = (name: string): string => (name.includes(".") ? name.slice(name.lastIndexOf(".") + 1).toLowerCase() : "");
+
+/** "12 KB", "1.4 MB"; an empty string when the size is unknown (callers show a dash). */
+export function fmtSize(bytes: number | null | undefined): string {
+  if (typeof bytes !== "number" || !Number.isFinite(bytes) || bytes < 0) return "";
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024).toLocaleString("en-US")} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export const when = (v: string | null | undefined): string => {
+  if (!v) return "";
+  const d = new Date(v);
+  return Number.isNaN(d.getTime()) ? "" : d.toLocaleString();
+};
+
+/** Keep the files that may go up and say why the others cannot. The same files are counted in the confirm and sent. */
+export function checkFiles(files: readonly File[], allowed: readonly string[], maxBytes: number): { ok: File[]; problems: string[] } {
+  const ok: File[] = [];
+  const problems: string[] = [];
+  for (const f of files) {
+    if (!allowed.includes(extOf(f.name))) problems.push(`${f.name}: only ${allowed.join(", ")} files can be added.`);
+    else if (f.size === 0) problems.push(`${f.name}: the file is empty.`);
+    else if (f.size > maxBytes) problems.push(`${f.name}: ${fmtSize(f.size)} is over the ${fmtSize(maxBytes)} limit.`);
+    else ok.push(f);
+  }
+  return { ok, problems };
+}
+
+/** The API's folder-name rule (letters, digits, spaces, hyphens, underscores; at most 50) and its three-level depth limit. */
+export function folderNameProblem(name: string, parentPath: string): string | null {
+  const n = name.trim();
+  if (!n) return "Give the folder a name.";
+  if (n.length > 50) return "A folder name is at most 50 characters.";
+  if (!/^[\w\s-]+$/.test(n)) return "Use letters, numbers, spaces, hyphens and underscores only.";
+  if (`${parentPath}/${n}`.split("/").length > 3) return "Folders go three levels deep at most.";
+  return null;
+}
+
+/** A stored file name proposed from a title: lower case, hyphens, `.md`. The person can edit it. */
+export function fileNameFor(title: string): string {
+  const base = title.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return base ? `${base}.md` : "";
+}
+
+export const docName = (d: Pick<LibraryDoc, "display_name" | "file_name">): string => d.display_name || d.file_name || "Untitled document";
+export const folderLabel = (path: string): string => (path === ROOT ? "Library" : path.replace(/^Library\//, ""));
+
+export const QUESTIONNAIRE_STATUS: Record<string, { label: string; tone: Tone }> = {
+  pending: { label: "Waiting", tone: "neutral" },
+  processing: { label: "Answering", tone: "info" },
+  completed: { label: "Completed", tone: "positive" },
+  needs_review: { label: "Needs review", tone: "warning" },
+  failed: { label: "Failed", tone: "negative" },
+};
+export const statusInfo = (s: string | null | undefined): { label: string; tone: Tone } =>
+  QUESTIONNAIRE_STATUS[s ?? ""] ?? { label: s ? s.replace(/_/g, " ") : "Unknown", tone: "neutral" };
+/** The filled workbook is only available in these states (the API refuses earlier). */
+export const canDownload = (s: string | null | undefined): boolean => s === "completed" || s === "needs_review";
+export const isWorking = (s: string | null | undefined): boolean => s === "pending" || s === "processing";
+
+/** What a person should read as the state of one question. */
+export function reviewState(q: Question): { label: string; tone: Tone } {
+  if (q.review_status === "skip") return { label: "Not applicable", tone: "neutral" };
+  if (q.review_status === "wrong") return { label: "Marked wrong", tone: "negative" };
+  if (q.status === "escalated") return { label: "Escalated", tone: "warning" };
+  if (q.status === "approved" || q.confidence === "confirmed") return { label: "Approved", tone: "positive" };
+  if (q.final_answer) return { label: "Edited", tone: "info" };
+  if (q.answer_text) return { label: "Answered", tone: "neutral" };
+  return { label: "No answer", tone: "warning" };
+}
+
+/** The answer the filled workbook carries: the person's edit when there is one, else the AI's. */
+export const answerOf = (q: Question): string => q.final_answer || q.answer_text || "";
+
+/** Whole-number percent, or null when there is nothing to divide. */
+export function percentOf(done: number | null | undefined, total: number | null | undefined): number | null {
+  if (typeof done !== "number" || typeof total !== "number" || total <= 0) return null;
+  return Math.min(100, Math.round((done / total) * 100));
+}
+
+/** One piece of correspondence as the import call takes it, or the reason it cannot be sent. */
+export function parseImportItems(text: string): { items: Rec[]; problem: string | null } {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { items: [], problem: "That is not valid JSON." };
+  }
+  const list = Array.isArray(parsed) ? parsed : (parsed as { items?: unknown } | null)?.items;
+  if (!Array.isArray(list) || list.length === 0) return { items: [], problem: "Paste a JSON array with at least one message." };
+  const channels = CORRESPONDENCE_CHANNELS.map((c) => c.value as string);
+  const directions = DIRECTIONS.map((d) => d.value as string);
+  for (const [i, raw] of list.entries()) {
+    const it = raw as Rec;
+    const at = `Message ${i + 1}`;
+    if (!it || typeof it !== "object") return { items: [], problem: `${at} is not an object.` };
+    if (typeof it.content !== "string" || !it.content.trim()) return { items: [], problem: `${at} needs content.` };
+    if (typeof it.channel !== "string" || !channels.includes(it.channel)) return { items: [], problem: `${at}: channel must be ${channels.join(", ")}.` };
+    if (typeof it.direction !== "string" || !directions.includes(it.direction)) return { items: [], problem: `${at}: direction must be inbound or outbound.` };
+    if (typeof it.correspondence_date !== "string" || Number.isNaN(Date.parse(it.correspondence_date))) return { items: [], problem: `${at}: correspondence_date must be a date and time, for example 2026-09-30T14:00:00Z.` };
+  }
+  return { items: list as Rec[], problem: null };
+}

package/blocks/documents/lib/download.ts

@@ -0,0 +1,64 @@
+"use client";
+
+/**
+ * Save a file the API returns as raw bytes (a Library document in its original format, a filled questionnaire workbook).
+ * These two routes are NOT the JSON envelope, so `g8Get` (which parses JSON) cannot read them; this goes through the same
+ * /api/g8 proxy and keeps the key on the server.
+ *
+ * SDK operations: none directly. The callers declare downloadLibraryDocument / downloadSecurityQuestionnaire.
+ */
+
+import { G8Error } from "@graph8/sdk/errors";
+import { buildG8Url, transport } from "@/g8/lib/g8-client";
+
+/** @internal Swappable in tests (jsdom has no object URLs). */
+export const saver = {
+  save(blob: Blob, name: string): void {
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = name;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+  },
+};
+
+/** The file name a Content-Disposition header names (RFC 5987 `filename*` first), or null. */
+export function nameFromDisposition(header: string | null): string | null {
+  if (!header) return null;
+  const star = /filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/.exec(header);
+  if (star) {
+    try {
+      return decodeURIComponent(star[1].trim());
+    } catch {
+      /* fall through to the plain form */
+    }
+  }
+  const plain = /filename\s*=\s*"?([^";]+)"?/.exec(header);
+  return plain ? plain[1].trim() : null;
+}
+
+/** Fetch `path` (relative to /api/v1) and hand the bytes to the browser as a download. Throws `G8Error` on any failure. */
+export async function downloadFile(path: string, fallbackName: string): Promise<string> {
+  let resp: Response;
+  try {
+    resp = await transport.fetch(buildG8Url(path), { method: "GET", credentials: "same-origin" });
+  } catch (err) {
+    throw new G8Error({ message: `Network error: ${(err as Error)?.message ?? "request failed"}`, status: 0, type: "network_error", retryable: true });
+  }
+  if (!resp.ok) {
+    let message = `Request failed with status ${resp.status}`;
+    try {
+      const env = JSON.parse(await resp.text()) as { message?: string; detail?: unknown };
+      message = env.message || (typeof env.detail === "string" ? env.detail : message);
+    } catch {
+      /* keep the status line */
+    }
+    throw new G8Error({ message, status: resp.status, type: "api_error", code: String(resp.status), retryable: resp.status === 429 || resp.status >= 500 });
+  }
+  const name = nameFromDisposition(resp.headers.get("content-disposition")) || fallbackName;
+  saver.save(await resp.blob(), name);
+  return name;
+}

package/blocks/documents/recipes/follow-a-questionnaire.ts

@@ -0,0 +1,26 @@
+/**
+ * @title Follow a security questionnaire until it is answered and list the questions that need a person
+ * @when After a questionnaire was uploaded in the app (answering uses credits, so a person confirms the upload; upload is
+ * multipart and not part of this typed client). Poll the cheap status read, not the full detail, until the status is no longer
+ * pending or processing. This only READS: it approves nothing, because an approval is a person's judgement. The filled workbook
+ * is available only once the status is completed or needs_review.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const accountId = process.env.G8_COMPANY_ID!;
+const questionnaireId = process.env.G8_QUESTIONNAIRE_ID!;
+const path = { account_id: accountId, questionnaire_id: questionnaireId };
+
+let status = "pending";
+for (let i = 0; i < 60 && (status === "pending" || status === "processing"); i++) {
+  const s = (await g8.api.documents.getSecurityQuestionnaireStatus({ path })).data as { status?: string; answered_questions?: number; total_questions?: number };
+  status = s.status ?? "unknown";
+  console.log(status, `${s.answered_questions ?? "-"} of ${s.total_questions ?? "-"} answered`);
+  if (status === "pending" || status === "processing") await new Promise((r) => setTimeout(r, 5000));
+}
+
+const detail = (await g8.api.documents.getSecurityQuestionnaire({ path })).data as { questions?: Array<{ id: string; question_text?: string; status?: string; review_status?: string; answer_text?: string | null }> };
+const needsAPerson = (detail.questions ?? []).filter((q) => q.status !== "approved" && q.review_status !== "skip");
+console.log(`${needsAPerson.length} questions still need review`, needsAPerson.slice(0, 5).map((q) => q.question_text));