@graph8/sdk 0.308.1 → 0.357.0

package/blocks/enrichment/block.json

@@ -0,0 +1,204 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "enrichment",
+  "title": "Enrichment",
+  "summary": "Look up a person or company, verify emails, enrich many contacts with a credit quote and a polled job, and manage waterfall pipelines.",
+  "features": [
+    "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"
+  ],
+  "dependsOn": [
+    "lists"
+  ],
+  "operations": [
+    "cancel_enrichment_job_enrichment_jobs__job_id__cancel_post",
+    "create_default_waterfall_config_enrichment_waterfall_configs_post",
+    "create_list_lists_post",
+    "delete_contact_contacts__contact_id__delete",
+    "delete_waterfall_config_enrichment_waterfall_configs__column_id__delete",
+    "get_enrichment_job_enrichment_jobs__job_id__get",
+    "list_contact_fields_fields_get",
+    "list_contacts_contacts_get",
+    "list_enrichment_providers_enrichment_providers_get",
+    "list_lists_lists_get",
+    "list_waterfall_configs_enrichment_waterfall_configs_get",
+    "lookup_company_enrichment_lookup_company_post",
+    "lookup_person_enrichment_lookup_person_post",
+    "preflight_enrichment_enrichment_preflight_post",
+    "start_enrichment_enrichment_enrich_post",
+    "update_company_companies__company_id__patch",
+    "update_contact_contacts__contact_id__patch",
+    "verify_email_enrichment_verify_email_post"
+  ],
+  "components": [
+    {
+      "name": "EnrichButton",
+      "file": "components/enrich-button.tsx",
+      "purpose": "Look up one person or company (2 credits only if found, confirmed) and optionally apply the chosen fields to the CRM record.",
+      "operations": [
+        "lookup_person_enrichment_lookup_person_post",
+        "lookup_company_enrichment_lookup_company_post",
+        "update_contact_contacts__contact_id__patch",
+        "update_company_companies__company_id__patch"
+      ],
+      "tiers": [
+        "write",
+        "billable"
+      ]
+    },
+    {
+      "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.",
+      "operations": [
+        "verify_email_enrichment_verify_email_post"
+      ],
+      "tiers": [
+        "billable"
+      ]
+    },
+    {
+      "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).",
+      "operations": [
+        "list_enrichment_providers_enrichment_providers_get",
+        "preflight_enrichment_enrichment_preflight_post",
+        "start_enrichment_enrichment_enrich_post",
+        "get_enrichment_job_enrichment_jobs__job_id__get",
+        "cancel_enrichment_job_enrichment_jobs__job_id__cancel_post",
+        "list_lists_lists_get",
+        "create_list_lists_post",
+        "list_contacts_contacts_get",
+        "list_contact_fields_fields_get",
+        "delete_contact_contacts__contact_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "WaterfallConfig",
+      "file": "components/waterfall-config.tsx",
+      "purpose": "Saved waterfall pipelines of a list plus a form to create one: field, providers, order, credential readiness.",
+      "operations": [
+        "list_waterfall_configs_enrichment_waterfall_configs_get",
+        "list_enrichment_providers_enrichment_providers_get",
+        "create_default_waterfall_config_enrichment_waterfall_configs_post",
+        "delete_waterfall_config_enrichment_waterfall_configs__column_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "destructive"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useProviders",
+      "file": "hooks/use-providers.ts",
+      "purpose": "The enrichment provider catalog: graph8-funded vs own key, credits per action.",
+      "operations": [
+        "list_enrichment_providers_enrichment_providers_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/enrichment-types.ts",
+      "purpose": "Credit prices, field and job vocabularies, preflight/job/pipeline shapes, estimateCredits and isJobTerminal."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/lookup-and-verify.ts",
+      "title": "Look up a person or company and verify an email",
+      "when": "One-off enrichment of a single record. A lookup costs 2 credits ONLY when it finds a match (a miss is free); an email verification costs 1 credit. Both are billable: ask a human before looping over many records (use the bulk job for that). The lookup returns data, it does not update the CRM: write the fields you want with `g8.contacts.update` afterwards."
+    },
+    {
+      "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."
+    },
+    {
+      "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)."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "crm-installed",
+      "where": "app",
+      "description": "The crm block is installed (the CLI does it); enrichment acts on CRM contacts that sit on a list.",
+      "verify": "components/g8/crm/ exists."
+    },
+    {
+      "id": "proxy-allowlist",
+      "where": "app",
+      "description": "allowedPrefixes in the /api/g8 route includes `enrichment` (plus `contacts` and `companies` for Apply).",
+      "verify": "GET /api/g8/enrichment/providers returns 200 when signed in."
+    },
+    {
+      "id": "provider-keys",
+      "where": "api",
+      "description": "For providers that are not graph8-funded, the workspace has its own API key saved in graph8 settings (Integrations). Without it that step is skipped. There is no API to add provider keys.",
+      "verify": "GET /enrichment/providers shows byok_configured true for the provider, or the preflight lists no missing_credentials."
+    },
+    {
+      "id": "credits",
+      "where": "api",
+      "description": "The workspace has credits for graph8-funded providers. The API has no balance read, so the UI shows estimates only; a run without enough credits fails with 402.",
+      "verify": "A one-contact enrichment succeeds."
+    }
+  ],
+  "scopes": [
+    "companies:write",
+    "contacts:delete",
+    "contacts:read",
+    "contacts:write",
+    "enrichment:delete",
+    "enrichment:read",
+    "enrichment:run",
+    "enrichment:write",
+    "fields:read",
+    "lists:read",
+    "lists:write"
+  ],
+  "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",
+      "askHuman": false
+    },
+    {
+      "decision": "Field a bulk run fills",
+      "default": "work email",
+      "askHuman": false
+    },
+    {
+      "decision": "Credit estimate shown before a run",
+      "default": "The preflight's max_total_credits; else 2 credits x contacts on the list",
+      "askHuman": false
+    },
+    {
+      "decision": "Lookup results applied to a record",
+      "default": "Never automatically: the person ticks fields; fields the record already has start unticked",
+      "askHuman": false
+    },
+    {
+      "decision": "Who may spend credits on enrichment",
+      "default": "Anyone the proxy's authorize lets through",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

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

@@ -0,0 +1,205 @@
+"use client";
+
+/**
+ * BulkEnrichPanel: fill a field (work email, direct phone, mobile phone) for many contacts of a list with a
+ * provider waterfall. Shows a free preflight (counts, missing provider keys, warnings, the credit quote),
+ * asks for confirmation with that estimate, starts the job and follows it to the end.
+ *
+ * SDK operations, in order:
+ *   1. listEnrichmentProviders  GET  /enrichment/providers            (read)    provider choices, graph8-funded vs own key
+ *   2. preflightEnrichment      POST /enrichment/preflight            (read, free; nothing is written or charged)
+ *        { list_id, contact_ids, mode: "waterfall", providers, target_field }  -> contact_count, not_in_list,
+ *        missing_credentials, warnings, credits_per_record, max_total_credits
+ *   3. startEnrichment          POST /enrichment/enrich               (billable)  202 { job_id, status }
+ *        Goes through ConfirmSpendDialog first with `max_total_credits` (or 2 credits x contacts when the
+ *        preflight could not price it). There is no balance read, so this is an estimate of the most it can charge.
+ *   4. getEnrichmentJob         GET  /enrichment/jobs/{job_id}        (read)    polled with useJobPoll (no streams), backoff;
+ *        read once more with ?include_provider_errors=true when nothing was enriched or some records failed.
+ *   5. cancelEnrichmentJob      POST /enrichment/jobs/{job_id}/cancel (write, free; records already done keep their data and charge)
+ *
+ * The contacts must be on `listId`; ids not on it are skipped and not charged. Locked contacts are enriched
+ * like any other once they sit in a list.
+ */
+
+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 { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+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 { 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";
+
+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. */
+  listId?: number;
+  contactIds?: number[];
+  /** Providers tried, in order, when the person has not chosen. Default: prospeo, dropcontact (the API's own default). */
+  defaultProviders?: string[];
+  defaultField?: TargetField;
+  /** Called when the job reached a final state. */
+  onDone?: (job: EnrichJob) => 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[] }) {
+  const [field, setField] = useState<TargetField>(defaultField);
+  const [chosen, setChosen] = useState<string[] | null>(null);
+  const [confirmOpen, setConfirmOpen] = useState(false);
+  const [jobId, setJobId] = useState<string | null>(null);
+  const catalog = useProviders();
+
+  const known = new Set(catalog.providers.map((p) => p.provider));
+  const providers = chosen ?? defaultProviders.filter((p) => known.size === 0 || known.has(p));
+  const column = TARGET_FIELDS.find((f) => f.value === field)!;
+  const ids = [...new Set(contactIds)];
+
+  const preflight = useG8Query(
+    async (signal) => (await g8Post<Preflight>("/enrichment/preflight", { list_id: listId, contact_ids: ids, mode: "waterfall", providers, target_field: column.target }, { signal })).data,
+    [listId, ids.join(","), providers.join(","), field],
+    { enabled: ids.length > 0 && !jobId },
+  );
+  const quote = preflight.data;
+  const credits = estimateCredits(quote, ids.length);
+  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); },
+  });
+  const job = useJobPoll<EnrichJob>(
+    async (signal) => (await g8Get<EnrichJob>(`/enrichment/jobs/${jobId}`, undefined, { signal })).data,
+    { enabled: jobId != null, intervalMs: 2000, isTerminal: (j) => isJobTerminal(j.status), onDone: (j) => onDone?.(j) },
+  );
+  const cancel = useG8Mutation(() => g8Post(`/enrichment/jobs/${jobId}/cancel`, {}));
+  const finished = job.status;
+  const nothingWritten = job.done && ((finished?.successful_enrichments ?? 0) === 0 || (finished?.failed_enrichments ?? 0) > 0);
+  const errors = useG8Query(
+    async (signal) => (await g8Get<EnrichJob>(`/enrichment/jobs/${jobId}`, { include_provider_errors: true }, { signal })).data.provider_errors ?? [],
+    [jobId, job.done],
+    { enabled: job.done && nothingWritten },
+  );
+
+  const toggleProvider = (name: string) => setChosen(providers.includes(name) ? providers.filter((p) => p !== name) : [...providers, name]);
+  const move = (name: string, delta: number) => {
+    const i = providers.indexOf(name), j = i + delta;
+    if (i < 0 || j < 0 || j >= providers.length) return;
+    const next = [...providers];
+    [next[i], next[j]] = [next[j], next[i]];
+    setChosen(next);
+  };
+
+  if (jobId) {
+    const j = job.status;
+    const total = j?.total ?? runnable;
+    const pct = total ? Math.round(((j?.completed ?? 0) / total) * 100) : 0;
+    return (
+      <div className={`flex flex-col gap-3 ${className ?? ""}`} role="status">
+        <h3 className="text-base font-semibold">{job.done ? (j?.status === "completed" ? "Enrichment finished" : `Enrichment ${j?.status}`) : "Enriching..."}</h3>
+        <div className="h-2 overflow-hidden rounded bg-muted" aria-label="Progress"><div className="h-full bg-primary transition-all" style={{ width: `${job.done ? 100 : pct}%` }} /></div>
+        <p className="text-sm">{j?.completed ?? 0} of {total} contacts processed{j?.successful_enrichments != null ? `, ${j.successful_enrichments} enriched, ${j.failed_enrichments ?? 0} failed` : ""}.{j?.total_credits_used != null ? ` ${j.total_credits_used} credits used.` : ""}</p>
+        {j?.warnings?.map((w) => <p key={w} className="text-xs text-muted-foreground">{w}</p>)}
+        {job.error ? <ApiError error={job.error} title="Could not read the job" onRetry={() => job.start()} /> : null}
+        {errors.data?.length ? (
+          <ul className="text-xs text-destructive" aria-label="Provider errors">
+            {errors.data.slice(0, 5).map((e, i) => <li key={i}>{e.provider}: {e.error}</li>)}
+          </ul>
+        ) : null}
+        {cancel.error ? <ApiError error={cancel.error} title="Could not cancel" /> : null}
+        <div className="flex gap-2">
+          {!job.done ? <Button variant="outline" size="sm" loading={cancel.loading} onClick={() => void cancel.mutate(undefined)}>Cancel</Button> : null}
+          {job.done ? <Button size="sm" variant="outline" onClick={() => { setJobId(null); job.stop(); }}>Enrich more</Button> : null}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center gap-3">
+        <label className="flex items-center gap-2 text-sm">Fill
+          <select aria-label="Field to fill" className="h-9 rounded-md border bg-background px-2" value={field} onChange={(e) => setField(e.target.value as TargetField)}>
+            {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>
+      </div>
+
+      <fieldset className="flex flex-col gap-1">
+        <legend className="mb-1 text-sm font-medium">Providers, tried in this order</legend>
+        {catalog.error ? <ApiError error={catalog.error} title="Could not load providers" onRetry={() => void catalog.refetch()} /> : null}
+        {providers.map((p, i) => (
+          <div key={p} className="flex items-center gap-2 text-sm">
+            <span className="w-6 text-muted-foreground">{i + 1}.</span><span className="w-32 font-medium">{p}</span>
+            <Button variant="ghost" size="sm" aria-label={`Move ${p} up`} disabled={i === 0} onClick={() => move(p, -1)}>Up</Button>
+            <Button variant="ghost" size="sm" aria-label={`Move ${p} down`} disabled={i === providers.length - 1} onClick={() => move(p, 1)}>Down</Button>
+            <Button variant="ghost" size="sm" aria-label={`Remove ${p}`} onClick={() => toggleProvider(p)}>Remove</Button>
+          </div>
+        ))}
+        <div className="flex flex-wrap gap-1">
+          {catalog.providers.filter((p) => !providers.includes(p.provider)).map((p) => (
+            <Button key={p.provider} variant="outline" size="sm" onClick={() => toggleProvider(p.provider)}>Add {p.provider}{p.byok_configured ? " (your key)" : p.system_funded ? "" : " (needs a key)"}</Button>
+          ))}
+        </div>
+      </fieldset>
+
+      {preflight.error ? <ApiError error={preflight.error} title="The check failed" onRetry={() => void preflight.refetch()} /> : null}
+      {quote ? (
+        <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.warnings.map((w) => <p key={w} className="mt-1 text-xs text-muted-foreground">{w}</p>)}
+        </div>
+      ) : null}
+      {start.error ? <ApiError error={start.error} title="Could not start the enrichment" /> : null}
+
+      <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"}
+        </Button>
+      </div>
+
+      <ConfirmSpendDialog
+        open={confirmOpen}
+        tier="billable"
+        title={`Enrich ${runnable.toLocaleString()} contacts: ${column.label.toLowerCase()}`}
+        description={`Providers in order: ${providers.join(", ")}. The estimate is the most this run can charge; your balance is not checked here.`}
+        estimatedCredits={credits}
+        affected={runnable}
+        confirmLabel="Start enrichment"
+        confirming={start.loading}
+        onConfirm={() => void start.mutate(undefined)}
+        onCancel={() => setConfirmOpen(false)}
+      />
+    </div>
+  );
+}
+
+/**
+ * Enrich the contacts of a list. Give it `listId` and `contactIds` (for example from a ContactTable selection), or
+ * mount it with no props as a page: choose a list, tick the contacts to enrich, then run.
+ */
+export function BulkEnrichPanel(props: BulkEnrichPanelProps) {
+  const [listId, setListId] = useState<number | undefined>(undefined);
+  const [picked, setPicked] = useState<number[]>([]);
+  if (props.listId != null && props.contactIds) return <BulkEnrichCore {...props} listId={props.listId} contactIds={props.contactIds} />;
+  const { listId: _l, contactIds: _c, ...rest } = props;
+  return (
+    <div className={`flex flex-col gap-4 ${props.className ?? ""}`}>
+      <ListPicker value={listId} allowCreate={false} onChange={(l) => { setListId(l.id); setPicked([]); }} />
+      {listId != null ? (
+        <>
+          <ContactTable listId={listId} selectable pageSize={10} onSelectionChange={(ids) => setPicked(ids)} />
+          <BulkEnrichCore {...rest} className={undefined} listId={listId} contactIds={picked} />
+        </>
+      ) : <p className="text-sm text-muted-foreground">Choose a list to enrich its contacts.</p>}
+    </div>
+  );
+}

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

