@graph8/sdk 0.370.0 → 0.374.0

package/blocks/enrichment/components/pipeline-editor.tsx

@@ -0,0 +1,144 @@
+"use client";
+
+/**
+ * PipelineEditor: create or edit a list pipeline (an ordered chain of enrichment steps that runs over a whole list)
+ * in a side sheet. Steps are picked from the configs this list can already use (AI groups and provider waterfalls);
+ * each step can be turned off, told to fill only empty values, or to skip recently enriched records.
+ *
+ * SDK operations, in order:
+ *   1. listPipelineStepOptions  GET  /enrichment/lists/{list_id}/pipeline-step-options   (read, free)  the menu steps are picked from
+ *   2. createListPipeline       POST /enrichment/lists/{list_id}/pipelines               (billable tier; saved TURNED OFF, nothing runs)
+ *   3. updateListPipeline       PUT  /enrichment/lists/{list_id}/pipelines/{pipeline_id} (billable tier; replaces the steps, keeps on/off)
+ * Both saves go through ConfirmSpendDialog. Saving never runs the pipeline and charges nothing in this API: a run is a
+ * separate, priced step (see PipelineDetail). The dialog says so, because its generic tier note talks about credits.
+ *
+ * An edit seeds from the pipeline row the list already loaded (a full record) and sends the whole step list back with
+ * every field of every step kept (run conditions and builder state included), changing only what was edited. Saving
+ * is disabled until the step menu has loaded, and while nothing changed.
+ */
+
+import { useState } from "react";
+import { ArrowDown, ArrowUp, Trash2 } from "lucide-react";
+import { Button, Input, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import { itemsOf, moveItem, pipelineChanged, savePayload, stepFromOption, stepLabel } from "../lib/pipeline-types";
+import type { ListPipeline, PipelineStep, StepOption } from "../lib/pipeline-types";
+
+export interface PipelineEditorProps {
+  listId: number;
+  /** The pipeline to edit; omit to create a new one. */
+  pipeline?: ListPipeline;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Called with the saved pipeline after the API accepted it. */
+  onSaved?: (pipeline: ListPipeline) => void;
+}
+
+const MAX_STEPS = 20;
+const toggle = "flex items-center gap-2 text-xs text-muted-foreground";
+
+export function PipelineEditor({ listId, pipeline, open, onOpenChange, onSaved }: PipelineEditorProps) {
+  const [name, setName] = useState(pipeline?.name ?? "");
+  const [steps, setSteps] = useState<PipelineStep[]>(() => (pipeline?.steps ?? []).map((s) => ({ ...s })));
+  const [confirming, setConfirming] = useState(false);
+  const [pick, setPick] = useState("");
+  const options = useG8Query(async (signal) => itemsOf<StepOption>((await g8Get(`/enrichment/lists/${listId}/pipeline-step-options`, undefined, { signal })).data), [listId], { enabled: open, key: ["enrichment", "step-options", listId], staleTime: 30_000 });
+  const menu = options.data ?? [];
+  const editing = pipeline != null;
+  const save = useG8Mutation(
+    async () => {
+      const body = savePayload(name, steps);
+      const res = editing
+        ? await g8Put<ListPipeline>(`/enrichment/lists/${listId}/pipelines/${pipeline.id}`, body)
+        : await g8Post<ListPipeline>(`/enrichment/lists/${listId}/pipelines`, body);
+      return res.data;
+    },
+    { onSuccess: (saved) => { setConfirming(false); onSaved?.(saved); onOpenChange(false); }, onError: () => setConfirming(false) },
+  );
+
+  const available = menu.filter((o) => !steps.some((s) => s.config_ref === o.config_ref && s.type === o.type));
+  const patch = (i: number, change: Partial<PipelineStep>) => setSteps((cur) => cur.map((s, at) => (at === i ? { ...s, ...change } : s)));
+  const addStep = () => {
+    const option = available.find((o) => `${o.type}:${o.config_ref}` === pick);
+    if (!option) return;
+    setSteps((cur) => [...cur, stepFromOption(option, cur.map((s) => s.id))]);
+    setPick("");
+  };
+  const valid = name.trim().length > 0 && name.trim().length <= 255 && steps.length > 0 && steps.length <= MAX_STEPS;
+  const dirty = editing ? pipelineChanged(pipeline, name, steps) : true;
+  const ready = valid && dirty && !options.loading && !options.error;
+
+  return (
+    <FormSheet
+      open={open}
+      onOpenChange={onOpenChange}
+      title={editing ? `Edit ${pipeline.name}` : "New list pipeline"}
+      description="Steps run in order over every record on the list. Saving does not run anything."
+      width="lg"
+      footer={<>
+        <Button type="button" variant="outline" onClick={() => onOpenChange(false)}>Cancel</Button>
+        <Button type="button" disabled={!ready} onClick={() => setConfirming(true)}>{editing ? "Save changes" : "Save pipeline"}</Button>
+      </>}
+    >
+      <div className="flex flex-col gap-1">
+        <Label htmlFor="pl-name">Name</Label>
+        <Input id="pl-name" value={name} maxLength={255} onChange={(e) => setName(e.target.value)} />
+      </div>
+      {options.error ? <ApiError error={options.error} title="Could not load the steps you can use" onRetry={() => void options.refetch()} /> : null}
+      <section className="flex flex-col gap-2" aria-label="Steps">
+        <h3 className="text-sm font-medium">Steps</h3>
+        {steps.length === 0 ? <p className="text-sm text-muted-foreground">Add at least one step.</p> : null}
+        <ol className="flex flex-col gap-2">
+          {steps.map((s, i) => (
+            <li key={s.id} className="rounded-md border p-3" data-testid="editor-step">
+              <div className="flex items-center gap-2">
+                <span className="w-5 text-sm text-muted-foreground">{i + 1}.</span>
+                <span className="min-w-0 flex-1 truncate text-sm font-medium">{stepLabel(s, menu)}</span>
+                <StatusPill tone="neutral">{s.type === "ai" ? "AI" : "Providers"}</StatusPill>
+                <Button type="button" variant="ghost" size="sm" aria-label={`Move step ${i + 1} up`} disabled={i === 0} onClick={() => setSteps((cur) => moveItem(cur, i, -1))}><ArrowUp className="size-4" aria-hidden /></Button>
+                <Button type="button" variant="ghost" size="sm" aria-label={`Move step ${i + 1} down`} disabled={i === steps.length - 1} onClick={() => setSteps((cur) => moveItem(cur, i, 1))}><ArrowDown className="size-4" aria-hidden /></Button>
+                <Button type="button" variant="ghost" size="sm" aria-label={`Remove step ${i + 1}`} onClick={() => setSteps((cur) => cur.filter((_, at) => at !== i))}><Trash2 className="size-4" aria-hidden /></Button>
+              </div>
+              <div className="mt-2 flex flex-col gap-1 pl-7">
+                <label className={toggle}><input type="checkbox" checked={s.enabled !== false} onChange={(e) => patch(i, { enabled: e.target.checked })} /> Run this step</label>
+                <label className={toggle}><input type="checkbox" checked={s.skip_existing_values !== false} onChange={(e) => patch(i, { skip_existing_values: e.target.checked })} /> Fill only empty values</label>
+                <label className={toggle}><input type="checkbox" checked={s.skip_recently_enriched !== false} onChange={(e) => patch(i, { skip_recently_enriched: e.target.checked })} /> Skip records enriched recently</label>
+                {s.run_condition ? <p className="text-xs text-muted-foreground">Runs only when: {s.run_condition}</p> : null}
+              </div>
+            </li>
+          ))}
+        </ol>
+        <div className="flex items-end gap-2">
+          <div className="flex min-w-0 flex-1 flex-col gap-1">
+            <Label htmlFor="pl-add">Add a step</Label>
+            <select id="pl-add" className="h-9 rounded-md border bg-background px-2 text-sm" value={pick} disabled={options.loading || steps.length >= MAX_STEPS} onChange={(e) => setPick(e.target.value)}>
+              <option value="">{options.loading ? "Loading steps..." : available.length ? "Choose a step" : "No more steps to add"}</option>
+              {available.map((o) => <option key={`${o.type}:${o.config_ref}`} value={`${o.type}:${o.config_ref}`}>{o.name}{o.is_qualification ? " (qualification)" : ""}</option>)}
+            </select>
+          </div>
+          <Button type="button" variant="outline" disabled={!pick} onClick={addStep}>Add step</Button>
+        </div>
+        {!options.loading && !options.error && menu.length === 0 ? <p className="text-xs text-muted-foreground">This list has no enrichment configs yet. Create a provider waterfall in the Pipelines tab, then come back.</p> : null}
+        {steps.length >= MAX_STEPS ? <p className="text-xs text-muted-foreground">A pipeline can have at most {MAX_STEPS} steps.</p> : null}
+      </section>
+      {save.error ? <ApiError error={save.error} title="Could not save the pipeline" /> : null}
+      <ConfirmSpendDialog
+        open={confirming}
+        tier="billable"
+        title={editing ? `Save changes to "${name.trim()}"` : `Save pipeline "${name.trim()}"`}
+        description={`${editing ? `Replaces the pipeline's steps with the ${plural(steps.length, "step")} shown; it stays ${pipeline.enabled ? "on" : "off"}. ` : `Saves ${plural(steps.length, "step")}, turned off. `}Saving does not run the pipeline and charges nothing. You see the price before every run.`}
+        confirmLabel="Save"
+        confirming={save.loading}
+        onConfirm={() => void save.mutate(undefined)}
+        onCancel={() => setConfirming(false)}
+      />
+    </FormSheet>
+  );
+}

package/blocks/enrichment/components/pipeline-templates.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+/**
+ * PipelineTemplates: pick a ready-made pipeline for a list (for example "Find + verify missing emails") and add it.
+ * The catalog is filtered by the API to the recipes that fit this list's kind (people or companies).
+ *
+ * SDK operations, in order:
+ *   1. listPipelineTemplates          GET  /enrichment/lists/pipeline-templates?list_id   (read, free)  recipes + whether the workspace has a
+ *        qualification template (recipes that score records first need one)
+ *   2. createListPipelineFromTemplate POST /enrichment/lists/{list_id}/pipelines/from-template { template_key }   (write, free)
+ *        saves the recipe TURNED OFF and creates any columns it needs. Adding a recipe the list already has REPLACES that
+ *        pipeline's steps with the recipe's (it is saved by name), so that case goes through ConfirmSpendDialog (destructive).
+ *
+ * Nothing runs or charges here: open the new pipeline to price and run it.
+ */
+
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { itemsOf, templateExists } from "../lib/pipeline-types";
+import type { ListPipeline, PipelineTemplate } from "../lib/pipeline-types";
+
+export interface PipelineTemplatesProps {
+  listId: number;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** The pipelines already on the list, to warn before a recipe replaces one. */
+  existing: ListPipeline[];
+  /** Called with the saved pipeline. */
+  onAdded: (pipeline: ListPipeline) => void;
+}
+
+interface Catalog { items?: PipelineTemplate[]; has_qualification_templates?: boolean }
+
+export function PipelineTemplates({ listId, open, onOpenChange, existing, onAdded }: PipelineTemplatesProps) {
+  const [replacing, setReplacing] = useState<PipelineTemplate | null>(null);
+  const [working, setWorking] = useState<string | null>(null);
+  const catalog = useG8Query(async (signal) => (await g8Get<Catalog>("/enrichment/lists/pipeline-templates", { list_id: listId }, { signal })).data, [listId], { enabled: open });
+  const add = useG8Mutation(
+    async (t: PipelineTemplate) => (await g8Post<ListPipeline>(`/enrichment/lists/${listId}/pipelines/from-template`, { template_key: t.key })).data,
+    { onSuccess: (p) => { setReplacing(null); setWorking(null); onAdded(p); onOpenChange(false); }, onError: () => { setWorking(null); setReplacing(null); } },
+  );
+  const templates = itemsOf<PipelineTemplate>(catalog.data);
+  const hasQualification = catalog.data?.has_qualification_templates === true;
+  const choose = (t: PipelineTemplate) => {
+    if (templateExists(t, existing)) { setReplacing(t); return; }
+    setWorking(t.key);
+    void add.mutate(t);
+  };
+
+  return (
+    <FormSheet open={open} onOpenChange={onOpenChange} title="Start from a template" description="Ready-made pipelines for this list. They are saved turned off; nothing runs until you run one." width="lg"
+      footer={<Button type="button" variant="outline" onClick={() => onOpenChange(false)}>Close</Button>}>
+      {catalog.error ? <ApiError error={catalog.error} title="Could not load templates" onRetry={() => void catalog.refetch()} /> : null}
+      {catalog.loading && !catalog.data ? <p className="text-sm text-muted-foreground">Loading templates...</p> : null}
+      {!catalog.loading && !catalog.error && templates.length === 0 ? <EmptyState title="No templates for this list" description="The API has no ready-made pipeline for this kind of list." /> : null}
+      {add.error ? <ApiError error={add.error} title="Could not add the template" /> : null}
+      <ul className="flex flex-col gap-3">
+        {templates.map((t) => {
+          const needsQualification = t.requires_qualification && !hasQualification;
+          return (
+            <li key={t.key} className="rounded-md border p-3" data-testid="template">
+              <div className="flex items-start justify-between gap-3">
+                <div className="min-w-0">
+                  <p className="text-sm font-medium">{t.name}</p>
+                  <p className="text-xs text-muted-foreground">{t.description}</p>
+                  <ol className="mt-2 flex flex-wrap gap-1" aria-label={`${t.name} steps`}>{t.step_names.map((n, i) => <li key={`${n}-${i}`}><StatusPill tone="neutral">{i + 1}. {n}</StatusPill></li>)}</ol>
+                  {needsQualification ? <p className="mt-2 text-xs text-warning-foreground">Needs a qualification template, and this workspace has none yet.</p> : null}
+                  {templateExists(t, existing) ? <p className="mt-2 text-xs text-muted-foreground">This list already has it. Adding it again resets its steps to the recipe.</p> : null}
+                </div>
+                <Button type="button" size="sm" variant="outline" disabled={needsQualification || working != null} loading={working === t.key} aria-label={`Add ${t.name}`} onClick={() => choose(t)}>{templateExists(t, existing) ? "Reset" : "Add"}</Button>
+              </div>
+            </li>
+          );
+        })}
+      </ul>
+      <ConfirmSpendDialog open={replacing != null} tier="destructive" title={`Reset "${replacing?.name ?? ""}" to the template`}
+        description="The pipeline's steps are replaced with the template's. Any edits you made to its steps are lost. Values it already wrote stay on the records."
+        affected={1} confirmLabel="Reset pipeline" confirming={add.loading}
+        onConfirm={() => replacing && void add.mutate(replacing)} onCancel={() => setReplacing(null)} />
+    </FormSheet>
+  );
+}

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

@@ -13,6 +13,9 @@
  *        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.
  */
@@ -27,7 +30,7 @@ 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";
 
@@ -54,6 +57,8 @@ export function WaterfallConfig({ listId, onChanged, onOpen, selectedId, onLoade
   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]);
@@ -76,6 +81,16 @@ export function WaterfallConfig({ listId, onChanged, onOpen, selectedId, onLoade
   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) => {
@@ -102,7 +117,7 @@ export function WaterfallConfig({ listId, onChanged, onOpen, selectedId, onLoade
                 <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"} ({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}
+              {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>
@@ -113,7 +128,7 @@ export function WaterfallConfig({ listId, onChanged, onOpen, selectedId, onLoade
         <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>
@@ -130,9 +145,14 @@ export function WaterfallConfig({ listId, onChanged, onOpen, selectedId, onLoade
             </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>
@@ -143,7 +163,7 @@ export function WaterfallConfig({ listId, onChanged, onOpen, selectedId, onLoade
             {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>
+        <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()}"`}

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;
@@ -65,6 +104,7 @@ export interface EnrichJob {
   successful_enrichments?: number | null;
   failed_enrichments?: number | null;
   total_credits_used?: number | null;
+  paused_at?: string | null;
   warnings?: string[] | null;
   provider_errors?: Array<{ record_id?: number; provider?: string; error?: string }> | null;
 }
@@ -90,6 +130,17 @@ export function isJobTerminal(status: string | undefined | null): boolean {
 }
 
 /**
+ * The API's own quote for a run (`max_total_credits` from the preflight), or null when it could not price it. Null means
+ * "no total": callers show that, never a made-up number.
+ */
+export function quotedCredits(preflight: Pick<Preflight, "max_total_credits"> | undefined): number | null {
+  return preflight?.max_total_credits ?? null;
+}
+
+/**
+ * @deprecated Guesses 2 credits per record when the preflight cannot price a run, which is an invented price. The bulk panel
+ * no longer uses it (see `quotedCredits`); kept exported so existing imports keep working.
+ *
  * What to show as the cost of a run: the API's own quote when the preflight priced it, otherwise the flat
  * per-record estimate times the contacts that are really on the list. Never a balance.
  */

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

@@ -0,0 +1,234 @@
+"use client";
+
+/**
+ * Shapes and pure helpers for list pipelines, auto-enrichment and the enrichment activity view.
+ *
+ * Everything here is read off the API's own responses (enrichment/interfaces/fastapi/list_pipelines_router.py,
+ * auto_enrichment_router.py, router.py). The contract types these payloads as open objects, so the shapes below are the
+ * handlers' documented fields; a field the API leaves out is `undefined`/`null` here and the UI shows a dash, never a
+ * guessed default.
+ *
+ * No prices live here: the cost of a pipeline run is whatever `POST .../estimate` answers for that exact list and
+ * pipeline (`required_credits`, an upper bound that ignores run conditions).
+ */
+
+/** The step kinds a saved pipeline step can have. */
+export type StepType = "ai" | "waterfall";
+
+export interface PipelineStep {
+  id: string;
+  name?: string;
+  type: StepType;
+  config_ref: string;
+  run_condition?: string | null;
+  skip_existing_values?: boolean;
+  skip_recently_enriched?: boolean;
+  enabled?: boolean;
+  ui_meta?: Record<string, unknown> | null;
+  [extra: string]: unknown;
+}
+
+export interface StepProgress {
+  step_index: number;
+  step_id?: string | null;
+  name?: string | null;
+  job_id?: string | null;
+  status?: string | null;
+  total_records?: number;
+  processed_records?: number;
+  successful?: number;
+  failed?: number;
+  skipped_by_reason?: Record<string, number>;
+  note?: string | null;
+}
+
+export interface PipelineRun {
+  run_id: string;
+  status: string;
+  current_index: number;
+  total_steps: number;
+  started_at?: string | null;
+  error?: string | null;
+  cancelled_by?: string | null;
+  step_progress?: StepProgress[];
+  /** Present on a run read by id (GET .../pipeline-runs/{run_id}). */
+  pipeline_id?: string;
+  pipeline_name?: string;
+  list_id?: number;
+  current_job_id?: string | null;
+}
+
+export interface ListPipeline {
+  id: string;
+  list_id: number;
+  name: string;
+  steps: PipelineStep[];
+  enabled: boolean;
+  created_at?: string | null;
+  last_run?: PipelineRun | null;
+}
+
+export interface PipelineEstimate {
+  can_run: boolean;
+  subscription_valid?: boolean;
+  estimated_evaluations: number;
+  required_credits: number;
+  available_credits: number;
+  reason?: string | null;
+  steps: Array<{ step_id: string; name: string; type: string; estimated_records: number; required_credits: number }>;
+}
+
+export interface StepOption {
+  type: StepType;
+  config_ref: string;
+  name: string;
+  is_qualification?: boolean;
+  qualification_entity?: string | null;
+  uses_existing_field?: boolean;
+  target_column_name?: string | null;
+}
+
+export interface PipelineTemplate {
+  key: string;
+  name: string;
+  description: string;
+  target_type: string;
+  requires_qualification: boolean;
+  step_names: string[];
+}
+
+export interface AutoConfig {
+  id: string;
+  audience_id: number;
+  enrichment_type: StepType;
+  column_id: string;
+  trigger_on_insert: boolean;
+  created_at?: string | null;
+  created_by?: string | null;
+}
+
+export const MERGE_RULES = ["sticky", "user_wins", "mashup_wins"] as const;
+export type MergeRule = (typeof MERGE_RULES)[number];
+
+/** What each merge rule does, from enrichment/usecases/apply_mashup_merge/handler.py. */
+export const MERGE_RULE_COPY: Record<MergeRule, { label: string; help: string }> = {
+  sticky: { label: "Keep edits, fill the rest", help: "Fields a person edited are left alone; every other field takes the matched value." },
+  user_wins: { label: "Never overwrite", help: "No matched value is copied onto the record." },
+  mashup_wins: { label: "Matched data wins", help: "Every field takes the matched value, including fields a person edited." },
+};
+
+export interface AutoSettings {
+  entity_type: "contact" | "company";
+  enabled: boolean;
+  default_rule: MergeRule;
+  per_field_overrides: Record<string, MergeRule>;
+  sync_policy_version?: number;
+}
+
+export interface JobControlResult {
+  job_id?: string;
+  success?: boolean;
+  message?: string;
+  previous_status?: string;
+  paused_at?: string;
+  resumed_at?: string;
+}
+
+/** The analytics windows the API accepts (anything else is a 422). */
+export const PERIODS = [
+  { value: "last_7_days", label: "Last 7 days" },
+  { value: "last_30_days", label: "Last 30 days" },
+  { value: "last_90_days", label: "Last 90 days" },
+  { value: "current_month", label: "This month" },
+  { value: "last_month", label: "Last month" },
+] as const;
+export type Period = (typeof PERIODS)[number]["value"];
+
+export const GRANULARITIES = ["day", "week", "month"] as const;
+export type Granularity = (typeof GRANULARITIES)[number];
+
+/** Rows of an open `{ items }` payload, or of a bare array; anything else is an empty list. */
+export function itemsOf<T>(data: unknown, key = "items"): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const v = (data as Record<string, unknown> | null | undefined)?.[key];
+  return Array.isArray(v) ? (v as T[]) : [];
+}
+
+/** The only states a run never leaves (the app's useListPipelines treats everything else as in progress). */
+export const RUN_TERMINAL = ["completed", "failed", "cancelled"] as const;
+
+/**
+ * A run that can still change: poll it, offer Stop, block another Run. The backend creates every run as "pending", so
+ * "active" is "has a status and it is not terminal", never "equals running": a second run priced and confirmed while the
+ * first is pending would charge twice.
+ */
+export function runIsActive(status: string | null | undefined): boolean {
+  const s = String(status ?? "").toLowerCase();
+  return s !== "" && !(RUN_TERMINAL as readonly string[]).includes(s);
+}
+
+/** The pipeline's steps that will run (a disabled step is skipped). */
+export function enabledSteps(p: Pick<ListPipeline, "steps">): PipelineStep[] {
+  return p.steps.filter((s) => s.enabled !== false);
+}
+
+/** A unique, stable step id (1 to 64 characters) for a step added in the editor. */
+export function newStepId(taken: readonly string[]): string {
+  let n = taken.length + 1;
+  while (taken.includes(`step-${n}`)) n += 1;
+  return `step-${n}`;
+}
+
+/** A step for a picked config. Defaults mirror the API's own: fill only empty values, skip recently enriched records. */
+export function stepFromOption(option: StepOption, taken: readonly string[]): PipelineStep {
+  return { id: newStepId(taken), name: option.name, type: option.type, config_ref: option.config_ref, skip_existing_values: true, skip_recently_enriched: true, enabled: true };
+}
+
+/** Move the item at `index` by `delta` (clamped), returning a new array. */
+export function moveItem<T>(items: readonly T[], index: number, delta: number): T[] {
+  const to = index + delta;
+  if (to < 0 || to >= items.length) return [...items];
+  const next = [...items];
+  [next[index], next[to]] = [next[to], next[index]];
+  return next;
+}
+
+/** The body of a save: the name and the FULL step list (the API replaces steps), keeping every field of an edited step. */
+export function savePayload(name: string, steps: readonly PipelineStep[]): { name: string; steps: PipelineStep[] } {
+  return { name: name.trim(), steps: steps.map((s) => ({ ...s })) };
+}
+
+/** Did the editor change anything the API would store? */
+export function pipelineChanged(original: Pick<ListPipeline, "name" | "steps">, name: string, steps: readonly PipelineStep[]): boolean {
+  return original.name !== name.trim() || JSON.stringify(original.steps) !== JSON.stringify(steps);
+}
+
+/** The label of a step: its own name, else the name of the config it points at, else its kind. Never the raw id. */
+export function stepLabel(step: PipelineStep, options: readonly StepOption[]): string {
+  const hit = options.find((o) => o.config_ref === step.config_ref && o.type === step.type);
+  return step.name?.trim() || hit?.name || (step.type === "ai" ? "AI step" : "Provider waterfall step");
+}
+
+/** `n / total` as a whole percent, or null when there is nothing to divide by (shown as a dash, never 0%). */
+export function percentOf(part: number | null | undefined, total: number | null | undefined): number | null {
+  if (part == null || !total) return null;
+  return Math.min(100, Math.round((part / total) * 100));
+}
+
+/** The reason a run reads as "skipped" in plain words. */
+export function skipReasonLabel(reason: string): string {
+  if (reason === "run_condition_not_met") return "skipped by the step condition";
+  return reason.replace(/_/g, " ");
+}
+
+/** True when the pipeline named like this template already exists on the list (re-adding it replaces that pipeline's steps). */
+export function templateExists(template: Pick<PipelineTemplate, "name">, pipelines: readonly Pick<ListPipeline, "name">[]): boolean {
+  return pipelines.some((p) => p.name === template.name);
+}
+
+/** The most useful single sentence about why a pipeline cannot be run right now, or null when it can. */
+export function runBlockedReason(p: Pick<ListPipeline, "steps" | "last_run">): string | null {
+  if (enabledSteps(p).length === 0) return "Every step is turned off, so there is nothing to run.";
+  if (runIsActive(p.last_run?.status)) return "A run is already in progress.";
+  return null;
+}