@graph8/sdk 0.361.0 → 0.370.0

package/blocks/dialer/components/dialer-session-detail.tsx

@@ -0,0 +1,153 @@
+"use client";
+
+/**
+ * DialerSessionDetail: one dialer session as a complete record. Tabs: Overview (stats and every session field), Calls (the
+ * calls in the session with hang up, mute and confirmed voicemail drop) and Queue (contacts still waiting, with skip).
+ * Header actions: Pause, Resume (dials the next contacts, so it is confirmed), Stop (hangs up live calls, confirmed) and
+ * "Work this session" (hands the id to the caller so the calling workspace can take over).
+ *
+ * SDK operations, in order:
+ *   1. GET /dialer/sessions/{id}/queue-stats + GET /dialer/sessions/{id}   read    (polled every 5s via useDialerSession)
+ *   2. POST /dialer/sessions/{id}/pause                                      write   (hangs up live calls)
+ *   3. POST /voice/dialer/sessions/{id}/resume { max_contacts }              EXTERNAL -> ConfirmSpendDialog first (places real calls)
+ *   4. POST /dialer/sessions/{id}/stop                                       write   -> ConfirmSpendDialog (one-way, hangs up live calls)
+ * Calls and queue use LiveCallsTable and WaitingContacts (see those files for their operations and confirmations).
+ * Full-page mode: pass `expanded` plus `onExpand` / `onCollapse` (DialerScreen ties them to `?view=full`).
+ */
+import { useState, type ReactNode } from "react";
+import { Phone } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useDialerSession } from "../hooks/use-dialer-session";
+import { isLiveCall, isSessionOver, needsDisposition, normalizeStatus } from "../lib/dialer-types";
+import { WaitingContacts } from "./call-queue";
+import { LiveCallsTable } from "./live-calls-table";
+import { pluralWord } from "@/g8/lib/plural";
+
+export interface DialerSessionDetailProps {
+  sessionId: string;
+  /** Needed by pause on some orgs; optional. */
+  userEmail?: string;
+  /** Show "Work this session" and call this with the id. */
+  onWork?: (sessionId: string) => void;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  /** Called after pause, resume or stop succeeded (refresh your list). */
+  onChanged?: () => void;
+  /** Extra buttons in the header. */
+  actions?: ReactNode;
+  className?: string;
+}
+
+function tone(status: string) {
+  return status === "active" ? "positive" : status === "paused" ? "warning" : status === "completed" || status === "stopped" ? "neutral" : "info";
+}
+
+export function DialerSessionDetail({ sessionId, userEmail, onWork, onClose, onExpand, onCollapse, onChanged, actions, className }: DialerSessionDetailProps) {
+  const session = useDialerSession(sessionId);
+  const [version, setVersion] = useState(0);
+  const [asking, setAsking] = useState<"resume" | "stop" | null>(null);
+  const changed = () => { setVersion((v) => v + 1); session.refresh(); onChanged?.(); };
+  const base = `/dialer/sessions/${encodeURIComponent(sessionId)}`;
+  const pause = useG8Mutation(() => g8Post(`${base}/pause`, undefined, { query: { user_email: userEmail } }), { onSuccess: changed });
+  const stop = useG8Mutation(() => g8Post(`${base}/stop`), { onSuccess: () => { setAsking(null); changed(); }, onError: () => setAsking(null) });
+  const detail = session.detail;
+  const mode = detail?.dialing_mode ?? "power";
+  const count = mode === "parallel" ? Math.min(4, Math.max(1, detail?.parallel_count ?? 2)) : 1;
+  const resume = useG8Mutation(() => g8Post(`/voice/dialer/sessions/${encodeURIComponent(sessionId)}/resume`, { max_contacts: count }), { onSuccess: () => { setAsking(null); changed(); }, onError: () => setAsking(null) });
+
+  if (!session.stats && !session.error) return <Skeleton className="h-48 w-full" aria-label="Loading session" />;
+  const status = normalizeStatus(session.stats?.status ?? detail?.status);
+  const over = isSessionOver(status);
+  const calls = session.calls;
+  const failure = session.error ?? pause.error ?? stop.error ?? resume.error;
+
+  const header = (
+    <>
+      {onWork && !over ? <Button size="sm" variant="outline" onClick={() => onWork(sessionId)}><Phone className="mr-1 size-4" />Work this session</Button> : null}
+      {status === "active" ? <Button size="sm" variant="outline" disabled={pause.loading} loading={pause.loading} onClick={() => void pause.mutate(undefined)}>Pause</Button> : null}
+      {status === "paused" ? <Button size="sm" variant="outline" onClick={() => setAsking("resume")}>Resume</Button> : null}
+      {!over ? <Button size="sm" variant="outline" onClick={() => setAsking("stop")}>Stop</Button> : null}
+      {actions}
+    </>
+  );
+  const overview = (
+    <div className="space-y-4">
+      <StatStrip
+        items={[
+          { label: "Left in queue", value: session.stats?.queue_remaining ?? detail?.counts?.queue_remaining ?? 0 },
+          { label: "On calls now", value: calls.filter(isLiveCall).length, tone: calls.some(isLiveCall) ? "positive" : "neutral" },
+          { label: "Need an outcome", value: calls.filter(needsDisposition).length, tone: calls.some(needsDisposition) ? "warning" : "neutral" },
+          { label: "Voicemails", value: detail?.live_state?.voicemail_calls ?? calls.filter((c) => c.is_voicemail).length },
+        ]}
+      />
+      <SectionCard title="Session details">
+        <KeyValueList
+          columns={2}
+          items={[
+            { label: "Name", value: detail?.name ?? "" },
+            { label: "Status", value: status },
+            { label: "List", value: detail?.list_title ?? detail?.list_id ?? "" },
+            { label: "Mode", value: detail?.dialing_mode ? `${detail.dialing_mode}${detail.dialing_mode === "parallel" ? ` (${count} at once)` : ""}` : "" },
+            { label: "Caller ID", value: detail?.from_phone ?? "" },
+            { label: "Contacts", value: detail?.counts?.total },
+            { label: "Dialed", value: detail?.counts?.total_dialed },
+            { label: "Not dialed yet", value: detail?.counts?.total_undialed },
+            { label: "Session id", value: sessionId, mono: true, wide: true },
+          ]}
+        />
+      </SectionCard>
+    </div>
+  );
+
+  return (
+    <div className={className}>
+      {failure ? <ApiError error={failure} title="Session problem" onRetry={() => session.refresh()} /> : null}
+      <DetailPanel
+        title={detail?.name ?? "Dialing session"}
+        subtitle={detail?.list_title ?? undefined}
+        badges={<StatusPill tone={tone(status)} dot>{status || "unknown"}</StatusPill>}
+        actions={header}
+        onClose={onClose}
+        onExpand={onExpand}
+        onCollapse={onCollapse}
+        tabs={[
+          { id: "overview", label: "Overview", content: overview },
+          { id: "calls", label: "Calls", count: calls.length, content: <LiveCallsTable sessionId={sessionId} calls={calls} onChanged={changed} /> },
+          { id: "queue", label: "Queue", content: <WaitingContacts sessionId={sessionId} version={version} onSkipped={changed} /> },
+        ]}
+      />
+      <ConfirmSpendDialog
+        open={asking === "resume"}
+        tier="external"
+        title={count > 1 ? `Resume and dial the next ${count} ${pluralWord(count, "contact")}?` : "Resume and dial the next contact?"}
+        description="This places real phone calls to people on the list and reserves credits for each attempt."
+        confirmLabel="Resume and dial"
+        recipients={count}
+        confirming={resume.loading}
+        onConfirm={() => void resume.mutate(undefined)}
+        onCancel={() => setAsking(null)}
+      />
+      <ConfirmSpendDialog
+        open={asking === "stop"}
+        tier="destructive"
+        title="Stop this session?"
+        description="Every live call is hung up and the session is completed. It cannot be resumed."
+        confirmLabel="Stop session"
+        affected={calls.filter(isLiveCall).length}
+        confirming={stop.loading}
+        onConfirm={() => void stop.mutate(undefined)}
+        onCancel={() => setAsking(null)}
+      />
+    </div>
+  );
+}

