@graph8/sdk 0.308.1 → 0.357.0

package/blocks/webchat/components/chat-widget-config.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+/**
+ * ChatWidgetConfig: pick a chat bot, style its widget, set starter questions, and get the embed code.
+ *
+ * SDK operations, in order:
+ *   1. listChatBots (GET /webchat/chat-bots)                              read    (START HERE: the bot id is the chat_bot_id of every other call)
+ *   2. createChatBot (POST /webchat/chat-bots)                            write
+ *   3. getWebchatSettings (GET /webchat/settings?chat_bot_id=&surface=)   read    (404 when the bot has no theme yet)
+ *   4. createWebchatSettings (POST /webchat/settings) / updateWebchatSettings (PATCH)   write  (LIVE: the next visitor sees it, there is no publish step)
+ *   5. listWebchatQuestions / createWebchatQuestion                       read / write
+ *   6. deleteWebchatQuestion (DELETE /webchat/questions/{id}?chat_bot_id=)   destructive -> ConfirmSpendDialog
+ *   7. getOrgSnippet (GET /snippet)                                       read    (the widget loads through the graph8 tracking snippet on your pages)
+ * Colours must be hex and sizes CSS lengths; the API also refuses an illegible text/background pair (422).
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, 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 { G8Error } from "@graph8/sdk";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { isCssLength, isHexColor, pickItems, readSettings } from "../lib/webchat-types";
+import type { ChatBot, StarterQuestion, WidgetSettings } from "../lib/webchat-types";
+
+export interface ChatWidgetConfigProps {
+  initialBotId?: string;
+  /** "external" is the public website widget (default); "internal" is the in-app one. */
+  surface?: "external" | "internal";
+}
+
+const EMPTY: WidgetSettings = { assistantName: "", darkMode: false, chatWidth: "", borderRadius: "", assistantMessageBgColor: "", assistantMessageTextColor: "" };
+
+function validate(s: WidgetSettings): string | null {
+  for (const key of ["assistantMessageBgColor", "assistantMessageTextColor"] as const) {
+    if (s[key] && !isHexColor(s[key] as string)) return "Colours must be hex, like #1a1a1a.";
+  }
+  for (const key of ["chatWidth", "borderRadius"] as const) {
+    if (s[key] && !isCssLength(s[key] as string)) return "Sizes must be CSS lengths, like 380px or 1rem.";
+  }
+  return null;
+}
+
+export function ChatWidgetConfig({ initialBotId, surface = "external" }: ChatWidgetConfigProps) {
+  const bots = useG8Query((signal) => g8Get<unknown>("/webchat/chat-bots", {}, { signal }).then((r) => pickItems<ChatBot>(r.data)), []);
+  const [botId, setBotId] = useState(initialBotId ?? "");
+  const [newBot, setNewBot] = useState("");
+  const [draft, setDraft] = useState<WidgetSettings>(EMPTY);
+  const [exists, setExists] = useState(false);
+  const [question, setQuestion] = useState("");
+  const [toDelete, setToDelete] = useState<StarterQuestion | null>(null);
+  const id = botId || bots.data?.find((b) => b.is_default)?.id || bots.data?.[0]?.id || "";
+  const q = { chat_bot_id: id, surface };
+
+  const settings = useG8Query((signal) => g8Get<unknown>("/webchat/settings", q, { signal }).then((r) => readSettings(r.data)).catch((e: unknown) => {
+    if (e instanceof G8Error && e.status === 404) return null;
+    throw e;
+  }), [id, surface], { enabled: Boolean(id) });
+  const questions = useG8Query((signal) => g8Get<unknown>("/webchat/questions", { chat_bot_id: id }, { signal }).then((r) => pickItems<StarterQuestion>(r.data)), [id], { enabled: Boolean(id) });
+  const snippet = useG8Query((signal) => g8Get<{ script_tag?: string }>("/snippet", {}, { signal }).then((r) => r.data), []);
+
+  // A half-typed question or an open delete belongs to the previous bot.
+  useEffect(() => {
+    setQuestion("");
+    setToDelete(null);
+  }, [id]);
+
+  useEffect(() => {
+    if (settings.loading) return;
+    setExists(settings.data != null);
+    setDraft({ ...EMPTY, ...(settings.data ?? {}) });
+  }, [settings.data, settings.loading, id]);
+
+  const createBot = useG8Mutation(async () => (await g8Post<ChatBot>("/webchat/chat-bots", { name: newBot.trim() })).data, { onSuccess: (b) => { setNewBot(""); setBotId(b.id); void bots.refetch(); } });
+  const save = useG8Mutation(async () => {
+    const body = { chat_bot_id: id, surface, ...Object.fromEntries(Object.entries(draft).filter(([, v]) => v !== "" && v !== undefined)) };
+    return exists ? g8Patch("/webchat/settings", body) : g8Post("/webchat/settings", body);
+  }, { onSuccess: () => void settings.refetch() });
+  const addQuestion = useG8Mutation(() => g8Post("/webchat/questions", { chat_bot_id: id, question: question.trim(), surface }), { onSuccess: () => { setQuestion(""); void questions.refetch(); } });
+  const removeQuestion = useG8Mutation((qn: StarterQuestion) => g8Delete(`/webchat/questions/${encodeURIComponent(qn.id)}`, { query: { chat_bot_id: id, expected_revision: qn.revision } }), { onSuccess: () => { setToDelete(null); void questions.refetch(); } });
+
+  if (bots.error) return <ApiError error={bots.error} title="Could not load chat bots" onRetry={() => void bots.refetch()} />;
+  if (bots.loading && !bots.data) return <Skeleton className="h-40 w-full" aria-busy="true" />;
+  const problem = validate(draft);
+  const set = (patch: WidgetSettings): void => setDraft((d) => ({ ...d, ...patch }));
+  return (
+    <div className="grid gap-4">
+      <Card>
+        <CardHeader><CardTitle>Chat bot</CardTitle></CardHeader>
+        <CardContent className="grid gap-3">
+          {(bots.data ?? []).length > 0 ? (
+            <select aria-label="Chat bot" className="border-input bg-background h-9 max-w-sm rounded-md border px-2 text-sm" value={id} onChange={(e) => setBotId(e.target.value)}>
+              {(bots.data ?? []).map((b) => <option key={b.id} value={b.id}>{b.name}{b.is_default ? " (default)" : ""}</option>)}
+            </select>
+          ) : <EmptyState title="No chat bot yet" description="Create one to configure its widget." />}
+          <form className="flex max-w-sm gap-2" onSubmit={(e) => { e.preventDefault(); if (newBot.trim()) void createBot.mutate(undefined); }}>
+            <Input aria-label="New bot name" placeholder="New bot name" value={newBot} onChange={(e) => setNewBot(e.target.value)} />
+            <Button type="submit" size="sm" variant="outline" loading={createBot.loading} disabled={!newBot.trim()}>Create bot</Button>
+          </form>
+          {createBot.error ? <ApiError error={createBot.error} title="Could not create the bot" /> : null}
+        </CardContent>
+      </Card>
+      {id ? (
+        <>
+          <Card>
+            <CardHeader><CardTitle>Widget appearance</CardTitle></CardHeader>
+            <CardContent className="grid gap-3">
+              {settings.error ? <ApiError error={settings.error} title="Could not load the widget settings" onRetry={() => void settings.refetch()} /> : null}
+              <p className="text-muted-foreground text-sm">Changes are live for the next visitor. {settings.loading ? "Loading..." : exists ? "" : "This bot uses default styling until you save."}</p>
+              <div className="grid gap-3 sm:grid-cols-2">
+                <div><Label htmlFor="g8-wc-name" className="mb-1">Assistant name</Label><Input id="g8-wc-name" value={draft.assistantName ?? ""} onChange={(e) => set({ assistantName: e.target.value })} /></div>
+                <div><Label htmlFor="g8-wc-width" className="mb-1">Chat width</Label><Input id="g8-wc-width" placeholder="380px" value={draft.chatWidth ?? ""} onChange={(e) => set({ chatWidth: e.target.value })} /></div>
+                <div><Label htmlFor="g8-wc-radius" className="mb-1">Corner radius</Label><Input id="g8-wc-radius" placeholder="12px" value={draft.borderRadius ?? ""} onChange={(e) => set({ borderRadius: e.target.value })} /></div>
+                <div><Label htmlFor="g8-wc-bg" className="mb-1">Reply background</Label><Input id="g8-wc-bg" placeholder="#f4f4f5" value={draft.assistantMessageBgColor ?? ""} onChange={(e) => set({ assistantMessageBgColor: e.target.value })} /></div>
+                <div><Label htmlFor="g8-wc-text" className="mb-1">Reply text</Label><Input id="g8-wc-text" placeholder="#111111" value={draft.assistantMessageTextColor ?? ""} onChange={(e) => set({ assistantMessageTextColor: e.target.value })} /></div>
+                <label className="flex items-center gap-2 self-end text-sm"><input type="checkbox" checked={Boolean(draft.darkMode)} onChange={(e) => set({ darkMode: e.target.checked })} />Dark mode</label>
+              </div>
+              {problem ? <p role="alert" className="text-sm text-red-700">{problem}</p> : null}
+              {save.error ? <ApiError error={save.error} title="Could not save the widget settings" /> : null}
+              <div><Button loading={save.loading} disabled={Boolean(problem) || settings.loading} onClick={() => void save.mutate(undefined)}>{exists ? "Save changes" : "Create widget settings"}</Button></div>
+            </CardContent>
+          </Card>
+          <Card>
+            <CardHeader><CardTitle>Starter questions</CardTitle></CardHeader>
+            <CardContent className="grid gap-3">
+              {questions.error ? <ApiError error={questions.error} title="Could not load questions" onRetry={() => void questions.refetch()} /> : (questions.data ?? []).length === 0 ? <p className="text-muted-foreground text-sm">No starter questions yet.</p> : (
+                <ul className="grid gap-1">{(questions.data ?? []).map((qn) => <li key={qn.id} className="flex items-center justify-between text-sm"><span>{qn.question}</span><Button size="sm" variant="ghost" onClick={() => setToDelete(qn)}>Delete</Button></li>)}</ul>
+              )}
+              <form className="flex gap-2" onSubmit={(e) => { e.preventDefault(); if (question.trim()) void addQuestion.mutate(undefined); }}>
+                <Input aria-label="New question" placeholder="What does it cost?" value={question} onChange={(e) => setQuestion(e.target.value)} />
+                <Button type="submit" size="sm" loading={addQuestion.loading} disabled={!question.trim()}>Add question</Button>
+              </form>
+              {addQuestion.error ? <ApiError error={addQuestion.error} title="Could not add the question" /> : null}
+            </CardContent>
+          </Card>
+        </>
+      ) : null}
+      <Card>
+        <CardHeader><CardTitle>Put the widget on your site</CardTitle></CardHeader>
+        <CardContent className="grid gap-2">
+          <p className="text-muted-foreground text-sm">The widget loads through the graph8 tracking snippet. Add it to every page that should show the chat.</p>
+          {snippet.error ? <ApiError error={snippet.error} title="Could not load the snippet" onRetry={() => void snippet.refetch()} /> : snippet.data?.script_tag ? <pre aria-label="Embed code" className="bg-muted overflow-auto rounded-md p-3 text-xs">{snippet.data.script_tag}</pre> : <Skeleton className="h-12 w-full" />}
+        </CardContent>
+      </Card>
+      <ConfirmSpendDialog
+        open={toDelete !== null}
+        tier="destructive"
+        title="Delete this starter question?"
+        description={<><p>{toDelete?.question}</p>{removeQuestion.error ? <ApiError error={removeQuestion.error} title="Could not delete" /> : null}</>}
+        confirmLabel="Delete"
+        confirming={removeQuestion.loading}
+        onCancel={() => setToDelete(null)}
+        onConfirm={() => { if (toDelete) void removeQuestion.mutate(toDelete); }}
+      />
+    </div>
+  );
+}

