@graph8/sdk 0.362.0 → 0.370.0

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/block.json

@@ -15,25 +15,25 @@
     "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": [
@@ -41,8 +41,21 @@
       "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": [],
-      "tiers": []
+      "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",
@@ -97,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",

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

@@ -28,6 +28,7 @@ import { STATUS_LABEL, formLabel, formStatus, pageUrlText, pickItems } from "../
 import type { FormListItem, FormOverview, FormRef } from "../lib/form-types";
 import { FormMappingEditor } from "./form-mapping-editor";
 import { SubmissionsTable } from "./submissions-table";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface FormBuilderProps {
   /** Form to open first. */
@@ -83,6 +84,7 @@ function FormHeader({ form, onChanged }: { form: FormListItem; onChanged: () =>
 }
 
 export function FormBuilder({ initialForm, onSelectForm }: FormBuilderProps) {
+  const brand = useBrand();
   const [page, setPage] = useState(1);
   const [searchText, setSearchText] = useState("");
   const [search, setSearch] = useState("");
@@ -109,7 +111,7 @@ export function FormBuilder({ initialForm, onSelectForm }: FormBuilderProps) {
             <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."} />
+            <EmptyState title={search ? "No forms match" : "No forms captured yet"} description={search ? "Try another name." : `Install the ${brand.linkLabel} snippet on your site (see FormEmbed). Forms appear here after their first submission.`} />
           ) : (
             <ul className="grid gap-1">
               {items.map((f) => {

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

@@ -15,6 +15,7 @@ import { Button, Card, CardContent, CardHeader, CardTitle, Label, Skeleton } fro
 import { ApiError } from "@/g8/components/api-error";
 import { g8Get } from "@/g8/lib/g8-client";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface FormEmbedProps {
   /** Stream (site) to read the snippet for. Omit for the organization's main stream. */
@@ -55,6 +56,7 @@ function CodeBlock({ label, code }: { label: string; code: string }) {
 }
 
 export function FormEmbed({ streamId }: FormEmbedProps) {
+  const brand = useBrand();
   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]);
@@ -80,7 +82,7 @@ export function FormEmbed({ streamId }: FormEmbedProps) {
       <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>
+          <p className="text-muted-foreground text-sm">Put this on every page that has a form. {brand.linkLabel} 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>

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

@@ -47,6 +47,8 @@ import { FormEmbed } from "./form-embed";
 import { FormMappingEditor } from "./form-mapping-editor";
 import { SiteAuditPanel } from "./site-audit-panel";
 import { SubmissionsTable } from "./submissions-table";
+import { pluralWord } from "@/g8/lib/plural";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface FormsScreenProps {
   renderRowActions?: (form: FormListItem) => ReactNode;
@@ -204,6 +206,7 @@ function SubmissionDetail({ form, submission, onChanged }: { form: FormRef; subm
 }
 
 export function FormsScreen({ renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions, className }: FormsScreenProps) {
+  const brand = useBrand();
   const [tabParam, setTabParam] = useUrlState("tab", "forms");
   const tab: Tab = tabParam === "install" || tabParam === "audit" ? tabParam : "forms";
   const setTab = (next: Tab): void => setTabParam(next === "forms" ? null : next);
@@ -253,7 +256,7 @@ export function FormsScreen({ renderRowActions, renderDetailActions, extraDetail
     <EmptyState
       icon={<ClipboardList className="size-8" />}
       title={search || health ? "No forms match" : "No forms captured yet"}
-      description={search || health ? "Try another name or health." : "Install the graph8 snippet on your site. Forms appear here after their first submission."}
+      description={search || health ? "Try another name or health." : `Install the ${brand.linkLabel} snippet on your site. Forms appear here after their first submission.`}
       action={!search && !health ? <Button onClick={() => setTab("install")}>Get the install code</Button> : undefined}
     />
   ) : (
@@ -267,7 +270,7 @@ export function FormsScreen({ renderRowActions, renderDetailActions, extraDetail
               <span className="block truncate font-medium">{formLabel(f)}</span>
               <span className="text-muted-foreground block truncate text-xs">{pageUrlText(f.page_url) || f.form_key}</span>
               <span className="text-muted-foreground block text-xs">
-                {(f.total_submissions ?? 0).toLocaleString()} {(f.total_submissions ?? 0) === 1 ? "submission" : "submissions"}{f.failed_submissions ? ` · ${f.failed_submissions} failed` : ""}{f.target_list_name ? ` · to ${f.target_list_name}` : ""}
+                {(f.total_submissions ?? 0).toLocaleString()} {pluralWord(f.total_submissions ?? 0, "submission")}{f.failed_submissions ? ` · ${f.failed_submissions} failed` : ""}{f.target_list_name ? ` · to ${f.target_list_name}` : ""}
               </span>
             </button>
             <StatusPill tone={TONE[status]}>{STATUS_LABEL[status]}</StatusPill>