@graph8/sdk 0.303.0 → 0.357.0

package/blocks/workbench/components/workbench-add-rows.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+/**
+ * WorkbenchAddRows: put records into a workbench table by hand. Two tabs: one row typed into the table's own
+ * columns, or many rows pasted from a spreadsheet (tab or comma separated, first line = headers).
+ *
+ * SDK operations, in order:
+ *   1. addWorkbenchRow            POST /workbench/tables/{table_id}/rows           (write)  { data: { <column machine name>: value } }
+ *   2. pasteImportWorkbenchRows   POST /workbench/tables/{table_id}/import/paste   (write)  { headers, rows }; new headers become columns
+ *
+ * Both are plain writes on rows the person typed, so neither needs ConfirmSpendDialog. Searching for people to
+ * import (which lands locked rows and costs credits) is a separate, billable flow: see recipes/import-from-search.ts.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { parsePasted } from "../lib/workbench-types";
+import type { WorkbenchColumn } from "../lib/workbench-types";
+
+/** The proxy rejects request bodies over 5 MiB; stay under it with room for the JSON wrapping. */
+export const MAX_PASTE_BYTES = 4 * 1024 * 1024;
+
+export interface WorkbenchAddRowsProps {
+  tableId: string;
+  columns: WorkbenchColumn[];
+  /** Called after rows were added so the grid can reload. */
+  onAdded?: (count: number) => void;
+  className?: string;
+}
+
+export function WorkbenchAddRows({ tableId, columns, onAdded, className }: WorkbenchAddRowsProps) {
+  const [tab, setTab] = useState<"row" | "paste">("row");
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [pasted, setPasted] = useState("");
+  const [notice, setNotice] = useState<string | null>(null);
+
+  const typeable = columns.filter((c) => (c.column_type ?? "data") === "data" && !c.enrichment_type);
+  const parsed = parsePasted(pasted);
+  const width = parsed.headers.length;
+  const tooBig = new Blob([pasted]).size > MAX_PASTE_BYTES;
+  const ragged = parsed.rows.filter((r) => r.length !== width).length;
+
+  const addRow = useG8Mutation(
+    () => {
+      const data = Object.fromEntries(Object.entries(values).filter(([, v]) => v.trim() !== ""));
+      return g8Post(`/workbench/tables/${tableId}/rows`, { data });
+    },
+    { onSuccess: () => { setValues({}); setNotice("Row added."); onAdded?.(1); } },
+  );
+  const paste = useG8Mutation(
+    () => g8Post(`/workbench/tables/${tableId}/import/paste`, { headers: parsed.headers, rows: parsed.rows }),
+    { onSuccess: () => { setPasted(""); setNotice(`Imported ${parsed.rows.length} rows.`); onAdded?.(parsed.rows.length); } },
+  );
+
+  return (
+    <div className={`flex flex-col gap-3 rounded-md border p-3 ${className ?? ""}`}>
+      <div role="tablist" aria-label="Add rows" className="flex gap-2">
+        {(["row", "paste"] as const).map((t) => (
+          <Button key={t} role="tab" aria-selected={tab === t} size="sm" variant={tab === t ? "default" : "outline"} onClick={() => { setTab(t); setNotice(null); }}>
+            {t === "row" ? "Add a row" : "Paste from a spreadsheet"}
+          </Button>
+        ))}
+      </div>
+
+      {tab === "row" ? (
+        <div className="flex flex-col gap-2">
+          {typeable.length === 0 ? <p className="text-sm text-muted-foreground">This table has no plain data columns yet. Paste a spreadsheet to create them from its headers.</p> : null}
+          <div className="grid gap-2 sm:grid-cols-2">
+            {typeable.map((c) => (
+              <div key={c.id} className="flex flex-col gap-1">
+                <Label htmlFor={`wb-add-${c.name}`}>{c.display_name || c.name}</Label>
+                <Input id={`wb-add-${c.name}`} value={values[c.name] ?? ""} onChange={(e) => setValues({ ...values, [c.name]: e.target.value })} />
+              </div>
+            ))}
+          </div>
+          {addRow.error ? <ApiError error={addRow.error} title="Could not add the row" /> : null}
+          <div><Button size="sm" loading={addRow.loading} disabled={Object.values(values).every((v) => !v.trim())} onClick={() => void addRow.mutate(undefined)}>Add row</Button></div>
+        </div>
+      ) : (
+        <div className="flex flex-col gap-2">
+          <Label htmlFor="wb-paste">Paste rows (the first line is the header)</Label>
+          <Textarea id="wb-paste" rows={6} value={pasted} onChange={(e) => setPasted(e.target.value)} placeholder={"Company\tDomain\nAcme\tacme.com"} />
+          {width > 0 ? (
+            <p className="text-sm text-muted-foreground">
+              {parsed.rows.length.toLocaleString()} rows, {width} columns: {parsed.headers.join(", ")}.
+              {ragged ? ` ${ragged} rows have a different number of cells than the header; check them before importing.` : ""}
+            </p>
+          ) : null}
+          {tooBig ? <p role="alert" className="text-sm text-destructive">This is over 4 MB, more than one request can carry. Paste it in smaller parts.</p> : null}
+          {paste.error ? <ApiError error={paste.error} title="Could not import the rows" /> : null}
+          <div><Button size="sm" loading={paste.loading} disabled={parsed.rows.length === 0 || tooBig} onClick={() => void paste.mutate(undefined)}>Import {parsed.rows.length.toLocaleString()} rows</Button></div>
+        </div>
+      )}
+      {notice ? <p role="status" className="text-sm text-muted-foreground">{notice}</p> : null}
+    </div>
+  );
+}