package/blocks/webchat/components/conversation-list.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+/**
+ * ConversationList: the people who used the chat widget, identified where possible, with the engagement funnel.
+ *
+ * SDK operations, in order:
+ *   1. listWebchatVisitors (GET /webchat/visitors?page&page_size&identified_only&search)   read
+ *   2. getWebchatVisitorFunnel (GET /webchat/visitors/funnel?bot_id=)                      read   (per-event counts and top pages)
+ * Message threads themselves live in the inbox (the `inbox` block); this list is the widget's visitors. Note the funnel's
+ * `abandonment_window_minutes` is accepted but not applied by the API yet, so the component does not offer it.
+ */
+
+import { 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 { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { pickItems, visitorCompany, visitorEmail, visitorLastSeen, visitorName } from "../lib/webchat-types";
+import type { Visitor } from "../lib/webchat-types";
+
+export interface ConversationListProps {
+  /** Limit the funnel to one bot. */
+  botId?: string;
+  pageSize?: number;
+  onSelectVisitor?: (visitor: Visitor) => void;
+}
+
+export function ConversationList({ botId, pageSize = 25, onSelectVisitor }: ConversationListProps) {
+  const [page, setPage] = useState(1);
+  const [identifiedOnly, setIdentifiedOnly] = useState(false);
+  const [text, setText] = useState("");
+  const [search, setSearch] = useState("");
+  const visitors = useG8Query(
+    (signal) => g8Get<unknown>("/webchat/visitors", { page, page_size: pageSize, identified_only: identifiedOnly || undefined, search: search || undefined }, { signal }).then((r) => ({ items: pickItems<Visitor>(r.data), total: (r.data as { total?: number } | undefined)?.total })),
+    [page, pageSize, identifiedOnly, search],
+  );
+  const funnel = useG8Query((signal) => g8Get<Record<string, unknown>>("/webchat/visitors/funnel", { bot_id: botId }, { signal }).then((r) => r.data), [botId]);
+  const items = visitors.data?.items ?? [];
+  const counts = Object.entries((funnel.data?.counts ?? funnel.data?.events ?? {}) as Record<string, unknown>).filter(([, v]) => typeof v === "number") as Array<[string, number]>;
+
+  return (
+    <div className="grid gap-3">
+      {counts.length > 0 ? (
+        <dl className="grid grid-cols-2 gap-2 sm:grid-cols-4">
+          {counts.map(([k, v]) => <div key={k} className="rounded-md border p-3"><dt className="text-muted-foreground text-xs">{k.replace(/_/g, " ")}</dt><dd className="text-lg font-semibold">{v.toLocaleString()}</dd></div>)}
+        </dl>
+      ) : null}
+      <form className="flex flex-wrap items-center gap-2" onSubmit={(e) => { e.preventDefault(); setPage(1); setSearch(text.trim()); }}>
+        <Input aria-label="Search visitors" placeholder="Search by name or email" className="max-w-xs" value={text} onChange={(e) => setText(e.target.value)} />
+        <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={identifiedOnly} onChange={(e) => { setPage(1); setIdentifiedOnly(e.target.checked); }} />Identified only</label>
+        <Button type="submit" size="sm" variant="outline">Search</Button>
+      </form>
+      {visitors.error ? <ApiError error={visitors.error} title="Could not load visitors" onRetry={() => void visitors.refetch()} /> : visitors.loading && !visitors.data ? (
+        <div aria-busy="true" className="grid gap-2"><Skeleton className="h-9 w-full" /><Skeleton className="h-9 w-full" /></div>
+      ) : items.length === 0 ? <EmptyState title="No chat visitors yet" description="People appear here after they use the widget on your site." /> : (
+        <Table>
+          <TableHeader><TableRow><TableHead>Visitor</TableHead><TableHead>Email</TableHead><TableHead>Company</TableHead><TableHead>Last seen</TableHead></TableRow></TableHeader>
+          <TableBody>
+            {items.map((v, i) => (
+              <TableRow key={String(v.id ?? i)} className={onSelectVisitor ? "cursor-pointer" : undefined} onClick={() => onSelectVisitor?.(v)}>
+                <TableCell>{visitorName(v)}</TableCell><TableCell>{visitorEmail(v)}</TableCell><TableCell>{visitorCompany(v)}</TableCell><TableCell>{visitorLastSeen(v)}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
+      <div className="flex justify-end">
+        <Button size="sm" variant="ghost" disabled={page <= 1} onClick={() => setPage(page - 1)}>Previous</Button>
+        <Button size="sm" variant="ghost" disabled={items.length < pageSize} onClick={() => setPage(page + 1)}>Next</Button>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,83 @@
+"use client";
+
+/**
+ * Types and helpers for the webchat block. Webchat responses are passed through from the app and only partly typed,
+ * so readers accept the shapes the app is known to send. The chat bot id (`chat_bot_id`) is the key almost every
+ * call needs: start from listChatBots.
+ */
+
+export interface ChatBot {
+  id: string;
+  name: string;
+  is_default?: boolean;
+  revision?: number;
+}
+
+export interface WidgetSettings {
+  assistantName?: string;
+  darkMode?: boolean;
+  chatWidth?: string;
+  borderRadius?: string;
+  assistantMessageBgColor?: string;
+  assistantMessageTextColor?: string;
+}
+
+export interface StarterQuestion {
+  id: string;
+  question: string;
+  active?: boolean;
+  revision?: number;
+}
+
+export type Visitor = Record<string, unknown> & { id?: string | number };
+
+export function pickItems<T>(data: unknown, key = "items"): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const v = data && typeof data === "object" ? (data as Record<string, unknown>)[key] : undefined;
+  return Array.isArray(v) ? (v as T[]) : [];
+}
+
+/** Settings may arrive bare or wrapped in `settings`. */
+export const SETTING_KEYS = ["assistantName", "darkMode", "chatWidth", "borderRadius", "assistantMessageBgColor", "assistantMessageTextColor"] as const;
+
+export function readSettings(data: unknown): WidgetSettings {
+  const d = (data ?? {}) as Record<string, unknown>;
+  const row = ((d.settings as Record<string, unknown> | undefined) ?? d) || {};
+  // Only the fields this screen edits: a PATCH must stay a real partial update, never echo back the whole row.
+  const out: Record<string, unknown> = {};
+  for (const key of SETTING_KEYS) if (row[key] !== undefined && row[key] !== null) out[key] = row[key];
+  return out as WidgetSettings;
+}
+
+export function isHexColor(value: string): boolean {
+  return /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(value.trim());
+}
+
+export function isCssLength(value: string): boolean {
+  return /^\d+(\.\d+)?(px|rem|em|%|vw|vh)$/.test(value.trim());
+}
+
+function firstText(v: Visitor, keys: string[]): string {
+  for (const k of keys) {
+    const x = v[k];
+    if (typeof x === "string" && x) return x;
+  }
+  return "";
+}
+
+export function visitorName(v: Visitor): string {
+  return firstText(v, ["name", "full_name", "display_name", "email", "visitor_id"]) || `Visitor ${v.id ?? ""}`.trim();
+}
+
+export function visitorEmail(v: Visitor): string {
+  return firstText(v, ["email", "work_email"]);
+}
+
+export function visitorCompany(v: Visitor): string {
+  return firstText(v, ["company", "company_name", "company_domain"]);
+}
+
+export function visitorLastSeen(v: Visitor): string {
+  const t = firstText(v, ["last_seen_at", "last_seen", "last_message_at", "updated_at"]);
+  return t && !Number.isNaN(new Date(t).getTime()) ? new Date(t).toLocaleString() : t;
+}

package/blocks/webchat/recipes/create-bot-and-style-widget.ts

@@ -0,0 +1,24 @@
+/**
+ * @title Create a chat bot, style its widget and add starter questions
+ * @when First-time chat setup. Settings are LIVE the moment they are saved (no publish step), so style a new bot
+ * before the snippet is on production pages. A bot with no answering agent answers nothing until one is mapped.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+// 1. The bot id is the chat_bot_id every other call needs.
+const bot = await g8.api.webChat.createChatBot({ body: { name: "Website chat" } });
+const chatBotId = (bot.data as { id?: string }).id;
+if (!chatBotId) throw new Error("No bot id returned");
+
+// 2. ONE settings row per bot and surface; POST creates it (409 if it exists: use PATCH then).
+await g8.api.webChat.createWebchatSettings({
+  body: { chat_bot_id: chatBotId, surface: "external", assistantName: "Ada", chatWidth: "380px", borderRadius: "12px", assistantMessageBgColor: "#f4f4f5", assistantMessageTextColor: "#111111" },
+});
+
+// 3. Starter questions shown in the launcher.
+for (const question of ["What does it cost?", "Can I book a demo?"]) {
+  await g8.api.webChat.createWebchatQuestion({ body: { chat_bot_id: chatBotId, question, surface: "external" } });
+}
+console.log("bot", chatBotId);

package/blocks/webchat/recipes/list-chat-visitors.ts

@@ -0,0 +1,24 @@
+/**
+ * @title List identified chat visitors and the engagement funnel
+ * @when A daily pull of people who chatted, to route hot ones to sales. Visitors come back as open dicts, so read
+ * fields defensively. The funnel's `abandonment_window_minutes` is accepted but not applied by the API yet.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function identifiedVisitors(max = 200): Promise<Array<Record<string, unknown>>> {
+  const out: Array<Record<string, unknown>> = [];
+  for (let page = 1; out.length < max; page += 1) {
+    const res = await g8.api.webChat.listWebchatVisitors({ query: { page, page_size: 50, identified_only: true } });
+    const items = (res.data as { items?: Array<Record<string, unknown>> }).items ?? [];
+    out.push(...items);
+    if (items.length < 50) break;
+  }
+  return out.slice(0, max);
+}
+
+export async function funnel(botId?: string): Promise<unknown> {
+  const res = await g8.api.webChat.getWebchatVisitorFunnel({ query: { bot_id: botId } });
+  return res.data;
+}

package/blocks/workbench/README.md

@@ -0,0 +1,135 @@
+# workbench
+
+A Clay-style table: rows are records (people or companies), columns are plain data or the output of a recipe (an AI
+prompt, a provider waterfall, a formula). You add rows, add recipe columns, **price a run for free**, confirm the
+price, run it, and watch it finish. Finished rows go to a list. Builds on `enrichment` (provider catalog) and `lists`
+(the destination picker).
+
+Install: `npx @graph8/sdk add workbench` (installs `foundation`, `crm`, `enrichment` and `lists` first).
+
+## What you get
+
+| Component | Use it for | Props |
+|---|---|---|
+| `WorkbenchTableList` | Pick, create (people or companies) or delete a workbench | `onOpen(table)` (optional: omit it and the table opens in a `WorkbenchGrid` inside the component) |
+| `WorkbenchGrid` | The table: select rows, edit cells, add rows or columns, run recipe columns, act on the selection | `tableId`, `pageSize` |
+| `WorkbenchAddRows` | Type a row or paste a spreadsheet (header line = columns) | `tableId`, `columns`, `onAdded` |
+| `ColumnRecipeEditor` | Add an AI, enrichment, formula or plain column; map your columns to graph8 targets | `tableId`, `columns`, `entityType`, `onSaved` |
+| `RunProgress` | Quote, confirm, run and follow one recipe column | `tableId`, `target`, `rowIds`, `label`, `onFinished` |
+| `WorkbenchRowActions` | Unlock locked rows, send rows to a list, delete rows | `tableId`, `rowIds`, `entityType`, `onChanged` |
+
+Hook `useWorkbenchTable(tableId)` (table + columns). `WorkbenchGrid` already composes the other four panels around one
+table; use them alone only when you build your own layout.
+
+## Cost, in plain numbers (every billable step is confirmed)
+
+| Action | Cost | Confirmed with |
+|---|---|---|
+| Add/paste/edit rows, add columns, save an AI prompt or a waterfall | free (saving never runs anything) | nothing |
+| Run an AI or waterfall column | the quote's `required_credits` (free to ask); graph8-key providers spend, your own keys do not | `ConfirmSpendDialog` (billable) with that number |
+| Unlock locked rows | 1 credit per locked row (quote first) | `ConfirmSpendDialog` (billable) |
+| Import people from a search | billable; rows land LOCKED (see `recipes/import-from-search.ts`) | confirm in your UI |
+| Scrape the web into the table | per result, plus enrichment if `auto_enrich` (see `recipes/scrape-into-table.ts`) | confirm in your UI |
+| Delete rows or a table | free, irreversible | `ConfirmSpendDialog` (destructive) |
+
+The quote endpoints also return `available_credits` and a shortfall, so the dialog can say you cannot afford a run.
+
+## The flow, with the ids that pass between steps
+
+1. `GET /workbench/tables` -> pick or `POST /workbench/tables { name, entity_type }` -> `table_id` (a UUID string).
+2. Rows: `POST .../import/paste { headers, rows }` (creates a column per header) or `POST .../rows { data }` where `data` is keyed
+   by the column's **machine name** (`^[a-z][a-z0-9_]*$`), not its display name. Read `GET .../columns` first.
+3. Columns: `POST .../columns { name, display_name }` -> `{ id }` (the **numeric** column id); AI prompt:
+   `PUT .../columns/{id}/ai-config { prompt, usecase }`, where `{{machine_name}}` in the prompt reads another cell of the row.
+   Waterfall: map your columns to graph8 targets (`PUT .../columns/{id}/mapping { mapping_target: "CONTACT_FIRST_NAME" }`), then
+   `POST .../waterfall/configs { config }`. Afterwards `GET .../columns` shows the new column with `enrichment_type` `ai` or `waterfall`.
+4. Quote (free): `POST .../ai/validate-credits { column_id, row_ids? }` or `POST .../waterfall/configs/{column_id}/validate-credits`
+   -> `required_credits`, `available_credits`, `estimated_records`, `quote_id`, `quote_expires_at` (about 5 minutes).
+5. A person confirms. Run: `POST .../columns/{id}/ai/run` or `.../waterfall/configs/{column_id}/run` with
+   `{ approved_max_credits: required_credits, quote_expires_at, quote_id, row_ids? }` -> 202 `{ job_id }`. **No `row_ids` = every row.**
+   An expired quote, or a price that grew since, is refused until you re-quote.
+6. Poll `GET .../history?limit=10` (`useJobPoll`, backoff; there is no stream): the run is the receipt whose `external_ref` is the
+   `job_id`; it is final at `completed`, `partial`, `failed` or `cancelled`. `GET .../analytics` gives rows per status meanwhile.
+7. Read results with `GET .../rows?start_row&end_row` (a recipe writes `extracted_data`, imports write `raw_data`), then
+   `POST .../export { row_ids, list_id }` to send them to a list.
+
+Locked rows (`credit_charged: false`) hold masked cells (`"***"`): unlock them (quote, confirm, 1 credit per row) before using the values.
+
+```tsx
+"use client";
+import { useState } from "react";
+import { WorkbenchTableList } from "@/components/g8/workbench/workbench-table-list";
+import { WorkbenchGrid } from "@/components/g8/workbench/workbench-grid";
+
+export function Workbench() {
+  const [tableId, setTableId] = useState<string | null>(null);
+  return tableId ? <WorkbenchGrid tableId={tableId} /> : <WorkbenchTableList onOpen={(t) => setTableId(t.id)} />;
+}
+```
+
+(`add` flattens `components/` into `components/g8/workbench/`; adjust the alias to your app.)
+
+## Prerequisites (a human must do these)
+
+- `enrichment-and-lists-installed` (app): the CLI installs them.
+- `proxy-allowlist` (app): `allowedPrefixes` includes `workbench`, `enrichment`, `lists`.
+- `provider-keys` (api): providers graph8 does not fund need the workspace's own key in graph8 settings (no API for it).
+- `credits` (api): the workspace needs credits for AI columns, graph8-funded providers, scraping and unlocking.
+
+## Defaults the agent can use without asking
+
+| Decision | Default |
+|---|---|
+| Rows a run covers | the selected rows; with no selection, every row (quote and dialog say so) |
+| Waterfall auto-update on new rows | off: saving a waterfall never starts spending by itself |
+| Waterfall providers and order | the preset's order, own key if configured else graph8's |
+| AI column web research | off |
+| Where finished rows go | a list from the picker in the row actions panel |
+
+Ask the person: who approves a run's price (the proxy's `authorize` decides who may call at all).
+
+## Recipes
+
+| File | Does |
+|---|---|
+| `recipes/build-enriched-table.ts` | Create a table, paste rows, add an AI column, quote, run, poll, read the rows |
+| `recipes/waterfall-column.ts` | Map columns, save a work-email waterfall, quote, run |
+| `recipes/import-from-search.ts` | Free search preview, billable import (locked rows), unlock quote and unlock, export to a list |
+| `recipes/scrape-into-table.ts` | Free credit estimate, run the built-in scraper with it as the cap, poll the run |
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| addWorkbenchColumn | POST /workbench/tables/{table_id}/columns | write | ColumnRecipeEditor |
+| addWorkbenchRow | POST /workbench/tables/{table_id}/rows | write | WorkbenchAddRows |
+| bulkDeleteWorkbenchRows | POST /workbench/tables/{table_id}/rows/bulk-delete | destructive | WorkbenchRowActions |
+| createWorkbenchFormulaColumns | POST /workbench/tables/{table_id}/formula-columns | write | ColumnRecipeEditor |
+| createWorkbenchTable | POST /workbench/tables | write | WorkbenchTableList |
+| deleteWorkbenchTable | DELETE /workbench/tables/{table_id} | destructive | WorkbenchTableList |
+| estimateWorkbenchScraperCredits | GET /workbench/scraper/credit-estimate | read | recipes |
+| exportWorkbenchTable | POST /workbench/tables/{table_id}/export | write | WorkbenchRowActions |
+| getWorkbenchAnalytics | GET /workbench/tables/{table_id}/analytics | read | RunProgress |
+| getWorkbenchHistory | GET /workbench/tables/{table_id}/history | read | RunProgress |
+| getWorkbenchScraperRun | GET /workbench/tables/{table_id}/scraper/runs/{run_id} | read | recipes |
+| getWorkbenchTable | GET /workbench/tables/{table_id} | read | WorkbenchGrid, useWorkbenchTable |
+| importWorkbenchFromSearch | POST /workbench/tables/{table_id}/import/search | billable | recipes |
+| listEnrichmentProviders | GET /enrichment/providers | read | ColumnRecipeEditor |
+| listWorkbenchColumns | GET /workbench/tables/{table_id}/columns | read | WorkbenchGrid, useWorkbenchTable |
+| listWorkbenchRows | GET /workbench/tables/{table_id}/rows | read | WorkbenchGrid |
+| listWorkbenchTables | GET /workbench/tables | read | WorkbenchTableList |
+| listWorkbenchTargetFields | GET /workbench/target-fields | read | ColumnRecipeEditor |
+| mapWorkbenchColumn | PUT /workbench/tables/{table_id}/columns/{column_id}/mapping | write | ColumnRecipeEditor |
+| pasteImportWorkbenchRows | POST /workbench/tables/{table_id}/import/paste | write | WorkbenchAddRows |
+| previewWorkbenchSearchImport | POST /workbench/tables/{table_id}/import/search/preview | read | recipes |
+| quoteWorkbenchAiRun | POST /workbench/tables/{table_id}/ai/validate-credits | read | RunProgress |
+| quoteWorkbenchUnlock | POST /workbench/tables/{table_id}/unlock-quote | read | WorkbenchRowActions |
+| quoteWorkbenchWaterfallRun | POST /workbench/tables/{table_id}/waterfall/configs/{column_id}/validate-credits | read | RunProgress |
+| runWorkbenchColumnAi | POST /workbench/tables/{table_id}/columns/{col_id}/ai/run | billable | RunProgress |
+| runWorkbenchDefaultAi | POST /workbench/tables/{table_id}/ai/run | billable | RunProgress |
+| runWorkbenchScraper | POST /workbench/tables/{table_id}/scraper/runs | billable | recipes |
+| runWorkbenchWaterfall | POST /workbench/tables/{table_id}/waterfall/configs/{column_id}/run | billable | RunProgress |
+| saveWorkbenchColumnAiConfig | PUT /workbench/tables/{table_id}/columns/{col_id}/ai-config | write | ColumnRecipeEditor |
+| saveWorkbenchWaterfall | POST /workbench/tables/{table_id}/waterfall/configs | write | ColumnRecipeEditor |
+| unlockWorkbenchRows | POST /workbench/tables/{table_id}/unlock-rows | billable | WorkbenchRowActions |
+| updateWorkbenchRow | PATCH /workbench/tables/{table_id}/rows/{row_id} | write | WorkbenchGrid |