@graph8/sdk 0.362.0 → 0.373.0

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

@@ -0,0 +1,341 @@
+"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),
+ * createDefaultWaterfallConfig + runWaterfallPipeline (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 { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { CompanyPicker } from "@/g8/pickers/components/company-picker";
+import type { CompanyOption } from "@/g8/pickers/components/company-picker";
+import { ContactPicker } from "@/g8/pickers/components/contact-picker";
+import type { ContactOption } from "@/g8/pickers/components/contact-picker";
+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-warning-foreground">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>
+  );
+}
+
+interface ActiveJob { job_id: string; status?: string | null; column_id?: string | null; enrichment_type?: string | null; completed?: number | null; total?: number | null; failed?: number | null; paused_at?: string | null }
+
+/** Jobs running, paused or pending in the last six hours, org-wide (GET /enrichment/active-jobs, read, free): no job id to remember. */
+function ActiveJobs({ jobParam, onOpen }: { jobParam: string; onOpen: (id: string) => void }) {
+  const q = useG8Query(async (signal) => {
+    const d = (await g8Get("/enrichment/active-jobs", undefined, { signal })).data as { jobs?: ActiveJob[] } | ActiveJob[] | undefined;
+    return (Array.isArray(d) ? d : (d?.jobs ?? [])).filter((j) => j?.job_id);
+  }, []);
+  const rows = q.data ?? [];
+  return (
+    <SectionCard title="Running now" description="Jobs from the last 6 hours, from anyone on your team." flush actions={<Button size="sm" variant="ghost" onClick={() => void q.refetch()}>Refresh</Button>}>
+      {q.error ? <div className="p-3"><ApiError error={q.error} title="Could not load running jobs" onRetry={() => void q.refetch()} /></div> : null}
+      {!q.error && q.loading && rows.length === 0 ? <p className="p-4 text-sm text-muted-foreground">Loading jobs...</p> : null}
+      {!q.error && !q.loading && rows.length === 0 ? <EmptyState title="Nothing running" description="Jobs that are running, paused or pending show here." /> : null}
+      <ul className="divide-y">{rows.map((j) => (
+        <li key={j.job_id}>
+          <button type="button" aria-label={`Open job ${j.column_id ?? j.enrichment_type ?? j.job_id}`} className={`flex w-full items-center justify-between gap-2 px-4 py-2 text-left text-sm ${j.job_id === jobParam ? "bg-muted/50" : ""}`} onClick={() => onOpen(j.job_id)}>
+            <span className="truncate">{j.column_id ?? j.enrichment_type ?? "Enrichment"}</span>
+            <span className="flex items-center gap-2 text-xs text-muted-foreground">
+              <span className="tabular-nums">{j.completed ?? 0}/{j.total ?? 0}</span>
+              <StatusPill tone={j.status === "running" ? "positive" : "neutral"} dot>{j.status ?? "unknown"}</StatusPill>
+            </span>
+          </button>
+        </li>
+      ))}</ul>
+    </SectionCard>
+  );
+}
+
+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">
+      <ActiveJobs jobParam={jobParam} onOpen={setJobParam} />
+      <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>
+      <details className="px-1 text-sm">
+        <summary className="cursor-pointer text-muted-foreground">Open an older job by id</summary>
+        <form className="mt-2 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>
+      </details>
+    </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 [contactPick, setContactPick] = useState<ContactOption | null>(null);
+  const [companyPick, setCompanyPick] = useState<CompanyOption | null>(null);
+  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">Save the result on a contact (optional)</Label>
+            <div className="flex items-center gap-2">
+              <ContactPicker id="lk-rec" label="Contact to update" placeholder="Choose a contact" value={contactPick} onChange={setContactPick} />
+              {contactPick ? <Button size="sm" variant="ghost" onClick={() => setContactPick(null)}>Clear</Button> : null}
+            </div>
+          </div>
+          <div className="flex items-center gap-2">
+            <EnrichButton kind="person" lookup={person} record={contactPick ? { id: contactPick.id } : undefined} label="Find person" variant="default" size="default" onApplied={() => setApplied(`Updated ${contactPick?.name ?? "the contact"}.`)} />
+            {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">Save the result on a company (optional)</Label>
+              <div className="flex items-center gap-2">
+                <CompanyPicker id="lk-crec" label="Company to update" placeholder="Choose a company" value={companyPick} onChange={setCompanyPick} />
+                {companyPick ? <Button size="sm" variant="ghost" onClick={() => setCompanyPick(null)}>Clear</Button> : null}
+              </div>
+            </div>
+            <div><EnrichButton kind="company" lookup={company} record={companyPick ? { id: companyPick.id } : 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[]>([]);
+  // A finished run reloads the contact table (tableVersion) so the filled values show; the reload clears the ticks,
+  // so `runShown` keeps the panel and its result on screen until the person ticks contacts again.
+  const [tableVersion, setTableVersion] = useState(0);
+  const [runShown, setRunShown] = useState(false);
+  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([]); setRunShown(false); 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} refreshKey={tableVersion} 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 && !runShown ? <p className="text-sm text-muted-foreground">Tick contacts on the left.</p> : <BulkEnrichPanel key={listId} listId={listId} contactIds={picked} onStarted={(id) => { setRunShown(true); started(id); }} onDone={() => setTableVersion((v) => v + 1)} />}
+              </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,19 @@
  *   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)
  *
