@graph8/sdk 0.370.0 → 0.374.0

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

@@ -7,21 +7,31 @@
  *
  * SDK operations, in order:
  *   1. listEnrichmentProviders  GET  /enrichment/providers            (read)    provider choices, graph8-funded vs own key
+ *   1b. listWaterfallConfigs    GET  /enrichment/waterfall/configs?list_id (read)  the list's own pipeline for the field, if any:
+ *        a run reuses it with ITS providers, so the quote and the confirm are priced with those, not the chosen ones.
  *   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;
+ *   After ConfirmSpendDialog (with `max_total_credits`; when the preflight could not price the run the confirm shows NO total
+ *   and says so, never a guess; there is no balance read, so a quote is the most it can charge):
+ *   3. createDefaultWaterfallConfig POST /enrichment/waterfall/configs { list_id, name, field, providers }  (billable tier, free)
+ *        Creates the list's pipeline for that field, or reuses the one it already has (`created: false`; it then runs
+ *        with ITS providers). The column_id is kept, so a retry after step 4 failed does not create it again.
+ *   4. runWaterfallPipeline     POST /enrichment/waterfall/enrich { column_id, list_id, record_ids }  (billable) 202 { job_id, status }
+ *        A 202 whose status is "error" (or a 502) means the job never started: shown as a failure, never polled.
+ *   5. 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)
+ *   6. cancelEnrichmentJob      POST /enrichment/jobs/{job_id}/cancel (write, free; records already done keep their data and charge)
+ *
+ * When the job ends, every cached `contacts` query is refreshed (and the page mode's ContactTable reloads) so the
+ * filled values show. The panel does not use POST /enrichment/enrich (startEnrichment): before the API fix of
+ * 2026-10-16 that route dispatched the field name instead of a pipeline and silently enriched nothing.
  *
  * 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 { useRef, useState } from "react";
 import { Button } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
@@ -29,19 +39,23 @@ 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 { g8QueryCache } from "@/g8/lib/g8-cache";
 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 { FIELD_PROVIDERS, TARGET_FIELDS, isJobTerminal, providersForField, quotedCredits } from "../lib/enrichment-types";
+import type { EnrichJob, Preflight, TargetField, WaterfallConfigSummary, WaterfallPipelineResult } 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. */
   listId?: number;
   contactIds?: number[];
-  /** Providers tried, in order, when the person has not chosen. Default: prospeo, dropcontact (the API's own default). */
+  /**
+   * Providers tried, in order, when the person has not chosen. Kept to the providers the field supports. Default: the
+   * API's own per field (work email: prospeo, dropcontact; phones: leadmagic, prospeo, apollo).
+   */
   defaultProviders?: string[];
   defaultField?: TargetField;
   /** Called when the job reached a final state. */
@@ -51,37 +65,64 @@ export interface BulkEnrichPanelProps {
   className?: string;
 }
 
-const DEFAULT_PROVIDERS = ["prospeo", "dropcontact"];
+type StartedRun = { job: EnrichJob; pipeline: WaterfallPipelineResult; asked: string[] };
 
-function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDERS, defaultField = "work_email", onDone, onStarted, className }: BulkEnrichPanelProps & { listId: number; contactIds: number[] }) {
+function BulkEnrichCore({ listId, contactIds, defaultProviders, 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);
   const [jobId, setJobId] = useState<string | null>(null);
+  const [run, setRun] = useState<StartedRun | null>(null);
+  // The pipeline step 3 created or reused, kept per list/field/providers so a retry does not create it twice.
+  const pipelineRef = useRef<{ key: string; pipeline: WaterfallPipelineResult } | 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 providers = chosen ?? providersForField(field, defaultProviders).filter((p) => known.size === 0 || known.has(p));
+  const offered = catalog.providers.filter((p) => FIELD_PROVIDERS[field].includes(p.provider) && !providers.includes(p.provider));
   const column = TARGET_FIELDS.find((f) => f.value === field)!;
   const ids = [...new Set(contactIds)];
 
+  // The list's own pipeline for this field wins over the chosen providers (the API reuses it), so price that one.
+  const saved = useG8Query(
+    async (signal) => (await g8Get<{ configs: WaterfallConfigSummary[] }>("/enrichment/waterfall/configs", { list_id: listId }, { signal })).data.configs ?? [],
+    [listId],
+    { enabled: !jobId },
+  );
+  const existing = saved.data?.find((c) => c.field_to_enrich === column.target && c.providers.length > 0) ?? null;
+  const runProviders = existing ? existing.providers : providers;
+
   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],
+    async (signal) => (await g8Post<Preflight>("/enrichment/preflight", { list_id: listId, contact_ids: ids, mode: "waterfall", providers: runProviders, target_field: column.target }, { signal })).data,
+    [listId, ids.join(","), runProviders.join(","), field],
     { enabled: ids.length > 0 && !jobId },
   );
   const quote = preflight.data;