package/blocks/dialer/components/live-calls-table.tsx

@@ -18,8 +18,12 @@ import { EmptyState } from "@/g8/components/empty-state";
 import { g8Post } from "@/g8/lib/g8-client";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { contactName, isLiveCall, normalizeStatus, type LiveCall } from "../lib/dialer-types";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+import { RecordLink } from "@/g8/components/screen/record-link";
 
 export interface LiveCallsTableProps {
+  /** URL param the host screen reads for this record type. With it the name is a real link (Cmd-click opens it in a new tab); without it a plain button. */
+  linkParam?: string;
   sessionId: string;
   calls: LiveCall[];
   /** Called after a control succeeded; refresh the session here. */
@@ -29,7 +33,7 @@ export interface LiveCallsTableProps {
   className?: string;
 }
 
-export function LiveCallsTable({ sessionId, calls, onChanged, onSelect, className }: LiveCallsTableProps) {
+export function LiveCallsTable({ linkParam, sessionId, calls, onChanged, onSelect, className }: LiveCallsTableProps) {
   const [voicemailFor, setVoicemailFor] = useState<LiveCall | null>(null);
   // Per-row busy state: only the row being acted on is disabled, not every call in the table.
   const [busy, setBusy] = useState<ReadonlySet<string>>(new Set());
@@ -71,8 +75,8 @@ export function LiveCallsTable({ sessionId, calls, onChanged, onSelect, classNam
             const live = isLiveCall(call);
             const rowBusy = busy.has(call.call_id);
             return (
-              <TableRow key={call.call_id} className={onSelect ? "cursor-pointer" : undefined} onClick={() => onSelect?.(call)}>
-                <TableCell className="font-medium">{contactName(call)}</TableCell>
+              <TableRow key={call.call_id} className={onSelect ? "cursor-pointer" : undefined} {...(onSelect ? rowActivationProps(() => onSelect(call)) : {})}>
+                <TableCell className="font-medium">{onSelect ? <RecordLink param={linkParam} id={call.call_id} onOpen={() => onSelect(call)}>{contactName(call)}</RecordLink> : contactName(call)}</TableCell>
                 <TableCell>{call.to_phone}</TableCell>
                 <TableCell className="capitalize">{call.is_voicemail ? "voicemail" : normalizeStatus(call.status)}{call.disposition ? ` · ${call.disposition}` : ""}</TableCell>
                 <TableCell className="space-x-1 text-right" onClick={(e) => e.stopPropagation()}>

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

@@ -16,6 +16,7 @@ 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";
 
 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,6 +31,7 @@ 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 [typedUserId, setTypedUserId] = useState("");
@@ -55,7 +57,7 @@ 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 },
@@ -72,7 +74,7 @@ export function SessionStartForm({ userId, userEmail, listId: initialListId = ""
         {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" />
+            <Input id="ds-user" value={typedUserId} onChange={(e) => setTypedUserId(e.target.value)} placeholder={`${brand.linkLabel} user id`} />
           </div>
         )}
         <div className="space-y-1">

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 };
   });
 

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; jobs started this session are listed, any job id can be opened) 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`.

package/blocks/enrichment/block.json

@@ -7,7 +7,8 @@
     "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"
@@ -18,6 +19,8 @@
     "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_contact_fields_fields_get",
     "list_contacts_contacts_get",
@@ -41,9 +44,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 +57,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"
       ],
@@ -97,6 +103,26 @@
         "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": [],
+      "tiers": []
+    },
+    {
+      "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": [
@@ -129,7 +155,7 @@
     {
       "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 +185,7 @@
     }
   ],
   "scopes": [
+    "companies:read",
     "companies:write",
     "contacts:delete",
     "contacts:read",
@@ -199,6 +226,7 @@
     }
   ],
   "peerDependencies": {
+    "lucide-react": ">=0.400.0",
     "react": ">=18"
   }
 }

package/blocks/enrichment/components/bulk-enrich-panel.tsx

@@ -31,9 +31,11 @@ import { useJobPoll } from "@/g8/hooks/use-job-poll";
 import { g8Get, g8Post } from "@/g8/lib/g8-client";
 import { ContactTable } from "@/g8/crm/components/contact-table";
 import { ListPicker } from "@/g8/lists/components/list-picker";
+import { plural } from "@/g8/lib/plural";
 import { useProviders } from "../hooks/use-providers";
 import { CREDITS_PER_RECORD_ESTIMATE, TARGET_FIELDS, estimateCredits, isJobTerminal } from "../lib/enrichment-types";
 import type { EnrichJob, Preflight, TargetField } from "../lib/enrichment-types";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface BulkEnrichPanelProps {
   /** With `listId` and `contactIds` it is just the enrichment panel. Omit them and it is a whole page: pick a list, tick contacts, enrich. */
@@ -44,12 +46,15 @@ export interface BulkEnrichPanelProps {
   defaultField?: TargetField;
   /** Called when the job reached a final state. */
   onDone?: (job: EnrichJob) => void;
+  /** Called with the job id as soon as a run starts (to list it in a job history). */
+  onStarted?: (jobId: string) => void;
   className?: string;
 }
 
 const DEFAULT_PROVIDERS = ["prospeo", "dropcontact"];
 
-function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDERS, defaultField = "work_email", onDone, className }: BulkEnrichPanelProps & { listId: number; contactIds: number[] }) {
+function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDERS, defaultField = "work_email", onDone, onStarted, className }: BulkEnrichPanelProps & { listId: number; contactIds: number[] }) {
+  const brand = useBrand();
   const [field, setField] = useState<TargetField>(defaultField);
   const [chosen, setChosen] = useState<string[] | null>(null);
   const [confirmOpen, setConfirmOpen] = useState(false);
@@ -71,7 +76,7 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
   const runnable = quote ? quote.contact_count - quote.not_in_list.length : ids.length;
 
   const start = useG8Mutation(() => g8Post<{ job_id: string }>("/enrichment/enrich", { contact_ids: ids, list_id: listId, fields_config: { [column.column]: providers } }), {
-    onSuccess: (res) => { setConfirmOpen(false); setJobId(res.data.job_id); },
+    onSuccess: (res) => { setConfirmOpen(false); setJobId(res.data.job_id); onStarted?.(res.data.job_id); },
   });
   const job = useJobPoll<EnrichJob>(
     async (signal) => (await g8Get<EnrichJob>(`/enrichment/jobs/${jobId}`, undefined, { signal })).data,
@@ -128,7 +133,7 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
             {TARGET_FIELDS.map((f) => <option key={f.value} value={f.value}>{f.label}</option>)}
           </select>
         </label>
-        <span className="text-sm text-muted-foreground">for {ids.length.toLocaleString()} contact{ids.length === 1 ? "" : "s"}</span>
+        <span className="text-sm text-muted-foreground">for {plural(ids.length, "contact")}</span>
       </div>
 
       <fieldset className="flex flex-col gap-1">
@@ -154,7 +159,7 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
         <div className="rounded-md border p-3 text-sm" aria-label="Preflight">
           <p><strong>{runnable.toLocaleString()}</strong> of {quote.contact_count.toLocaleString()} contacts will be enriched{quote.not_in_list.length ? `; ${quote.not_in_list.length} are not on this list and are skipped (not charged)` : ""}{quote.duplicates_removed ? `; ${quote.duplicates_removed} duplicates removed` : ""}.</p>
           <p className="mt-1">{quote.max_total_credits != null ? `At most ${quote.max_total_credits.toLocaleString()} credits (${quote.credits_per_record} per record).` : `About ${credits.toLocaleString()} credits (${CREDITS_PER_RECORD_ESTIMATE} per record, the API's flat estimate).`} Records that already have a value or find nothing cost less.</p>
-          {quote.missing_credentials.length ? <p role="alert" className="mt-1 text-amber-700">No API key for {quote.missing_credentials.join(", ")}: those steps are skipped. Add the keys in graph8 settings.</p> : null}
+          {quote.missing_credentials.length ? <p role="alert" className="mt-1 text-amber-700">No API key for {quote.missing_credentials.join(", ")}: those steps are skipped. Add the keys in {brand.linkLabel} settings.</p> : null}
           {quote.warnings.map((w) => <p key={w} className="mt-1 text-xs text-muted-foreground">{w}</p>)}
         </div>
       ) : null}
@@ -162,7 +167,7 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
 
       <div className="flex justify-end">
         <Button disabled={ids.length === 0 || providers.length === 0 || preflight.loading || runnable === 0 || Boolean(preflight.error)} onClick={() => setConfirmOpen(true)}>
-          Enrich {runnable.toLocaleString()} contact{runnable === 1 ? "" : "s"}
+          Enrich {plural(runnable, "contact")}
         </Button>
       </div>
 

package/blocks/enrichment/components/email-verify-badge.tsx

@@ -4,6 +4,12 @@
  * EmailVerifyBadge: a small status chip next to an email address (Unverified, Valid, Risky, Invalid) with
  * a "Verify" action.
  *
+ * The verdict comes from the verifier's own result code (EmailListVerify and friends; the backend's vocabulary is
+ * shared/services/email_verification_classifier.py): `ok`/`valid` is Valid; catch-all codes (`ok_for_all`,
+ * `accept_all`) are Risky; hard failures (`email_disabled`, `invalid_mx`, `dead_server`, `no_mx`, ...) are Invalid, so a
+ * known-bad address is never offered a second paid Verify; `unknown`/`error` (the verifier was inconclusive or the call
+ * failed) is "Couldn't verify", which can be retried.
+ *
  * SDK operations, in order:
  *   1. verifyEmail   POST /enrichment/verify-email { email }   (billable)
  *        Goes through ConfirmSpendDialog first: 1 credit per verification.