@@ -0,0 +1,82 @@
+"use client";
+
+/**
+ * EmailVerifyBadge: a small status chip next to an email address (Unverified, Valid, Risky, Invalid) with
+ * a "Verify" action.
+ *
+ * SDK operations, in order:
+ *   1. verifyEmail   POST /enrichment/verify-email { email }   (billable)
+ *        Goes through ConfirmSpendDialog first: 1 credit per verification.
+ *
+ * A locked ("***") or missing email renders "Locked" / nothing and cannot be verified: the placeholder is
+ * never sent to the API. Reveal the contact first (save it to a list or enrich 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 { 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 interface EmailVerifyBadgeProps {
+  email?: string | null;
+  /** A status you already know (for example from the contact's meta), so the badge starts verified. */
+  initialStatus?: string | null;
+  onVerified?: (result: { email: string; status: string; is_valid: boolean }) => void;
+  /** Hide the Verify button and only show the chip. */
+  readOnly?: boolean;
+  className?: string;
+}
+
+/** Collapse the verifier's vocabulary into the four states the chip shows. */
+export function classifyVerification(status: string | null | undefined, isValid?: boolean): VerifyState {
+  const s = String(status ?? "").toLowerCase().replace(/_/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";
+  return isValid === true ? "valid" : "unverified"; // an unrecognised status is not proof of a bad address
+}
+
+const STYLE: Record<VerifyState, string> = {
+  unverified: "bg-muted text-muted-foreground",
+  valid: "bg-emerald-100 text-emerald-800",
+  risky: "bg-amber-100 text-amber-800",
+  invalid: "bg-red-100 text-red-800",
+};
+const LABEL: Record<VerifyState, string> = { unverified: "Unverified", valid: "Valid", risky: "Risky", invalid: "Invalid" };
+
+export function EmailVerifyBadge({ email, initialStatus, onVerified, readOnly, className }: EmailVerifyBadgeProps) {
+  const [confirmOpen, setConfirmOpen] = useState(false);
+  // The verdict belongs to one address: keyed by email, so reusing the badge for another contact starts clean.
+  const [verdict, setVerdict] = useState<{ email: string; state: VerifyState; detail: string | null } | null>(null);
+  const mine = verdict && verdict.email === email ? verdict : null;
+  const state = mine?.state ?? classifyVerification(initialStatus);
+  const detail = mine?.detail ?? null;
+
+  const verify = useG8Mutation(() => g8Post<{ email: string; status: string; sub_status?: string | null; is_valid: boolean }>("/enrichment/verify-email", { email }), {
+    onSuccess: (res) => {
+      setConfirmOpen(false);
+      setVerdict({ email: res.data.email ?? String(email), state: classifyVerification(res.data.status, res.data.is_valid), detail: [res.data.status, res.data.sub_status].filter(Boolean).join(": ") });
+      onVerified?.(res.data);
+    },
+  });
+
+  if (!email) return null;
+  if (isMaskedValue(email)) return <span className={`inline-flex rounded-full px-2 py-0.5 text-xs italic ${STYLE.unverified} ${className ?? ""}`} title="Locked: save to a list or enrich to reveal">Locked</span>;
+
+  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}
+      {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}
+        onConfirm={() => void verify.mutate(undefined)} onCancel={() => setConfirmOpen(false)} />
+    </span>
+  );
+}

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

