@graph8/sdk 0.308.1 → 0.357.0

package/blocks/forms/block.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "forms",
+  "title": "Forms",
+  "summary": "Capture website lead forms, route each submission to a list with a field mapping, watch submissions and retry failed deliveries.",
+  "features": [
+    "tracking snippet and lead-form embed code",
+    "forms inventory with health and counts",
+    "destination list and field mapping with preview and test",
+    "pause and resume delivery",
+    "submissions table with delivery trace and retry",
+    "site audit of uncaptured forms"
+  ],
+  "dependsOn": [
+    "crm"
+  ],
+  "operations": [
+    "list_forms_forms_get",
+    "get_form_overview_forms__form_key__overview_get",
+    "update_form_registry_forms__form_key__patch",
+    "pause_form_delivery_forms__form_key__delivery_pause_post",
+    "resume_form_delivery_forms__form_key__delivery_resume_post",
+    "get_form_fields_forms__form_key__fields_get",
+    "get_contact_form_fields_contacts_form_fields_get",
+    "list_lists_lists_get",
+    "get_form_route_recommendations_forms__form_key__route_recommendations_get",
+    "preview_form_mapping_forms__form_key__mapping_preview_post",
+    "save_form_mapping_forms__form_key__mapping_save_post",
+    "test_form_route_forms__form_key__route_test_post",
+    "get_org_snippet_snippet_get",
+    "get_form_template_snippet_form_get",
+    "search_form_submissions_forms__form_key__submissions_post",
+    "get_form_submission_trace_forms__form_key__submissions__submission_id__trace_get",
+    "retry_form_delivery_forms_deliveries__receipt_id__retry_post",
+    "get_site_audit_forms_site_audit_get",
+    "request_site_audit_scan_forms_site_audit_scan_post",
+    "update_site_audit_finding_forms_site_audit_findings__finding_id__patch"
+  ],
+  "components": [
+    {
+      "name": "FormBuilder",
+      "file": "components/form-builder.tsx",
+      "purpose": "Forms workspace: list captured forms, rename, pause/resume delivery, set destination and mapping, view submissions.",
+      "operations": [
+        "list_forms_forms_get",
+        "get_form_overview_forms__form_key__overview_get",
+        "update_form_registry_forms__form_key__patch",
+        "pause_form_delivery_forms__form_key__delivery_pause_post",
+        "resume_form_delivery_forms__form_key__delivery_resume_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external"
+      ]
+    },
+    {
+      "name": "FormMappingEditor",
+      "file": "components/form-mapping-editor.tsx",
+      "purpose": "Pick the destination list and map submitted fields to contact fields, with suggest, preview, save and test.",
+      "operations": [
+        "get_form_overview_forms__form_key__overview_get",
+        "get_form_fields_forms__form_key__fields_get",
+        "get_contact_form_fields_contacts_form_fields_get",
+        "list_lists_lists_get",
+        "get_form_route_recommendations_forms__form_key__route_recommendations_get",
+        "preview_form_mapping_forms__form_key__mapping_preview_post",
+        "save_form_mapping_forms__form_key__mapping_save_post",
+        "test_form_route_forms__form_key__route_test_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "FormEmbed",
+      "file": "components/form-embed.tsx",
+      "purpose": "Copyable tracking snippet (script tag, React) and a ready-made lead-capture form with live preview.",
+      "operations": [
+        "get_org_snippet_snippet_get",
+        "get_form_template_snippet_form_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SubmissionsTable",
+      "file": "components/submissions-table.tsx",
+      "purpose": "Paged submissions with delivery state, a per-lead trace and a confirmed retry for failed deliveries.",
+      "operations": [
+        "search_form_submissions_forms__form_key__submissions_post",
+        "get_form_submission_trace_forms__form_key__submissions__submission_id__trace_get",
+        "retry_form_delivery_forms_deliveries__receipt_id__retry_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "SiteAuditPanel",
+      "file": "components/site-audit-panel.tsx",
+      "purpose": "Forms on your site that are not captured, from the latest crawl; rescan and triage findings.",
+      "operations": [
+        "get_site_audit_forms_site_audit_get",
+        "request_site_audit_scan_forms_site_audit_scan_post",
+        "update_site_audit_finding_forms_site_audit_findings__finding_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/form-types.ts",
+      "purpose": "Form/submission types and tolerant readers for passthrough responses, status labels, mapping payload builder."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/install-snippet-and-form.ts",
+      "title": "Get the tracking snippet and a lead-capture form",
+      "when": "Wiring a site so graph8 captures its forms."
+    },
+    {
+      "file": "recipes/route-form-to-list.ts",
+      "title": "Route a captured form's leads to a list with a field mapping",
+      "when": "A form appears in the inventory but its leads go nowhere (Needs setup)."
+    },
+    {
+      "file": "recipes/retry-failed-deliveries.ts",
+      "title": "Find failed lead deliveries and retry them",
+      "when": "A destination was broken for a while and leads piled up as failed."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "snippet-installed",
+      "description": "The graph8 tracking snippet must be loaded on every page that has a form. Forms only appear after their first captured submission. FormEmbed gives the code; the human (or the agent, in the site's code) pastes it.",
+      "where": "app",
+      "verify": "Submit a form on the live site, then GET /api/v1/forms lists it within a minute."
+    },
+    {
+      "id": "destination-list",
+      "description": "A list to receive leads. Create one in the graph8 workspace (or with the lists block / recipe) before saving a mapping.",
+      "where": "api",
+      "verify": "GET /api/v1/lists returns at least one list."
+    },
+    {
+      "id": "proxy-allowlist",
+      "description": "Add \"forms\", \"snippet\", \"contacts\" and \"lists\" to allowedPrefixes in app/api/g8/[...path]/route.ts.",
+      "where": "app",
+      "verify": "The route file's allowedPrefixes contains those four prefixes."
+    },
+    {
+      "id": "signals-write",
+      "description": "Submitted values (emails, names) are redacted for keys without the Signals write capability. Use a key that has it if the app must show the leads' contact details.",
+      "where": "api",
+      "verify": "A submission's identifying fields are not empty in SubmissionsTable."
+    }
+  ],
+  "scopes": [
+    "contacts:read",
+    "forms:read",
+    "forms:run",
+    "forms:write",
+    "integrations:read",
+    "lists:read"
+  ],
+  "defaults": [
+    {
+      "decision": "Hosted form designer vs capture existing forms",
+      "default": "Capture the site's existing forms through the snippet; the generated lead form (FormEmbed) is only a starting point, graph8 has no form designer API",
+      "askHuman": false
+    },
+    {
+      "decision": "Which list receives a form's leads",
+      "default": "A new list named after the form",
+      "askHuman": true
+    },
+    {
+      "decision": "Mapping when the form has an email field",
+      "default": "Map it to CONTACT_WORK_EMAIL; use Suggest mapping for the rest",
+      "askHuman": false
+    },
+    {
+      "decision": "Retrying failed deliveries",
+      "default": "One lead at a time, after the person confirms (it creates or updates a contact)",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

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

@@ -0,0 +1,150 @@
+"use client";
+
+/**
+ * FormBuilder: the forms workspace. Pick a captured form, name it, route its leads, and watch what arrives.
+ *
+ * graph8 captures the lead forms already on your site (install the snippet with FormEmbed) rather than hosting
+ * a form designer, so "building" a form here means setting up where its submissions go and how fields map.
+ *
+ * SDK operations, in order:
+ *   1. listForms (GET /forms?search=&page=&per_page=)                         read
+ *   2. getFormOverview (GET /forms/{form_key}/overview?source_id=)            read
+ *   3. updateFormRegistry (PATCH /forms/{form_key})                           write     (rename)
+ *   4. pauseFormDelivery / resumeFormDelivery (POST .../delivery/pause|resume)  external -> ConfirmSpendDialog
+ *   5. FormMappingEditor (destination list + field mapping) and SubmissionsTable (what arrived)
+ * Pausing keeps accepting submissions (they queue); resuming starts delivering to the list again, which creates
+ * and updates contacts, so both go through the confirm dialog.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, 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 { 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 { STATUS_LABEL, formLabel, formStatus, pageUrlText, pickItems } from "../lib/form-types";
+import type { FormListItem, FormOverview, FormRef } from "../lib/form-types";
+import { FormMappingEditor } from "./form-mapping-editor";
+import { SubmissionsTable } from "./submissions-table";
+
+export interface FormBuilderProps {
+  /** Form to open first. */
+  initialForm?: FormRef;
+  onSelectForm?: (form: FormListItem) => void;
+}
+
+const PER_PAGE = 20;
+
+function FormHeader({ form, onChanged }: { form: FormListItem; onChanged: () => void }) {
+  const base = `/forms/${encodeURIComponent(form.form_key)}`;
+  const overview = useG8Query((signal) => g8Get<FormOverview>(`${base}/overview`, { source_id: form.source_id }, { signal }).then((r) => r.data), [base, form.source_id]);
+  const [name, setName] = useState(form.display_name ?? "");
+  const [confirm, setConfirm] = useState<"pause" | "resume" | null>(null);
+  const rename = useG8Mutation(() => g8Patch(base, { source_id: form.source_id, display_name: name.trim() }), { onSuccess: onChanged });
+  const toggle = useG8Mutation((action: "pause" | "resume") => g8Post(`${base}/delivery/${action}`, { source_id: form.source_id }), {
+    onSuccess: () => { setConfirm(null); void overview.refetch(); onChanged(); },
+  });
+  const paused = overview.data?.delivery_health === "paused";
+  const m = overview.data?.metrics;
+  return (
+    <div className="grid gap-3">
+      <form className="flex items-end gap-2" onSubmit={(e) => { e.preventDefault(); if (name.trim()) void rename.mutate(undefined); }}>
+        <div className="max-w-sm flex-1">
+          <label htmlFor="g8-form-name" className="text-muted-foreground text-xs">Form name</label>
+          <Input id="g8-form-name" value={name} placeholder={form.form_key} onChange={(e) => setName(e.target.value)} />
+        </div>
+        <Button type="submit" size="sm" variant="outline" loading={rename.loading} disabled={!name.trim() || name.trim() === form.display_name}>Rename</Button>
+        <Button type="button" size="sm" variant="outline" disabled={!overview.data} onClick={() => setConfirm(paused ? "resume" : "pause")}>{paused ? "Resume delivery" : "Pause delivery"}</Button>
+      </form>
+      {rename.error ? <ApiError error={rename.error} title="Could not rename the form" /> : null}
+      {overview.error ? <ApiError error={overview.error} title="Could not load the form overview" onRetry={() => void overview.refetch()} /> : null}
+      {m ? (
+        <dl className="grid grid-cols-2 gap-2 text-sm sm:grid-cols-5">
+          {([["Captured", m.captured], ["Processed", m.processed], ["In destination", m.destination_verified], ["Failed", m.failed], ["Activated", m.activated]] as const).map(([label, value]) => (
+            <div key={label}><dt className="text-muted-foreground text-xs">{label}</dt><dd className="font-medium">{value ?? 0}</dd></div>
+          ))}
+        </dl>
+      ) : null}
+      {overview.data?.delivery_warning ? <p className="text-sm text-amber-700">{overview.data.delivery_warning}</p> : null}
+      <ConfirmSpendDialog
+        open={confirm !== null}
+        tier="external"
+        title={confirm === "pause" ? "Pause delivery for this form?" : "Resume delivery for this form?"}
+        confirmLabel={confirm === "pause" ? "Pause" : "Resume"}
+        description={<><p>{confirm === "pause" ? "New submissions are still captured but queue instead of reaching your list." : "Queued and new submissions are delivered to the destination list, creating or updating contacts."}</p>{toggle.error ? <ApiError error={toggle.error} title="Could not change delivery" /> : null}</>}
+        confirming={toggle.loading}
+        onCancel={() => setConfirm(null)}
+        onConfirm={() => { if (confirm) void toggle.mutate(confirm); }}
+      />
+    </div>
+  );
+}
+
+export function FormBuilder({ initialForm, onSelectForm }: FormBuilderProps) {
+  const [page, setPage] = useState(1);
+  const [searchText, setSearchText] = useState("");
+  const [search, setSearch] = useState("");
+  const [selected, setSelected] = useState<FormRef | undefined>(initialForm);
+  const [view, setView] = useState<"setup" | "submissions">("setup");
+  const forms = useG8Query(
+    (signal) => g8Get<{ items?: FormListItem[]; total?: number }>("/forms", { page, per_page: PER_PAGE, search: search || undefined }, { signal }).then((r) => ({ items: pickItems<FormListItem>(r.data, "items"), total: (r.data as { total?: number } | undefined)?.total ?? 0 })),
+    [page, search],
+  );
+  const items = forms.data?.items ?? [];
+  const [lastItem, setLastItem] = useState<FormListItem | undefined>(undefined);
+  const onPage = items.find((f) => f.form_key === selected?.form_key && f.source_id === selected?.source_id);
+  // A selected form can be off this page (initialForm, or filtered out by a search): keep working with it.
+  const current: FormListItem | undefined = onPage ?? (selected ? (lastItem?.form_key === selected.form_key && lastItem.source_id === selected.source_id ? lastItem : { id: `${selected.source_id}:${selected.form_key}`, ...selected }) : undefined);
+
+  if (forms.error) return <ApiError error={forms.error} title="Could not load forms" onRetry={() => void forms.refetch()} />;
+  return (
+    <div className="grid gap-4 md:grid-cols-[20rem_1fr]">
+      <Card>
+        <CardHeader><CardTitle>Forms</CardTitle></CardHeader>
+        <CardContent className="grid gap-3">
+          <form className="flex gap-2" onSubmit={(e) => { e.preventDefault(); setPage(1); setSearch(searchText.trim()); }}>
+            <Input aria-label="Search forms" placeholder="Search forms" value={searchText} onChange={(e) => setSearchText(e.target.value)} />
+            <Button type="submit" size="sm" variant="outline">Search</Button>
+          </form>
+          {forms.loading && !forms.data ? <div className="grid gap-2" aria-busy="true"><Skeleton className="h-12 w-full" /><Skeleton className="h-12 w-full" /></div> : items.length === 0 ? (
+            <EmptyState title={search ? "No forms match" : "No forms captured yet"} description={search ? "Try another name." : "Install the graph8 snippet on your site (see FormEmbed). Forms appear here after their first submission."} />
+          ) : (
+            <ul className="grid gap-1">
+              {items.map((f) => {
+                const status = formStatus(f);
+                return (
+                  <li key={`${f.source_id}:${f.form_key}`}>
+                    <Button variant={f === current ? "secondary" : "ghost"} className="h-auto w-full flex-col items-start gap-0 py-2 text-left" onClick={() => { setSelected({ form_key: f.form_key, source_id: f.source_id }); setLastItem(f); onSelectForm?.(f); }}>
+                      <span className="font-medium">{formLabel(f)}</span>
+                      <span className="text-muted-foreground text-xs">{STATUS_LABEL[status]} · {f.total_submissions ?? 0} submissions{f.failed_submissions ? ` · ${f.failed_submissions} failed` : ""}</span>
+                      <span className="text-muted-foreground max-w-full truncate text-xs">{pageUrlText(f.page_url)}</span>
+                    </Button>
+                  </li>
+                );
+              })}
+            </ul>
+          )}
+          <div className="flex items-center justify-between text-sm">
+            <Button size="sm" variant="ghost" disabled={page <= 1} onClick={() => setPage(page - 1)}>Previous</Button>
+            <span className="text-muted-foreground">Page {page}</span>
+            <Button size="sm" variant="ghost" disabled={page * PER_PAGE >= (forms.data?.total ?? 0)} onClick={() => setPage(page + 1)}>Next</Button>
+          </div>
+        </CardContent>
+      </Card>
+      <div className="grid content-start gap-4">
+        {!selected || !current ? <EmptyState title="Pick a form" description="Choose a form to set its destination list and field mapping, or to see its submissions." /> : (
+          <>
+            <FormHeader key={`${current.source_id}:${current.form_key}`} form={current} onChanged={() => void forms.refetch()} />
+            <div className="flex gap-2" role="group" aria-label="Form sections">
+              <Button size="sm" variant={view === "setup" ? "secondary" : "ghost"} onClick={() => setView("setup")}>Setup</Button>
+              <Button size="sm" variant={view === "submissions" ? "secondary" : "ghost"} onClick={() => setView("submissions")}>Submissions</Button>
+            </div>
+            {view === "setup" ? <FormMappingEditor key={`${current.source_id}:${current.form_key}`} form={current} onSaved={() => void forms.refetch()} /> : <SubmissionsTable form={current} />}
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,103 @@
+"use client";
+
+/**
+ * FormEmbed: the code to put on your site so graph8 captures forms, plus a ready-made lead-capture form.
+ *
+ * SDK operations, in order:
+ *   1. getOrgSnippet (GET /snippet?stream_id=)       read   (write key, <script> tag, React component, allowed domains)
+ *   2. getFormTemplate (GET /snippet/form?stream_id=) read   (a self-contained HTML lead form that calls graph8.track)
+ * Both are copy-and-paste outputs; nothing is installed for you. The snippet must load on every page that has a form.
+ * With several streams (sites) the API answers `action_required` and lists them: the picker below chooses one.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+
+export interface FormEmbedProps {
+  /** Stream (site) to read the snippet for. Omit for the organization's main stream. */
+  streamId?: string;
+}
+
+interface Snippet {
+  write_key: string;
+  script_tag: string;
+  react_snippet: string;
+  domains?: string[];
+  stream_id?: string;
+  action_required?: boolean;
+  warning?: string | null;
+  available_streams?: Array<{ id: string; name: string; domains?: string[] }>;
+}
+
+function CodeBlock({ label, code }: { label: string; code: string }) {
+  const [copied, setCopied] = useState(false);
+  const copy = async (): Promise<void> => {
+    try {
+      await navigator.clipboard.writeText(code);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    } catch {
+      setCopied(false);
+    }
+  };
+  return (
+    <div className="grid gap-1">
+      <div className="flex items-center justify-between">
+        <Label>{label}</Label>
+        <Button size="sm" variant="outline" onClick={() => void copy()}>{copied ? "Copied" : `Copy ${label.toLowerCase()}`}</Button>
+      </div>
+      <pre className="bg-muted max-h-64 overflow-auto rounded-md p-3 text-xs" aria-label={label}>{code}</pre>
+    </div>
+  );
+}
+
+export function FormEmbed({ streamId }: FormEmbedProps) {
+  const [stream, setStream] = useState<string | undefined>(streamId);
+  const snippet = useG8Query((signal) => g8Get<Snippet>("/snippet", { stream_id: stream }, { signal }).then((r) => r.data), [stream]);
+  const template = useG8Query((signal) => g8Get<{ html?: string }>("/snippet/form", { stream_id: stream }, { signal }).then((r) => r.data), [stream]);
+  const [showPreview, setShowPreview] = useState(false);
+
+  if (snippet.error) return <ApiError error={snippet.error} title="Could not load the tracking snippet" onRetry={() => void snippet.refetch()} />;
+  if (snippet.loading && !snippet.data) return <div className="grid gap-2" aria-busy="true"><Skeleton className="h-8 w-48" /><Skeleton className="h-32 w-full" /></div>;
+  const s = snippet.data;
+  const html = template.data?.html ?? "";
+  return (
+    <div className="grid gap-4">
+      {s?.action_required && s.available_streams?.length ? (
+        <Card>
+          <CardContent className="grid gap-2 pt-6">
+            <Label htmlFor="g8-stream">Which site is this for?</Label>
+            <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}
+          </CardContent>
+        </Card>
+      ) : null}
+      <Card>
+        <CardHeader><CardTitle>1. Install the tracking snippet</CardTitle></CardHeader>
+        <CardContent className="grid gap-3">
+          <p className="text-muted-foreground text-sm">Put this on every page that has a form. graph8 then detects the forms and records submissions. Allowed domains: {s?.domains?.join(", ") || "any"}.</p>
+          {s?.script_tag ? <CodeBlock label="Script tag" code={s.script_tag} /> : null}
+          {s?.react_snippet ? <CodeBlock label="React component" code={s.react_snippet} /> : null}
+          <p className="text-muted-foreground text-xs">Write key: <code>{s?.write_key}</code> (public, safe in page source).</p>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle>2. Optional: a ready-made lead form</CardTitle></CardHeader>
+        <CardContent className="grid gap-3">
+          {template.error ? <ApiError error={template.error} title="Could not load the form template" onRetry={() => void template.refetch()} /> : template.loading && !template.data ? <Skeleton className="h-24 w-full" /> : html ? (
+            <>
+              <CodeBlock label="Form HTML" code={html} />
+              <div><Button size="sm" variant="outline" onClick={() => setShowPreview((v) => !v)}>{showPreview ? "Hide preview" : "Preview the form"}</Button></div>
+              {showPreview ? <iframe title="Form preview" sandbox="" srcDoc={html} className="h-72 w-full rounded-md border" /> : null}
+            </>
+          ) : <p className="text-muted-foreground text-sm">No template is available for this site.</p>}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/blocks/forms/components/form-mapping-editor.tsx

@@ -0,0 +1,125 @@
+"use client";
+
+/**
+ * FormMappingEditor: where a form's submissions go and how its fields become contact fields.
+ *
+ * SDK operations, in order:
+ *   1. getFormOverview (GET /forms/{form_key}/overview?source_id=)            read   (current destination + route version)
+ *   2. getFormFields (GET /forms/{form_key}/fields?source_id=)                read   (what the mapping maps FROM)
+ *   3. getContactFormFields (GET /contacts/form-fields)                       read   (what it maps TO, grouped)
+ *   4. listLists (GET /lists)                                                 read   (the destination list)
+ *   5. getFormRouteRecommendations (GET /forms/{form_key}/route/recommendations)   read   ("Suggest mapping")
+ *   6. previewFormMapping (POST /forms/{form_key}/mapping/preview)            read   (nothing is written)
+ *   7. saveFormMapping (POST /forms/{form_key}/mapping/save)                  write  (FULL replacement; sends expected_route_version)
+ *   8. testFormRoute (POST /forms/{form_key}/route/test)                      write  (adds ONE synthetic test contact to the list)
+ * Preview before you save: a saved mapping applies to every submission captured from then on.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { 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, mappingPayload, pickItems } from "../lib/form-types";
+import type { ContactFieldGroup, FormOverview, FormRef, MappingRow } from "../lib/form-types";
+
+export interface FormMappingEditorProps {
+  form: FormRef;
+  onSaved?: () => void;
+}
+
+interface ListOption { id: number; title: string }
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+
+/** A different form needs its own mapping state, so the editor is remounted per form (key). */
+export function FormMappingEditor(props: FormMappingEditorProps) {
+  return <FormMappingEditorFor key={`${props.form.source_id}:${props.form.form_key}`} {...props} />;
+}
+
+function FormMappingEditorFor({ form, onSaved }: FormMappingEditorProps) {
+  const base = `/forms/${encodeURIComponent(form.form_key)}`;
+  const q = { source_id: form.source_id };
+  const overview = useG8Query((signal) => g8Get<FormOverview>(`${base}/overview`, q, { signal }).then((r) => r.data), [base, form.source_id]);
+  const fields = useG8Query((signal) => g8Get(`${base}/fields`, q, { signal }).then((r) => pickItems<{ name: string }>(r.data, "items", "fields")), [base, form.source_id]);
+  const targets = useG8Query((signal) => g8Get<{ groups?: ContactFieldGroup[] }>("/contacts/form-fields", {}, { signal }).then((r) => r.data?.groups ?? []), []);
+  const lists = useG8Query((signal) => g8Get<ListOption[]>("/lists", { limit: 200 }, { signal }).then((r) => r.data ?? []), []);
+  const [rows, setRows] = useState<MappingRow[]>([]);
+  const [listId, setListId] = useState<number | undefined>(undefined);
+  const [seeded, setSeeded] = useState(false);
+
+  useEffect(() => {
+    if (seeded || !overview.data || !fields.data) return;
+    const existing = overview.data.route?.mapping ?? overview.data.form_to_contact_field_mapping ?? [];
+    // Save is a FULL replacement: keep every saved row and add a blank row for each captured field that has none yet
+    // (a site can add a field to an already-routed form).
+    const known = new Set(existing.map((m) => m.source_field));
+    setRows([...existing.map((m) => ({ ...m })), ...fields.data.filter((f) => !known.has(f.name)).map((f) => ({ source_field: f.name, target_field: "" }))]);
+    setListId(overview.data.destination?.list_id ?? undefined);
+    setSeeded(true);
+  }, [overview.data, fields.data, seeded]);
+
+  const listName = (lists.data ?? []).find((l) => l.id === listId)?.title ?? overview.data?.destination?.list_name ?? "";
+  const body = mappingPayload(form.source_id, rows, listName, listId, overview.data?.route?.version ?? overview.data?.destination?.route_version);
+  const ready = Boolean(listId) && body.form_to_contact_field_mapping.length > 0;
+
+  const suggest = useG8Mutation(async () => {
+    const r = await g8Get(`${base}/route/recommendations`, { ...q, target_list_id: listId }, {});
+    const recs = pickItems<{ source_field: string; target_field: string }>(r.data, "recommendations", "items", "mapping_recommendations");
+    setRows((prev) => prev.map((row) => (row.target_field ? row : { ...row, target_field: recs.find((x) => x.source_field === row.source_field)?.target_field ?? "" })));
+    return recs.length;
+  });
+  const preview = useG8Mutation(async () => (await g8Post(`${base}/mapping/preview`, body)).data);
+  const save = useG8Mutation(async () => (await g8Post(`${base}/mapping/save`, body)).data, { onSuccess: () => { void overview.refetch(); onSaved?.(); } });
+  const test = useG8Mutation(async () => (await g8Post(`${base}/route/test`, { source_id: form.source_id })).data);
+
+  const set = (i: number, patch: Partial<MappingRow>): void => setRows((prev) => prev.map((r, at) => (at === i ? { ...r, ...patch } : r)));
+  const loadError = overview.error ?? fields.error ?? targets.error ?? lists.error;
+  if (loadError) return <ApiError error={loadError} title="Could not load the form setup" onRetry={() => { void overview.refetch(); void fields.refetch(); }} />;
+  if (!seeded) return <div className="grid gap-2" aria-busy="true"><Skeleton className="h-9 w-64" /><Skeleton className="h-32 w-full" /></div>;
+
+  const previewRows = pickItems<Record<string, unknown>>(preview.data, "items", "rows", "preview", "submissions").slice(0, 3);
+  return (
+    <Card>
+      <CardHeader><CardTitle>Destination and field mapping</CardTitle></CardHeader>
+      <CardContent className="grid gap-4">
+        <div className="max-w-sm">
+          <Label htmlFor="g8-form-list" className="mb-1">Save leads to list</Label>
+          <select id="g8-form-list" className={SELECT} value={listId ?? ""} onChange={(e) => setListId(e.target.value ? Number(e.target.value) : undefined)}>
+            <option value="">Choose a list...</option>
+            {(lists.data ?? []).map((l) => <option key={l.id} value={l.id}>{l.title}</option>)}
+          </select>
+        </div>
+        {rows.length === 0 ? <p className="text-muted-foreground text-sm">No fields have been captured for this form yet. Submit it once on your site, then reload.</p> : (
+          <div className="grid gap-2">
+            {rows.map((row, i) => (
+              <div key={`${row.source_field}-${i}`} className="grid items-center gap-2 sm:grid-cols-[1fr_1fr_1fr]">
+                <span className="truncate text-sm font-mono">{row.source_field || "(constant)"}</span>
+                <select aria-label={`Contact field for ${row.source_field}`} className={SELECT} value={row.target_field} onChange={(e) => set(i, { target_field: e.target.value })}>
+                  <option value="">Do not save</option>
+                  {(targets.data ?? []).map((g) => (
+                    <optgroup key={g.name} label={g.name}>{g.fields.map((f) => <option key={f.field} value={f.field}>{f.label}</option>)}</optgroup>
+                  ))}
+                </select>
+                <Input aria-label={`Constant for ${row.source_field}`} placeholder="Optional constant value" value={row.static_value ?? ""} onChange={(e) => set(i, { static_value: e.target.value })} />
+              </div>
+            ))}
+          </div>
+        )}
+        <div className="flex flex-wrap gap-2">
+          <Button variant="outline" size="sm" loading={suggest.loading} disabled={!listId} onClick={() => void suggest.mutate(undefined)}>Suggest mapping</Button>
+          <Button variant="outline" size="sm" loading={preview.loading} disabled={!ready} onClick={() => void preview.mutate(undefined)}>Preview</Button>
+          <Button size="sm" loading={save.loading} disabled={!ready} onClick={() => void save.mutate(undefined)}>Save mapping</Button>
+          <Button variant="ghost" size="sm" loading={test.loading} disabled={!overview.data?.destination?.list_id} onClick={() => void test.mutate(undefined)}>Send a test submission</Button>
+        </div>
+        {[suggest.error, preview.error, save.error, test.error].filter(Boolean).map((e, i) => <ApiError key={i} error={e} title="That did not work" />)}
+        {save.data ? <p role="status" className="text-sm text-green-700">Mapping saved. New submissions follow it.</p> : null}
+        {test.data ? <p role="status" className="text-sm">Test submission sent to the list (one synthetic contact was added). {cellText(test.data).slice(0, 200)}</p> : null}
+        {previewRows.length > 0 ? (
+          <div className="rounded border p-3 text-xs"><p className="mb-1 font-medium">Preview (nothing saved)</p>{previewRows.map((r, i) => <pre key={i} className="overflow-x-auto">{JSON.stringify(r)}</pre>)}</div>
+        ) : preview.data ? <pre className="overflow-x-auto rounded border p-3 text-xs">{JSON.stringify(preview.data, null, 2).slice(0, 1200)}</pre> : null}
+      </CardContent>
+    </Card>
+  );
+}