@@ -20,7 +26,7 @@ import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { g8Post } from "@/g8/lib/g8-client";
 import { CREDITS_PER_EMAIL_VERIFICATION, isMaskedValue } from "../lib/enrichment-types";
 
-export type VerifyState = "unverified" | "valid" | "risky" | "invalid";
+export type VerifyState = "unverified" | "valid" | "risky" | "invalid" | "unverifiable";
 
 export interface EmailVerifyBadgeProps {
   email?: string | null;
@@ -32,13 +38,26 @@ export interface EmailVerifyBadgeProps {
   className?: string;
 }
 
-/** Collapse the verifier's vocabulary into the four states the chip shows. */
+// The verifier's result codes, normalised to lowercase with "-" (shared/services/email_verification_classifier.py).
+// `error` is EmailListVerify's "delivery failed" and the classifier counts it NOT_VALID, so it is Invalid here; a
+// vendor failure reaches the client as `unknown` (the endpoint catches it and charges nothing). `role-based` and
+// `timeout` are not in the backend vocabulary; they are kept as harmless aliases from other verifiers.
+const VALID = new Set(["valid", "ok", "deliverable", "ultra-sure", "sure"]);
+const RISKY = new Set(["catch-all", "accept-all", "ok-for-all", "role-based"]);
+const INVALID = new Set([
+  "invalid", "fail", "undeliverable", "unlikely", "unsure", "email-disabled", "dead-server", "invalid-mx", "invalid-syntax",
+  "bad-mx", "no-mx", "abuse", "do-not-mail", "spamtrap", "disposable", "bounced", "error",
+]);
+const UNVERIFIABLE = new Set(["unknown", "unverifiable", "smtp-protocol", "antispam-system", "timeout"]);
+
+/** Collapse the verifier's vocabulary into the states the chip shows. */
 export function classifyVerification(status: string | null | undefined, isValid?: boolean): VerifyState {
-  const s = String(status ?? "").toLowerCase().replace(/_/g, "-");
+  const s = String(status ?? "").trim().toLowerCase().replace(/[_\s]+/g, "-");
   if (!s) return "unverified";
-  if (["catch-all", "unknown", "role-based", "accept-all"].includes(s)) return "risky";
-  if (s === "valid") return "valid";
-  if (["invalid", "do-not-mail", "spamtrap", "abuse", "disposable", "bounced"].includes(s)) return "invalid";
+  if (RISKY.has(s)) return "risky";
+  if (VALID.has(s)) return "valid";
+  if (INVALID.has(s)) return "invalid";
+  if (UNVERIFIABLE.has(s)) return "unverifiable";
   return isValid === true ? "valid" : "unverified"; // an unrecognised status is not proof of a bad address
 }
 
@@ -47,8 +66,9 @@ const STYLE: Record<VerifyState, string> = {
   valid: "bg-emerald-100 text-emerald-800",
   risky: "bg-amber-100 text-amber-800",
   invalid: "bg-red-100 text-red-800",
+  unverifiable: "bg-muted text-muted-foreground",
 };
-const LABEL: Record<VerifyState, string> = { unverified: "Unverified", valid: "Valid", risky: "Risky", invalid: "Invalid" };
+const LABEL: Record<VerifyState, string> = { unverified: "Unverified", valid: "Valid", risky: "Risky", invalid: "Invalid", unverifiable: "Couldn't verify" };
 
 export function EmailVerifyBadge({ email, initialStatus, onVerified, readOnly, className }: EmailVerifyBadgeProps) {
   const [confirmOpen, setConfirmOpen] = useState(false);
@@ -72,7 +92,7 @@ export function EmailVerifyBadge({ email, initialStatus, onVerified, readOnly, c
   return (
     <span className={`inline-flex items-center gap-1 ${className ?? ""}`}>
       <span data-state={state} title={detail ?? undefined} className={`rounded-full px-2 py-0.5 text-xs font-medium ${STYLE[state]}`}>{LABEL[state]}</span>
-      {!readOnly && state === "unverified" ? <Button variant="link" size="sm" className="h-auto p-0 text-xs" onClick={() => setConfirmOpen(true)}>Verify</Button> : null}
+      {!readOnly && (state === "unverified" || state === "unverifiable") ? <Button variant="link" size="sm" className="h-auto p-0 text-xs" onClick={() => setConfirmOpen(true)}>{state === "unverifiable" ? "Try again" : "Verify"}</Button> : null}
       {verify.error ? <ApiError error={verify.error} title="Could not verify" /> : null}
       <ConfirmSpendDialog open={confirmOpen} tier="billable" title={`Verify ${email}`} description="Checks whether the address can receive mail."
         estimatedCredits={CREDITS_PER_EMAIL_VERIFICATION} confirmLabel="Verify" confirming={verify.loading}

package/blocks/enrichment/components/enrich-button.tsx

@@ -13,6 +13,11 @@
  *
  * Apply is opt-in per field: fields the record already has are shown unticked so a lookup never silently
  * overwrites good data. A locked ("***") value on the record counts as empty.
+ *
+ * "Already has" is judged on the FULL record. A list row can omit fields the record has, so unless the caller says
+ * `recordLoaded` (it passed the full record from GET /contacts/{id} or /companies/{id}), the button reads the full
+ * record itself right after the lookup (GET /contacts/{id} | /companies/{id}, read). If that read fails nothing is
+ * pre-ticked and the dialog says existing values were not checked. The record id is captured when the lookup runs.
  */
 
 import { useState } from "react";
@@ -20,7 +25,8 @@ import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogH
 import { ApiError } from "@/g8/components/api-error";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
-import { g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
 import { CREDITS_PER_FOUND_LOOKUP, isMaskedValue } from "../lib/enrichment-types";
 
 export interface PersonLookup { email?: string; linkedin_url?: string; first_name?: string; last_name?: string; company_domain?: string }
@@ -32,6 +38,8 @@ export interface EnrichButtonProps {
   lookup: PersonLookup | CompanyLookup;
   /** The CRM record the result can be applied to (its current values decide what is pre-ticked). */
   record?: { id: number } & Record<string, unknown>;
+  /** True when `record` is the full record (not a list row). Default false: the button then reads the full record itself before pre-ticking. */
+  recordLoaded?: boolean;
   label?: string;
   variant?: "default" | "outline" | "secondary" | "ghost";
   size?: "default" | "sm";
@@ -60,25 +68,39 @@ function hasIdentity(kind: EnrichButtonProps["kind"], l: PersonLookup & CompanyL
   return kind === "person" ? Boolean(l.email || l.linkedin_url || (l.first_name && l.last_name && l.company_domain)) : Boolean(l.domain || l.name);
 }
 
-export function EnrichButton({ kind, lookup, record, label, variant = "outline", size = "sm", onResult, onApplied, className }: EnrichButtonProps) {
+export function EnrichButton({ kind, lookup, record, recordLoaded = false, label, variant = "outline", size = "sm", onResult, onApplied, className }: EnrichButtonProps) {
   const [confirmOpen, setConfirmOpen] = useState(false);
   const [result, setResult] = useState<LookupResult | null>(null);
   const [ticked, setTicked] = useState<Set<string>>(new Set());
   const [applied, setApplied] = useState(false);
+  /** What the record held when the lookup ran: its id, its full values, and whether those values could be read. */
+  const [target, setTarget] = useState<{ id: number; existing: Record<string, unknown>; checked: boolean } | null>(null);
   const clean = Object.fromEntries(Object.entries(lookup).filter(([, v]) => typeof v === "string" && v.trim() && !isMaskedValue(v)));
   const ready = hasIdentity(kind, clean);
+  const path = (id: number): string => `/${kind === "person" ? "contacts" : "companies"}/${id}`;
 
-  const run = useG8Mutation(() => g8Post<LookupResult>(`/enrichment/lookup/${kind}`, clean), {
-    onSuccess: (res) => {
+  const run = useG8Mutation(async () => {
+    const res = await g8Post<LookupResult>(`/enrichment/lookup/${kind}`, clean);
+    if (!record) return { res, target: null };
+    if (recordLoaded) return { res, target: { id: record.id, existing: record, checked: true } };
+    try {
+      const full = await g8Get<Record<string, unknown>>(path(record.id));
+      return { res, target: { id: record.id, existing: full.data ?? {}, checked: true } };
+    } catch {
+      return { res, target: { id: record.id, existing: {}, checked: false } };
+    }
+  }, {
+    onSuccess: ({ res, target: t }) => {
       setConfirmOpen(false);
       setResult(res.data);
       setApplied(false);
+      setTarget(t);
       const fields = res.data.data ? normalise(kind, res.data.data) : {};
-      setTicked(new Set(Object.keys(fields).filter((k) => !record || !record[k] || isMaskedValue(record[k]))));
+      setTicked(new Set(t?.checked ? Object.keys(fields).filter((k) => !t.existing[k] || isMaskedValue(t.existing[k])) : []));
       onResult?.(res.data);
     },
   });
-  const apply = useG8Mutation((values: Record<string, string>) => g8Patch(`/${kind === "person" ? "contacts" : "companies"}/${record!.id}`, values), {
+  const apply = useG8Mutation((values: Record<string, string>) => g8Patch(path(target!.id), values), {
     onSuccess: (_r, values) => { setApplied(true); onApplied?.(values); },
   });
 
@@ -114,19 +136,20 @@ export function EnrichButton({ kind, lookup, record, label, variant = "outline",
             <ul className="flex flex-col gap-1 text-sm" aria-label="Found fields">
               {Object.entries(fields).map(([k, v]) => (
                 <li key={k} className="flex items-center gap-2">
-                  {record ? <input type="checkbox" aria-label={`Apply ${k}`} checked={ticked.has(k)} onChange={() => setTicked((t) => { const n = new Set(t); if (!n.delete(k)) n.add(k); return n; })} /> : null}
+                  {target ? <input type="checkbox" aria-label={`Apply ${k}`} checked={ticked.has(k)} onChange={() => setTicked((t) => { const n = new Set(t); if (!n.delete(k)) n.add(k); return n; })} /> : null}
                   <span className="w-36 text-muted-foreground">{k.replace(/_/g, " ")}</span><span className="truncate">{v}</span>
-                  {record && record[k] && !isMaskedValue(record[k]) && record[k] !== v ? <span className="text-xs text-amber-600">replaces {String(record[k])}</span> : null}
+                  {target?.checked && target.existing[k] && !isMaskedValue(target.existing[k]) && target.existing[k] !== v ? <span className="text-xs text-amber-600">replaces {String(target.existing[k])}</span> : null}
                 </li>
               ))}
               {Object.keys(fields).length === 0 ? <li className="text-muted-foreground">The match had no fields to show.</li> : null}
             </ul>
           ) : null}
+          {target && !target.checked && result?.found ? <p role="status" className="text-sm text-muted-foreground">Existing values were not checked, so nothing is ticked. Tick only what you want to write.</p> : null}
           {apply.error ? <ApiError error={apply.error} title="Could not update the record" /> : null}
           {applied ? <p role="status" className="text-sm">Updated the record.</p> : null}
           <DialogFooter>
             <Button variant="ghost" onClick={() => setResult(null)}>Close</Button>
-            {result?.found && record && !applied ? <Button loading={apply.loading} disabled={Object.keys(chosen).length === 0} onClick={() => void apply.mutate(chosen)}>Apply {Object.keys(chosen).length} field{Object.keys(chosen).length === 1 ? "" : "s"}</Button> : null}
+            {result?.found && target && !applied ? <Button loading={apply.loading} disabled={Object.keys(chosen).length === 0} onClick={() => void apply.mutate(chosen)}>Apply {plural(Object.keys(chosen).length, "field")}</Button> : null}
           </DialogFooter>
         </DialogContent>
       </Dialog>