+ * The provider choices follow the chosen field (the API refuses a provider that cannot fill it with 400
+ * `unsupported_provider_for_field`): changing the field drops selected providers that no longer fit and says which.
+ *
  * 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 +28,69 @@ 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 { FIELD_PROVIDERS, 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);
+  // Providers dropped by the last field change, with the field they cannot fill, so the person sees why they went.
+  const [dropped, setDropped] = useState<{ providers: string[]; field: TargetField } | 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 fieldLabel = TARGET_FIELDS.find((f) => f.value === field)?.label ?? field;
+  const allowed = FIELD_PROVIDERS[field];
+  const unfit = order.filter((p) => !allowed.includes(p));
+  const changeField = (next: TargetField) => {
+    const gone = order.filter((p) => !FIELD_PROVIDERS[next].includes(p));
+    setField(next);
+    setOrder(order.filter((p) => FIELD_PROVIDERS[next].includes(p)));
+    setDropped(gone.length ? { providers: gone, field: next } : null);
+    setReused(null);
+  };
   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,13 +111,13 @@ 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>
-              {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}
+              <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-warning-foreground">Skipped at run time, no key: {c.missing_credentials.join(", ")}</p> : null}
             </li>
           ))}
         </ul>
@@ -90,7 +128,7 @@ export function WaterfallConfig({ listId, onChanged, className }: WaterfallConfi
         <div className="flex flex-wrap items-end gap-3">
           <div className="flex flex-col gap-1"><Label htmlFor="wf-name">Name</Label><Input id="wf-name" className="w-64" value={name} onChange={(e) => setName(e.target.value)} /></div>
           <div className="flex flex-col gap-1"><Label htmlFor="wf-field">Fill</Label>
-            <select id="wf-field" className="h-9 rounded-md border bg-background px-2 text-sm" value={field} onChange={(e) => setField(e.target.value as TargetField)}>
+            <select id="wf-field" className="h-9 rounded-md border bg-background px-2 text-sm" value={field} onChange={(e) => changeField(e.target.value as TargetField)}>
               {TARGET_FIELDS.map((f) => <option key={f.value} value={f.value}>{f.label}</option>)}
             </select>
           </div>
@@ -100,25 +138,36 @@ 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>
             </li>
           ))}
         </ol>
-        <div className="flex flex-wrap gap-1">
-          {catalog.providers.filter((p) => !order.includes(p.provider)).map((p) => (
-            <Button key={p.provider} variant="outline" size="sm" onClick={() => setOrder([...order, p.provider])}>Add {p.provider}</Button>
+        {dropped ? (
+          <p role="status" className="text-xs text-muted-foreground">
+            Removed {dropped.providers.join(", ")}: {dropped.providers.length === 1 ? "it cannot" : "they cannot"} find a {TARGET_FIELDS.find((f) => f.value === dropped.field)?.label.toLowerCase()}.
+          </p>
+        ) : null}
+        <div role="group" className="flex flex-wrap gap-1" aria-label="Provider choices" title={`Providers that can find a ${fieldLabel.toLowerCase()}`}>
+          {catalog.providers.filter((p) => allowed.includes(p.provider) && !order.includes(p.provider)).map((p) => (
+            <Button key={p.provider} variant="outline" size="sm" onClick={() => { setDropped(null); setOrder([...order, p.provider]); }}>Add {p.provider}</Button>
           ))}
         </div>
         <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={skipExisting} onChange={(e) => setSkipExisting(e.target.checked)} /> Skip contacts that already have a value</label>
         {create.error ? <ApiError error={create.error} title="Could not create the pipeline" /> : null}
-        <div className="flex justify-end"><Button disabled={!name.trim() || order.length === 0} onClick={() => setConfirmCreate(true)}>Create pipeline</Button></div>
+        {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 || unfit.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/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/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) {