-  const credits = estimateCredits(quote, ids.length);
+  const credits = quotedCredits(quote); // null: the API could not price this run, so no total is shown
   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); onStarted?.(res.data.job_id); },
+  const start = useG8Mutation(async (): Promise<StartedRun> => {
+    const key = `${listId}|${column.target}|${providers.join(",")}`;
+    let pipeline = pipelineRef.current?.key === key ? pipelineRef.current.pipeline : null;
+    if (!pipeline) {
+      pipeline = (await g8Post<WaterfallPipelineResult>("/enrichment/waterfall/configs", { list_id: listId, name: `${column.label} enrichment`, field: column.target, providers })).data;
+      pipelineRef.current = { key, pipeline };
+    }
+    const job = (await g8Post<EnrichJob>("/enrichment/waterfall/enrich", { column_id: pipeline.column_id, list_id: listId, record_ids: ids })).data;
+    if (!job?.job_id || String(job.status).toLowerCase() === "error") throw new Error("The enrichment did not start, so nothing was charged. Try again in a minute.");
+    return { job, pipeline, asked: providers };
+  }, {
+    onSuccess: (res) => { setConfirmOpen(false); setRun(res); setJobId(res.job.job_id); onStarted?.(res.job.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) },
+    {
+      enabled: jobId != null, intervalMs: 2000, isTerminal: (j) => isJobTerminal(j.status),
+      onDone: (j) => { void g8QueryCache.invalidate(["contacts"]); onDone?.(j); },
+    },
   );
+  const reused = run && !run.pipeline.created && run.pipeline.providers?.length && run.pipeline.providers.join() !== run.asked.join() ? run.pipeline.providers : null;
   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);
@@ -106,9 +147,10 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
     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>
+        <h3 className="text-base font-medium">{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>
+        {reused ? <p className="text-xs text-muted-foreground">This list already had a {column.label.toLowerCase()} pipeline, so it ran with its providers: {reused.join(" > ")}.</p> : null}
         {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 ? (
@@ -119,7 +161,7 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
         {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}
+          {job.done ? <Button size="sm" variant="outline" onClick={() => { setJobId(null); setRun(null); job.stop(); }}>Enrich more</Button> : null}
         </div>
       </div>
     );
@@ -129,7 +171,7 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
     <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)}>
+          <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); setChosen(null); }}>
             {TARGET_FIELDS.map((f) => <option key={f.value} value={f.value}>{f.label}</option>)}
           </select>
         </label>
@@ -139,7 +181,11 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
       <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) => (
+        {existing ? (
+          <p className="text-sm text-muted-foreground" data-testid="saved-pipeline">
+            This list already has a {column.label.toLowerCase()} pipeline (&quot;{existing.name}&quot;), so a run uses its providers: {existing.providers.join(" > ")}. Delete it under Pipelines to choose others.
+          </p>
+        ) : 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>
@@ -148,7 +194,7 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
           </div>
         ))}
         <div className="flex flex-wrap gap-1">
