@graph8/sdk 0.362.0 → 0.373.0

package/blocks/dialer/components/record-calls-tab.tsx

@@ -0,0 +1,101 @@
+"use client";
+
+/**
+ * RecordCallsTab: one contact's call history, newest first, with a "Call" button that places one confirmed call through the
+ * dialer. Use it as an `extraDetailTabs` entry of ContactsScreen:
+ *   { id: "calls", label: "Calls", render: (c) => <RecordCallsTab contact={{ id: c.id, first_name: c.first_name, last_name: c.last_name, email: c.work_email, mobile_phone: c.mobile_phone, direct_phone: c.direct_phone }} onOpenCall={(room) => router.push(`/calls?id=${room}`)} /> }
+ *
+ * SDK operations, in order:
+ *   1. listCallsForContact  GET /voice/dialer/calls?contact_id=&limit=   (read; 25 at first, "Show more" asks for up to 100, the API maximum)
+ *   2. CallContactButton: getMyTeamMember, listDialerSessions, listDialerNumbers, manualDial   (external: confirmed in its dialog)
+ * The API has no offset, so past 100 calls the tab says so instead of cutting the list silently.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { PhoneCall } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { CallContactButton } from "./call-contact-button";
+import type { CallableContact } from "./call-contact-button";
+import { dataOf, formatDuration, type CallSummary } from "../lib/dialer-types";
+import { outcomeTone } from "./call-log-screen";
+
+/** The most calls one read can return. */
+export const CALLS_TAB_API_MAX = 100;
+
+function when(iso?: string | null): string {
+  const d = iso ? new Date(iso) : null;
+  return d && !Number.isNaN(d.getTime()) ? d.toLocaleString(undefined, { month: "short", day: "numeric", year: "numeric", hour: "numeric", minute: "2-digit" }) : "";
+}
+
+export interface RecordCallsTabProps {
+  /** The contact: `id` scopes the history; the name and numbers feed the call button. */
+  contact: CallableContact & { id: string | number };
+  /** Route to the call in your calls screen; receives the call's room name. Without it the rows link to `${callsPath}?id=<room name>`. */
+  onOpenCall?: (roomName: string) => void;
+  /** Path of your calls screen for the plain links. Default "/calls". */
+  callsPath?: string;
+  /** Calls to read first. Default 25. */
+  pageSize?: number;
+  /** Pass the rep's softphone identity through to the call button (see CallContactButton). */
+  userId?: string;
+  userEmail?: string;
+}
+
+export function RecordCallsTab({ contact, onOpenCall, callsPath = "/calls", pageSize = 25, userId, userEmail }: RecordCallsTabProps) {
+  const [limit, setLimit] = useState(Math.min(pageSize, CALLS_TAB_API_MAX));
+  const contactId = String(contact.id);
+  const q = useG8Query(
+    async (signal) => dataOf<{ calls?: CallSummary[] }>(await g8Get("/voice/dialer/calls", { contact_id: contactId, limit }, { signal })).calls ?? [],
+    [contactId, limit],
+  );
+  const call = <CallContactButton contact={contact} userId={userId} userEmail={userEmail} onCalled={() => void q.refetch()} />;
+  if (q.error) return <ApiError error={q.error} title="Could not load calls" onRetry={() => void q.refetch()} />;
+  if (!q.data) return <Skeleton className="h-24 w-full" aria-label="Loading calls" />;
+  const calls = q.data;
+  const full = calls.length >= limit;
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center justify-between gap-2">
+        <p className="text-sm text-muted-foreground">{calls.length === 1 ? "1 call" : `${calls.length.toLocaleString()}${full ? "+" : ""} calls`}</p>
+        {call}
+      </div>
+      {calls.length === 0 ? (
+        <EmptyState compact icon={<PhoneCall className="size-8" />} title="No calls yet" description="Calls the dialer places to this contact show up here." />
+      ) : (
+        <ul className="divide-y rounded-md border" aria-label="Calls">
+          {calls.map((c) => (
+            <li key={c.room_name}>
+              <a
+                href={`${callsPath}?id=${encodeURIComponent(c.room_name)}`}
+                className="flex items-center justify-between gap-3 p-3 text-sm hover:bg-muted"
+                onClick={(e) => {
+                  if (!onOpenCall || e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+                  e.preventDefault();
+                  onOpenCall(c.room_name);
+                }}
+              >
+                <span className="min-w-0">
+                  <span className="block font-medium">{when(c.created_at) || "Call"}</span>
+                  <span className="block truncate text-xs text-muted-foreground">{[c.to, formatDuration(c.call_duration), c.summary ?? (c.has_transcript ? "Transcript available" : null)].filter(Boolean).join(" · ")}</span>
+                </span>
+                <StatusPill tone={outcomeTone(c.disposition)}>{c.disposition ? c.disposition.replace(/_/g, " ") : "no outcome"}</StatusPill>
+              </a>
+            </li>
+          ))}
+        </ul>
+      )}
+      {full && limit < CALLS_TAB_API_MAX ? (
+        <div className="flex items-center justify-between text-sm text-muted-foreground">
+          <span role="status">Showing {calls.length.toLocaleString()} calls</span>
+          <Button size="sm" variant="outline" onClick={() => setLimit(CALLS_TAB_API_MAX)}>Show more</Button>
+        </div>
+      ) : null}
+      {full && limit >= CALLS_TAB_API_MAX ? <p role="note" className="text-xs text-muted-foreground">Showing the {CALLS_TAB_API_MAX} most recent calls. Older calls are in the call log by rep or session.</p> : null}
+    </div>
+  );
+}