package/blocks/workbench/components/workbench-grid.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+/**
+ * WorkbenchGrid: the Clay-style table. Rows are records, columns are data or recipes (AI prompt, enrichment
+ * waterfall, formula). Select rows, edit a cell, add rows or columns, run a recipe column and watch it finish,
+ * unlock/export/delete the selection. It composes WorkbenchAddRows, ColumnRecipeEditor, RunProgress and
+ * WorkbenchRowActions around one table.
+ *
+ * SDK operations, in order:
+ *   1. getWorkbenchTable      GET   /workbench/tables/{table_id}                      (read)   name, entity_type, row_count
+ *   2. listWorkbenchColumns   GET   /workbench/tables/{table_id}/columns              (read)   machine names rows are keyed by
+ *   3. listWorkbenchRows      GET   /workbench/tables/{table_id}/rows?start_row&end_row (read) windows of 100; "Load more" widens it
+ *   4. updateWorkbenchRow     PATCH /workbench/tables/{table_id}/rows/{row_id} { field, value }  (write) double-click a cell; Enter saves
+ *   (the panels it opens call: addWorkbenchRow, pasteImportWorkbenchRows, addWorkbenchColumn, saveWorkbenchColumnAiConfig,
+ *    saveWorkbenchWaterfall, createWorkbenchFormulaColumns, mapWorkbenchColumn, quote*Run + run* (billable, confirmed),
+ *    getWorkbenchHistory, getWorkbenchAnalytics, quoteWorkbenchUnlock, unlockWorkbenchRows (billable, confirmed),
+ *    exportWorkbenchTable, bulkDeleteWorkbenchRows (destructive, confirmed))
+ *
+ * A locked row (credit_charged false) shows masked cells and cannot be edited: unlock it first (1 credit per row).
+ * Cells show `extracted_data` (what a recipe wrote) before `raw_data` (what was imported).
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Patch } from "@/g8/lib/g8-client";
+import { useWorkbenchTable } from "../hooks/use-workbench-table";
+import { cellValue, formatCell, isLocked, isMasked, pageItems, pageTotal } from "../lib/workbench-types";
+import type { RunTarget, WorkbenchColumn, WorkbenchRow } from "../lib/workbench-types";
+import { ColumnRecipeEditor } from "./column-recipe-editor";
+import { RunProgress } from "./run-progress";
+import { WorkbenchAddRows } from "./workbench-add-rows";
+import { WorkbenchRowActions } from "./workbench-row-actions";
+
+export interface WorkbenchGridProps {
+  tableId: string;
+  /** Rows per window. Default 100. */
+  pageSize?: number;
+  className?: string;
+}
+
+type Panel = "rows" | "columns" | "selection" | null;
+
+function runTarget(column: WorkbenchColumn): RunTarget | null {
+  if (column.enrichment_type === "waterfall") return { kind: "waterfall", columnId: column.id };
+  if (column.enrichment_type === "ai") return { kind: "ai-column", columnId: column.id };
+  return null;
+}
+
+export function WorkbenchGrid({ tableId, pageSize = 100, className }: WorkbenchGridProps) {
+  const [end, setEnd] = useState(pageSize);
+  const [panel, setPanel] = useState<Panel>(null);
+  const [selected, setSelected] = useState<number[]>([]);
+  const [editing, setEditing] = useState<{ rowId: number; column: string; value: string } | null>(null);
+  const [running, setRunning] = useState<WorkbenchColumn | null>(null);
+  const { table, columns, loading: metaLoading, error: metaError, refetch: refetchMeta } = useWorkbenchTable(tableId);
+
+  const rows = useG8Query(async (signal) => (await g8Get(`/workbench/tables/${tableId}/rows`, { start_row: 0, end_row: end }, { signal })).data, [tableId, end]);
+  const items = pageItems<WorkbenchRow>(rows.data);
+  const total = pageTotal(rows.data, items.length);
+  const save = useG8Mutation(
+    (v: { rowId: number; column: string; value: string }) => g8Patch(`/workbench/tables/${tableId}/rows/${v.rowId}`, { field: v.column, value: v.value }),
+    { onSuccess: () => { setEditing(null); void rows.refetch(); } },
+  );
+  // Selection and open panels belong to one table and one set of rows: drop them when the table changes,
+  // and prune the selection to rows that still exist after any reload (delete, import, run).
+  useEffect(() => { setSelected([]); setEditing(null); setRunning(null); setEnd(pageSize); }, [tableId, pageSize]);
+  useEffect(() => {
+    if (rows.loading || !rows.data) return;
+    const alive = new Set(items.map((r) => r.id));
+    setSelected((cur) => (cur.every((id) => alive.has(id)) ? cur : cur.filter((id) => alive.has(id))));
+  }, [rows.data, rows.loading]); // eslint-disable-line react-hooks/exhaustive-deps
+  const reload = () => { void rows.refetch(); void refetchMeta(); };
+  const toggle = (id: number) => setSelected(selected.includes(id) ? selected.filter((x) => x !== id) : [...selected, id]);
+  const allOn = items.length > 0 && items.every((r) => selected.includes(r.id));
+  const entityType = table?.entity_type === "company" ? "company" : "contact";
+
+  if (metaError) return <ApiError error={metaError} title="Could not load the table" onRetry={() => void refetchMeta()} />;
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <div>
+          <h2 className="text-base font-semibold">{table?.name ?? "Workbench"}</h2>
+          <p className="text-xs text-muted-foreground">{total.toLocaleString()} rows, {columns.length} columns</p>
+        </div>
+        <div className="flex gap-2" role="toolbar" aria-label="Workbench tools">
+          {([["rows", "Add rows"], ["columns", "Add column"], ["selection", `Selection (${selected.length})`]] as const).map(([id, label]) => (
+            <Button key={id} size="sm" variant={panel === id ? "default" : "outline"} onClick={() => setPanel(panel === id ? null : id)}>{label}</Button>
+          ))}
+        </div>
+      </div>
+
+      {panel === "rows" ? <WorkbenchAddRows tableId={tableId} columns={columns} onAdded={reload} /> : null}
+      {panel === "columns" ? <ColumnRecipeEditor tableId={tableId} columns={columns} entityType={entityType} onSaved={reload} /> : null}
+      {panel === "selection" ? <WorkbenchRowActions tableId={tableId} rowIds={selected} entityType={entityType} onChanged={(what) => { if (what !== "exported") setSelected([]); reload(); }} /> : null}
+      {running ? (
+        <div className="rounded-md border p-3">
+          <RunProgress key={running.id} tableId={tableId} target={runTarget(running)!} rowIds={selected.length ? selected : undefined} label={running.display_name || running.name} onFinished={reload} />
+          <Button size="sm" variant="ghost" onClick={() => setRunning(null)}>Close</Button>
+        </div>
+      ) : null}
+      {save.error ? <ApiError error={save.error} title="Could not save the cell" /> : null}
+      {rows.error ? <ApiError error={rows.error} title="Could not load the rows" onRetry={() => void rows.refetch()} /> : null}
+
+      {(metaLoading || rows.loading) && items.length === 0 ? <Skeleton className="h-40 w-full" /> : null}
+      {!rows.loading && !rows.error && items.length === 0 ? <EmptyState title="No rows yet" description="Add a row, paste a spreadsheet, or import people from a search." /> : null}
+      {items.length > 0 ? (
+        <div className="overflow-x-auto rounded-md border">
+          <Table>
+            <TableHeader>
+              <TableRow>
+                <TableHead className="w-8"><input type="checkbox" aria-label="Select all rows" checked={allOn} onChange={() => setSelected(allOn ? [] : items.map((r) => r.id))} /></TableHead>
+                {columns.map((c) => {
+                  const target = runTarget(c);
+                  return (
+                    <TableHead key={c.id}>
+                      <div className="flex items-center gap-1">
+                        <span>{c.display_name || c.name}</span>
+                        {c.enrichment_type ? <span className="rounded bg-muted px-1 text-xs">{c.enrichment_type}</span> : null}
+                        {target ? <Button size="sm" variant="ghost" aria-label={`Run ${c.display_name || c.name}`} onClick={() => setRunning(c)}>Run</Button> : null}
+                      </div>
+                    </TableHead>
+                  );
+                })}
+              </TableRow>
+            </TableHeader>
+            <TableBody>
+              {items.map((row) => (
+                <TableRow key={row.id} data-state={selected.includes(row.id) ? "selected" : undefined}>
+                  <TableCell><input type="checkbox" aria-label={`Select row ${row.id}`} checked={selected.includes(row.id)} onChange={() => toggle(row.id)} /></TableCell>
+                  {columns.map((c) => {
+                    const value = cellValue(row, c);
+                    const isEdit = editing?.rowId === row.id && editing.column === c.name;
+                    const editable = !isLocked(row) && (c.column_type ?? "data") === "data" && !c.enrichment_type;
+                    return (
+                      <TableCell key={c.id} onDoubleClick={() => editable && setEditing({ rowId: row.id, column: c.name, value: formatCell(value) })}>
+                        {isEdit && editing ? (
+                          <Input autoFocus aria-label={`Edit ${c.name}`} value={editing.value} onChange={(e) => setEditing({ ...editing, value: e.target.value })}
+                            onKeyDown={(e) => { if (e.key === "Enter" && !save.loading) void save.mutate(editing); if (e.key === "Escape") setEditing(null); }} />
+                        ) : (
+                          <span className={isMasked(value) || (isLocked(row) && value == null) ? "text-muted-foreground" : ""} title={isLocked(row) ? "Locked: unlock the row to see this" : undefined}>{formatCell(value) || (isLocked(row) ? "locked" : "")}</span>
+                        )}
+                      </TableCell>
+                    );
+                  })}
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </div>
+      ) : null}
+      {items.length < total ? <div><Button size="sm" variant="outline" loading={rows.loading} onClick={() => setEnd(end + pageSize)}>Load more ({items.length.toLocaleString()} of {total.toLocaleString()})</Button></div> : null}
+    </div>
+  );
+}

package/blocks/workbench/components/workbench-row-actions.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+/**
+ * WorkbenchRowActions: what to do with the selected rows of a workbench table. Unlock locked rows (reveal real
+ * emails and phones), send the rows to a graph8 list, or delete them.
+ *
+ * SDK operations, in order:
+ *   1. quoteWorkbenchUnlock       POST .../unlock-quote { row_ids }   (read, free)  -> operation_id, locked_count, required_credits,
+ *        available_credits, can_unlock, quote_expires_at. Locked rows come from prospect search imports and find-people.
+ *   2. unlockWorkbenchRows        POST .../unlock-rows { row_ids, approved_max_credits, quote_expires_at, operation_id }  (billable)
+ *        ONE CREDIT PER ROW. Goes through ConfirmSpendDialog first with the quote's required_credits.
+ *   3. exportWorkbenchTable       POST .../export { row_ids, list_id | create_new_list + new_list_name, entity_type }  (write)
+ *        The way finished rows leave the workbench for a list (ListPicker from the lists block).
+ *   4. bulkDeleteWorkbenchRows    POST .../rows/bulk-delete { row_ids }   (destructive) ConfirmSpendDialog first.
+ */
+
+import { useEffect, useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { ListPicker } from "@/g8/lists/components/list-picker";
+import type { ListSummary } from "@/g8/lists/components/list-picker";
+import type { CreditQuote } from "../lib/workbench-types";
+
+export interface WorkbenchRowActionsProps {
+  tableId: string;
+  /** Row ids selected in the grid. The actions are disabled until at least one is selected. */
+  rowIds: number[];
+  entityType?: "contact" | "company";
+  /** Called after rows were unlocked, deleted or exported so the grid can reload. */
+  onChanged?: (what: "unlocked" | "deleted" | "exported") => void;
+  className?: string;
+}
+
+export function WorkbenchRowActions({ tableId, rowIds, entityType = "contact", onChanged, className }: WorkbenchRowActionsProps) {
+  const [quote, setQuote] = useState<CreditQuote | null>(null);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+  const [listId, setListId] = useState<number | null>(null);
+  const [notice, setNotice] = useState<string | null>(null);
+  const none = rowIds.length === 0;
+  // A quote prices one selection: drop it (and its "nothing to unlock" note) when the selection changes.
+  const scope = rowIds.join(",");
+  useEffect(() => { setQuote(null); }, [scope]);
+
+  const getQuote = useG8Mutation(async () => (await g8Post<CreditQuote>(`/workbench/tables/${tableId}/unlock-quote`, { row_ids: rowIds })).data, { onSuccess: (q) => setQuote(q) });
+  const unlock = useG8Mutation(
+    async (q: CreditQuote) => (await g8Post<{ unlocked_count?: number }>(`/workbench/tables/${tableId}/unlock-rows`, {
+      row_ids: rowIds, approved_max_credits: q.required_credits, quote_expires_at: q.quote_expires_at, operation_id: q.operation_id,
+    })).data,
+    { onSuccess: (r) => { setQuote(null); setNotice(`Unlocked ${r.unlocked_count ?? "the"} rows.`); onChanged?.("unlocked"); } },
+  );
+  const remove = useG8Mutation(() => g8Post(`/workbench/tables/${tableId}/rows/bulk-delete`, { row_ids: rowIds }), {
+    onSuccess: () => { setConfirmDelete(false); setNotice(`Deleted ${rowIds.length} rows.`); onChanged?.("deleted"); },
+  });
+  const exportRows = useG8Mutation(
+    (list: number) => g8Post(`/workbench/tables/${tableId}/export`, { row_ids: rowIds, list_id: list, entity_type: entityType }),
+    { onSuccess: () => { setNotice(`Sent ${rowIds.length} rows to the list.`); onChanged?.("exported"); } },
+  );
+  const pick = (list: ListSummary) => setListId(list.id);
+  const noLocked = quote != null && (quote.locked_count ?? 0) === 0;
+
+  return (
+    <div className={`flex flex-col gap-3 rounded-md border p-3 ${className ?? ""}`}>
+      <p className="text-sm font-medium">{none ? "Select rows to act on them" : `${rowIds.length.toLocaleString()} rows selected`}</p>
+      <div className="flex flex-wrap items-end gap-3">
+        <ListPicker value={listId} onChange={pick} type={entityType === "company" ? "companies" : "contacts"} allowCreate />
+        <Button size="sm" variant="outline" disabled={none || listId == null} loading={exportRows.loading} onClick={() => listId != null && void exportRows.mutate(listId)}>Send to list</Button>
+        <Button size="sm" variant="outline" disabled={none} loading={getQuote.loading} onClick={() => void getQuote.mutate(undefined)}>Unlock locked rows</Button>
+        <Button size="sm" variant="outline" disabled={none} onClick={() => setConfirmDelete(true)}>Delete rows</Button>
+      </div>
+      {[getQuote.error, exportRows.error, remove.error, unlock.error].filter(Boolean).map((e, i) => <ApiError key={i} error={e} title="That did not work" />)}
+      {noLocked ? <p role="status" className="text-sm text-muted-foreground">None of the selected rows are locked. Nothing to unlock.</p> : null}
+      {notice ? <p role="status" className="text-sm text-muted-foreground">{notice}</p> : null}
+
+      <ConfirmSpendDialog
+        open={quote != null && !noLocked}
+        tier="billable"
+        title={`Unlock ${quote?.locked_count ?? 0} rows`}
+        description={quote?.can_unlock === false ? `Not enough credits: you need ${quote.required_credits} and have ${quote.available_credits}.` : "One credit per locked row. Rows that are already unlocked are not charged."}
+        estimatedCredits={quote?.required_credits}
+        affected={quote?.locked_count}
+        confirmLabel={quote?.can_unlock === false ? "Not enough credits" : "Unlock rows"}
+        confirming={unlock.loading}
+        onConfirm={() => { if (quote && quote.can_unlock !== false) void unlock.mutate(quote); }}
+        onCancel={() => setQuote(null)}
+      />
+      <ConfirmSpendDialog
+        open={confirmDelete}
+        tier="destructive"
+        title={`Delete ${rowIds.length} rows`}
+        description="The rows and everything in their cells are removed from this table."
+        affected={rowIds.length}
+        confirmLabel="Delete rows"
+        confirming={remove.loading}
+        onConfirm={() => void remove.mutate(undefined)}
+        onCancel={() => setConfirmDelete(false)}
+      />
+    </div>
+  );
+}

package/blocks/workbench/components/workbench-table-list.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+/**
+ * WorkbenchTableList: the workbenches of the workspace, a form to create one, and delete. Pick one to open it
+ * in a WorkbenchGrid. Pass `onOpen` to handle the pick yourself; OMIT it (for example as a stack nav page) and the
+ * component opens the chosen table in a WorkbenchGrid itself, with a back button.
+ *
+ * SDK operations, in order:
+ *   1. listWorkbenchTables    GET    /workbench/tables?page&limit&filter_name   (read)   { tables, total }
+ *   2. createWorkbenchTable   POST   /workbench/tables { name, entity_type }    (write)  entity_type is "contact" or "company"; the id is a UUID string
+ *   3. deleteWorkbenchTable   DELETE /workbench/tables/{table_id}               (destructive) ConfirmSpendDialog first; removes the rows too
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input, Label, 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 { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { WorkbenchGrid } from "./workbench-grid";
+import { pageItems } from "../lib/workbench-types";
+import type { WorkbenchTable } from "../lib/workbench-types";
+
+export interface WorkbenchTableListProps {
+  /** Called when a person opens a table (or right after one is created). Omit it and the table opens in a WorkbenchGrid inside this component. */
+  onOpen?: (table: WorkbenchTable) => void;
+  className?: string;
+}
+
+export function WorkbenchTableList({ onOpen, className }: WorkbenchTableListProps) {
+  const [name, setName] = useState("");
+  const [entity, setEntity] = useState<"contact" | "company">("contact");
+  const [search, setSearch] = useState("");
+  const [term, setTerm] = useState("");
+  useEffect(() => { const t = setTimeout(() => setTerm(search), 250); return () => clearTimeout(t); }, [search]);
+  const [deleting, setDeleting] = useState<WorkbenchTable | null>(null);
+  const [opened, setOpened] = useState<WorkbenchTable | null>(null);
+  const open = (t: WorkbenchTable) => { if (onOpen) onOpen(t); else setOpened(t); };
+
+  const tables = useG8Query(async (signal) => pageItems<WorkbenchTable>((await g8Get("/workbench/tables", { page: 1, limit: 100, filter_name: term || undefined }, { signal })).data), [term]);
+  const create = useG8Mutation(
+    async () => (await g8Post<WorkbenchTable>("/workbench/tables", { name: name.trim(), entity_type: entity })).data,
+    { onSuccess: (t) => { setName(""); void tables.refetch(); open(t); } },
+  );
+  const remove = useG8Mutation((id: string) => g8Delete(`/workbench/tables/${id}`), { onSuccess: () => { setDeleting(null); void tables.refetch(); } });
+
+  if (!onOpen && opened) {
+    return (
+      <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+        <div className="flex items-center gap-2">
+          <Button size="sm" variant="ghost" onClick={() => setOpened(null)}>Back to workbenches</Button>
+          <span className="text-sm font-medium">{opened.name}</span>
+        </div>
+        <WorkbenchGrid tableId={opened.id} />
+      </div>
+    );
+  }
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <form className="flex flex-wrap items-end gap-2" onSubmit={(e) => { e.preventDefault(); if (name.trim()) void create.mutate(undefined); }}>
+        <div className="flex flex-col gap-1">
+          <Label htmlFor="wb-new-name">New workbench</Label>
+          <Input id="wb-new-name" value={name} onChange={(e) => setName(e.target.value)} placeholder="Series B fintech accounts" />
+        </div>
+        <select aria-label="Records are" className="h-9 rounded-md border bg-background px-2" value={entity} onChange={(e) => setEntity(e.target.value as "contact" | "company")}>
+          <option value="contact">People</option>
+          <option value="company">Companies</option>
+        </select>
+        <Button type="submit" loading={create.loading} disabled={!name.trim()}>Create</Button>
+      </form>
+      {create.error ? <ApiError error={create.error} title="Could not create the workbench" /> : null}
+
+      <Input aria-label="Search workbenches" placeholder="Search by name" value={search} onChange={(e) => setSearch(e.target.value)} />
+      {tables.error ? <ApiError error={tables.error} title="Could not load workbenches" onRetry={() => void tables.refetch()} /> : null}
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the workbench" /> : null}
+      {tables.loading && !tables.data ? <Skeleton className="h-24 w-full" /> : null}
+      {!tables.loading && !tables.error && (tables.data ?? []).length === 0 ? <EmptyState title="No workbenches yet" description="Create one above, then paste rows or import people." /> : null}
+      <ul className="flex flex-col gap-2">
+        {(tables.data ?? []).map((t) => (
+          <li key={t.id} className="flex items-center justify-between gap-2 rounded-md border p-3">
+            <button type="button" className="flex flex-col text-left" onClick={() => open(t)}>
+              <span className="text-sm font-medium">{t.name}</span>
+              <span className="text-xs text-muted-foreground">{(t.row_count ?? 0).toLocaleString()} rows, {t.entity_type === "company" ? "companies" : "people"}</span>
+            </button>
+            <Button size="sm" variant="ghost" onClick={() => setDeleting(t)}>Delete</Button>
+          </li>
+        ))}
+      </ul>
+      <ConfirmSpendDialog
+        open={deleting != null}
+        tier="destructive"
+        title={`Delete "${deleting?.name ?? ""}"`}
+        description="The table, its columns and all of its rows are removed."
+        affected={deleting?.row_count ?? undefined}
+        confirmLabel="Delete workbench"
+        confirming={remove.loading}
+        onConfirm={() => deleting && void remove.mutate(deleting.id)}
+        onCancel={() => setDeleting(null)}
+      />
+    </div>
+  );
+}

package/blocks/workbench/hooks/use-workbench-table.ts

@@ -0,0 +1,30 @@
+"use client";
+
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { pageItems } from "../lib/workbench-types";
+import type { WorkbenchColumn, WorkbenchTable } from "../lib/workbench-types";
+
+/**
+ * A workbench table and its columns (`GET /workbench/tables/{id}` then `GET /workbench/tables/{id}/columns`).
+ * Rows are loaded by the grid in windows; columns are small, so they load whole. `refetch` re-reads both,
+ * which is what to call after a column was added or a run finished.
+ */
+export function useWorkbenchTable(tableId: string | null | undefined) {
+  const enabled = Boolean(tableId);
+  const table = useG8Query(async (signal) => (await g8Get<WorkbenchTable>(`/workbench/tables/${tableId}`, undefined, { signal })).data, [tableId], { enabled });
+  const columns = useG8Query(
+    async (signal) => pageItems<WorkbenchColumn>((await g8Get(`/workbench/tables/${tableId}/columns`, undefined, { signal })).data),
+    [tableId],
+    { enabled },
+  );
+  return {
+    table: table.data,
+    columns: columns.data ?? [],
+    loading: table.loading || columns.loading,
+    error: table.error ?? columns.error,
+    refetch: async () => {
+      await Promise.all([table.refetch(), columns.refetch()]);
+    },
+  };
+}

package/blocks/workbench/lib/waterfall-presets.ts

@@ -0,0 +1,119 @@
+"use client";
+
+/**
+ * Ready-made waterfall recipes for the fields people enrich most. Each step is one provider call; the
+ * waterfall tries them in order and stops at the first value. The provider/action/output path triples come
+ * from graph8's own waterfall templates (the same ones the app seeds), so a step the person does not touch
+ * works the way the app's would.
+ *
+ * `input_mapping` maps a provider's parameter to a graph8 target field (CONTACT_FIRST_NAME, COMPANY_WEBSITE...).
+ * The table's own columns must be mapped to those targets first (ColumnRecipeEditor, "Map columns" tab):
+ * a waterfall step whose inputs are not mapped has nothing to look up.
+ */
+
+export interface PresetStep {
+  provider: string;
+  action: string;
+  actionDisplayName: string;
+  outputField: string;
+  inputMapping: Record<string, string>;
+}
+
+export interface WaterfallPreset {
+  id: string;
+  label: string;
+  /** Default name for the new column. */
+  columnName: string;
+  steps: PresetStep[];
+}
+
+const PERSON_BY_NAME = { first_name: "CONTACT_FIRST_NAME", last_name: "CONTACT_LAST_NAME" } as const;
+const WEB = { domain: "COMPANY_WEBSITE" } as const;
+
+export const WATERFALL_PRESETS: WaterfallPreset[] = [
+  {
+    id: "work_email",
+    label: "Work email",
+    columnName: "Work email",
+    steps: [
+      { provider: "apollo", action: "enrich_person", actionDisplayName: "Enrich Person", outputField: "person.email", inputMapping: { ...PERSON_BY_NAME, ...WEB, linkedin_url: "CONTACT_LINKEDIN_URL" } },
+      { provider: "leadmagic", action: "email_finder", actionDisplayName: "Find Email", outputField: "email", inputMapping: { ...PERSON_BY_NAME, ...WEB, company_name: "COMPANY_NAME" } },
+      { provider: "prospeo", action: "find_email", actionDisplayName: "Find Email", outputField: "result.email", inputMapping: { linkedin_url: "CONTACT_LINKEDIN_URL", ...WEB, ...PERSON_BY_NAME } },
+      { provider: "hunter", action: "find_email", actionDisplayName: "Find Email", outputField: "data.email", inputMapping: { ...PERSON_BY_NAME, ...WEB, company_name: "COMPANY_NAME" } },
+      { provider: "dropcontact", action: "find_work_email", actionDisplayName: "Find Work Email", outputField: "result.email", inputMapping: { ...PERSON_BY_NAME, ...WEB, linkedin_url: "CONTACT_LINKEDIN_URL" } },
+    ],
+  },
+  {
+    id: "mobile_phone",
+    label: "Mobile phone",
+    columnName: "Mobile phone",
+    steps: [
+      { provider: "leadmagic", action: "mobile_finder", actionDisplayName: "Mobile Finder", outputField: "mobile_number", inputMapping: { ...PERSON_BY_NAME, linkedin_url: "CONTACT_LINKEDIN_URL" } },
+      { provider: "prospeo", action: "mobile_finder", actionDisplayName: "Mobile Finder", outputField: "phone.raw_format", inputMapping: { url: "CONTACT_LINKEDIN_URL" } },
+      { provider: "apollo", action: "enrich_person", actionDisplayName: "Enrich Person (Mobile)", outputField: "person.phone_numbers.raw_number", inputMapping: { linkedin_url: "CONTACT_LINKEDIN_URL", ...PERSON_BY_NAME, ...WEB } },
+    ],
+  },
+  {
+    id: "linkedin_url",
+    label: "Person LinkedIn URL",
+    columnName: "LinkedIn URL",
+    steps: [
+      { provider: "icypeas", action: "find_profile_urls", actionDisplayName: "Find Profile URLs", outputField: "profile.linkedin_url", inputMapping: { ...PERSON_BY_NAME, ...WEB } },
+      { provider: "apollo", action: "enrich_person", actionDisplayName: "Enrich Person", outputField: "person.linkedin_url", inputMapping: { ...PERSON_BY_NAME, ...WEB } },
+    ],
+  },
+  {
+    id: "company_phone",
+    label: "Company phone",
+    columnName: "Company phone",
+    steps: [{ provider: "apollo", action: "enrich_company", actionDisplayName: "Enrich Company", outputField: "organization.phone", inputMapping: { ...WEB } }],
+  },
+];
+
+/** The graph8 target fields a step reads, for example CONTACT_FIRST_NAME. */
+export function requiredTargets(steps: PresetStep[]): string[] {
+  return [...new Set(steps.flatMap((s) => Object.values(s.inputMapping)))].sort();
+}
+
+export interface ProviderInfo { provider: string; system_funded: boolean; byok_configured: boolean }
+
+/** The save body for `POST /workbench/tables/{id}/waterfall/configs`. Saving never runs or charges anything. */
+export function buildWaterfallConfig(name: string, steps: PresetStep[], catalog: ProviderInfo[], id: () => string) {
+  const known = new Map(catalog.map((p) => [p.provider, p]));
+  const columnId = `waterfall_${id().replace(/-/g, "_")}`;
+  return {
+    config: {
+      id: id(),
+      name,
+      column_id: columnId,
+      field_to_enrich: name,
+      data_type: "text",
+      is_existing_column: false,
+      steps: steps.map((s, order) => {
+        const p = known.get(s.provider);
+        return {
+          id: `step_${s.provider}_${order}`,
+          provider: s.provider,
+          action: s.action,
+          action_display_name: s.actionDisplayName,
+          output_field: s.outputField,
+          output_mapping: {},
+          input_mapping: s.inputMapping,
+          order,
+          config: {},
+          enabled: true,
+          // Own key wins; otherwise graph8's key (and its credits).
+          is_system_provider: p ? !p.byok_configured && p.system_funded : true,
+          stop_on_success: true,
+          confidence_threshold: 0,
+          max_retries: 0,
+        };
+      }),
+      output_successful_provider: false,
+      hide_provider_columns: true,
+      skip_existing_values: true,
+      skip_recently_enriched: true,
+      auto_update: false,
+    },
+  };
+}