@@ -0,0 +1,136 @@
+"use client";
+
+/**
+ * EnrichButton: look up ONE person or company and (optionally) copy the result onto a CRM record.
+ * Drop it into ContactDetail's `renderActions` or a company page.
+ *
+ * SDK operations, in order:
+ *   1. lookupPerson | lookupCompany   POST /enrichment/lookup/person | /enrichment/lookup/company   (billable)
+ *        Goes through ConfirmSpendDialog first: 2 credits, charged ONLY when a match is found (a miss is free).
+ *        Person: email, or linkedin_url, or first_name + last_name + company_domain. Company: domain or name.
+ *   2. updateContact | updateCompany  PATCH /contacts/{id} | /companies/{id}   (write)   only when the person
+ *        clicks "Apply" and only for the fields they ticked; nothing is written automatically.
+ *
+ * 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.
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "@graph8/sdk/ui";
+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 { 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 }
+export interface CompanyLookup { domain?: string; name?: string }
+interface LookupResult { found: boolean; confidence: number; data: Record<string, unknown> | null }
+
+export interface EnrichButtonProps {
+  kind: "person" | "company";
+  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>;
+  label?: string;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+  onResult?: (result: LookupResult) => void;
+  /** Called after the chosen fields were written to the record. */
+  onApplied?: (applied: Record<string, string>) => void;
+  className?: string;
+}
+
+const APPLY_KEYS: Record<EnrichButtonProps["kind"], string[]> = {
+  person: ["first_name", "last_name", "work_email", "direct_phone", "mobile_phone", "job_title", "job_department", "seniority_level", "linkedin_url", "city", "state", "country"],
+  company: ["name", "website", "phone", "industry", "employee_count", "linkedin_url", "city", "state", "country"],
+};
+
+/** Lookup keys come back lowercased from the index; company ones may carry a `company_` prefix. */
+function normalise(kind: EnrichButtonProps["kind"], data: Record<string, unknown>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(data)) {
+    const key = kind === "company" ? k.replace(/^company_/, "") : k;
+    if (APPLY_KEYS[kind].includes(key) && v != null && String(v).trim() !== "" && !isMaskedValue(v)) out[key] = String(v);
+  }
+  return out;
+}
+
+function hasIdentity(kind: EnrichButtonProps["kind"], l: PersonLookup & CompanyLookup): boolean {
+  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) {
+  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);
+  const clean = Object.fromEntries(Object.entries(lookup).filter(([, v]) => typeof v === "string" && v.trim() && !isMaskedValue(v)));
+  const ready = hasIdentity(kind, clean);
+
+  const run = useG8Mutation(() => g8Post<LookupResult>(`/enrichment/lookup/${kind}`, clean), {
+    onSuccess: (res) => {
+      setConfirmOpen(false);
+      setResult(res.data);
+      setApplied(false);
+      const fields = res.data.data ? normalise(kind, res.data.data) : {};
+      setTicked(new Set(Object.keys(fields).filter((k) => !record || !record[k] || isMaskedValue(record[k]))));
+      onResult?.(res.data);
+    },
+  });
+  const apply = useG8Mutation((values: Record<string, string>) => g8Patch(`/${kind === "person" ? "contacts" : "companies"}/${record!.id}`, values), {
+    onSuccess: (_r, values) => { setApplied(true); onApplied?.(values); },
+  });
+
+  const fields = result?.data ? normalise(kind, result.data) : {};
+  const chosen = Object.fromEntries(Object.entries(fields).filter(([k]) => ticked.has(k)));
+  const noun = kind === "person" ? "person" : "company";
+
+  return (
+    <>
+      <Button className={className} variant={variant} size={size} disabled={!ready} title={ready ? undefined : `Needs ${kind === "person" ? "an email, a LinkedIn URL, or a name plus company domain" : "a domain or a name"}`} onClick={() => setConfirmOpen(true)}>
+        {label ?? `Enrich ${noun}`}
+      </Button>
+
+      <ConfirmSpendDialog
+        open={confirmOpen}
+        tier="billable"
+        title={`Look up this ${noun}`}
+        description={`Charged only if a match is found. A lookup that finds nothing costs nothing.`}
+        estimatedCredits={CREDITS_PER_FOUND_LOOKUP}
+        confirmLabel="Look up"
+        confirming={run.loading}
+        onConfirm={() => void run.mutate(undefined)}
+        onCancel={() => setConfirmOpen(false)}
+      />
+
+      <Dialog open={result != null} onOpenChange={(o) => !o && (setResult(null), run.reset(), apply.reset())}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>{result?.found ? `Found this ${noun}` : "No match found"}</DialogTitle>
+            <DialogDescription>{result?.found ? `Confidence ${Math.round((result.confidence ?? 0) * 100)}%. About ${CREDITS_PER_FOUND_LOOKUP} credits were used (current pricing).` : "Nothing was charged."}</DialogDescription>
+          </DialogHeader>
+          {result?.found ? (
+            <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}
+                  <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}
+                </li>
+              ))}
+              {Object.keys(fields).length === 0 ? <li className="text-muted-foreground">The match had no fields to show.</li> : null}
+            </ul>
+          ) : 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}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      {run.error ? <ApiError error={run.error} title="Lookup failed" /> : null}
+    </>
+  );
+}