package/blocks/dialer/components/session-start-form.tsx

@@ -4,9 +4,15 @@
  * SessionStartForm: create a DRAFT dialer session for a list. A draft dials NOBODY; dialing starts only when
  * CallQueue's "Dial next batch" is confirmed.
  *
+ * No ids to type: the rep defaults to the signed-in team member (`useCurrentMember`, GET /team-members/me) and can be
+ * switched with a MemberPicker; the list is picked with a ListPicker. A `userId` / `listId` prop still wins, and the
+ * raw id fields stay under "Use a ... id instead" for a key that is not a person (an organisation key).
+ *
  * SDK operations, in order:
+ *   0. GET  /team-members/me           (teamMembers.getMyTeamMember)   read  - only without `userId`: the rep is you
  *   1. GET  /voice/dialer/numbers      (voice.listDialerNumbers)       read  - caller IDs and today's usage
  *   2. POST /dialer/sessions/draft     (dialer.createSessionDraft)     write - safe: resolves the list, dials no one
+ * A personal key may only name itself as the rep: naming someone else answers 403, which the form explains.
  * Calling the draft twice for the same list returns the existing live session instead of making a second one.
  */
 import { useState } from "react";
@@ -16,6 +22,11 @@ import { g8Post } from "@/g8/lib/g8-client";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useDialerNumbers } from "../hooks/use-dialer-numbers";
 import { dataOf, type DialerMode } from "../lib/dialer-types";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { useCurrentMember } from "@/g8/pickers/hooks/use-current-member";
