@graph8/sdk 0.303.0 → 0.357.0

package/blocks/enrichment/components/waterfall-config.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+/**
+ * WaterfallConfig: the saved enrichment pipelines of a list ("try provider A, then B, then C until one finds
+ * the value") and a form to create one: pick the field to fill, the providers and their order.
+ *
+ * SDK operations, in order:
+ *   1. listWaterfallConfigs          GET    /enrichment/waterfall/configs?list_id   (read)   pipelines runnable on the list
+ *   2. listEnrichmentProviders       GET    /enrichment/providers                   (read)   graph8-funded vs own key, credits per action
+ *   3. createDefaultWaterfallConfig  POST   /enrichment/waterfall/configs { list_id, name, field, providers, skip_existing_values }
+ *        (billable tier) goes through ConfirmSpendDialog first; idempotent by (list_id, name) - the same name reuses the pipeline.
+ *   4. deleteWaterfallConfig         DELETE /enrichment/waterfall/configs/{column_id}   (destructive, ConfirmSpendDialog)
+ *
+ * Providers on graph8's system key spend credits when the pipeline RUNS; providers on the org's own key (BYOK) do not.
+ * A BYOK provider without a key is listed under `missing_credentials` and is skipped at run time.
+ */
+
+import { 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 { useProviders } from "../hooks/use-providers";
+import { TARGET_FIELDS } from "../lib/enrichment-types";
+import type { TargetField, WaterfallConfigSummary } from "../lib/enrichment-types";
+
+export interface WaterfallConfigProps {
+  listId: number;
+  /** Called with the pipeline's column_id after create or delete (for example to refresh a BulkEnrichPanel). */
+  onChanged?: () => void;
+  className?: string;
+}
+
+export function WaterfallConfig({ listId, onChanged, className }: WaterfallConfigProps) {
+  const [name, setName] = useState("");
+  const [field, setField] = useState<TargetField>("work_email");
+  const [order, setOrder] = useState<string[]>([]);
+  const [skipExisting, setSkipExisting] = useState(true);
+  const [confirmCreate, setConfirmCreate] = useState(false);
+  const [deleting, setDeleting] = useState<WaterfallConfigSummary | null>(null);
+  const catalog = useProviders();
+
+  const configs = useG8Query((signal) => g8Get<{ configs: WaterfallConfigSummary[] }>("/enrichment/waterfall/configs", { list_id: listId }, { signal }), [listId]);
+  const create = useG8Mutation(
+    () => g8Post<{ column_id: string; created: boolean }>("/enrichment/waterfall/configs", { list_id: listId, name: name.trim(), field, providers: order, skip_existing_values: skipExisting }),
+    { onSuccess: () => { setConfirmCreate(false); setName(""); setOrder([]); void configs.refetch(); onChanged?.(); } },
+  );
+  const remove = useG8Mutation((columnId: string) => g8Delete(`/enrichment/waterfall/configs/${columnId}`), {
+    onSuccess: () => { setDeleting(null); void configs.refetch(); onChanged?.(); },
+  });
+
+  const items = configs.data?.data.configs ?? [];
+  const byName = new Map(catalog.providers.map((p) => [p.provider, p]));
+  const systemUsed = order.filter((p) => byName.get(p)?.system_funded && !byName.get(p)?.byok_configured);
+  const move = (p: string, d: number) => {
+    const i = order.indexOf(p), j = i + d;
+    if (j < 0 || j >= order.length) return;
+    const next = [...order];
+    [next[i], next[j]] = [next[j], next[i]];
+    setOrder(next);
+  };
+
+  return (
+    <div className={`flex flex-col gap-5 ${className ?? ""}`}>
+      <section className="flex flex-col gap-2" aria-label="Saved pipelines">
+        <h3 className="text-sm font-medium">Saved pipelines</h3>
+        {configs.error ? <ApiError error={configs.error} title="Could not load pipelines" onRetry={() => void configs.refetch()} /> : null}
+        {remove.error ? <ApiError error={remove.error} title="Could not delete the pipeline" /> : null}
+        {configs.loading && !configs.data ? <Skeleton className="h-12 w-full" /> : null}
+        {!configs.loading && !configs.error && items.length === 0 ? <EmptyState title="No pipelines yet" description="Create one below, or let the first enrichment run create a default." /> : null}
+        <ul className="flex flex-col gap-2">
+          {items.map((c) => (
+            <li key={c.column_id} className="rounded-md border p-3" data-testid="pipeline">
+              <div className="flex items-center justify-between gap-2">
+                <p className="text-sm font-medium">{c.name}{c.is_global ? <span className="ml-2 text-xs text-muted-foreground">all lists</span> : null}</p>
+                <Button variant="ghost" size="sm" onClick={() => setDeleting(c)}>Delete</Button>
+              </div>
+              <p className="text-xs text-muted-foreground">{c.field_to_enrich ?? "field"}: {c.providers.join(" > ") || "no providers"} ({c.step_count} step{c.step_count === 1 ? "" : "s"})</p>
+              {c.missing_credentials.length ? <p role="alert" className="mt-1 text-xs text-amber-700">Skipped at run time, no key: {c.missing_credentials.join(", ")}</p> : null}
+            </li>
+          ))}
+        </ul>
+      </section>
+
+      <section className="flex flex-col gap-3" aria-label="New pipeline">
+        <h3 className="text-sm font-medium">New pipeline</h3>
+        <div className="flex flex-wrap items-end gap-3">
+          <div className="flex flex-col gap-1"><Label htmlFor="wf-name">Name</Label><Input id="wf-name" className="w-64" value={name} onChange={(e) => setName(e.target.value)} /></div>
+          <div className="flex flex-col gap-1"><Label htmlFor="wf-field">Fill</Label>
+            <select id="wf-field" className="h-9 rounded-md border bg-background px-2 text-sm" value={field} onChange={(e) => setField(e.target.value as TargetField)}>
+              {TARGET_FIELDS.map((f) => <option key={f.value} value={f.value}>{f.label}</option>)}
+            </select>
+          </div>
+        </div>
+        {catalog.error ? <ApiError error={catalog.error} title="Could not load providers" onRetry={() => void catalog.refetch()} /> : null}
+        <ol className="flex flex-col gap-1" aria-label="Provider order">
+          {order.map((p, i) => (
+            <li key={p} className="flex items-center gap-2 text-sm">
+              <span className="w-6 text-muted-foreground">{i + 1}.</span><span className="w-32 font-medium">{p}</span>
+              <span className="text-xs text-muted-foreground">{byName.get(p)?.byok_configured ? "your key, free" : byName.get(p)?.system_funded ? "graph8 credits" : "needs your key"}</span>
+              <Button variant="ghost" size="sm" aria-label={`Move ${p} up`} disabled={i === 0} onClick={() => move(p, -1)}>Up</Button>
+              <Button variant="ghost" size="sm" aria-label={`Move ${p} down`} disabled={i === order.length - 1} onClick={() => move(p, 1)}>Down</Button>
+              <Button variant="ghost" size="sm" aria-label={`Remove ${p}`} onClick={() => setOrder(order.filter((x) => x !== p))}>Remove</Button>
+            </li>
+          ))}
+        </ol>
+        <div className="flex flex-wrap gap-1">
+          {catalog.providers.filter((p) => !order.includes(p.provider)).map((p) => (
+            <Button key={p.provider} variant="outline" size="sm" onClick={() => setOrder([...order, p.provider])}>Add {p.provider}</Button>
+          ))}
+        </div>
+        <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={skipExisting} onChange={(e) => setSkipExisting(e.target.checked)} /> Skip contacts that already have a value</label>
+        {create.error ? <ApiError error={create.error} title="Could not create the pipeline" /> : null}
+        <div className="flex justify-end"><Button disabled={!name.trim() || order.length === 0} onClick={() => setConfirmCreate(true)}>Create pipeline</Button></div>
+      </section>
+
+      <ConfirmSpendDialog open={confirmCreate} tier="billable" title={`Create pipeline "${name.trim()}"`}
+        description={systemUsed.length ? `Running it uses graph8 credits for ${systemUsed.join(", ")}; providers on your own key cost nothing. Creating the pipeline itself does not run it.` : "All providers use your own keys, so running it costs no graph8 credits. Creating the pipeline does not run it."}
+        confirmLabel="Create" confirming={create.loading} onConfirm={() => void create.mutate(undefined)} onCancel={() => setConfirmCreate(false)} />
+      <ConfirmSpendDialog open={deleting != null} tier="destructive" title={`Delete pipeline "${deleting?.name ?? ""}"`} description="Values it already wrote stay on the contacts."
+        affected={1} confirming={remove.loading} onConfirm={() => deleting && void remove.mutate(deleting.column_id)} onCancel={() => setDeleting(null)} />
+    </div>
+  );
+}

package/blocks/enrichment/hooks/use-providers.ts

@@ -0,0 +1,18 @@
+"use client";
+
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import type { ProviderEntry } from "../lib/enrichment-types";
+
+/**
+ * The enrichment provider catalog (`GET /enrichment/providers`): which providers graph8 funds with its own key
+ * (usable with no setup, spends credits) and which need the org's own key (BYOK), with the credits per action.
+ */
+export function useProviders(enabled = true) {
+  const query = useG8Query(
+    async (signal) => (await g8Get<{ providers: ProviderEntry[]; count: number }>("/enrichment/providers", undefined, { signal })).data.providers ?? [],
+    [],
+    { enabled },
+  );
+  return { providers: query.data ?? [], loading: query.loading, error: query.error, refetch: query.refetch };
+}

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

@@ -0,0 +1,104 @@
+"use client";
+
+/**
+ * Prices, vocabularies and shapes for the enrichment components.
+ *
+ * Prices are the ones the API charges today (developer_api/constants.py): a person or company lookup costs 2
+ * credits ONLY when it finds a match (a miss is free), an email verification costs 1, and a bulk enrichment is
+ * quoted at 2 credits per record before it runs. The API has no "get balance" call, so every number the UI shows
+ * is an ESTIMATE of what a run can cost, not a balance check. Prefer the API's own quote (`max_total_credits` from
+ * the preflight) whenever it is there.
+ */
+
+export const CREDITS_PER_FOUND_LOOKUP = 2;
+export const CREDITS_PER_EMAIL_VERIFICATION = 1;
+export const CREDITS_PER_RECORD_ESTIMATE = 2;
+
+/** What a bulk run can fill. `column` is the key in `fields_config`; `target` is the preflight's target_field. */
+export const TARGET_FIELDS = [
+  { value: "work_email", label: "Work email", column: "work_email", target: "CONTACT_WORK_EMAIL" },
+  { value: "direct_phone", label: "Direct phone", column: "direct_phone", target: "CONTACT_DIRECT_PHONE" },
+  { value: "mobile_phone", label: "Mobile phone", column: "mobile_phone", target: "CONTACT_MOBILE_PHONE" },
+] as const;
+export type TargetField = (typeof TARGET_FIELDS)[number]["value"];
+
+export interface ProviderEntry {
+  provider: string;
+  system_funded: boolean;
+  byok_configured: boolean;
+  default_credential_source: "system" | "byok";
+  credits_per_row: Record<string, number>;
+  actions: string[];
+}
+
+export interface ProviderStep {
+  provider: string;
+  is_system_provider: boolean;
+  credential_source: "system" | "byok";
+  credential_ready: boolean;
+}
+
+export interface Preflight {
+  list_id: number;
+  list_name?: string | null;
+  mode: string;
+  contact_ids: number[];
+  contact_count: number;
+  duplicates_removed: number;
+  not_in_list: number[];
+  providers: string[];
+  uses_saved_pipeline: boolean;
+  providers_detail: ProviderStep[];
+  missing_credentials: string[];
+  warnings: string[];
+  pipeline_column_id?: string | null;
+  credits_per_record?: number | null;
+  priced_records?: number | null;
+  max_total_credits?: number | null;
+}
+
+export interface EnrichJob {
+  job_id: string;
+  status: string;
+  total?: number | null;
+  completed?: number | null;
+  successful_enrichments?: number | null;
+  failed_enrichments?: number | null;
+  total_credits_used?: number | null;
+  warnings?: string[] | null;
+  provider_errors?: Array<{ record_id?: number; provider?: string; error?: string }> | null;
+}
+
+export interface WaterfallConfigSummary {
+  column_id: string;
+  name: string;
+  field_to_enrich?: string | null;
+  is_global?: boolean;
+  is_active?: boolean;
+  list_id?: number | null;
+  step_count: number;
+  providers: string[];
+  providers_detail: ProviderStep[];
+  missing_credentials: string[];
+}
+
+const TERMINAL = new Set(["completed", "complete", "failed", "cancelled", "canceled", "completed_with_errors", "partial", "error"]);
+
+/** A job in one of these states will not change any more: stop polling. */
+export function isJobTerminal(status: string | undefined | null): boolean {
+  return TERMINAL.has(String(status ?? "").toLowerCase());
+}
+
+/**
+ * What to show as the cost of a run: the API's own quote when the preflight priced it, otherwise the flat
+ * per-record estimate times the contacts that are really on the list. Never a balance.
+ */
+export function estimateCredits(preflight: Pick<Preflight, "max_total_credits" | "contact_count" | "not_in_list"> | undefined, fallbackCount: number): number {
+  if (preflight?.max_total_credits != null) return preflight.max_total_credits;
+  const count = preflight ? Math.max(0, preflight.contact_count - (preflight.not_in_list?.length ?? 0)) : fallbackCount;
+  return count * CREDITS_PER_RECORD_ESTIMATE;
+}
+
+export function isMaskedValue(value: unknown): boolean {
+  return typeof value === "string" && value.trim() === "***";
+}

package/blocks/enrichment/recipes/bulk-enrich-and-poll.ts

@@ -0,0 +1,41 @@
+/**
+ * @title Enrich many contacts of a list and wait for the job
+ * @when Filling work emails or phones for a list. Order: preflight (free: counts, missing provider keys and the
+ * credit quote) -> a human approves the quote -> start the job -> poll it (the API has no streams or
+ * webhook for completion) -> read provider errors if nothing was written. Contact ids must be on the list;
+ * ids not on it are skipped and not charged. Never enrich contacts you only have as masked search results:
+ * save them to a list first.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function quote(listId: number, contactIds: number[]) {
+  const res = await g8.api.enrichment.preflightEnrichment({
+    body: { list_id: listId, contact_ids: contactIds, mode: "waterfall", providers: ["prospeo", "dropcontact"], target_field: "CONTACT_WORK_EMAIL" },
+  });
+  return res.data; // contact_count, not_in_list, missing_credentials, warnings, credits_per_record, max_total_credits
+}
+
+/** Only after a person approved `max_total_credits`. */
+export async function enrichAndWait(listId: number, contactIds: number[]) {
+  const started = await g8.api.enrichment.startEnrichment({
+    body: { list_id: listId, contact_ids: contactIds, fields_config: { work_email: ["prospeo", "dropcontact"] } },
+  });
+  const jobId = started.data.job_id;
+
+  let delay = 2000;
+  for (let i = 0; i < 100; i++) {
+    const job = await g8.api.enrichment.getEnrichmentJob({ path: { job_id: jobId } });
+    if (["completed", "failed", "cancelled"].includes(job.data.status)) {
+      if (!job.data.successful_enrichments) {
+        const why = await g8.api.enrichment.getEnrichmentJob({ path: { job_id: jobId }, query: { include_provider_errors: true } });
+        return { jobId, job: job.data, providerErrors: why.data.provider_errors };
+      }
+      return { jobId, job: job.data };
+    }
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(15000, Math.round(delay * 1.5));
+  }
+  throw new Error(`job ${jobId} did not finish in time; keep polling later`);
+}

package/blocks/enrichment/recipes/lookup-and-verify.ts

@@ -0,0 +1,25 @@
+/**
+ * @title Look up a person or company and verify an email
+ * @when One-off enrichment of a single record. A lookup costs 2 credits ONLY when it finds a match (a miss is
+ * free); an email verification costs 1 credit. Both are billable: ask a human before looping over many records
+ * (use the bulk job for that). The lookup returns data, it does not update the CRM: write the fields you want
+ * with `g8.contacts.update` afterwards.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function enrichOnePerson(email: string) {
+  const person = await g8.enrich.person({ email });
+  if (!person.found) return { found: false as const }; // nothing was charged
+  return { found: true as const, confidence: person.confidence, data: person.data };
+}
+
+export async function enrichOneCompany(domain: string) {
+  return g8.enrich.company({ domain });
+}
+
+export async function isDeliverable(email: string) {
+  const v = await g8.enrich.verifyEmail(email);
+  return { valid: v.valid, deliverable: v.deliverable, catchAll: v.catch_all };
+}

package/blocks/enrichment/recipes/waterfall-pipeline.ts

@@ -0,0 +1,26 @@
+/**
+ * @title Create a waterfall pipeline for a list and see which providers are ready
+ * @when Setting up "try provider A, then B" enrichment for a column once, then reusing it. Check the provider
+ * catalog first: graph8-funded providers spend credits when the pipeline runs, providers on your own key do not,
+ * and a provider without a key is skipped. Creating is idempotent by (list_id, name).
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function readyProviders() {
+  const res = await g8.api.enrichment.listEnrichmentProviders();
+  return (res.data.providers ?? []).map((p) => ({ provider: p.provider, usable: p.system_funded || p.byok_configured, source: p.default_credential_source }));
+}
+
+export async function createPipeline(listId: number) {
+  const res = await g8.api.enrichment.createDefaultWaterfallConfig({
+    body: { list_id: listId, name: "Work email waterfall", field: "work_email", providers: ["prospeo", "dropcontact"], skip_existing_values: true },
+  });
+  return { columnId: res.data.column_id, created: res.data.created, missing: res.data.missing_credentials };
+}
+
+export async function pipelinesOf(listId: number) {
+  const res = await g8.api.enrichment.listWaterfallConfigs({ query: { list_id: listId } });
+  return res.data.configs;
+}

package/blocks/forms/README.md

@@ -0,0 +1,112 @@
+# forms: capture, route and monitor website forms
+
+graph8 does not host a form designer. It **captures the lead forms already on your site** through the tracking
+snippet, lists them, and routes every submission to a list with a field mapping. This block is the screen set for
+that: install the code (`FormEmbed`), set where leads go and how fields map (`FormBuilder`), see what arrived and
+retry failures (`SubmissionsTable`), and find forms that are not captured (`SiteAuditPanel`).
+
+## Install
+
+```
+npx @graph8/sdk add forms
+```
+
+Installs `foundation` and `crm` first if missing. Everything lands under `g8/forms/`.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| Your site | Load the graph8 snippet (from `FormEmbed`) on every page that has a form. Forms appear only after a first captured submission. | Submit the form on the live site; `GET /api/v1/forms` lists it within a minute. |
+| graph8 workspace | A list to receive leads. | `GET /api/v1/lists` returns one. |
+| Your app | `allowedPrefixes` in `app/api/g8/[...path]/route.ts` must include `forms`, `snippet`, `contacts`, `lists`. | The route file lists them. |
+| graph8 key | Submitted values (emails, names) are **redacted** for a key without the Signals write capability. | Identifying fields are not empty in `SubmissionsTable`. |
+
+## The flow, in order
+
+1. **Get the code**: `<FormEmbed />` calls `getOrgSnippet` (write key, `<script>` tag, React component) and `getFormTemplate`
+   (ready-made lead form HTML). With several sites the API answers `action_required` and lists streams; the component shows a picker
+   and re-reads with `stream_id`.
+2. **List captured forms**: `<FormBuilder />` calls `listForms`. Each item carries **`form_key` and `source_id`**; every later call
+   needs BOTH (a form key is only unique inside one source/site).
+3. **Open a form**: `getFormOverview(form_key, source_id)` gives health, counts and the current destination (`destination.list_id`,
+   `route.version`).
+4. **Map and route** (`FormMappingEditor`):
+   `getFormFields` (names the form really submits) + `getContactFormFields` (contact fields, grouped, `CONTACT_WORK_EMAIL` etc.)
+   + `listLists` (destination) -> optional `getFormRouteRecommendations` -> `previewFormMapping` (writes nothing)
+   -> `saveFormMapping` (a FULL replacement; sends `expected_route_version` so a colleague's save is a 409, not an overwrite)
+   -> `testFormRoute` (adds one synthetic contact to the list).
+5. **Watch it**: `SubmissionsTable` uses `searchFormSubmissions` (paged). `Trace` calls `getFormSubmissionTrace` (where did this lead go).
+   A failed row carries `delivery.receipt_id`; **Retry** calls `retryFormDelivery(receipt_id)` after a confirm.
+6. **Pause**: `pauseFormDelivery` keeps accepting submissions but queues them; `resumeFormDelivery` delivers again. Both open `ConfirmSpendDialog` (tier external).
+
+```tsx
+// app/forms/page.tsx
+"use client";
+import { FormBuilder } from "@/g8/forms/components/form-builder";
+export default function FormsPage() {
+  return <FormBuilder />;
+}
+// app/forms/install/page.tsx -> <FormEmbed />, app/forms/audit/page.tsx -> <SiteAuditPanel />
+```
+
+## Default decisions (do not ask the human unless marked)
+
+| Decision | Default | Ask? |
+|---|---|---|
+| Hosted designer vs capturing existing forms | Capture existing forms; the generated lead form is only a starting point | no |
+| Which list receives a form's leads | A new list named after the form | **yes** |
+| Email field mapping | `CONTACT_WORK_EMAIL`; use "Suggest mapping" for the rest | no |
+| Retrying failed deliveries | One lead at a time, after the person confirms | no |
+
+## Things that surprise people
+
+- **Responses are passed through from the app and only partly typed.** The components read them defensively (`items`/`fields`/`receipts`).
+  If you build on the raw API, log the first response of each call before relying on a field.
+- **Saving a mapping applies to every submission captured afterwards.** Always preview first (the editor's buttons are in that order).
+- **`testFormRoute` writes.** It adds one synthetic contact (`forms-test-...@example.com`) to the destination list and needs an active route.
+- **A scan is asynchronous.** `requestSiteAuditScan` is rate limited to one per minute per org (`already_queued`); `SiteAuditPanel` polls `getSiteAudit` with `useJobPoll`.
+- Retrying many failures is a loop of single retries (see the recipe); replaying a whole time window (a backfill) is not exposed to the SDK block.
+
+## Recipes (server-side, `recipes/`)
+
+- `install-snippet-and-form.ts`: fetch the snippet and the lead-form HTML for a site.
+- `route-form-to-list.ts`: find a form, read its fields, create a list, preview, save, test.
+- `retry-failed-deliveries.ts`: retry failed leads one by one, capped per run.
+
+## What is in the block
+
+| Component | File | What it is |
+|---|---|---|
+| `FormBuilder` | `components/form-builder.tsx` | Forms workspace: list captured forms, rename, pause/resume delivery, set destination and mapping, view submissions. |
+| `FormMappingEditor` | `components/form-mapping-editor.tsx` | Pick the destination list and map submitted fields to contact fields, with suggest, preview, save and test. |
+| `FormEmbed` | `components/form-embed.tsx` | Copyable tracking snippet (script tag, React) and a ready-made lead-capture form with live preview. |
+| `SubmissionsTable` | `components/submissions-table.tsx` | Paged submissions with delivery state, a per-lead trace and a confirmed retry for failed deliveries. |
+| `SiteAuditPanel` | `components/site-audit-panel.tsx` | Forms on your site that are not captured, from the latest crawl; rescan and triage findings. |
+
+## Operations
+
+Tiers: `read` and `write` need no confirmation; `external` (pause, resume, retry) opens `ConfirmSpendDialog` first.
+
+| Operation | Method and path | Tier | Scope | Used by |
+|---|---|---|---|---|
+| `forms.listForms` | `GET /api/v1/forms` | read | `forms:read` | FormBuilder |
+| `forms.getFormOverview` | `GET /api/v1/forms/{form_key}/overview` | read | `forms:read` | FormBuilder, FormMappingEditor |
+| `forms.updateFormRegistry` | `PATCH /api/v1/forms/{form_key}` | write | `forms:write` | FormBuilder |
+| `forms.pauseFormDelivery` | `POST /api/v1/forms/{form_key}/delivery/pause` | external | `forms:run` | FormBuilder |
+| `forms.resumeFormDelivery` | `POST /api/v1/forms/{form_key}/delivery/resume` | external | `forms:run` | FormBuilder |
+| `forms.getFormFields` | `GET /api/v1/forms/{form_key}/fields` | read | `forms:read` | FormMappingEditor |
+| `contacts.getContactFormFields` | `GET /api/v1/contacts/form-fields` | read | `contacts:read` | FormMappingEditor |
+| `lists.listLists` | `GET /api/v1/lists` | read | `lists:read` | FormMappingEditor |
+| `forms.getFormRouteRecommendations` | `GET /api/v1/forms/{form_key}/route/recommendations` | read | `forms:read` | FormMappingEditor |
+| `forms.previewFormMapping` | `POST /api/v1/forms/{form_key}/mapping/preview` | read | `forms:read` | FormMappingEditor |
+| `forms.saveFormMapping` | `POST /api/v1/forms/{form_key}/mapping/save` | write | `forms:write` | FormMappingEditor |
+| `forms.testFormRoute` | `POST /api/v1/forms/{form_key}/route/test` | write | `forms:write` | FormMappingEditor |
+| `snippet.getOrgSnippet` | `GET /api/v1/snippet` | read | `integrations:read` | FormEmbed |
+| `snippet.getFormTemplate` | `GET /api/v1/snippet/form` | read | `integrations:read` | FormEmbed |
+| `forms.searchFormSubmissions` | `POST /api/v1/forms/{form_key}/submissions` | read | `forms:read` | SubmissionsTable |
+| `forms.getFormSubmissionTrace` | `GET /api/v1/forms/{form_key}/submissions/{submission_id}/trace` | read | `forms:read` | SubmissionsTable |
+| `forms.retryFormDelivery` | `POST /api/v1/forms/deliveries/{receipt_id}/retry` | external | `forms:run` | SubmissionsTable |
+| `forms.getSiteAudit` | `GET /api/v1/forms/site-audit` | read | `forms:read` | SiteAuditPanel |
+| `forms.requestSiteAuditScan` | `POST /api/v1/forms/site-audit/scan` | write | `forms:write` | SiteAuditPanel |
+| `forms.updateSiteAuditFinding` | `PATCH /api/v1/forms/site-audit/findings/{finding_id}` | write | `forms:write` | SiteAuditPanel |