@graph8/sdk 0.308.1 → 0.357.0

package/blocks/forms/components/site-audit-panel.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+/**
+ * SiteAuditPanel: forms on your site that graph8 is NOT capturing, from the latest crawl.
+ *
+ * SDK operations, in order:
+ *   1. getSiteAudit (GET /forms/site-audit)                              read    (findings of the last crawl)
+ *   2. requestSiteAuditScan (POST /forms/site-audit/scan)                write   (crawl again; asynchronous, one per org per minute)
+ *   3. updateSiteAuditFinding (PATCH /forms/site-audit/findings/{id})    write   (acknowledge, ignore or resolve)
+ * The scan is queued, not finished: the panel re-reads the audit a few times after you ask (useJobPoll) until the
+ * last scan time changes.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { 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 { useJobPoll } from "@/g8/hooks/use-job-poll";
+
+interface Finding { id: string; severity?: string; page_url?: string; form_selector?: string; evidence?: string; recommendation?: string; status: string }
+interface Audit { last_scan_at: string | null; findings: Finding[]; summary?: { open?: number } }
+
+export function SiteAuditPanel() {
+  const audit = useG8Query((signal) => g8Get<Audit>("/forms/site-audit", {}, { signal }).then((r) => r.data), []);
+  const before = audit.data?.last_scan_at ?? null;
+  const poll = useJobPoll((signal) => g8Get<Audit>("/forms/site-audit", {}, { signal }).then((r) => r.data), {
+    enabled: false,
+    intervalMs: 3000,
+    maxAttempts: 20,
+    isTerminal: (a) => a.last_scan_at !== before,
+    onDone: () => void audit.refetch(),
+  });
+  const scan = useG8Mutation(() => g8Post("/forms/site-audit/scan"), { onSuccess: () => poll.start() });
+  const [busyId, setBusyId] = useState<string | null>(null);
+  const triage = useG8Mutation((v: { id: string; status: string }) => g8Patch(`/forms/site-audit/findings/${encodeURIComponent(v.id)}`, { status: v.status }), { onSuccess: () => void audit.refetch() });
+  const triageOne = async (id: string, status: string): Promise<void> => {
+    setBusyId(id);
+    await triage.mutate({ id, status });
+    setBusyId(null);
+  };
+
+  if (audit.error) return <ApiError error={audit.error} title="Could not load the site audit" onRetry={() => void audit.refetch()} />;
+  if (audit.loading && !audit.data) return <Skeleton className="h-24 w-full" aria-busy="true" />;
+  const open = (audit.data?.findings ?? []).filter((f) => f.status === "open" || f.status === "acknowledged");
+  return (
+    <section className="grid gap-3" aria-label="Site audit">
+      <div className="flex items-center justify-between">
+        <p className="text-muted-foreground text-sm">{audit.data?.last_scan_at ? `Last scan ${new Date(audit.data.last_scan_at).toLocaleString()}` : "Never scanned"}</p>
+        <Button size="sm" loading={scan.loading || poll.polling} onClick={() => void scan.mutate(undefined)}>{poll.polling ? "Scanning..." : "Scan my site again"}</Button>
+      </div>
+      {scan.error ? <ApiError error={scan.error} title="Could not start a scan" /> : null}
+      {triage.error ? <ApiError error={triage.error} title="Could not update the finding" /> : null}
+      {open.length === 0 ? <EmptyState title="No uncaptured forms found" description="Every form the last crawl found is being captured." /> : (
+        <ul className="grid gap-2">
+          {open.map((f) => (
+            <li key={f.id} className="rounded-md border p-3 text-sm">
+              <p className="font-medium">{f.severity ? `${f.severity}: ` : ""}{f.evidence ?? f.form_selector}</p>
+              <p className="text-muted-foreground truncate">{f.page_url}</p>
+              {f.recommendation ? <p>{f.recommendation}</p> : null}
+              <div className="mt-2 flex gap-2">
+                <Button size="sm" variant="outline" loading={busyId === f.id} disabled={busyId !== null} onClick={() => void triageOne(f.id, "ignored")}>Ignore</Button>
+                <Button size="sm" variant="outline" disabled={busyId !== null} onClick={() => void triageOne(f.id, "resolved")}>Mark resolved</Button>
+              </div>
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  );
+}

package/blocks/forms/components/submissions-table.tsx

@@ -0,0 +1,158 @@
+"use client";
+
+/**
+ * SubmissionsTable: what people submitted to one form, what happened to each lead, and a retry for failures.
+ *
+ * SDK operations, in order:
+ *   1. searchFormSubmissions (POST /forms/{form_key}/submissions)               read   (a read; POST only because filters are a body)
+ *   2. getFormSubmissionTrace (GET .../submissions/{submission_id}/trace)       read   ("the customer filled in the form, where did it go")
+ *   3. retryFormDelivery (POST /forms/deliveries/{receipt_id}/retry)            external -> ConfirmSpendDialog (re-delivers ONE lead)
+ * Identifying fields are redacted for keys without the Signals write capability: an empty-looking cell can be a
+ * redaction, not a missing value. Test submissions are marked.
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } 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 { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { cellText, pickItems, submissionFailed, submissionState } from "../lib/form-types";
+import type { FormRef, FormSubmission } from "../lib/form-types";
+
+export interface SubmissionsTableProps {
+  /** The form to show. Omit it (for example as a stack nav page) and a form picker is shown instead. */
+  form?: FormRef;
+  /** Rows per page. Default 20. */
+  pageSize?: number;
+  /** Max submitted-field columns. Default 4. */
+  maxFieldColumns?: number;
+}
+
+interface Page { items: FormSubmission[]; total: number }
+
+function SubmissionTrace({ form, submission, onClose }: { form: FormRef; submission: FormSubmission | null; onClose: () => void }) {
+  const trace = useG8Query(
+    (signal) => g8Get<{ capture_state?: string; receipts?: unknown[] }>(`/forms/${encodeURIComponent(form.form_key)}/submissions/${encodeURIComponent(submission?.id ?? "")}/trace`, { source_id: form.source_id }, { signal }).then((r) => r.data),
+    [form.form_key, form.source_id, submission?.id],
+    { enabled: Boolean(submission) },
+  );
+  return (
+    <Dialog open={submission !== null} onOpenChange={(open) => (open ? undefined : onClose())}>
+      <DialogContent className="max-h-[80vh] overflow-y-auto">
+        <DialogHeader>
+          <DialogTitle>Where did this lead go?</DialogTitle>
+          <DialogDescription>Every delivery step for this submission, in order.</DialogDescription>
+        </DialogHeader>
+        {trace.loading ? <Skeleton className="h-24 w-full" /> : trace.error ? <ApiError error={trace.error} title="No trace for this submission" /> : (
+          <div className="grid gap-2 text-sm">
+            <p>Capture: <strong>{trace.data?.capture_state ?? "unknown"}</strong></p>
+            {pickItems<Record<string, unknown>>(trace.data, "receipts").map((r, i) => (
+              <pre key={i} className="overflow-x-auto rounded border p-2 text-xs">{JSON.stringify(r, null, 2)}</pre>
+            ))}
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export function SubmissionsTable({ form: given, pageSize = 20, maxFieldColumns = 4 }: SubmissionsTableProps) {
+  const [picked, setPicked] = useState<FormRef | undefined>(undefined);
+  const forms = useG8Query((signal) => g8Get<unknown>("/forms", { per_page: 100 }, { signal }).then((r) => pickItems<FormRef & { display_name?: string | null }>(r.data, "items")), [], { enabled: !given });
+  const form = given ?? picked;
+  if (!form) {
+    if (forms.error) return <ApiError error={forms.error} title="Could not load forms" onRetry={() => void forms.refetch()} />;
+    if (forms.loading && !forms.data) return <Skeleton className="h-9 w-64" aria-busy="true" />;
+    if ((forms.data ?? []).length === 0) return <EmptyState title="No forms captured yet" description="Install the graph8 snippet on your site; forms appear after their first submission." />;
+    return (
+      <select aria-label="Choose a form" className="border-input bg-background h-9 max-w-sm rounded-md border px-2 text-sm" defaultValue="" onChange={(e) => { const f = forms.data?.[Number(e.target.value)]; if (f) setPicked({ form_key: f.form_key, source_id: f.source_id }); }}>
+        <option value="" disabled>Choose a form</option>
+        {(forms.data ?? []).map((f, i) => <option key={`${f.source_id}:${f.form_key}`} value={i}>{f.display_name || f.form_key}</option>)}
+      </select>
+    );
+  }
+  // Keyed on the form: page, trace and retry state belong to one form.
+  return <SubmissionsFor key={`${form.source_id}:${form.form_key}`} form={form} pageSize={pageSize} maxFieldColumns={maxFieldColumns} />;
+}
+
+function SubmissionsFor({ form, pageSize, maxFieldColumns }: { form: FormRef; pageSize: number; maxFieldColumns: number }) {
+  const [page, setPage] = useState(1);
+  const [traceOf, setTraceOf] = useState<FormSubmission | null>(null);
+  const [retrying, setRetrying] = useState<FormSubmission | null>(null);
+  const result = useG8Query<Page>(
+    (signal) => g8Post<unknown>(`/forms/${encodeURIComponent(form.form_key)}/submissions`, { page, per_page: pageSize, source_id: form.source_id }, { signal }).then((r) => {
+      const data = r.data as { submissions?: { items?: FormSubmission[]; total?: number }; items?: FormSubmission[]; total?: number } | undefined;
+      const block = data?.submissions ?? data;
+      return { items: block?.items ?? [], total: block?.total ?? 0 };
+    }),
+    [form.form_key, form.source_id, page, pageSize],
+  );
+  const retry = useG8Mutation((s: FormSubmission) => g8Post(`/forms/deliveries/${encodeURIComponent(s.delivery?.receipt_id ?? "")}/retry`), {
+    onSuccess: () => { setRetrying(null); void result.refetch(); },
+  });
+
+  if (result.error) return <ApiError error={result.error} title="Could not load submissions" onRetry={() => void result.refetch()} />;
+  if (result.loading && !result.data) return <div className="grid gap-2" aria-busy="true">{[0, 1, 2].map((i) => <Skeleton key={i} className="h-9 w-full" />)}</div>;
+  const items = result.data?.items ?? [];
+  const total = result.data?.total ?? items.length;
+  // A page past the end (rows removed, fewer submissions than before) is not "no submissions": keep the pager so the person can go back.
+  if (items.length === 0 && total > 0 && page > 1) {
+    return (
+      <div className="grid gap-2">
+        <EmptyState title="This page is empty" description={`There are ${total.toLocaleString()} submissions, but none on page ${page}.`} />
+        <div><Button size="sm" variant="outline" onClick={() => setPage(1)}>Back to the first page</Button></div>
+      </div>
+    );
+  }
+  if (items.length === 0) return <EmptyState title="No submissions yet" description="Submit the form once on your live site. Submissions appear within a minute." />;
+
+  const columns = [...new Set(items.flatMap((s) => Object.keys(s.form_data ?? {})))].slice(0, maxFieldColumns);
+  return (
+    <div className="grid gap-3">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Received</TableHead>
+            {columns.map((c) => <TableHead key={c}>{c}</TableHead>)}
+            <TableHead>Delivery</TableHead>
+            <TableHead />
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {items.map((s) => (
+            <TableRow key={s.id}>
+              <TableCell>{s.received_at ? new Date(s.received_at).toLocaleString() : ""}{s.is_test ? " (test)" : ""}</TableCell>
+              {columns.map((c) => <TableCell key={c}>{cellText(s.form_data?.[c])}</TableCell>)}
+              <TableCell className={submissionFailed(s) ? "text-red-700" : undefined}>{submissionState(s)}</TableCell>
+              <TableCell className="text-right">
+                <Button size="sm" variant="ghost" onClick={() => setTraceOf(s)}>Trace</Button>
+                {submissionFailed(s) && s.delivery?.receipt_id ? <Button size="sm" variant="ghost" onClick={() => { retry.reset(); setRetrying(s); }}>Retry</Button> : null}
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      <div className="flex items-center justify-between text-sm">
+        <span className="text-muted-foreground">{total.toLocaleString()} submissions. Empty identifying fields may be redacted for your key.</span>
+        <span>
+          <Button size="sm" variant="ghost" disabled={page <= 1} onClick={() => setPage(page - 1)}>Previous</Button>
+          <Button size="sm" variant="ghost" disabled={page * pageSize >= total} onClick={() => setPage(page + 1)}>Next</Button>
+        </span>
+      </div>
+      <SubmissionTrace form={form} submission={traceOf} onClose={() => setTraceOf(null)} />
+      <ConfirmSpendDialog
+        open={retrying !== null}
+        tier="external"
+        title="Retry delivering this lead?"
+        description={<><p>The lead is sent to the form's destination again, creating or updating a contact.</p>{retry.error ? <ApiError error={retry.error} title="Could not retry" /> : null}</>}
+        confirmLabel="Retry delivery"
+        confirming={retry.loading}
+        onCancel={() => { retry.reset(); setRetrying(null); }}
+        onConfirm={() => { if (retrying) void retry.mutate(retrying); }}
+      />
+    </div>
+  );
+}

package/blocks/forms/lib/form-types.ts

@@ -0,0 +1,127 @@
+"use client";
+
+/**
+ * Types and helpers for the forms block.
+ *
+ * graph8 does not host a drag-and-drop form designer. It CAPTURES the lead forms on your site (through the
+ * tracking snippet, see FormEmbed), lists them, and ROUTES each submission to a list with a field mapping.
+ * Several responses are passed through from the app and are not fully typed in the contract, so the readers
+ * here accept the shapes the app is known to send and fall back to an empty list instead of throwing.
+ */
+
+/** Identifies a form: a form key is only unique within one installed source (site). */
+export interface FormRef {
+  form_key: string;
+  source_id: string;
+}
+
+export interface FormListItem extends FormRef {
+  id: string;
+  display_name?: string | null;
+  page_url?: string | { value?: string } | null;
+  total_submissions?: number | null;
+  failed_submissions?: number | null;
+  latest_submitted_at?: string | null;
+  delivery_health?: string | null;
+  target_list_id?: number | string | null;
+  target_list_name?: string | null;
+}
+
+export interface FormOverview extends FormRef {
+  display_name?: string | null;
+  capture_health?: string | null;
+  delivery_health?: string | null;
+  delivery_source?: string | null;
+  delivery_warning?: string | null;
+  recommended_action?: string | null;
+  route?: { version?: number | null; mapping?: MappingRow[] | null } | null;
+  form_to_contact_field_mapping?: MappingRow[] | null;
+  destination?: { list_id?: number | null; list_name?: string | null; route_version?: number | null; source?: string | null } | null;
+  metrics?: { captured?: number; processed?: number; destination_verified?: number; failed?: number; activated?: number; unprocessed?: number | null } | null;
+}
+
+export interface MappingRow {
+  source_field: string;
+  target_field: string;
+  static_value?: string | null;
+}
+
+export interface ContactFieldGroup {
+  name: string;
+  fields: Array<{ field: string; label: string; type?: string }>;
+}
+
+export interface FormSubmission {
+  id: string;
+  received_at?: string;
+  form_data?: Record<string, unknown>;
+  delivery?: { state?: string; delivery_state?: string; failed?: boolean; reason?: string; receipt_id?: string } | null;
+  delivery_state?: string;
+  is_test?: boolean;
+  page?: { url?: string; path?: string } | null;
+}
+
+/** The first array found under any of `keys` (or the value itself if it is an array). */
+export function pickItems<T>(data: unknown, ...keys: string[]): T[] {
+  if (Array.isArray(data)) return data as T[];
+  if (data && typeof data === "object") {
+    for (const key of keys) {
+      const value = (data as Record<string, unknown>)[key];
+      if (Array.isArray(value)) return value as T[];
+    }
+  }
+  return [];
+}
+
+/** `page_url` is a string in the list and `{ value }` in the detail view. */
+export function pageUrlText(url: FormListItem["page_url"]): string {
+  if (!url) return "";
+  return typeof url === "string" ? url : (url.value ?? "");
+}
+
+export function formLabel(form: Partial<FormListItem> & { form_key?: string }): string {
+  return form.display_name?.trim() || form.form_key || "Untitled form";
+}
+
+/** One status word per form, from the server's own health fields. */
+export function formStatus(form: Pick<FormListItem, "delivery_health" | "target_list_id" | "total_submissions">): "failing" | "paused" | "live" | "needs_setup" | "no_data" {
+  if (form.delivery_health === "failing") return "failing";
+  if (form.delivery_health === "paused") return "paused";
+  if (form.target_list_id) return "live";
+  return (form.total_submissions ?? 0) > 0 ? "needs_setup" : "no_data";
+}
+
+export const STATUS_LABEL: Record<ReturnType<typeof formStatus>, string> = {
+  failing: "Failing",
+  paused: "Paused",
+  live: "Live",
+  needs_setup: "Needs setup",
+  no_data: "No data",
+};
+
+export function submissionState(s: FormSubmission): string {
+  return s.delivery?.state ?? s.delivery?.delivery_state ?? s.delivery_state ?? "not delivered";
+}
+
+export function submissionFailed(s: FormSubmission): boolean {
+  return Boolean(s.delivery?.failed) || /fail/i.test(submissionState(s));
+}
+
+export function cellText(value: unknown): string {
+  if (value == null) return "";
+  return typeof value === "object" ? JSON.stringify(value) : String(value);
+}
+
+/** The mapping body both preview and save take. Rows with no target are dropped. */
+export function mappingPayload(source_id: string, rows: readonly MappingRow[], listName: string, listId: number | undefined, routeVersion?: number | null) {
+  return {
+    source_id,
+    target_list_name: listName,
+    ...(listId ? { target_list_id: listId } : {}),
+    ...(routeVersion ? { expected_route_version: routeVersion } : {}),
+    form_to_contact_field_mapping: rows
+      .filter((r) => r.target_field && (r.source_field || r.static_value))
+      // A constant has no submitted field; the API still requires a source name, so reuse the target.
+      .map((r) => ({ source_field: r.source_field || r.target_field, target_field: r.target_field, ...(r.static_value ? { static_value: r.static_value } : {}) })),
+  };
+}

package/blocks/forms/recipes/install-snippet-and-form.ts

@@ -0,0 +1,21 @@
+/**
+ * @title Get the tracking snippet and a lead-capture form for a site
+ * @when Wiring a site (or your Next.js layout) so graph8 captures its forms. The snippet must load on every page
+ * that has a form; the generated form is optional and already calls graph8.track('form_submitted').
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+// 1. The snippet. With several sites the API sets action_required and lists them: pick one with stream_id.
+const snippet = await g8.api.snippet.getOrgSnippet({});
+if (snippet.data.action_required) {
+  for (const stream of snippet.data.available_streams ?? []) console.log(stream.id, stream.name, stream.domains);
+  throw new Error("Several sites: re-run with query: { stream_id } for the one you mean.");
+}
+console.log("Put this in <head> on every page:", snippet.data.script_tag);
+console.log("Or, in a React app:", snippet.data.react_snippet);
+
+// 2. A ready-made lead form (name, work email, company). Drop `html` into a page that loads the snippet.
+const form = await g8.api.snippet.getFormTemplate({});
+console.log((form.data as { html?: string }).html);

package/blocks/forms/recipes/retry-failed-deliveries.ts

@@ -0,0 +1,26 @@
+/**
+ * @title Find failed lead deliveries and retry them one by one
+ * @when A form's destination was broken for a while (deleted list, paused route) and leads piled up as failed.
+ * Retry is scoped to ONE receipt and creates or updates a real contact, so cap how many you retry per run.
+ * (Replaying a whole window is a backfill, which is not on this surface.)
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+interface Submission {
+  id: string;
+  delivery?: { failed?: boolean; receipt_id?: string; reason?: string } | null;
+}
+
+export async function retryFailed(formKey: string, sourceId: string, max = 25): Promise<number> {
+  const res = await g8.api.forms.searchFormSubmissions({ path: { form_key: formKey }, body: { source_id: sourceId, page: 1, per_page: 100 } });
+  const data = res.data as { submissions?: { items?: Submission[] }; items?: Submission[] };
+  const items = data.submissions?.items ?? data.items ?? [];
+  const failed = items.filter((s) => s.delivery?.failed && s.delivery.receipt_id).slice(0, max);
+  for (const s of failed) {
+    console.log("retrying", s.id, s.delivery?.reason);
+    await g8.api.forms.retryFormDelivery({ path: { receipt_id: s.delivery!.receipt_id! } });
+  }
+  return failed.length;
+}

package/blocks/forms/recipes/route-form-to-list.ts

@@ -0,0 +1,44 @@
+/**
+ * @title Route a captured form's leads to a list with a field mapping
+ * @when A form shows up in the inventory but its leads go nowhere ("Needs setup"). Order matters: read the
+ * fields it submits, preview the mapping, save it, then send one test submission. Preview writes nothing.
+ */
+import { g8, G8Error } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+// 1. Find the form. A form_key is only unique within its source_id (the site), so keep both.
+const forms = await g8.api.forms.listForms({ query: { search: "demo request" } });
+const form = forms.data.items?.[0];
+if (!form?.form_key || !form.source_id) throw new Error("No captured form matches. Submit it once on the live site first.");
+const ref = { path: { form_key: form.form_key }, query: { source_id: form.source_id } };
+
+// 2. What the form actually submits (the mapping's left side).
+const fields = await g8.api.forms.getFormFields(ref);
+console.log(fields.data);
+
+// 3. The destination list, created if you do not have one.
+const list = await g8.lists.create("Demo requests");
+
+// 4. Map submitted field -> contact field. Contact field names come from GET /contacts/form-fields.
+const mapping = {
+  source_id: form.source_id,
+  target_list_id: Number(list.id),
+  target_list_name: "Demo requests",
+  form_to_contact_field_mapping: [
+    { source_field: "email", target_field: "CONTACT_WORK_EMAIL" },
+    { source_field: "company", target_field: "COMPANY_NAME" },
+  ],
+};
+const preview = await g8.api.forms.previewFormMapping({ path: { form_key: form.form_key }, body: mapping });
+console.log("Preview (nothing saved):", preview.data);
+
+// 5. Save, then prove the route works. The test adds one synthetic contact to the list.
+try {
+  await g8.api.forms.saveFormMapping({ path: { form_key: form.form_key }, body: mapping });
+  const test = await g8.api.forms.testFormRoute({ path: { form_key: form.form_key }, body: { source_id: form.source_id } });
+  console.log("Test submission:", test.data);
+} catch (err) {
+  if (err instanceof G8Error && err.status === 409) console.error("Someone else saved this route in between: re-read and retry.");
+  else throw err;
+}

package/blocks/inbox/README.md

@@ -0,0 +1,72 @@
+# inbox: unified reply inbox
+
+One queue for replies on email, SMS and LinkedIn: a paged list with channel and status filters, a
+conversation view, an AI-assisted reply composer, tags and assignment. Compose the four parts yourself or
+copy `InboxScreen`, the finished two-pane page.
+
+Depends on: `crm` (the contact on each thread), `mailboxes` (the connected sending mailboxes). Install with
+`npx @graph8/sdk add inbox`.
+
+## The flow, in order
+
+1. **List** `GET /inbox?channel=&status=&page=&page_size=` (`InboxList`). Each row has `id` and `channel`.
+   Pagination is page-number based (`pagination.has_next`), not cursor based.
+2. **Open** `GET /inbox/{reply_id}?channel=` (`ThreadView`). Pass the row's `id` AND `channel`; ids are only
+   unique per channel. Messages with `is_draft: true` are unsent drafts.
+3. **Draft** `POST /inbox/drafts/generate` (`ReplyComposer`, **billable**, confirm first).
+   `generate_from_scratch` + `conversation_id` + `channel_type` writes a reply grounded in the thread;
+   `shorten` / `expand` / `fix_grammar_spelling` rework the text you pass in `message_html`. The response
+   `data.content` is HTML and `data.plain_content` is text. It sends nothing.
+4. **Send** `POST /inbox/{reply_id}/send` (`ReplyComposer`, **external**, confirm first) with
+   `{ channel, body, subject?, to? }`. The composer sends an `Idempotency-Key` so a double click cannot
+   send twice.
+5. **Route** (`TagAndAssign`): `POST /inbox/tags` creates a tag (write), `POST /inbox/{id}/tag?channel=`
+   applies tag ids and `POST /inbox/{id}/assign?channel=` hands the thread to a teammate by email. Both of
+   those are **external** (confirm first) because they can fire automations and notify people.
+
+IDs passed between steps: `thread.id` + `thread.channel` (list -> view -> draft/send/tag/assign),
+`tag.id` (create -> apply), `user.email` from `GET /inbox/users` (assign).
+
+## Prerequisites a human must do
+
+- Connect a mailbox in the graph8 app (Google / Microsoft OAuth exists only there; see the `mailboxes` block).
+  Until then the inbox has no email threads. `where: "app"`.
+- Give the proxy's API key `inbox:read`, `inbox:write` and `inbox:run`.
+- Credits for AI drafts (402 when none; there is no balance read, so the confirm dialog shows no estimate).
+
+## Defaults (the agent does not need to ask)
+
+- AI drafts are only ever written into the reply box. Sending is always a separate, confirmed click.
+- Tone `professional`, goal `follow_up`.
+- No assignee filter: the API cannot filter by an arbitrary assignee email (an org key owns no threads), so
+  filter `thread.assignees` client-side if you need it.
+- Ask the human only about **tags**: there is no list-tags operation. Pass `availableTags` from your own
+  state (collect them from `thread.tags` of loaded rows, or keep a list); tags created in the panel are
+  offered for the session.
+
+## Gotchas
+
+- `GET /inbox/{reply_id}/draft` is classified `read` but **charges credits**. Do not call it to preview;
+  this block uses `POST /inbox/drafts/generate` (billable, confirmed) instead.
+- LinkedIn threads have no AI drafting in this block (the draft endpoint supports email and SMS channel
+  types); the composer hides the AI buttons for them and sends with the thread's own account.
+- Tag and assign take the thread's `?channel=` query as well as the id.
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| `inbox.listInbox` | GET /inbox | read | InboxList, useInboxThreads |
+| `inbox.getReply` | GET /inbox/{reply_id} | read | ThreadView, useInboxThread |
+| `aiInbox.generateInboxDraft` | POST /inbox/drafts/generate | billable | ReplyComposer |
+| `inbox.sendReply` | POST /inbox/{reply_id}/send | external | ReplyComposer |
+| `aiInbox.listInboxUsers` | GET /inbox/users | read | TagAndAssign |
+| `aiInbox.createInboxTag` | POST /inbox/tags | write | TagAndAssign |
+| `inbox.tagReply` | POST /inbox/{reply_id}/tag | external | TagAndAssign |
+| `inbox.assignReply` | POST /inbox/{reply_id}/assign | external | TagAndAssign |
+
+## Recipes (server side)
+
+- `01-triage-and-reply.ts`: list, read, AI draft (billable), send (external).
+- `02-tag-and-assign.ts`: create a tag, apply it, assign a teammate.
+- `03-hot-contacts-digest.ts`: read-only digest of engaging contacts and unowned threads.