+import { MemberPicker } from "@/g8/pickers/components/member-picker";
+import type { MemberOption } from "@/g8/pickers/components/member-picker";
+import { ListPicker } from "@/g8/lists/components/list-picker";
 
 export interface SessionStartFormProps {
   /** The rep these calls are attributed to. An organisation API key has no user of its own, so you name one. */
@@ -30,14 +41,25 @@ export interface SessionStartFormProps {
 }
 
 export function SessionStartForm({ userId, userEmail, listId: initialListId = "", listTitle, onCreated, className }: SessionStartFormProps) {
+  const brand = useBrand();
   const { numbers, loading, error, refetch } = useDialerNumbers();
   const [listId, setListId] = useState(initialListId);
+  const [pickedTitle, setPickedTitle] = useState("");
   const [typedUserId, setTypedUserId] = useState("");
-  const repId = userId || typedUserId.trim();
+  const [refused, setRefused] = useState(false);
+  // With a passed userId nobody is looked up, until a 403 needs to know whether the rep is someone else.
+  const me = useCurrentMember({ enabled: !userId || refused });
+  const [picked, setPicked] = useState<MemberOption | null>(null);
+  // Who the session is for: a passed userId, else a typed id, else the chosen teammate, else you. user_id and user_email
+  // always describe the same person.
+  const resolved = userId || typedUserId.trim() ? null : (picked ?? me.member);
+  const repId = userId || typedUserId.trim() || resolved?.id || "";
+  const repEmail = resolved ? (resolved.email ?? undefined) : userEmail;
   const [fromPhone, setFromPhone] = useState("");
   const [mode, setMode] = useState<DialerMode>("power");
   const [parallelCount, setParallelCount] = useState(3);
   const [name, setName] = useState(listTitle ? `Dialing ${listTitle}` : "");
+  const title = listTitle ?? pickedTitle;
 
   const chosenPhone = fromPhone || numbers[0]?.phone_number || "";
   const create = useG8Mutation(
@@ -45,9 +67,9 @@ export function SessionStartForm({ userId, userEmail, listId: initialListId = ""
       const count = mode === "parallel" ? Math.min(10, Math.max(2, Math.round(parallelCount) || 2)) : 1;
       const env = await g8Post("/dialer/sessions/draft", {
         user_id: repId,
-        user_email: userEmail,
+        user_email: repEmail,
         list_id: listId,
-        list_title: listTitle,
+        list_title: title || undefined,
         name: name || undefined,
         from_phone: chosenPhone || undefined,
         dialing_mode: mode,
@@ -55,24 +77,44 @@ export function SessionStartForm({ userId, userEmail, listId: initialListId = ""
         user_timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
       });
       const sessionId = dataOf<{ session_id?: string }>(env).session_id;
-      if (!sessionId) throw new Error("graph8 did not return a session id");
+      if (!sessionId) throw new Error(`${brand.linkLabel} did not return a session id`);
       return { sessionId, mode, parallelCount: count, fromPhone: chosenPhone };
     },
-    { onSuccess: onCreated },
+    { onSuccess: onCreated, onError: (e) => setRefused((e as { status?: number } | undefined)?.status === 403) },
   );
 
   return (
     <form className={`space-y-3 rounded-lg border p-4 ${className ?? ""}`} onSubmit={(e) => { e.preventDefault(); if (listId && repId) void create.mutate(undefined); }}>
-      <h3 className="text-sm font-semibold">Start a dialing session</h3>
+      <h3 className="text-sm font-medium">Start a dialing session</h3>
       <div className="grid gap-3 sm:grid-cols-2">
-        <div className="space-y-1">
-          <Label htmlFor="ds-list">List id</Label>
-          <Input id="ds-list" value={listId} onChange={(e) => setListId(e.target.value)} placeholder="From your lists" />
+        <div className="space-y-1 sm:col-span-2">
+          <span className="text-sm font-medium leading-none">List</span>
+          {initialListId ? (
+            <p className="text-sm">{title || `List ${initialListId}`}</p>
+          ) : (
+            <ListPicker type="contacts" allowCreate={false} value={Number(listId) || null} onChange={(l) => { setListId(String(l.id)); setPickedTitle(l.title); setName((n) => n || `Dialing ${l.title}`); }} />
+          )}
+          <details className="text-sm">
+            <summary className="cursor-pointer text-muted-foreground">Use a list id instead</summary>
+            <div className="mt-1 space-y-1">
+              <Label htmlFor="ds-list">List id</Label>
+              <Input id="ds-list" value={listId} onChange={(e) => setListId(e.target.value)} placeholder="From your lists" />
+            </div>
+          </details>
         </div>
         {userId ? null : (
-          <div className="space-y-1">
-            <Label htmlFor="ds-user">Rep user id</Label>
-            <Input id="ds-user" value={typedUserId} onChange={(e) => setTypedUserId(e.target.value)} placeholder="graph8 user id" />
+          <div className="space-y-1 sm:col-span-2">
+            <span className="text-sm font-medium leading-none">Rep</span>
+            {me.loading ? <p className="text-sm text-muted-foreground">Finding your user...</p> : null}
+            {resolved ? <p className="text-sm">Calling as {resolved.name}{resolved.id === me.userId ? " (you)" : ""}</p> : null}
+            <MemberPicker label={resolved ? "Switch rep" : "Rep"} value={resolved?.id ?? null} onChange={(m) => { setPicked(m); setTypedUserId(""); }} placeholder="Choose who is calling" />
+            <details className="text-sm">
+              <summary className="cursor-pointer text-muted-foreground">Use a user id instead</summary>
+              <div className="mt-1 space-y-1">
+                <Label htmlFor="ds-user">Rep user id</Label>
+                <Input id="ds-user" value={typedUserId} onChange={(e) => setTypedUserId(e.target.value)} placeholder={`${brand.linkLabel} user id`} />
+              </div>
+            </details>
           </div>
         )}
         <div className="space-y-1">
@@ -103,6 +145,13 @@ export function SessionStartForm({ userId, userEmail, listId: initialListId = ""
       </div>
       {error ? <ApiError error={error} title="Could not load caller IDs" onRetry={() => void refetch()} /> : null}
       {create.error ? <ApiError error={create.error} title="Could not create the session" /> : null}
+      {(create.error as { status?: number } | undefined)?.status === 403 ? (
+        <p role="alert" className="text-sm text-muted-foreground">
+          {me.userId && repId && repId !== me.userId
+            ? "A personal API key can only act as its own user, so this session cannot be started for someone else. Switch the rep back to yourself."
+            : "This API key is not allowed to start dialer sessions. Check that it has the voice scopes, or ask an admin."}
+        </p>
+      ) : null}
       <Button type="submit" disabled={!listId || !repId || create.loading} loading={create.loading}>
         Create session (dials no one yet)
       </Button>

package/blocks/dialer/components/softphone.tsx

@@ -22,6 +22,7 @@ import { g8Get } from "@/g8/lib/g8-client";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { dataOf } from "../lib/dialer-types";
 import type { SoftphoneTransport } from "../lib/softphone-transport";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface SoftphoneProps {
   /** The rep whose identity the credential is minted for. */
@@ -38,6 +39,7 @@ export interface SoftphoneProps {
 export type SoftphoneState = "off" | "connecting" | "ready" | "in-call" | "error";
 
 export function Softphone({ userId, transport, conferenceName, joinMuted, onStateChange, className }: SoftphoneProps) {
+  const brand = useBrand();
   const [state, setState] = useState<SoftphoneState>("off");
   const [muted, setMuted] = useState(false);
   const [expiring, setExpiring] = useState(false);
@@ -61,7 +63,7 @@ export function Softphone({ userId, transport, conferenceName, joinMuted, onStat
   const mint = useG8Mutation(async () => {
     const env = await g8Get("/dialer/sessions/token", { user_id: userId });
     const { token, identity } = dataOf<{ token?: string; identity?: string }>(env);
-    if (!token) throw new Error("graph8 did not return a softphone credential");
+    if (!token) throw new Error(`${brand.linkLabel} did not return a softphone credential`);
     return { token, identity };
   });
 
@@ -91,7 +93,7 @@ export function Softphone({ userId, transport, conferenceName, joinMuted, onStat
   return (
     <section className={`space-y-3 rounded-lg border p-4 ${className ?? ""}`} aria-label="Softphone">
       <div className="flex items-center justify-between">
-        <h3 className="text-sm font-semibold">Softphone</h3>
+        <h3 className="text-sm font-medium">Softphone</h3>
         <span role="status" className="text-sm text-muted-foreground">{label}</span>
       </div>
       {transportError ? <p role="alert" className="text-sm text-destructive">{transportError}</p> : null}

package/blocks/enrichment/README.md

@@ -5,14 +5,26 @@ contacts of a list in one job, and manage the provider pipelines behind it. Buil
 
 Install: `npx @graph8/sdk add enrichment` (installs `foundation`, `crm` and `lists` first).
 
+## Screens
+
+`EnrichmentScreen` is the finished enrichment page; mount it with no props. Tabs (`?tab=`): **Enrich a list** (pick a list,
+tick contacts, run a bulk enrichment with preflight, confirmed price, progress and cancel; open a contact to look it up
+or verify its email), **Look up** (one person or company, and email verification), **Pipelines** (a list's saved
+provider waterfalls: create, delete) and **Providers** (graph8-funded vs your own key, credits per action; keys are
+added in graph8 settings, so it links out). Every paid step goes through the confirmation dialog.
+Also a **Jobs** tab (`?job=`, `EnrichmentJobDetail`: live progress, counts, credits, provider errors, cancel; the jobs running now come from `GET /enrichment/active-jobs` and jobs started this session are listed, so no id has to be pasted; an older job can still be opened by id) and a pipeline detail (`?pipeline=`: steps, credential status, missing keys). `?view=full` opens any detail full-page.
+Slots: `toolbarActions`, `renderDetailActions(contact)`, `extraDetailTabs`.
+
+Prerequisites: `crm` and `lists` installed, proxy allowlist `enrichment`, `lists`, `contacts`, `companies`; provider keys and credits as below.
+
 ## What you get
 
 | Component | Use it for | Props |
 |---|---|---|
 | `EnrichButton` | Look up one person/company; optionally apply the found fields to the record | `kind`, `lookup`, `record`, `onResult`, `onApplied` |
-| `EmailVerifyBadge` | Status chip (Unverified / Valid / Risky / Invalid) with a Verify action | `email`, `initialStatus`, `onVerified`, `readOnly` |
+| `EmailVerifyBadge` | Status chip (Unverified / Valid / Risky / Invalid / Couldn't verify) read from the verifier's own result codes: catch-all (`ok_for_all`) is Risky, a hard failure (`email_disabled`, `invalid_mx`, `dead_server`, `error`, ...) is Invalid and offers no second paid Verify, `unknown` (what the endpoint answers when the verifier itself fails, uncharged) is "Couldn't verify" with Try again. The verdict is shown, not saved to the contact (`POST /enrichment/verify-email` takes only `email`) | `email`, `initialStatus`, `onVerified`, `readOnly` |
 | `BulkEnrichPanel` | Fill work email / phones for many contacts of a list: preflight, estimate, job, progress | `listId`, `contactIds`, `defaultProviders`, `onDone` |
-| `WaterfallConfig` | Saved pipelines of a list and a form to create one | `listId`, `onChanged` |
+| `WaterfallConfig` | Saved pipelines of a list and a form to create one. Creating is idempotent per field and list: if the list already has a pipeline for the field, the API returns it (`created: false`, its own providers) and the form says "Already exists, reused" | `listId`, `onChanged` |
 
 `BulkEnrichPanel` with no props is a complete page (choose a list, tick contacts, enrich), so it can be mounted as a
 route as is; give it `listId` and `contactIds` to embed it. For that reason this block depends on `lists`.
@@ -37,11 +49,20 @@ you can afford it; an under-funded run fails with 402.
    Masked search results have no ids and cannot be enriched: save them to a list first (`search` block).
 2. `POST /enrichment/preflight { list_id, contact_ids, mode: "waterfall", providers, target_field }` (free) ->
    `contact_count`, `not_in_list`, `missing_credentials`, `warnings`, `credits_per_record`, `max_total_credits`.
-3. The person confirms the estimate. `POST /enrichment/enrich { contact_ids, list_id, fields_config: { work_email: [providers] } }`
-   -> 202 `{ job_id }`.
+3. The person confirms the estimate. `POST /enrichment/waterfall/configs { list_id, name, field: "CONTACT_WORK_EMAIL", providers }`
+   creates the list's pipeline for that field, or reuses the one it already has (`created: false`; the run then uses
+   ITS providers) -> `column_id`. Then `POST /enrichment/waterfall/enrich { column_id, list_id, record_ids }` -> 202
+   `{ job_id, status }`. A `status` of `"error"` (or a 502) means the job never started: show it as a failure, do not
+   poll. Providers must suit the field: phones take leadmagic, prospeo, apollo only (`FIELD_PROVIDERS`); the panel
+   resets the providers when the field changes. Before the confirm, the panel reads the list's pipelines
+   (`GET /enrichment/waterfall/configs?list_id`): when one already fills the field, the quote, the confirm and the run
+   use ITS providers (the API reuses it), and the panel says so instead of offering a provider editor.
+   `POST /enrichment/enrich` is not used: until the API fix of 2026-10-16 it dispatched the field name instead of a
+   pipeline and silently enriched nothing, so apps on older SDK copies should take this path.
 4. Poll `GET /enrichment/jobs/{job_id}` (`useJobPoll`, backoff; there is no stream and no completion webhook) until
    `status` is `completed`, `failed` or `cancelled`. It reports `completed/total`, `successful_enrichments`, `failed_enrichments`,
    `total_credits_used`. If nothing was enriched, `?include_provider_errors=true` explains why (usually a missing provider key).
+   When the job ends the panel refreshes every cached `contacts` query and calls `onDone`, so tables and records reload.
 5. `POST /enrichment/jobs/{job_id}/cancel` stops a running job; records already done keep their data and charge.
 
 ```tsx
@@ -85,7 +106,7 @@ Ask the person: who may spend credits (decide it in the proxy's `authorize`).
 | File | Does |
 |---|---|
 | `recipes/lookup-and-verify.ts` | One person/company lookup and an email check |
-| `recipes/bulk-enrich-and-poll.ts` | Preflight quote, start, poll with backoff, read provider errors |
+| `recipes/bulk-enrich-and-poll.ts` | Preflight quote, create or reuse the pipeline and run it, poll with backoff, read provider errors |
 | `recipes/waterfall-pipeline.ts` | Provider readiness, create and list pipelines |
 
 ## Operations
@@ -95,11 +116,12 @@ Ask the person: who may spend credits (decide it in the proxy's `authorize`).
 | lookupPerson / lookupCompany | POST /enrichment/lookup/person, /company | billable | EnrichButton |
 | verifyEmail | POST /enrichment/verify-email | billable | EmailVerifyBadge |
 | preflightEnrichment | POST /enrichment/preflight | read | BulkEnrichPanel |
-| startEnrichment | POST /enrichment/enrich | billable | BulkEnrichPanel |
+| startEnrichment | POST /enrichment/enrich | billable | (not used by the components; see the flow) |
+| runWaterfallPipeline | POST /enrichment/waterfall/enrich | billable | BulkEnrichPanel |
 | getEnrichmentJob | GET /enrichment/jobs/{job_id} | read | BulkEnrichPanel |
 | cancelEnrichmentJob | POST /enrichment/jobs/{job_id}/cancel | write | BulkEnrichPanel |
 | listEnrichmentProviders | GET /enrichment/providers | read | BulkEnrichPanel, WaterfallConfig |
 | listWaterfallConfigs | GET /enrichment/waterfall/configs | read | WaterfallConfig |
-| createDefaultWaterfallConfig | POST /enrichment/waterfall/configs | billable | WaterfallConfig |
+| createDefaultWaterfallConfig | POST /enrichment/waterfall/configs | billable | WaterfallConfig, BulkEnrichPanel |
 | deleteWaterfallConfig | DELETE /enrichment/waterfall/configs/{column_id} | destructive | WaterfallConfig |
 | updateContact / updateCompany | PATCH /contacts/{id}, /companies/{id} | write | EnrichButton (Apply) |

package/blocks/enrichment/block.json

@@ -7,10 +7,12 @@
     "single person/company lookup that can apply found fields to the record",
     "email verification chip with a one-click verify",
     "bulk enrichment with a free preflight, credit estimate confirmation, polled progress and cancel",
-    "waterfall pipeline manager with provider order and credential readiness"
+    "waterfall pipeline manager with provider order and credential readiness",
+    "finished EnrichmentScreen page"
   ],
   "dependsOn": [
-    "lists"
+    "lists",
+    "pickers"
   ],
   "operations": [
     "cancel_enrichment_job_enrichment_jobs__job_id__cancel_post",
@@ -18,7 +20,11 @@
     "create_list_lists_post",
     "delete_contact_contacts__contact_id__delete",
     "delete_waterfall_config_enrichment_waterfall_configs__column_id__delete",
+    "get_company_companies__company_id__get",
+    "get_contact_contacts__contact_id__get",
     "get_enrichment_job_enrichment_jobs__job_id__get",
+    "list_active_enrichment_jobs_enrichment_active_jobs_get",
+    "list_companies_companies_get",
     "list_contact_fields_fields_get",
     "list_contacts_contacts_get",
     "list_enrichment_providers_enrichment_providers_get",
@@ -27,6 +33,7 @@
     "lookup_company_enrichment_lookup_company_post",
     "lookup_person_enrichment_lookup_person_post",
     "preflight_enrichment_enrichment_preflight_post",
+    "run_waterfall_pipeline_enrichment_waterfall_enrich_post",
     "start_enrichment_enrichment_enrich_post",
     "update_company_companies__company_id__patch",
     "update_contact_contacts__contact_id__patch",
@@ -41,9 +48,12 @@
         "lookup_person_enrichment_lookup_person_post",
         "lookup_company_enrichment_lookup_company_post",
         "update_contact_contacts__contact_id__patch",
-        "update_company_companies__company_id__patch"
+        "update_company_companies__company_id__patch",
+        "get_contact_contacts__contact_id__get",
+        "get_company_companies__company_id__get"
       ],
       "tiers": [
+        "read",
         "write",
         "billable"
       ]
@@ -51,7 +61,7 @@
     {
       "name": "EmailVerifyBadge",
       "file": "components/email-verify-badge.tsx",
-      "purpose": "Status chip for an email (Unverified, Valid, Risky, Invalid) with a confirmed 1-credit Verify action; never verifies a locked email.",
+      "purpose": "Status chip for an email (Unverified, Valid, Risky, Invalid, Couldn't verify) from the verifier's own result codes, with a confirmed 1-credit Verify action; never verifies a locked email.",
       "operations": [
         "verify_email_enrichment_verify_email_post"
       ],
@@ -62,11 +72,13 @@
     {
       "name": "BulkEnrichPanel",
       "file": "components/bulk-enrich-panel.tsx",
-      "purpose": "Fill a field for many contacts of a list: free preflight, credit estimate in ConfirmSpendDialog, start the job, poll it with useJobPoll, cancel. With no props it is a whole page (pick a list, tick contacts).",
+      "purpose": "Fill a field for many contacts of a list: free preflight, credit estimate in ConfirmSpendDialog, create or reuse the field's pipeline and run it, poll it with useJobPoll, cancel. With no props it is a whole page (pick a list, tick contacts).",
       "operations": [
         "list_enrichment_providers_enrichment_providers_get",
+        "list_waterfall_configs_enrichment_waterfall_configs_get",
         "preflight_enrichment_enrichment_preflight_post",
-        "start_enrichment_enrichment_enrich_post",
+        "create_default_waterfall_config_enrichment_waterfall_configs_post",
+        "run_waterfall_pipeline_enrichment_waterfall_enrich_post",
         "get_enrichment_job_enrichment_jobs__job_id__get",
         "cancel_enrichment_job_enrichment_jobs__job_id__cancel_post",
         "list_lists_lists_get",
@@ -97,6 +109,32 @@
         "billable",
         "destructive"
       ]
+    },
+    {
+      "name": "EnrichmentScreen",
+      "file": "components/enrichment-screen.tsx",
+      "purpose": "Finished enrichment page: enrich a list, one-off lookups and email verification, pipelines and the provider catalog.",
+      "operations": [
+        "list_contacts_contacts_get",
+        "list_companies_companies_get",
+        "list_active_enrichment_jobs_enrichment_active_jobs_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "EnrichmentJobDetail",
+      "file": "components/enrichment-job-detail.tsx",
+      "purpose": "One bulk enrichment job: live progress, counts, credits, warnings, provider errors and cancel.",
+      "operations": [
+        "cancel_enrichment_job_enrichment_jobs__job_id__cancel_post",
+        "get_enrichment_job_enrichment_jobs__job_id__get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
     }
   ],
   "hooks": [
@@ -124,12 +162,12 @@
     {
       "file": "recipes/bulk-enrich-and-poll.ts",
       "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 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."
+      "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 -> 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."
     },
     {
       "file": "recipes/waterfall-pipeline.ts",
       "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)."
+      "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 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)."
     }
   ],
   "prerequisites": [
@@ -159,6 +197,7 @@
     }
   ],
   "scopes": [
+    "companies:read",
     "companies:write",
     "contacts:delete",
     "contacts:read",
@@ -174,7 +213,7 @@
   "defaults": [
     {
       "decision": "Providers a bulk run tries",
-      "default": "prospeo then dropcontact (the API's own default), filtered to those in the provider catalog; editable in the panel",
+      "default": "The API's own per field (work email: prospeo then dropcontact; phones: leadmagic, prospeo, apollo), kept to providers in the catalog that the field supports; editable in the panel. A list that already has a pipeline for the field runs with that pipeline's providers",
       "askHuman": false
     },
     {
@@ -199,6 +238,7 @@
     }
   ],
   "peerDependencies": {
+    "lucide-react": ">=0.400.0",
     "react": ">=18"
   }
 }