@graph8/sdk 0.361.0 → 0.370.0

package/blocks/enrichment/components/enrichment-job-detail.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+/**
+ * EnrichmentJobDetail: one bulk enrichment job in full. Live status (polled with backoff, there are no streams),
+ * progress, how many records were enriched or failed, credits used, warnings, the provider errors that explain a
+ * failure, and Cancel while it runs.
+ *
+ * SDK operations, in order:
+ *   1. getEnrichmentJob     GET  /enrichment/jobs/{job_id}   (read) polled with useJobPoll until a final status;
+ *        read once more with ?include_provider_errors=true when nothing was enriched or some records failed
+ *        -> { status, total, completed, successful_enrichments, failed_enrichments, total_credits_used, warnings, provider_errors }
+ *   2. cancelEnrichmentJob  POST /enrichment/jobs/{job_id}/cancel   (write, free; records already done keep their data and charge)
+ */
+
+import { Button } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill, humanizeStatus, toneForStatus } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { isJobTerminal } from "../lib/enrichment-types";
+import type { EnrichJob } from "../lib/enrichment-types";
+
+export interface EnrichmentJobDetailProps {
+  jobId: string;
+  /** Called when the job reached a final state. */
+  onDone?: (job: EnrichJob) => void;
+  className?: string;
+}
+
+export function EnrichmentJobDetail({ jobId, onDone, className }: EnrichmentJobDetailProps) {
+  const job = useJobPoll<EnrichJob>(
+    async (signal) => (await g8Get<EnrichJob>(`/enrichment/jobs/${jobId}`, undefined, { signal })).data,
+    { intervalMs: 2000, isTerminal: (j) => isJobTerminal(j.status), onDone },
+  );
+  const cancel = useG8Mutation(() => g8Post(`/enrichment/jobs/${jobId}/cancel`, {}));
+  const j = job.status;
+  const problems = job.done && j != null && ((j.successful_enrichments ?? 0) === 0 || (j.failed_enrichments ?? 0) > 0);
+  const errors = useG8Query(
+    async (signal) => (await g8Get<EnrichJob>(`/enrichment/jobs/${jobId}`, { include_provider_errors: true }, { signal })).data.provider_errors ?? [],
+    [jobId, job.done],
+    { enabled: problems },
+  );
+  const total = j?.total ?? 0;
+  const pct = total ? Math.min(100, Math.round(((j?.completed ?? 0) / total) * 100)) : 0;
+
+  if (job.error && !j) return <ApiError error={job.error} title="Could not read the job" onRetry={() => job.start()} />;
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`} role="status">
+      <div className="flex items-center gap-2">
+        {j ? <StatusPill tone={toneForStatus(j.status)} dot>{humanizeStatus(j.status)}</StatusPill> : <span className="text-sm text-muted-foreground">Loading...</span>}
+        {!job.done && j ? <Button size="sm" variant="outline" loading={cancel.loading} onClick={() => void cancel.mutate(undefined)}>Cancel job</Button> : null}
+      </div>
+      <div className="h-2 overflow-hidden rounded bg-muted" aria-label="Progress"><div className="h-full bg-primary" style={{ width: `${job.done ? 100 : pct}%` }} /></div>
+      {cancel.error ? <ApiError error={cancel.error} title="Could not cancel" /> : null}
+      <SectionCard title="Result">
+        <KeyValueList columns={2} items={[
+          { label: "Job id", value: jobId, mono: true, wide: true },
+          { label: "Processed", value: j ? `${(j.completed ?? 0).toLocaleString()} of ${total.toLocaleString()}` : "" },
+          { label: "Enriched", value: j?.successful_enrichments != null ? j.successful_enrichments.toLocaleString() : "" },
+          { label: "Failed", value: j?.failed_enrichments != null ? j.failed_enrichments.toLocaleString() : "" },
+          { label: "Credits used", value: j?.total_credits_used != null ? j.total_credits_used.toLocaleString() : "" },
+        ]} />
+      </SectionCard>
+      {j?.warnings?.length ? <SectionCard title="Warnings"><ul className="list-disc pl-5 text-sm">{j.warnings.map((w) => <li key={w}>{w}</li>)}</ul></SectionCard> : null}
+      {errors.data?.length ? (
+        <SectionCard title="Provider errors" description="Usually a missing or invalid provider key.">
+          <ul className="list-disc pl-5 text-sm text-destructive" aria-label="Provider errors">
+            {errors.data.slice(0, 20).map((e, i) => <li key={i}>{e.provider}: {e.error}</li>)}
+          </ul>
+        </SectionCard>
+      ) : null}
+    </div>
+  );
+}

package/blocks/enrichment/components/enrichment-screen.tsx

@@ -0,0 +1,288 @@
+"use client";
+
+/**
+ * EnrichmentScreen: the finished enrichment page, in four tabs (`?tab=`).
+ *   - Enrich a list: pick a list, tick contacts, run a confirmed bulk enrichment (preflight, price, progress, cancel);
+ *     open a contact to see its record and look it up or verify its email.
+ *   - Look up: find one person or company by email, LinkedIn, name and domain (2 credits only when found) and verify
+ *     an email address (1 credit). Nothing is written to a record without a tick.
+ *   - Pipelines: the saved provider waterfalls of a list, create and delete them.
+ *   - Providers: which providers graph8 funds, which need your own key, and what each action costs.
+ *
+ * Composes: ScreenLayout, StatStrip, SplitView, DetailPanel, SectionCard, KeyValueList, StatusPill (screen kit),
+ * BulkEnrichPanel, WaterfallConfig, EnrichButton, EmailVerifyBadge, ContactTable / ContactDetail (crm), ListPicker (lists).
+ * Provider keys are added in graph8 settings (no API), so the Providers tab links out for them.
+ *
+ * SDK operations (inside the parts it composes): listEnrichmentProviders, preflightEnrichment (read),
+ * startEnrichment (billable, ConfirmSpendDialog), getEnrichmentJob, cancelEnrichmentJob, lookupPerson / lookupCompany
+ * (billable, confirmed), verifyEmail (billable, confirmed), listWaterfallConfigs, createDefaultWaterfallConfig (billable,
+ * confirmed), deleteWaterfallConfig (destructive, confirmed), listContacts, getContact.
+ */
+
+import { useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import { Building2, ExternalLink, KeyRound, Sparkles, UserSearch } from "lucide-react";
+import { Button, Input, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { ContactDetail } from "@/g8/crm/components/contact-detail";
+import { ContactTable } from "@/g8/crm/components/contact-table";
+import type { ContactRecord } from "@/g8/crm/lib/crm-types";
+import { ListPicker } from "@/g8/lists/components/list-picker";
+import { plural } from "@/g8/lib/plural";
+import { useProviders } from "../hooks/use-providers";
+import { CREDITS_PER_EMAIL_VERIFICATION, CREDITS_PER_FOUND_LOOKUP } from "../lib/enrichment-types";
+import { BulkEnrichPanel } from "./bulk-enrich-panel";
+import { EmailVerifyBadge } from "./email-verify-badge";
+import { EnrichButton } from "./enrich-button";
+import { EnrichmentJobDetail } from "./enrichment-job-detail";
+import { WaterfallConfig } from "./waterfall-config";
+import type { WaterfallConfigSummary } from "../lib/enrichment-types";
+import { useBrand, brandUrl } from "@/g8/hooks/use-brand";
+
+export interface EnrichmentScreenProps {
+  toolbarActions?: ReactNode;
+  /** Extra buttons in the opened contact's header. */
+  renderDetailActions?: (contact: ContactRecord) => ReactNode;
+  extraDetailTabs?: { id: string; label: string; render: (contact: ContactRecord) => ReactNode }[];
+  /** Where provider keys are managed. Default: the graph8 app. */
+  providerSettingsUrl?: string;
+  className?: string;
+}
+
+const TABS = [{ id: "list", label: "Enrich a list" }, { id: "lookup", label: "Look up" }, { id: "pipelines", label: "Pipelines" }, { id: "jobs", label: "Jobs" }, { id: "providers", label: "Providers" }];
+const FIELD = "flex flex-col gap-1";
+
+
+const JOBS_KEY = "g8.enrichment.jobs";
+function loadJobs(): string[] {
+  try { const v = JSON.parse(window.sessionStorage.getItem(JOBS_KEY) ?? "[]"); return Array.isArray(v) ? v.filter((x) => typeof x === "string") : []; } catch { return []; }
+}
+function rememberJobs(ids: string[]): void {
+  try { window.sessionStorage.setItem(JOBS_KEY, JSON.stringify(ids.slice(0, 30))); } catch { /* private mode: the list lives for this page only */ }
+}
+
+function PipelineDetail({ config, onClose, onExpand, onCollapse }: { config: WaterfallConfigSummary; onClose: () => void; onExpand?: () => void; onCollapse?: () => void }) {
+  const brand = useBrand();
+  return (
+    <DetailPanel onExpand={onExpand} onCollapse={onCollapse} title={config.name} subtitle={`Fills ${config.field_to_enrich ?? "a field"} in ${plural(config.step_count, "step")}`} onClose={onClose}
+      badges={config.is_active === false ? <StatusPill tone="neutral" dot>Inactive</StatusPill> : <StatusPill tone="positive" dot>Active</StatusPill>}>
+      <div className="flex flex-col gap-4 p-1">
+        {config.missing_credentials.length ? <p role="alert" className="text-sm text-amber-700">No key for {config.missing_credentials.join(", ")}: those steps are skipped when it runs. Add the keys in {brand.linkLabel} settings.</p> : null}
+        <ol className="flex flex-col gap-2" aria-label="Pipeline steps">
+          {(config.providers_detail.length ? config.providers_detail : config.providers.map((p) => ({ provider: p, is_system_provider: false, credential_source: "system" as const, credential_ready: true }))).map((p, i) => (
+            <li key={`${p.provider}-${i}`} 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.provider}</span>
+              <StatusPill tone={p.credential_ready ? "positive" : "warning"} dot>{p.credential_source === "byok" ? "Your key" : `${brand.linkLabel} credits`}{p.credential_ready ? "" : ", not ready"}</StatusPill>
+            </li>
+          ))}
+        </ol>
+        <KeyValueList columns={2} items={[
+          { label: "Scope", value: config.is_global ? "All lists" : config.list_id != null ? `List #${config.list_id}` : "" },
+          { label: "Pipeline id", value: config.column_id, mono: true, wide: true },
+        ]} />
+        <p className="text-xs text-muted-foreground">Delete it from the list on the left. Values it already wrote stay on the contacts.</p>
+      </div>
+    </DetailPanel>
+  );
+}
+
+function JobsTab({ jobs, jobParam, setJobParam }: { jobs: string[]; jobParam: string; setJobParam: (v: string | null) => void }) {
+  const [typed, setTyped] = useState("");
+  const [view, setView] = useUrlState("view");
+  const full = view === "full";
+  const list = (
+    <div className="flex flex-col gap-3 p-1">
+      <SectionCard title="Open a job" description="Paste a job id from the API or an earlier run.">
+        <form className="flex gap-2" onSubmit={(e) => { e.preventDefault(); if (typed.trim()) setJobParam(typed.trim()); }}>
+          <Input aria-label="Job id" value={typed} onChange={(e) => setTyped(e.target.value)} placeholder="Job id" />
+          <Button type="submit" size="sm" variant="outline" disabled={!typed.trim()}>Open</Button>
+        </form>
+      </SectionCard>
+      <SectionCard title="Started in this session" flush>
+        {jobs.length === 0 ? <EmptyState title="No jobs yet" description="Enrich contacts and the job appears here, with live progress." /> : (
+          <ul className="divide-y">{jobs.map((id) => (
+            <li key={id}><button type="button" className={`w-full px-4 py-2 text-left text-sm font-mono ${id === jobParam ? "bg-muted/50" : ""}`} onClick={() => setJobParam(id)}>{id}</button></li>
+          ))}</ul>
+        )}
+      </SectionCard>
+    </div>
+  );
+  return (
+    <SplitView expanded={full} onExpandedChange={(e) => setView(e ? "full" : null)} list={list} detailOpen={Boolean(jobParam)} onCloseDetail={() => setJobParam(null)} detailTitle="Enrichment job"
+      detail={jobParam ? <DetailPanel key={jobParam} onExpand={full ? undefined : () => setView("full")} onCollapse={full ? () => setView(null) : undefined} title="Enrichment job" subtitle={jobParam} onClose={() => setJobParam(null)}><EnrichmentJobDetail jobId={jobParam} /></DetailPanel> : null} />
+  );
+}
+
+function ListRail({ listId, onPick }: { listId: number | null; onPick: (id: number) => void }) {
+  return (
+    <SectionCard title="List" description="The contacts must be on a list.">
+      <ListPicker value={listId} allowCreate={false} onChange={(l) => onPick(l.id)} />
+    </SectionCard>
+  );
+}
+
+function LookupTab() {
+  const [email, setEmail] = useState("");
+  const [linkedin, setLinkedin] = useState("");
+  const [first, setFirst] = useState("");
+  const [last, setLast] = useState("");
+  const [domain, setDomain] = useState("");
+  const [cDomain, setCDomain] = useState("");
+  const [cName, setCName] = useState("");
+  const [verifyEmail, setVerifyEmail] = useState("");
+  const [contactRecord, setContactRecord] = useState("");
+  const [companyRecord, setCompanyRecord] = useState("");
+  const [applied, setApplied] = useState<string | null>(null);
+  const person = { email: email.trim() || undefined, linkedin_url: linkedin.trim() || undefined, first_name: first.trim() || undefined, last_name: last.trim() || undefined, company_domain: domain.trim() || undefined };
+  const company = { domain: cDomain.trim() || undefined, name: cName.trim() || undefined };
+  return (
+    <div className="grid gap-4 lg:grid-cols-2">
+      <SectionCard title="Find a person" description={`${CREDITS_PER_FOUND_LOOKUP} credits, only when a match is found.`} actions={<UserSearch className="size-4 text-muted-foreground" aria-hidden />}>
+        <div className="flex flex-col gap-3">
+          <div className={FIELD}><Label htmlFor="lk-email">Work email</Label><Input id="lk-email" value={email} onChange={(e) => setEmail(e.target.value)} /></div>
+          <div className={FIELD}><Label htmlFor="lk-li">LinkedIn URL</Label><Input id="lk-li" value={linkedin} onChange={(e) => setLinkedin(e.target.value)} /></div>
+          <div className="grid grid-cols-2 gap-2">
+            <div className={FIELD}><Label htmlFor="lk-first">First name</Label><Input id="lk-first" value={first} onChange={(e) => setFirst(e.target.value)} /></div>
+            <div className={FIELD}><Label htmlFor="lk-last">Last name</Label><Input id="lk-last" value={last} onChange={(e) => setLast(e.target.value)} /></div>
+          </div>
+          <div className={FIELD}><Label htmlFor="lk-domain">Company domain</Label><Input id="lk-domain" placeholder="acme.com" value={domain} onChange={(e) => setDomain(e.target.value)} /></div>
+          <p className="text-xs text-muted-foreground">Use an email, a LinkedIn URL, or first name, last name and company domain together.</p>
+          <div className={FIELD}><Label htmlFor="lk-rec">Apply to contact id (optional)</Label><Input id="lk-rec" inputMode="numeric" className="w-40" value={contactRecord} onChange={(e) => setContactRecord(e.target.value)} /></div>
+          <div className="flex items-center gap-2">
+            <EnrichButton kind="person" lookup={person} record={Number(contactRecord) > 0 ? { id: Number(contactRecord) } : undefined} label="Find person" variant="default" size="default" onApplied={() => setApplied(`Updated contact ${contactRecord}.`)} />
+            {applied ? <span role="status" className="text-sm">{applied}</span> : null}
+          </div>
+        </div>
+      </SectionCard>
+      <div className="flex flex-col gap-4">
+        <SectionCard title="Find a company" description={`${CREDITS_PER_FOUND_LOOKUP} credits, only when a match is found.`} actions={<Building2 className="size-4 text-muted-foreground" aria-hidden />}>
+          <div className="flex flex-col gap-3">
+            <div className={FIELD}><Label htmlFor="lk-cdomain">Domain</Label><Input id="lk-cdomain" placeholder="acme.com" value={cDomain} onChange={(e) => setCDomain(e.target.value)} /></div>
+            <div className={FIELD}><Label htmlFor="lk-cname">Name</Label><Input id="lk-cname" value={cName} onChange={(e) => setCName(e.target.value)} /></div>
+            <div className={FIELD}><Label htmlFor="lk-crec">Apply to company id (optional)</Label><Input id="lk-crec" inputMode="numeric" className="w-40" value={companyRecord} onChange={(e) => setCompanyRecord(e.target.value)} /></div>
+            <div><EnrichButton kind="company" lookup={company} record={Number(companyRecord) > 0 ? { id: Number(companyRecord) } : undefined} label="Find company" variant="default" size="default" /></div>
+          </div>
+        </SectionCard>
+        <SectionCard title="Verify an email" description={`${CREDITS_PER_EMAIL_VERIFICATION} credit per check.`}>
+          <div className="flex flex-col gap-3">
+            <div className={FIELD}><Label htmlFor="vf-email">Email address</Label><Input id="vf-email" value={verifyEmail} onChange={(e) => setVerifyEmail(e.target.value)} /></div>
+            <EmailVerifyBadge key={verifyEmail.trim()} email={verifyEmail.trim()} />
+          </div>
+        </SectionCard>
+      </div>
+    </div>
+  );
+}
+
+function ProvidersTab({ settingsUrl }: { settingsUrl: string }) {
+  const brand = useBrand();
+  const catalog = useProviders();
+  if (catalog.error) return <ApiError error={catalog.error} title="Could not load providers" onRetry={() => void catalog.refetch()} />;
+  if (!catalog.loading && catalog.providers.length === 0) return <EmptyState title="No providers" description="The provider catalog is empty for this workspace." />;
+  return (
+    <SectionCard title="Providers" description={`Providers on ${brand.linkLabel}'s key spend credits when they run. Providers on your own key cost no ${brand.linkLabel} credits.`}
+      actions={<a className="inline-flex items-center gap-1 text-sm underline" href={settingsUrl} target="_blank" rel="noreferrer"><KeyRound className="size-4" aria-hidden />Manage keys in {brand.linkLabel}<ExternalLink className="size-3" aria-hidden /></a>}>
+      <ul className="divide-y">
+        {catalog.providers.map((p) => (
+          <li key={p.provider} className="flex flex-wrap items-center gap-3 py-2" data-testid="provider-row">
+            <span className="w-36 text-sm font-medium">{p.provider}</span>
+            {p.byok_configured ? <StatusPill tone="positive" dot>Your key set</StatusPill> : p.system_funded ? <StatusPill tone="info" dot>{brand.linkLabel} funded</StatusPill> : <StatusPill tone="warning" dot>Needs your key</StatusPill>}
+            <span className="min-w-0 flex-1 truncate text-xs text-muted-foreground">{p.actions.join(", ")}</span>
+            <span className="text-xs tabular-nums text-muted-foreground">{Object.entries(p.credits_per_row).map(([k, v]) => `${k} ${v}`).join(" / ")}</span>
+          </li>
+        ))}
+      </ul>
+    </SectionCard>
+  );
+}
+
+export function EnrichmentScreen({ toolbarActions, renderDetailActions, extraDetailTabs, providerSettingsUrl: providerSettingsUrlProp, className }: EnrichmentScreenProps) {
+  const brand = useBrand();
+  const providerSettingsUrl = providerSettingsUrlProp ?? brandUrl(brand, "/settings");
+  const [tab, setTab] = useUrlState("tab", "list");
+  const [listParam, setListParam] = useUrlState("list");
+  const [picked, setPicked] = useState<number[]>([]);
+  const [opened, setOpened] = useState<ContactRecord | null>(null);
+  const catalog = useProviders(tab === "providers");
+  const [jobParam, setJobParam] = useUrlState("job");
+  const [pipelineParam, setPipelineParam] = useUrlState("pipeline");
+  const [view, setView] = useUrlState("view");
+  const full = view === "full";
+  const [jobs, setJobs] = useState<string[]>([]);
+  useEffect(() => setJobs(loadJobs()), []);
+  const started = (id: string) => setJobs((cur) => { const next = [id, ...cur.filter((x) => x !== id)]; rememberJobs(next); return next; });
+  const listId = listParam ? Number(listParam) : null;
+  const pick = (id: number) => { setListParam(String(id)); setPicked([]); setOpened(null); setPipelineParam(null); };
+
+  const stats = tab === "providers" && catalog.providers.length > 0 ? [
+    { label: "Providers", value: catalog.providers.length },
+    { label: `${brand.linkLabel} funded`, value: catalog.providers.filter((p) => p.system_funded).length },
+    { label: "Your keys set", value: catalog.providers.filter((p) => p.byok_configured).length },
+  ] : undefined;
+
+  let body: ReactNode;
+  // WaterfallConfig owns the pipelines request and hands the result up, so the detail view needs no second fetch.
+  const [loaded, setLoaded] = useState<{ listId: number | null; configs: WaterfallConfigSummary[] }>({ listId: null, configs: [] });
+  const openPipeline = (loaded.listId === listId ? loaded.configs : []).find((c) => c.column_id === pipelineParam);
+  if (tab === "lookup") body = <LookupTab />;
+  else if (tab === "jobs") body = <JobsTab jobs={jobs} jobParam={jobParam} setJobParam={setJobParam} />;
+  else if (tab === "providers") body = <ProvidersTab settingsUrl={providerSettingsUrl} />;
+  else {
+    body = (
+      <div className="grid gap-4 lg:grid-cols-[18rem_minmax(0,1fr)]">
+        <ListRail listId={listId} onPick={pick} />
+        {listId == null ? (
+          <EmptyState icon={<Sparkles className="size-6" aria-hidden />} title="Choose a list" description={tab === "pipelines" ? "Pipelines belong to a list. Pick one to see and create them." : "Pick a list, tick the contacts to fill in, and enrich them."} />
+        ) : tab === "pipelines" ? (
+          <SplitView
+            list={<WaterfallConfig key={listId} listId={listId} selectedId={pipelineParam || null} onOpen={(c) => setPipelineParam(c.column_id)} onLoaded={(configs) => setLoaded({ listId, configs })} />}
+            expanded={full} onExpandedChange={(e) => setView(e ? "full" : null)} detailOpen={openPipeline != null} onCloseDetail={() => setPipelineParam(null)} detailTitle="Pipeline"
+            detail={openPipeline ? <PipelineDetail config={openPipeline} onClose={() => setPipelineParam(null)} onExpand={full ? undefined : () => setView("full")} onCollapse={full ? () => setView(null) : undefined} /> : null} />
+        ) : (
+          <div className="grid min-w-0 gap-4 xl:grid-cols-2">
+            <ContactTable key={listId} listId={listId} selectable pageSize={10} onSelectionChange={(ids) => setPicked(ids)} onOpen={setOpened} />
+            <div className="flex min-w-0 flex-col gap-4">
+              <SectionCard title={`Enrich ${picked.length} selected`} description="Fill work email or phones with a provider waterfall. You confirm the price first.">
+                {picked.length === 0 ? <p className="text-sm text-muted-foreground">Tick contacts on the left.</p> : <BulkEnrichPanel key={listId} listId={listId} contactIds={picked} onStarted={started} />}
+              </SectionCard>
+              {opened ? (
+                <DetailPanel key={opened.id} title={opened.full_name ?? ([opened.first_name, opened.last_name].filter(Boolean).join(" ") || `Contact #${opened.id}`)} subtitle={opened.job_title} onClose={() => setOpened(null)}>
+                  <ContactDetail contactId={opened.id} extraTabs={extraDetailTabs}
+                    renderActions={(c) => (<>
+                      <EnrichButton kind="person" record={c as ContactRecord & Record<string, unknown>} lookup={{ email: c.work_email ?? undefined, linkedin_url: c.linkedin_url ?? undefined, first_name: c.first_name ?? undefined, last_name: c.last_name ?? undefined, company_domain: c.company_domain ?? undefined }} />
+                      <EmailVerifyBadge email={c.work_email} />
+                      {renderDetailActions?.(c)}
+                    </>)} />
+                </DetailPanel>
+              ) : null}
+            </div>
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Enrichment"
+      description="Fill in what you do not know about your contacts: emails, phones and company facts. Every paid step shows its price first."
+      icon={<Sparkles className="size-5" aria-hidden />}
+      actions={toolbarActions}
+      tabs={TABS}
+      activeTab={TABS.some((t) => t.id === tab) ? tab : "list"}
+      onTabChange={setTab}
+      stats={stats}
+    >
+      {body}
+    </ScreenLayout>
+  );
+}

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

@@ -8,14 +8,16 @@
  *   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.
+ *        (billable tier) goes through ConfirmSpendDialog first. With `field` (always sent here) it is idempotent per field and
+ *        list: when the list already has a pipeline for that field the API returns it with `created: false` and its own
+ *        providers, whatever name and providers were sent. The form then says so instead of claiming a new 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 { useEffect, useRef, 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";
@@ -23,36 +25,57 @@ 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 { plural } from "@/g8/lib/plural";
 import { useProviders } from "../hooks/use-providers";
 import { TARGET_FIELDS } from "../lib/enrichment-types";
 import type { TargetField, WaterfallConfigSummary } from "../lib/enrichment-types";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface WaterfallConfigProps {
   listId: number;
   /** Called with the pipeline's column_id after create or delete (for example to refresh a BulkEnrichPanel). */
   onChanged?: () => void;
+  /** Makes each pipeline's name open a detail view in your layout. Omit it and the list is unchanged. */
+  onOpen?: (config: WaterfallConfigSummary) => void;
+  /** Highlights the open pipeline (its column_id). */
+  selectedId?: string | null;
+  /** Called with the loaded pipelines each time they load or reload, so a screen can show one in a detail view without a second request. */
+  onLoaded?: (configs: WaterfallConfigSummary[]) => void;
   className?: string;
 }
 
-export function WaterfallConfig({ listId, onChanged, className }: WaterfallConfigProps) {
+export function WaterfallConfig({ listId, onChanged, onOpen, selectedId, onLoaded, className }: WaterfallConfigProps) {
+  const brand = useBrand();
   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);
+  // The answer to the last create when the API reused the list's pipeline for that field instead of creating one.
+  const [reused, setReused] = useState<{ name?: string; field: TargetField; providers: string[]; asked: string[] } | 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?.(); } },
+    () => g8Post<{ column_id: string; created: boolean; name?: string; providers?: string[] }>("/enrichment/waterfall/configs", { list_id: listId, name: name.trim(), field, providers: order, skip_existing_values: skipExisting }),
+    {
+      onSuccess: (res) => {
+        setReused(res.data.created === false ? { name: res.data.name, field, providers: res.data.providers ?? [], asked: order } : null);
+        setConfirmCreate(false); setName(""); setOrder([]); void configs.refetch(); onChanged?.();
+      },
+      // A failed create must not leave the previous answer's "Already exists, reused" next to the error.
+      onError: () => setReused(null),
+    },
   );
   const remove = useG8Mutation((columnId: string) => g8Delete(`/enrichment/waterfall/configs/${columnId}`), {
     onSuccess: () => { setDeleting(null); void configs.refetch(); onChanged?.(); },
   });
 
   const items = configs.data?.data.configs ?? [];
+  const loadedRef = useRef(onLoaded);
+  loadedRef.current = onLoaded;
+  useEffect(() => { if (configs.data) loadedRef.current?.(configs.data.data.configs ?? []); }, [configs.data]);
   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) => {
@@ -73,12 +96,12 @@ export function WaterfallConfig({ listId, onChanged, className }: WaterfallConfi
         {!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">
+            <li key={c.column_id} className={`rounded-md border p-3 ${selectedId === c.column_id ? "bg-muted/50" : ""}`} 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>
+                <p className="text-sm font-medium">{onOpen ? <button type="button" className="underline-offset-2 hover:underline" onClick={() => onOpen(c)}>{c.name}</button> : 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>
+              <p className="text-xs text-muted-foreground">{c.field_to_enrich ?? "field"}: {c.providers.join(" > ") || "no providers"} ({plural(c.step_count, "step")})</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>
           ))}
@@ -100,7 +123,7 @@ export function WaterfallConfig({ listId, onChanged, className }: WaterfallConfi
           {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>
+              <span className="text-xs text-muted-foreground">{byName.get(p)?.byok_configured ? "your key, free" : byName.get(p)?.system_funded ? `${brand.linkLabel} 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>
@@ -114,11 +137,17 @@ export function WaterfallConfig({ listId, onChanged, className }: WaterfallConfi
         </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}
+        {reused ? (
+          <p role="status" className="text-sm text-muted-foreground">
+            Already exists, reused: this list already has a {TARGET_FIELDS.find((f) => f.value === reused.field)?.label.toLowerCase() ?? reused.field} pipeline{reused.name ? ` ("${reused.name}")` : ""}, so no new one was created.
+            {reused.providers.length && reused.providers.join() !== reused.asked.join() ? ` It keeps its providers: ${reused.providers.join(" > ")}. Delete it first to use ${reused.asked.join(" > ")}.` : ""}
+          </p>
+        ) : 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."}
+        description={systemUsed.length ? `Running it uses ${brand.linkLabel} 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 ${brand.linkLabel} 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)} />

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

@@ -2,7 +2,7 @@
  * @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).
+ * and a provider without a key is skipped. Creating with `field` is idempotent per field and list: if the list already has a pipeline for that field it is returned with `created: false` and keeps its own providers, whatever name or providers you send (delete it first to change them). Without `field`, a pipeline is reused by (list_id, name).
  */
 import { g8 } from "@graph8/sdk";
 
@@ -17,7 +17,8 @@ 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 };
+  // created === false: the list already had a work-email pipeline; it was returned as is (check res.data.providers).
+  return { columnId: res.data.column_id, created: res.data.created, providers: res.data.providers, missing: res.data.missing_credentials };
 }
 
 export async function pipelinesOf(listId: number) {

package/blocks/forms/README.md

@@ -5,6 +5,17 @@ snippet, lists them, and routes every submission to a list with a field mapping.
 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`).
 
+## Screens
+
+`FormsScreen` (`components/forms-screen.tsx`) is the finished page: install code, captured forms, routing and submissions in one place.
+
+```tsx
+import { FormsScreen } from "@/g8/forms/components/forms-screen";
+export default function Page() { return <FormsScreen />; }
+```
+
+Flows: copy the snippet and ready-made lead form (Install tab, `?tab=install`), see every captured form with health and counts (search is debounced; the first 100 are listed), open one (deep link `?id=<source_id>/<form_key>`; a submission opens in a sheet at `&submission=<id>` with every field, its delivery and trace) to rename it, pause or resume delivery (confirmed), choose the destination list and map fields (suggest, preview, save, test), read submissions, trace a lead and retry a failed delivery (confirmed), and find forms that are not captured (Site audit tab, `?tab=audit`). A `&submission=` link opened cold (reload, shared link) is looked up in the form's latest 100 submissions; an older one shows its trace and points to the Submissions tab. Optional props: `renderRowActions`, `renderDetailActions`, `extraDetailTabs`, `toolbarActions`.
+
 ## Install
 
 ```
@@ -78,6 +89,7 @@ export default function FormsPage() {
 
 | Component | File | What it is |
 |---|---|---|
+| `FormsScreen` | `components/forms-screen.tsx` | The finished page: install code, captured forms, routing, submissions and site audit. |
 | `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. |

package/blocks/forms/block.json

@@ -15,28 +15,48 @@
     "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_fields_forms__form_key__fields_get",
+    "get_form_overview_forms__form_key__overview_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_form_template_snippet_form_get",
+    "get_org_snippet_snippet_get",
     "get_site_audit_forms_site_audit_get",
+    "list_forms_forms_get",
+    "list_lists_lists_get",
+    "pause_form_delivery_forms__form_key__delivery_pause_post",
+    "preview_form_mapping_forms__form_key__mapping_preview_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",
+    "save_form_mapping_forms__form_key__mapping_save_post",
+    "search_form_submissions_forms__form_key__submissions_post",
+    "test_form_route_forms__form_key__route_test_post",
+    "update_form_registry_forms__form_key__patch",
     "update_site_audit_finding_forms_site_audit_findings__finding_id__patch"
   ],
   "components": [
+    {
+      "name": "FormsScreen",
+      "file": "components/forms-screen.tsx",
+      "purpose": "Finished forms workspace: captured forms with health, detail (overview, destination and fields, submissions), install code and site audit tabs.",
+      "operations": [
+        "get_form_overview_forms__form_key__overview_get",
+        "get_form_submission_trace_forms__form_key__submissions__submission_id__trace_get",
+        "list_forms_forms_get",
+        "pause_form_delivery_forms__form_key__delivery_pause_post",
+        "resume_form_delivery_forms__form_key__delivery_resume_post",
+        "retry_form_delivery_forms_deliveries__receipt_id__retry_post",
+        "search_form_submissions_forms__form_key__submissions_post",
+        "update_form_registry_forms__form_key__patch"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external"
+      ]
+    },
     {
       "name": "FormBuilder",
       "file": "components/form-builder.tsx",
@@ -90,9 +110,10 @@
       "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"
+        "list_forms_forms_get",
+        "retry_form_delivery_forms_deliveries__receipt_id__retry_post",
+        "search_form_submissions_forms__form_key__submissions_post"
       ],
       "tiers": [
         "read",
@@ -195,6 +216,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
   }
 }