-          {catalog.providers.filter((p) => !providers.includes(p.provider)).map((p) => (
+          {(existing ? [] : offered).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>
@@ -158,15 +204,15 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
       {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 {brand.linkLabel} settings.</p> : null}
+          <p className="mt-1">{quote.max_total_credits != null ? `At most ${quote.max_total_credits.toLocaleString()} credits (${quote.credits_per_record} per record). Records that already have a value or find nothing cost less.` : `The API could not price this run, so no total is shown. Providers on ${brand.linkLabel}'s key spend credits per record; providers on your own key cost none.`}</p>
+          {quote.missing_credentials.length ? <p role="alert" className="mt-1 text-warning-foreground">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}
       {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)}>
+        <Button disabled={ids.length === 0 || runProviders.length === 0 || preflight.loading || runnable === 0 || Boolean(preflight.error)} onClick={() => setConfirmOpen(true)}>
           Enrich {plural(runnable, "contact")}
         </Button>
       </div>
@@ -175,8 +221,8 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
         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}
+        description={`Providers in order: ${runProviders.join(", ")}${existing ? ` (the list's saved ${column.label.toLowerCase()} pipeline)` : ""}. ${credits != null ? "The estimate is the most this run can charge; your balance is not checked here." : "The API could not price this run, so no total is shown; your balance is not checked here."}`}
+        estimatedCredits={credits ?? undefined}
         affected={runnable}
         confirmLabel="Start enrichment"
         confirming={start.loading}
@@ -194,15 +240,18 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders = DEFAULT_PROVIDE
 export function BulkEnrichPanel(props: BulkEnrichPanelProps) {
   const [listId, setListId] = useState<number | undefined>(undefined);
   const [picked, setPicked] = useState<number[]>([]);
+  const [tableVersion, setTableVersion] = useState(0);
   if (props.listId != null && props.contactIds) return <BulkEnrichCore {...props} listId={props.listId} contactIds={props.contactIds} />;
   const { listId: _l, contactIds: _c, ...rest } = props;
+  // A finished run reloads the table so the filled values show (this also clears the ticked contacts).
+  const done = (job: EnrichJob) => { setTableVersion((v) => v + 1); props.onDone?.(job); };
   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} />
+          <ContactTable listId={listId} selectable pageSize={10} refreshKey={tableVersion} onSelectionChange={(ids) => setPicked(ids)} />
+          <BulkEnrichCore {...rest} className={undefined} listId={listId} contactIds={picked} onDone={done} />
         </>
       ) : <p className="text-sm text-muted-foreground">Choose a list to enrich its contacts.</p>}
     </div>

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

@@ -63,9 +63,9 @@ export function classifyVerification(status: string | null | undefined, isValid?
 
 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",
+  valid: "bg-positive text-positive-foreground",
+  risky: "bg-warning text-warning-foreground",
+  invalid: "bg-error text-error-foreground",
   unverifiable: "bg-muted text-muted-foreground",
 };
 const LABEL: Record<VerifyState, string> = { unverified: "Unverified", valid: "Valid", risky: "Risky", invalid: "Invalid", unverifiable: "Couldn't verify" };

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

@@ -138,7 +138,7 @@ export function EnrichButton({ kind, lookup, record, recordLoaded = false, label
                 <li key={k} className="flex items-center gap-2">
                   {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>
-                  {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}
+                  {target?.checked && target.existing[k] && !isMaskedValue(target.existing[k]) && target.existing[k] !== v ? <span className="text-xs text-warning-foreground">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}

package/blocks/enrichment/components/enrichment-activity.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+/**
+ * EnrichmentActivity: how much enrichment ran, how often it worked, and which fields it filled, for a chosen window.
+ * All four reads are free.
+ *
+ * SDK operations (all read, free):
+ *   1. getEnrichmentMetrics        GET /enrichment/analytics/metrics?period            -> { total_enrichments, success_rate (a percent, 0 to 100) }
+ *   2. getEnrichmentTrends         GET /enrichment/analytics/trends?period&granularity -> { data_points[{ date, successful_enrichments, failed_enrichments }] }
+ *   3. getEnrichmentDailyActivity  GET /enrichment/analytics/daily-activity?period      -> { activity_points[{ date, enrichments, new_contacts }] }
+ *   4. getEnrichmentFieldDistribution GET /enrichment/analytics/field-distribution?period -> { field_types[{ field_type, count, percentage }], total_enrichments }
+ *
+ * The API counts COMPLETED jobs only (running, paused and failed jobs are not in these numbers), says so here, and the
+ * cost it returns is the API's own estimate at a fixed rate rather than credits charged, so no cost is shown.
+ * Every panel clears its numbers while a new window loads and when a read fails; a rate with nothing behind it shows
+ * a dash, never 0%.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { BarList } from "@/g8/components/screen/bar-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { TimeSeriesChart } from "@/g8/components/screen/time-series-chart";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { GRANULARITIES, PERIODS } from "../lib/pipeline-types";
+import type { Granularity, Period } from "../lib/pipeline-types";
+
+interface Metrics { total_enrichments: number; success_rate: number }
+interface Trend { data_points: Array<{ date: string; total_enrichments: number; successful_enrichments: number; failed_enrichments: number }> }
+interface Daily { activity_points: Array<{ date: string; enrichments: number; new_contacts: number }> }
+interface Distribution { field_types: Array<{ field_type: string; count: number; percentage: number }>; total_enrichments: number }
+
+const SELECT = "h-9 rounded-md border bg-background px-2 text-sm";
+const humanField = (t: string) => t.replace(/[_-]+/g, " ").replace(/^./, (c) => c.toUpperCase());
+
+function Panel({ title, description, q, empty, children }: { title: string; description?: string; q: { error: unknown; loading: boolean; refetch: () => Promise<unknown> }; empty: boolean; children: ReactNode }) {
+  return (
+    <SectionCard title={title} description={description}>
+      {q.error ? <ApiError error={q.error} title={`Could not load ${title.toLowerCase()}`} onRetry={() => void q.refetch()} /> : null}
+      {!q.error && q.loading ? <p className="text-sm text-muted-foreground" role="status">Loading...</p> : null}
+      {!q.error && !q.loading && empty ? <EmptyState title="Nothing in this window" description="No completed enrichment jobs fall in these dates." /> : null}
+      {!q.error && !q.loading && !empty ? children : null}
+    </SectionCard>
+  );
+}
+
+export function EnrichmentActivity({ className }: { className?: string }) {
+  const [period, setPeriod] = useState<Period>("last_30_days");
+  const [granularity, setGranularity] = useState<Granularity>("day");
+  const metrics = useG8Query(async (signal) => (await g8Get<Metrics>("/enrichment/analytics/metrics", { period }, { signal })).data, [period]);
+  const trends = useG8Query(async (signal) => (await g8Get<Trend>("/enrichment/analytics/trends", { period, granularity }, { signal })).data, [period, granularity]);
+  const daily = useG8Query(async (signal) => (await g8Get<Daily>("/enrichment/analytics/daily-activity", { period }, { signal })).data, [period]);
+  const fields = useG8Query(async (signal) => (await g8Get<Distribution>("/enrichment/analytics/field-distribution", { period }, { signal })).data, [period]);
+
+  const m = metrics.error || metrics.loading ? undefined : metrics.data;
+  const points = trends.error || trends.loading ? [] : trends.data?.data_points ?? [];
+  const days = daily.error || daily.loading ? [] : daily.data?.activity_points ?? [];
+  const kinds = fields.error || fields.loading ? [] : fields.data?.field_types ?? [];
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-end gap-3">
+        <label className="flex flex-col gap-1 text-sm">Window
+          <select className={SELECT} value={period} onChange={(e) => setPeriod(e.target.value as Period)}>{PERIODS.map((p) => <option key={p.value} value={p.value}>{p.label}</option>)}</select>
+        </label>
+        <label className="flex flex-col gap-1 text-sm">Group trends by
+          <select className={SELECT} value={granularity} onChange={(e) => setGranularity(e.target.value as Granularity)}>{GRANULARITIES.map((g) => <option key={g} value={g}>{g === "day" ? "Day" : g === "week" ? "Week" : "Month"}</option>)}</select>
+        </label>
+        <p className="pb-2 text-xs text-muted-foreground">Counts completed jobs only. Running, paused and failed jobs are not included.</p>
+      </div>
+      <StatStrip loading={metrics.loading} items={[
+        { label: "Records enriched", value: m ? m.total_enrichments.toLocaleString() : "-" },
+        { label: "Success rate", value: m && m.total_enrichments > 0 ? `${Math.round(m.success_rate)}%` : "-", hint: "Share of records the providers found a value for." },
+      ]} />
+      {metrics.error ? <ApiError error={metrics.error} title="Could not load the totals" onRetry={() => void metrics.refetch()} /> : null}
+      <div className="grid gap-4 lg:grid-cols-2">
+        <Panel title="Results over time" description="Records enriched and failed in each period." q={trends} empty={points.length === 0}>
+          <TimeSeriesChart kind="bar" stacked xKey="date" data={points} series={[{ key: "successful_enrichments", label: "Enriched", tone: "positive" }, { key: "failed_enrichments", label: "Failed", tone: "negative" }]} />
+        </Panel>
+        <Panel title="Daily activity" description="Records enriched and new contacts each day." q={daily} empty={days.length === 0}>
+          <TimeSeriesChart kind="line" xKey="date" data={days} series={[{ key: "enrichments", label: "Enriched" }, { key: "new_contacts", label: "New contacts", tone: "prior" }]} />
+        </Panel>
+      </div>
+      <Panel title="Fields filled" description="Which fields enrichment filled in this window." q={fields} empty={kinds.length === 0}>
+        <BarList items={kinds.map((k) => ({ label: humanField(k.field_type), value: k.count, display: `${k.count.toLocaleString()} (${Math.round(k.percentage)}%)` }))} />
+      </Panel>
+    </div>
+  );
+}

package/blocks/enrichment/components/enrichment-job-detail.tsx

@@ -10,10 +10,15 @@
  *        read once more with ?include_provider_errors=true when nothing was enriched or some records failed
  *        -> { status, total, completed, successful_enrichments, failed_enrichments, total_credits_used, warnings, provider_errors }
  *   2. cancelEnrichmentJob  POST /enrichment/jobs/{job_id}/cancel   (write, free; records already done keep their data and charge)
+ *   3. pauseEnrichmentJob   POST /enrichment/jobs/{job_id}/pause    (write, free; stops further charges until resumed)
+ *   4. resumeEnrichmentJob  POST /enrichment/jobs/{job_id}/resume   (billable, ConfirmSpendDialog; carries on with, and charges for, the records not yet reached)
+ * The state shown is always the server's: after Pause or Resume the job is read again, never assumed.
  */
 
+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 { KeyValueList } from "@/g8/components/screen/key-value-list";
 import { SectionCard } from "@/g8/components/screen/section-card";
 import { StatusPill, humanizeStatus, toneForStatus } from "@/g8/components/screen/status-pill";
@@ -37,6 +42,9 @@ export function EnrichmentJobDetail({ jobId, onDone, className }: EnrichmentJobD
     { intervalMs: 2000, isTerminal: (j) => isJobTerminal(j.status), onDone },
   );
   const cancel = useG8Mutation(() => g8Post(`/enrichment/jobs/${jobId}/cancel`, {}));
+  const [resuming, setResuming] = useState(false);
+  const pause = useG8Mutation(() => g8Post(`/enrichment/jobs/${jobId}/pause`, {}), { onSuccess: () => job.start() });
+  const resume = useG8Mutation(() => g8Post(`/enrichment/jobs/${jobId}/resume`, {}), { onSuccess: () => { setResuming(false); job.start(); }, onError: () => setResuming(false) });
   const j = job.status;
   const problems = job.done && j != null && ((j.successful_enrichments ?? 0) === 0 || (j.failed_enrichments ?? 0) > 0);
   const errors = useG8Query(
@@ -45,6 +53,8 @@ export function EnrichmentJobDetail({ jobId, onDone, className }: EnrichmentJobD
     { enabled: problems },
   );
   const total = j?.total ?? 0;
+  const state = String(j?.status ?? "").toLowerCase();
+  const remaining = Math.max(0, total - (j?.completed ?? 0));
   const pct = total ? Math.min(100, Math.round(((j?.completed ?? 0) / total) * 100)) : 0;
 
   if (job.error && !j) return <ApiError error={job.error} title="Could not read the job" onRetry={() => job.start()} />;
@@ -52,10 +62,15 @@ export function EnrichmentJobDetail({ jobId, onDone, className }: EnrichmentJobD
     <div className={`flex flex-col gap-4 ${className ?? ""}`} role="status">
       <div className="flex items-center gap-2">
         {j ? <StatusPill tone={toneForStatus(j.status)} dot>{humanizeStatus(j.status)}</StatusPill> : <span className="text-sm text-muted-foreground">Loading...</span>}
+        {!job.done && state === "paused" ? <Button size="sm" onClick={() => setResuming(true)}>Resume job</Button> : null}
+        {!job.done && (state === "running" || state === "pending") ? <Button size="sm" variant="outline" loading={pause.loading} onClick={() => void pause.mutate(undefined)}>Pause job</Button> : null}
         {!job.done && j ? <Button size="sm" variant="outline" loading={cancel.loading} onClick={() => void cancel.mutate(undefined)}>Cancel job</Button> : null}
       </div>
       <div className="h-2 overflow-hidden rounded bg-muted" aria-label="Progress"><div className="h-full bg-primary" style={{ width: `${job.done ? 100 : pct}%` }} /></div>
+      {j?.paused_at && state === "paused" ? <p className="text-sm text-muted-foreground">Paused {new Date(j.paused_at).toLocaleString()}. Nothing more is enriched or charged until you resume.</p> : null}
       {cancel.error ? <ApiError error={cancel.error} title="Could not cancel" /> : null}
+      {pause.error ? <ApiError error={pause.error} title="Could not pause" /> : null}
+      {resume.error ? <ApiError error={resume.error} title="Could not resume" /> : null}
       <SectionCard title="Result">
         <KeyValueList columns={2} items={[
           { label: "Job id", value: jobId, mono: true, wide: true },
@@ -73,6 +88,9 @@ export function EnrichmentJobDetail({ jobId, onDone, className }: EnrichmentJobD
           </ul>
         </SectionCard>
       ) : null}
+      <ConfirmSpendDialog open={resuming} tier="billable" title="Resume this job" affected={remaining}
+        description="The job carries on with the records it had not reached and charges for them as it goes. Records already enriched are not charged again. The API does not quote a total for a resume, so no credit figure is shown."
+        confirmLabel="Resume" confirming={resume.loading} onConfirm={() => void resume.mutate(undefined)} onCancel={() => setResuming(false)} />
     </div>
   );
 }