@graph8/sdk 0.370.0 → 0.373.0

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

@@ -22,6 +22,45 @@ export const TARGET_FIELDS = [
 ] as const;
 export type TargetField = (typeof TARGET_FIELDS)[number]["value"];
 
+/**
+ * Providers the API can run for each field: the per-field waterfall templates the server builds pipelines from
+ * (a phone runs leadmagic `mobile_finder`, never an email finder). Any other provider is refused with 400
+ * `unsupported_provider_for_field`, so the UI only offers these.
+ */
+export const FIELD_PROVIDERS: Record<TargetField, readonly string[]> = {
+  work_email: ["apollo", "leadmagic", "prospeo", "hunter", "icypeas", "dropcontact"],
+  direct_phone: ["leadmagic", "prospeo", "apollo"],
+  mobile_phone: ["leadmagic", "prospeo", "apollo"],
+};
+
+/** Providers a run tries for a field when nobody chose: the API's own defaults. */
+export const FIELD_DEFAULT_PROVIDERS: Record<TargetField, readonly string[]> = {
+  work_email: ["prospeo", "dropcontact"],
+  direct_phone: ["leadmagic", "prospeo", "apollo"],
+  mobile_phone: ["leadmagic", "prospeo", "apollo"],
+};
+
+/**
+ * The providers to start from for `field`: `preferred` (in its order) kept to those the field supports, else the
+ * field's API defaults when none of `preferred` fits (for example email providers asked for a phone).
+ */
+export function providersForField(field: TargetField, preferred?: readonly string[]): string[] {
+  const allowed = FIELD_PROVIDERS[field];
+  const kept = (preferred ?? FIELD_DEFAULT_PROVIDERS[field]).filter((p) => allowed.includes(p));
+  return kept.length ? [...new Set(kept)] : [...FIELD_DEFAULT_PROVIDERS[field]];
+}
+
+/** What POST /enrichment/waterfall/configs answers (created, or the list's existing pipeline for that field reused). */
+export interface WaterfallPipelineResult {
+  column_id: string;
+  config_id?: string;
+  name?: string;
+  list_id?: number | null;
+  created: boolean;
+  providers?: string[];
+  missing_credentials?: string[];
+}
+
 export interface ProviderEntry {
   provider: string;
   system_funded: boolean;

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

@@ -1,7 +1,7 @@
 /**
  * @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
+ * credit quote) -> a human approves the quote -> create or reuse the field's pipeline and run it -> 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.
@@ -17,11 +17,22 @@ export async function quote(listId: number, contactIds: number[]) {
   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`. */
+/**
+ * Only after a person approved `max_total_credits`.
+ *
+ * Runs through a saved waterfall pipeline: create (or reuse) the list's work-email pipeline, then run it on the
+ * contacts. Creating is idempotent per (field, list): a list that already has a work-email pipeline reuses it with
+ * ITS providers (`created: false`). Keep the column_id: a retry only needs the second call.
+ */
 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 pipeline = await g8.api.enrichment.createDefaultWaterfallConfig({
+    body: { list_id: listId, name: "Work email enrichment", field: "CONTACT_WORK_EMAIL", providers: ["prospeo", "dropcontact"] },
+  });
+  const started = await g8.api.enrichment.runWaterfallPipeline({
+    body: { column_id: pipeline.data.column_id, list_id: listId, record_ids: contactIds },
   });
+  // A 202 whose status is "error" never started (newer APIs answer 502): do not poll a job that will not exist.
+  if (!started.data.job_id || started.data.status === "error") throw new Error("enrichment did not start; nothing was charged");
   const jobId = started.data.job_id;
 
   let delay = 2000;

package/blocks/forms/README.md

@@ -122,3 +122,11 @@ Tiers: `read` and `write` need no confirmation; `external` (pause, resume, retry
 | `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 |
+
+## Depth added (C7c)
+
+graph8 captures forms from your site; there is **no create-form operation in the API** (an API gap, not a missing screen).
+
+New on `FormsScreen`: a **Groups** tab (`FormGroups`: create, rename, re-type, add and remove forms, delete), saved views (`FormSavedViews`), "Load more" past the first 100 forms, and on an open form: a **Routing** tab (`FormBackfill`: preview, then a confirmed delivery; `FormRouteHistory`: restore the previous route or stop routing, both destructive confirms that send the version they read), an **Activity** tab (`FormActivity`: audit trail and pages), and **Export CSV** on Submissions (`SubmissionsExport`, formula-safe, says when the file is not the whole set).
+
+Not covered (and why): `saveFormRoute` (the mapping editor's save already writes the route); `captureFormPreview` and `getFormPreview` return untyped image data; unidentified-form grouping (`previewUnidentifiedGrouping`, `setUnidentifiedGrouping`, `syncUnidentifiedGroup`) needs a list picker (owned by the pickers PR). The mapping editor's list select keeps its existing cap until that PR lands.

package/blocks/forms/block.json

@@ -15,24 +15,37 @@
     "crm"
   ],
   "operations": [
+    "add_form_group_members_forms_groups__group_id__members_post",
+    "create_form_backfill_forms__form_key__backfills_post",
+    "create_form_group_forms_groups_post",
+    "delete_form_group_forms_groups__group_id__delete",
     "get_contact_form_fields_contacts_form_fields_get",
+    "get_form_activity_forms__form_key__activity_get",
+    "get_form_backfill_forms__form_key__backfills__job_id__get",
     "get_form_fields_forms__form_key__fields_get",
     "get_form_overview_forms__form_key__overview_get",
+    "get_form_placements_forms__form_key__placements_get",
     "get_form_route_recommendations_forms__form_key__route_recommendations_get",
     "get_form_submission_trace_forms__form_key__submissions__submission_id__trace_get",
     "get_form_template_snippet_form_get",
     "get_org_snippet_snippet_get",
     "get_site_audit_forms_site_audit_get",
+    "list_form_groups_forms_groups_get",
     "list_forms_forms_get",
     "list_lists_lists_get",
+    "list_saved_form_views_forms_views_saved_get",
     "pause_form_delivery_forms__form_key__delivery_pause_post",
     "preview_form_mapping_forms__form_key__mapping_preview_post",
+    "remove_form_group_members_forms_groups__group_id__members_remove_post",
     "request_site_audit_scan_forms_site_audit_scan_post",
     "resume_form_delivery_forms__form_key__delivery_resume_post",
     "retry_form_delivery_forms_deliveries__receipt_id__retry_post",
+    "rollback_form_route_forms__form_key__route_delete",
     "save_form_mapping_forms__form_key__mapping_save_post",
+    "save_form_view_forms_views_saved__view_id__put",
     "search_form_submissions_forms__form_key__submissions_post",
     "test_form_route_forms__form_key__route_test_post",
+    "update_form_group_forms_groups__group_id__patch",
     "update_form_registry_forms__form_key__patch",
     "update_site_audit_finding_forms_site_audit_findings__finding_id__patch"
   ],
@@ -133,6 +146,95 @@
         "read",
         "write"
       ]
+    },
+    {
+      "name": "FormActivity",
+      "file": "components/form-activity.tsx",
+      "purpose": "Audit trail of one form and the pages it appears on.",
+      "operations": [
+        "get_form_activity_forms__form_key__activity_get",
+        "get_form_placements_forms__form_key__placements_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "FormBackfill",
+      "file": "components/form-backfill.tsx",
+      "purpose": "Deliver earlier captured leads through the form route: preview, then a confirmed delivery.",
+      "operations": [
+        "get_form_overview_forms__form_key__overview_get",
+        "get_form_backfill_forms__form_key__backfills__job_id__get",
+        "create_form_backfill_forms__form_key__backfills_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "FormGroups",
+      "file": "components/form-groups.tsx",
+      "purpose": "Curated groups of forms: create, rename, add and remove forms, delete.",
+      "operations": [
+        "list_forms_forms_get",
+        "update_form_group_forms_groups__group_id__patch",
+        "add_form_group_members_forms_groups__group_id__members_post",
+        "remove_form_group_members_forms_groups__group_id__members_remove_post",
+        "delete_form_group_forms_groups__group_id__delete",
+        "list_form_groups_forms_groups_get",
+        "create_form_group_forms_groups_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "FormRouteHistory",
+      "file": "components/form-route-history.tsx",
+      "purpose": "Undo a routing change: restore the previous route or stop routing the form.",
+      "operations": [
+        "get_form_overview_forms__form_key__overview_get",
+        "rollback_form_route_forms__form_key__route_delete"
+      ],
+      "tiers": [
+        "read",
+        "destructive"
+      ]
+    },
+    {
+      "name": "FormSavedViews",
+      "file": "components/form-saved-views.tsx",
+      "purpose": "Save and reapply the forms list search and health filter.",
+      "operations": [
+        "list_saved_form_views_forms_views_saved_get",
+        "save_form_view_forms_views_saved__view_id__put"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "MoreRows",
+      "file": "components/more-rows.tsx",
+      "purpose": "Footer for paged lists: how many rows are shown and a Load more button.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "SubmissionsExport",
+      "file": "components/submissions-export.tsx",
+      "purpose": "Download a form submissions as a CSV file.",
+      "operations": [
+        "search_form_submissions_forms__form_key__submissions_post"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [],
@@ -140,6 +242,10 @@
     {
       "file": "lib/form-types.ts",
       "purpose": "Form/submission types and tolerant readers for passthrough responses, status labels, mapping payload builder."
+    },
+    {
+      "file": "lib/forms-extra.ts",
+      "purpose": "Helpers for the forms management components: open-dict readers, paging adapter, date and CSV helpers."
     }
   ],
   "recipes": [
@@ -187,6 +293,7 @@
   ],
   "scopes": [
     "contacts:read",
+    "forms:delete",
     "forms:read",
     "forms:run",
     "forms:write",

package/blocks/forms/components/form-activity.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+/**
+ * FormActivity: the audit trail of one form (route saved, delivery paused, backfill queued...) and the pages it was
+ * seen on.
+ *
+ * SDK operations:
+ *   1. getFormActivity    GET /forms/{form_key}/activity?source_id     (read; newest first)
+ *   2. getFormPlacements  GET /forms/{form_key}/placements?source_id   (read; the page URLs the form was seen on)
+ *
+ * Both payloads are open dicts: events show whatever of `action`, `actor_id`, `created_at` and `details` is present.
+ * The API returns a bounded history (the latest events); when it comes back full the screen says so.
+ */
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import type { FormRef } from "../lib/form-types";
+import { rowsOf, str, when } from "../lib/forms-extra";
+import type { Rec } from "../lib/forms-extra";
+
+export interface FormActivityProps {
+  form: FormRef;
+  className?: string;
+}
+
+/** How many events the activity read is expected to hold at most; a full read gets a notice. */
+export const ACTIVITY_WINDOW = 500;
+
+const words = (v: unknown): string => str(v).replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+
+export function FormActivity({ form, className }: FormActivityProps) {
+  const base = `/forms/${encodeURIComponent(form.form_key)}`;
+  const q = { source_id: form.source_id };
+  const activity = useG8Query((signal) => g8Get(`${base}/activity`, q, { signal }), [form.form_key, form.source_id]);
+  const placements = useG8Query((signal) => g8Get(`${base}/placements`, q, { signal }), [form.form_key, form.source_id]);
+  const events = rowsOf<Rec>(activity.data?.data, "events", "activity");
+  const pages = rowsOf<Rec>(placements.data?.data, "placements");
+  return (
+    <div className={className}>
+      <div className="grid gap-4">
+        <SectionCard title="Where this form appears" description="Pages the form was seen on.">
+          {placements.error ? <ApiError error={placements.error} title="Could not load the pages" onRetry={() => void placements.refetch()} /> : placements.loading && !placements.data ? <Skeleton className="h-16 w-full" aria-busy="true" /> : pages.length === 0 ? (
+            <EmptyState compact title="No pages recorded yet" description="A page is recorded when the form is submitted from it." />
+          ) : (
+            <ul className="grid gap-1">{pages.map((p, i) => <li key={i} className="truncate text-sm">{str(p.page_url) || str(p.url) || str(p.path)}{p.last_seen_at ? <span className="text-muted-foreground text-xs"> · last seen {when(p.last_seen_at)}</span> : null}</li>)}</ul>
+          )}
+        </SectionCard>
+        <SectionCard title="Activity" description="Changes made to how this form is routed.">
+          {activity.error ? <ApiError error={activity.error} title="Could not load the activity" onRetry={() => void activity.refetch()} /> : activity.loading && !activity.data ? <Skeleton className="h-24 w-full" aria-busy="true" /> : events.length === 0 ? (
+            <EmptyState compact title="No activity yet" description="Changes to the destination, mapping and delivery are listed here." />
+          ) : (
+            <>
+              <ol className="grid gap-2">
+                {events.map((e, i) => (
+                  <li key={str(e.id) || i} className="rounded-md border p-2 text-sm">
+                    <span className="font-medium">{words(e.action) || words(e.type) || "Change"}</span>
+                    <span className="text-muted-foreground text-xs"> {when(e.created_at)}{str(e.actor_id) ? ` · by ${str(e.actor_id)}` : ""}</span>
+                  </li>
+                ))}
+              </ol>
+              {events.length >= ACTIVITY_WINDOW ? <p role="note" className="text-muted-foreground mt-2 text-xs">Showing the latest {ACTIVITY_WINDOW} events. Older ones are not listed.</p> : null}
+            </>
+          )}
+        </SectionCard>
+      </div>
+    </div>
+  );
+}

package/blocks/forms/components/form-backfill.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+/**
+ * FormBackfill: deliver leads that were captured BEFORE the form had a destination (or while it was paused) through the
+ * form's current route. Preview first, then deliver. Delivering creates or updates contacts and cannot be undone.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. getFormOverview    GET  /forms/{form_key}/overview?source_id          (read; the destination, the route version and how many leads were captured)
+ *   2. createFormBackfill POST /forms/{form_key}/backfills { source_id, start_at?, end_at?, preview: true }    (records a PREVIEW job; delivers nothing)
+ *   3. createFormBackfill POST /forms/{form_key}/backfills { ..., preview: false, estimated }                   (EXTERNAL, confirmed: delivers leads)
+ *   4. getFormBackfill    GET  /forms/{form_key}/backfills/{job}             (read; polled every 3 s while the job is queued or running)
+ *
+ * A form with no destination cannot be backfilled: the screen says so and points at "Destination and fields". The API
+ * does not count the leads in a window, so the confirm states the most that can be delivered (all captured leads) and
+ * the dates only narrow it. Dates are whole days in UTC: the end day is included.
+ */
+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 { useConfirmAction } from "@/g8/components/confirmed-action";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import type { FormOverview, FormRef } from "../lib/form-types";
+import { asRec, dayInstant, num, str } from "../lib/forms-extra";
+
+export interface FormBackfillProps {
+  form: FormRef;
+  className?: string;
+}
+
+const ACTIVE = new Set(["queued", "running"]);
+
+export function FormBackfill({ form, className }: FormBackfillProps) {
+  const base = `/forms/${encodeURIComponent(form.form_key)}`;
+  const { ask, dialog, failure } = useConfirmAction();
+  const overview = useG8Query((signal) => g8Get<FormOverview>(`${base}/overview`, { source_id: form.source_id }, { signal }).then((r) => r.data), [form.form_key, form.source_id]);
+  const [from, setFrom] = useState("");
+  const [to, setTo] = useState("");
+  const [jobId, setJobId] = useState("");
+  const job = useG8Query((signal) => g8Get(`${base}/backfills/${encodeURIComponent(jobId)}`, undefined, { signal }), [jobId], { enabled: jobId !== "" });
+  const j = asRec(job.data?.data);
+  const state = str(j.state);
+
+  useEffect(() => {
+    if (jobId === "" || !ACTIVE.has(state)) return;
+    const t = setTimeout(() => void job.refetch(), 3000);
+    return () => clearTimeout(t);
+  }, [jobId, state, job.data]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const startAt = dayInstant(from);
+  const endAt = dayInstant(to, true);
+  const reversed = startAt !== undefined && endAt !== undefined && startAt >= endAt;
+  // A legacy-mapping form has a destination but no route: the API refuses a backfill for it (409), so gate on the route.
+  const hasDestination = Boolean(overview.data?.route);
+  const captured = overview.data?.metrics?.captured ?? 0;
+  const window = { ...(startAt ? { start_at: startAt } : {}), ...(endAt ? { end_at: endAt } : {}) };
+  const preview = useG8Mutation(async () => { const res = await g8Post(`${base}/backfills`, { source_id: form.source_id, ...window, preview: true }); setJobId(str(asRec(res.data).id)); });
+
+  const deliver = (): void => ask({
+    tier: "external",
+    title: `Deliver captured leads from "${form.form_key}"`,
+    confirmLabel: "Deliver leads",
+    recipients: captured,
+    description: `Runs the saved leads through the current destination${overview.data?.destination?.list_name ? ` (${overview.data.destination.list_name})` : ""}, creating or updating contacts. Up to ${captured.toLocaleString()} captured leads, fewer if you set dates. This cannot be undone.`,
+    run: async () => { const res = await g8Post(`${base}/backfills`, { source_id: form.source_id, ...window, preview: false, estimated: captured }); setJobId(str(asRec(res.data).id)); },
+  });
+
+  return (
+    <SectionCard className={className} title="Backfill earlier leads" description="Send leads captured before the destination was set up.">
+      {overview.error ? <ApiError error={overview.error} title="Could not load the form" onRetry={() => void overview.refetch()} /> : !overview.data ? <Skeleton className="h-24 w-full" aria-busy="true" /> : !hasDestination ? (
+        <p className="text-sm">This form has no destination route yet. Set one in Destination and fields, then come back.</p>
+      ) : (
+        <div className="grid gap-3">
+          <p className="text-sm">{captured.toLocaleString()} captured {captured === 1 ? "lead" : "leads"} are available to deliver to <strong>{overview.data.destination?.list_name ?? "the destination"}</strong>.</p>
+          <div className="flex flex-wrap items-end gap-3">
+            <div><Label htmlFor="fb-from" className="mb-1">From (optional)</Label><Input id="fb-from" type="date" value={from} onChange={(e) => setFrom(e.target.value)} /></div>
+            <div><Label htmlFor="fb-to" className="mb-1">Through (optional)</Label><Input id="fb-to" type="date" value={to} onChange={(e) => setTo(e.target.value)} aria-invalid={reversed} /></div>
+            <Button variant="outline" loading={preview.loading} disabled={reversed} onClick={() => void preview.mutate(undefined)}>Preview</Button>
+            <Button disabled={reversed || captured === 0 || ACTIVE.has(state)} onClick={deliver}>Deliver leads</Button>
+          </div>
+          {reversed ? <p role="alert" className="text-error-foreground text-xs">The start day must be before the end day.</p> : null}
+          {captured === 0 ? <p className="text-muted-foreground text-xs">Nothing has been captured yet.</p> : null}
+          {jobId !== "" ? (
+            job.error ? <ApiError error={job.error} title="Could not read the backfill" onRetry={() => void job.refetch()} /> : (
+              <div className="grid gap-2" role="status">
+                <p className="flex items-center gap-2 text-sm">Backfill <StatusPill tone={state === "completed" ? "positive" : state === "failed" ? "negative" : state === "preview" ? "neutral" : "info"}>{state || "starting"}</StatusPill></p>
+                <KeyValueList columns={2} items={[
+                  { label: "Estimated leads", value: num(j.estimated) == null ? "" : String(j.estimated) },
+                  { label: "Delivered", value: num(j.delivered) == null ? (num(j.processed) == null ? "" : String(j.processed)) : String(j.delivered) },
+                  { label: "Failed", value: num(j.failed) == null ? "" : String(j.failed) },
+                ]} />
+                {state === "preview" ? <p className="text-muted-foreground text-xs">This was a preview. Nothing was delivered.</p> : null}
+              </div>
+            )
+          ) : null}
+        </div>
+      )}
+      {preview.error ? <ApiError error={preview.error} title="Could not preview" /> : null}
+      {failure ? <ApiError error={failure} title="Could not start the backfill" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </SectionCard>
+  );
+}

package/blocks/forms/components/form-builder.tsx

@@ -68,7 +68,7 @@ function FormHeader({ form, onChanged }: { form: FormListItem; onChanged: () =>
           ))}
         </dl>
       ) : null}
-      {overview.data?.delivery_warning ? <p className="text-sm text-amber-700">{overview.data.delivery_warning}</p> : null}
+      {overview.data?.delivery_warning ? <p className="text-sm text-warning-foreground">{overview.data.delivery_warning}</p> : null}
       <ConfirmSpendDialog
         open={confirm !== null}
         tier="external"

package/blocks/forms/components/form-embed.tsx

@@ -75,7 +75,7 @@ export function FormEmbed({ streamId }: FormEmbedProps) {
             <select id="g8-stream" className="border-input bg-background h-9 max-w-sm rounded-md border px-2 text-sm" value={stream ?? s.stream_id ?? ""} onChange={(e) => setStream(e.target.value)}>
               {s.available_streams.map((st) => <option key={st.id} value={st.id}>{st.name}{st.domains?.length ? ` (${st.domains.join(", ")})` : ""}</option>)}
             </select>
-            {s.warning ? <p className="text-sm text-amber-700">{s.warning}</p> : null}
+            {s.warning ? <p className="text-sm text-warning-foreground">{s.warning}</p> : null}
           </CardContent>
         </Card>
       ) : null}

package/blocks/forms/components/form-groups.tsx

@@ -0,0 +1,151 @@
+"use client";
+
+/**
+ * FormGroups: curated groups of forms ("Demo requests", "Newsletter sign-ups") so related forms are read together.
+ * Create a group, rename or re-type it, add and remove its forms, delete it. A form belongs to one group: adding it to
+ * another group moves it.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. listFormGroups          GET    /forms/groups                          (read)
+ *   2. listForms               GET    /forms?page&per_page&search            (read; the forms you can add, paged with "Load more")
+ *   3. createFormGroup         POST   /forms/groups { name, form_type, members }          (write)
+ *   4. updateFormGroup         PATCH  /forms/groups/{id} { name?, form_type? }            (write; only changed fields are sent)
+ *   5. addFormGroupMembers     POST   /forms/groups/{id}/members { members }              (write)
+ *   6. removeFormGroupMembers  POST   /forms/groups/{id}/members/remove { members }       (write)
+ *   7. deleteFormGroup         DELETE /forms/groups/{id}                                  (destructive, confirmed: the forms themselves stay)
+ */
+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 { useConfirmAction } from "@/g8/components/confirmed-action";
+import { EmptyState } from "@/g8/components/empty-state";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { usePaginated } from "@/g8/hooks/use-paginated";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { formLabel, pickItems } from "../lib/form-types";
+import type { FormListItem } from "../lib/form-types";
+import { memberRef, pageOf, rowsOf, str } from "../lib/forms-extra";
+import type { Rec } from "../lib/forms-extra";
+import { MoreRows } from "./more-rows";
+
+export interface FormGroupsProps {
+  className?: string;
+}
+
+const TYPES = ["lead", "newsletter", "meeting", "contact", "download", "other"] as const;
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+const PAGE = 50;
+
+const keyOf = (f: { form_key: string; source_id: string }): string => `${f.source_id}/${f.form_key}`;
+
+/** The forms that can be added, searchable and paged. Forms already picked are marked, never hidden. */
+function FormPicker({ picked, onToggle }: { picked: Set<string>; onToggle: (f: FormListItem) => void }) {
+  const [search, setSearch] = useState("");
+  const list = usePaginated<FormListItem>(async (cursor, signal) => {
+    const page = cursor ? Number(cursor) : 1;
+    const res = await g8Get("/forms", { page, per_page: PAGE, search: search.trim() || undefined }, { signal });
+    const d = res.data as { items?: FormListItem[]; total?: number } | undefined;
+    const got = pickItems<FormListItem>(d, "items");
+    return pageOf(got, got.length > 0 && page * PAGE < (d?.total ?? 0) ? page + 1 : null);
+  }, [search]);
+  return (
+    <div className="grid gap-2">
+      <Input aria-label="Search forms to add" placeholder="Search forms" value={search} onChange={(e) => setSearch(e.target.value)} />
+      {list.error ? <ApiError error={list.error} title="Could not load forms" onRetry={() => void list.reload()} /> : list.loading ? <Skeleton className="h-16 w-full" aria-busy="true" /> : list.items.length === 0 ? (
+        <EmptyState compact title={search ? "No form matches" : "No forms captured yet"} />
+      ) : (
+        <>
+          <ul className="grid max-h-64 gap-1 overflow-y-auto">
+            {list.items.map((f) => (
+              <li key={keyOf(f)}>
+                <label className="flex items-center gap-2 rounded-md border p-2 text-sm">
+                  <input type="checkbox" checked={picked.has(keyOf(f))} onChange={() => onToggle(f)} aria-label={`Include ${formLabel(f)}`} />
+                  <span className="truncate">{formLabel(f)}</span>
+                </label>
+              </li>
+            ))}
+          </ul>
+          <MoreRows shown={list.items.length} noun="forms" hasMore={list.hasMore} loading={list.loadingMore} onMore={() => void list.loadMore()} />
+        </>
+      )}
+    </div>
+  );
+}
+
+function GroupCard({ group, onChanged }: { group: Rec; onChanged: () => void }) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const id = str(group.id);
+  const members = rowsOf<Rec>(group.members).map(memberRef);
+  const [name, setName] = useState(str(group.name));
+  const [type, setType] = useState(str(group.form_type, "other"));
+  const [adding, setAdding] = useState(false);
+  const [picked, setPicked] = useState<Map<string, { form_key: string; source_id: string }>>(new Map());
+  const changes: Rec = {};
+  if (name.trim() !== str(group.name)) changes.name = name.trim();
+  if (type !== str(group.form_type, "other")) changes.form_type = type;
+  const save = useG8Mutation(() => g8Patch(`/forms/groups/${encodeURIComponent(id)}`, changes), { onSuccess: onChanged });
+  const add = useG8Mutation(() => g8Post(`/forms/groups/${encodeURIComponent(id)}/members`, { members: [...picked.values()] }), { onSuccess: () => { setAdding(false); setPicked(new Map()); onChanged(); } });
+  const remove = useG8Mutation((m: { form_key: string; source_id: string }) => g8Post(`/forms/groups/${encodeURIComponent(id)}/members/remove`, { members: [m] }), { onSuccess: onChanged });
+  const toggle = (f: FormListItem): void => setPicked((cur) => { const n = new Map(cur); if (n.has(keyOf(f))) n.delete(keyOf(f)); else n.set(keyOf(f), { form_key: f.form_key, source_id: f.source_id }); return n; });
+  return (
+    <li className="grid gap-3 rounded-md border p-3">
+      <div className="flex flex-wrap items-center gap-2">
+        <Input aria-label={`Group name ${str(group.name)}`} className="max-w-xs" value={name} onChange={(e) => setName(e.target.value)} />
+        <select aria-label={`Type of ${str(group.name)}`} className={SELECT} value={type} onChange={(e) => setType(e.target.value)}>{TYPES.map((t) => <option key={t} value={t}>{t[0].toUpperCase() + t.slice(1)}</option>)}</select>
+        <Button size="sm" variant="outline" loading={save.loading} disabled={Object.keys(changes).length === 0 || name.trim() === ""} onClick={() => void save.mutate(undefined)}>Save group</Button>
+        <Button size="sm" variant="ghost" className="ml-auto" aria-label={`Delete group ${str(group.name)}`} onClick={() => ask({
+          tier: "destructive", title: `Delete the group "${str(group.name)}"`, confirmLabel: "Delete group", affected: members.length,
+          description: "Only the group is removed. Its forms keep capturing and routing leads.", tolerateStatus: [404],
+          run: () => g8Delete(`/forms/groups/${encodeURIComponent(id)}`), onDone: onChanged,
+        })}>Delete</Button>
+      </div>
+      {members.length === 0 ? <p className="text-muted-foreground text-xs">No forms in this group yet.</p> : (
+        <ul className="flex flex-wrap gap-1">{members.map((m) => (
+          <li key={keyOf(m)} className="flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs">{m.form_key}<button type="button" aria-label={`Remove ${m.form_key} from ${str(group.name)}`} className="text-muted-foreground hover:text-foreground" onClick={() => void remove.mutate(m)}>x</button></li>
+        ))}</ul>
+      )}
+      <div><Button size="sm" variant="outline" onClick={() => setAdding(true)}>Add forms</Button></div>
+      {[save.error, remove.error].filter(Boolean).map((e, i) => <ApiError key={i} error={e} title="That did not work" />)}
+      {failure ? <ApiError error={failure} title="Could not delete the group" /> : null}
+      <FormSheet open={adding} onOpenChange={setAdding} title={`Add forms to ${str(group.name)}`} description="A form in another group moves here." width="lg"
+        footer={<><Button variant="outline" onClick={() => setAdding(false)}>Cancel</Button><Button loading={add.loading} disabled={picked.size === 0} onClick={() => void add.mutate(undefined)}>Add {picked.size || ""} forms</Button></>}>
+        <FormPicker picked={new Set(picked.keys())} onToggle={toggle} />
+        {add.error ? <ApiError error={add.error} title="Could not add the forms" /> : null}
+      </FormSheet>
+      <ConfirmSpendDialog {...dialog} />
+    </li>
+  );
+}
+
+export function FormGroups({ className }: FormGroupsProps) {
+  const groups = useG8Query((signal) => g8Get("/forms/groups", undefined, { signal }), []);
+  const rows = rowsOf<Rec>(groups.data?.data, "groups");
+  const [creating, setCreating] = useState(false);
+  const [name, setName] = useState("");
+  const [type, setType] = useState<(typeof TYPES)[number]>("lead");
+  const [picked, setPicked] = useState<Map<string, { form_key: string; source_id: string }>>(new Map());
+  const create = useG8Mutation(() => g8Post("/forms/groups", { name: name.trim(), form_type: type, members: [...picked.values()] }), {
+    onSuccess: () => { setCreating(false); setName(""); setPicked(new Map()); void groups.refetch(); },
+  });
+  const toggle = (f: FormListItem): void => setPicked((cur) => { const n = new Map(cur); if (n.has(keyOf(f))) n.delete(keyOf(f)); else n.set(keyOf(f), { form_key: f.form_key, source_id: f.source_id }); return n; });
+  return (
+    <div className={className}>
+      <SectionCard title="Form groups" description="Keep related forms together." actions={<Button size="sm" onClick={() => setCreating(true)}>New group</Button>}>
+        {groups.error ? <ApiError error={groups.error} title="Could not load groups" onRetry={() => void groups.refetch()} /> : groups.loading && !groups.data ? <Skeleton className="h-20 w-full" aria-busy="true" /> : rows.length === 0 ? (
+          <EmptyState compact title="No groups yet" description="Group forms such as every demo request form." action={<Button onClick={() => setCreating(true)}>New group</Button>} />
+        ) : <ul className="grid gap-3">{rows.map((g) => <GroupCard key={str(g.id)} group={g} onChanged={() => void groups.refetch()} />)}</ul>}
+      </SectionCard>
+      <FormSheet open={creating} onOpenChange={setCreating} title="New form group" description="Pick the forms that belong together." width="lg"
+        footer={<><Button variant="outline" onClick={() => setCreating(false)}>Cancel</Button><Button loading={create.loading} disabled={name.trim() === ""} onClick={() => void create.mutate(undefined)}>Create group</Button></>}>
+        <div><Label htmlFor="fg-name" className="mb-1">Name</Label><Input id="fg-name" value={name} onChange={(e) => setName(e.target.value)} /></div>
+        <div><Label htmlFor="fg-type" className="mb-1">Type</Label><select id="fg-type" className={`${SELECT} w-full`} value={type} onChange={(e) => setType(e.target.value as (typeof TYPES)[number])}>{TYPES.map((t) => <option key={t} value={t}>{t[0].toUpperCase() + t.slice(1)}</option>)}</select></div>
+        <FormPicker picked={new Set(picked.keys())} onToggle={toggle} />
+        {create.error ? <ApiError error={create.error} title="Could not create the group" /> : null}
+      </FormSheet>
+    </div>
+  );
+}