@graph8/sdk 0.373.0 → 0.374.0

package/blocks/enrichment/block.json

@@ -8,7 +8,10 @@
     "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",
-    "finished EnrichmentScreen page"
+    "finished EnrichmentScreen page",
+    "list pipelines: templates, build, edit, price (free estimate), run behind a confirm, watch, stop, on/off, delete, run history",
+    "automatic enrichment of a list's new records and the workspace-wide switch and merge rule, each confirmed with the real billing effect",
+    "pause and resume a running enrichment job; enrichment activity analytics (totals, success rate, trends, fields filled)"
   ],
   "dependsOn": [
     "lists",
@@ -16,27 +19,53 @@
   ],
   "operations": [
     "cancel_enrichment_job_enrichment_jobs__job_id__cancel_post",
+    "cancel_list_pipeline_run_enrichment_lists__list_id__pipelines__pipeline_id__cancel_post",
+    "create_auto_enrichment_config_enrichment_auto_enrichment_configs_post",
     "create_default_waterfall_config_enrichment_waterfall_configs_post",
     "create_list_lists_post",
+    "create_list_pipeline_enrichment_lists__list_id__pipelines_post",
+    "create_list_pipeline_from_template_enrichment_lists__list_id__pipelines_from_template_post",
+    "delete_auto_enrichment_config_enrichment_auto_enrichment_configs__config_id__delete",
     "delete_contact_contacts__contact_id__delete",
+    "delete_list_pipeline_enrichment_lists__list_id__pipelines__pipeline_id__delete",
     "delete_waterfall_config_enrichment_waterfall_configs__column_id__delete",
+    "estimate_list_pipeline_enrichment_lists__list_id__pipelines__pipeline_id__estimate_post",
+    "get_auto_enrichment_config_enrichment_auto_enrichment_configs__config_id__get",
+    "get_auto_enrichment_settings_enrichment_auto_enrichment_settings_get",
     "get_company_companies__company_id__get",
     "get_contact_contacts__contact_id__get",
+    "get_enrichment_daily_activity_enrichment_analytics_daily_activity_get",
+    "get_enrichment_field_distribution_enrichment_analytics_field_distribution_get",
     "get_enrichment_job_enrichment_jobs__job_id__get",
+    "get_enrichment_metrics_enrichment_analytics_metrics_get",
+    "get_enrichment_trends_enrichment_analytics_trends_get",
+    "get_pipeline_run_enrichment_lists_pipeline_runs__run_id__get",
     "list_active_enrichment_jobs_enrichment_active_jobs_get",
+    "list_auto_enrichment_configs_enrichment_auto_enrichment_configs_get",
     "list_companies_companies_get",
     "list_contact_fields_fields_get",
     "list_contacts_contacts_get",
     "list_enrichment_providers_enrichment_providers_get",
+    "list_list_pipeline_runs_enrichment_lists__list_id__pipelines__pipeline_id__runs_get",
+    "list_list_pipelines_enrichment_lists__list_id__pipelines_get",
     "list_lists_lists_get",
+    "list_pipeline_step_options_enrichment_lists__list_id__pipeline_step_options_get",
+    "list_pipeline_templates_enrichment_lists_pipeline_templates_get",
     "list_waterfall_configs_enrichment_waterfall_configs_get",
     "lookup_company_enrichment_lookup_company_post",
     "lookup_person_enrichment_lookup_person_post",
+    "pause_enrichment_job_enrichment_jobs__job_id__pause_post",
     "preflight_enrichment_enrichment_preflight_post",
+    "resume_enrichment_job_enrichment_jobs__job_id__resume_post",
+    "run_list_pipeline_enrichment_lists__list_id__pipelines__pipeline_id__runs_post",
     "run_waterfall_pipeline_enrichment_waterfall_enrich_post",
+    "set_pipeline_enabled_enrichment_lists__list_id__pipelines__pipeline_id__enabled_post",
     "start_enrichment_enrichment_enrich_post",
+    "update_auto_enrichment_config_enrichment_auto_enrichment_configs__config_id__patch",
+    "update_auto_enrichment_settings_enrichment_auto_enrichment_settings__entity_type__put",
     "update_company_companies__company_id__patch",
     "update_contact_contacts__contact_id__patch",
+    "update_list_pipeline_enrichment_lists__list_id__pipelines__pipeline_id__put",
     "verify_email_enrichment_verify_email_post"
   ],
   "components": [
@@ -113,7 +142,7 @@
     {
       "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.",
+      "purpose": "Finished enrichment page: enrich a list, one-off lookups and email verification, pipelines, list pipelines, auto-enrichment, jobs, activity and the provider catalog.",
       "operations": [
         "list_contacts_contacts_get",
         "list_companies_companies_get",
@@ -126,15 +155,122 @@
     {
       "name": "EnrichmentJobDetail",
       "file": "components/enrichment-job-detail.tsx",
-      "purpose": "One bulk enrichment job: live progress, counts, credits, warnings, provider errors and cancel.",
+      "purpose": "One bulk enrichment job: live progress, counts, credits, warnings, provider errors, cancel, pause and resume (resume is confirmed).",
       "operations": [
         "cancel_enrichment_job_enrichment_jobs__job_id__cancel_post",
-        "get_enrichment_job_enrichment_jobs__job_id__get"
+        "get_enrichment_job_enrichment_jobs__job_id__get",
+        "pause_enrichment_job_enrichment_jobs__job_id__pause_post",
+        "resume_enrichment_job_enrichment_jobs__job_id__resume_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable"
+      ]
+    },
+    {
+      "name": "ListPipelines",
+      "file": "components/list-pipelines.tsx",
+      "purpose": "The pipelines of one list with the open one beside them: templates, new pipeline, open to price, run, watch, stop, edit and delete. The open pipeline is in the URL (?lp=).",
+      "operations": [
+        "list_list_pipelines_enrichment_lists__list_id__pipelines_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "PipelineDetail",
+      "file": "components/pipeline-detail.tsx",
+      "purpose": "One list pipeline: price the run for this exact list (free estimate), run it behind a confirm showing that price, poll the run with per-step progress, stop it, turn it on or off, delete it, read its run history.",
+      "operations": [
+        "estimate_list_pipeline_enrichment_lists__list_id__pipelines__pipeline_id__estimate_post",
+        "run_list_pipeline_enrichment_lists__list_id__pipelines__pipeline_id__runs_post",
+        "get_pipeline_run_enrichment_lists_pipeline_runs__run_id__get",
+        "cancel_list_pipeline_run_enrichment_lists__list_id__pipelines__pipeline_id__cancel_post",
+        "list_list_pipeline_runs_enrichment_lists__list_id__pipelines__pipeline_id__runs_get",
+        "set_pipeline_enabled_enrichment_lists__list_id__pipelines__pipeline_id__enabled_post",
+        "delete_list_pipeline_enrichment_lists__list_id__pipelines__pipeline_id__delete",
+        "list_pipeline_step_options_enrichment_lists__list_id__pipeline_step_options_get"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "PipelineEditor",
+      "file": "components/pipeline-editor.tsx",
+      "purpose": "Create or edit a list pipeline in a side sheet: pick steps from the configs the list can use, order them, turn steps off, fill-only-empty and skip-recent options. Saving never runs it.",
+      "operations": [
+        "list_pipeline_step_options_enrichment_lists__list_id__pipeline_step_options_get",
+        "create_list_pipeline_enrichment_lists__list_id__pipelines_post",
+        "update_list_pipeline_enrichment_lists__list_id__pipelines__pipeline_id__put"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "PipelineTemplates",
+      "file": "components/pipeline-templates.tsx",
+      "purpose": "Pick a ready-made pipeline for the list; saved turned off. Adding one the list already has resets it (confirmed).",
+      "operations": [
+        "list_pipeline_templates_enrichment_lists_pipeline_templates_get",
+        "create_list_pipeline_from_template_enrichment_lists__list_id__pipelines_from_template_post"
       ],
       "tiers": [
         "read",
         "write"
       ]
+    },
+    {
+      "name": "AutoEnrichmentConfigs",
+      "file": "components/auto-enrichment-configs.tsx",
+      "purpose": "What a list enriches by itself as records are added: list, add, turn on or off, delete. Every change is confirmed and states that it spends credits with nobody confirming each record.",
+      "operations": [
+        "list_auto_enrichment_configs_enrichment_auto_enrichment_configs_get",
+        "get_auto_enrichment_config_enrichment_auto_enrichment_configs__config_id__get",
+        "create_auto_enrichment_config_enrichment_auto_enrichment_configs_post",
+        "update_auto_enrichment_config_enrichment_auto_enrichment_configs__config_id__patch",
+        "delete_auto_enrichment_config_enrichment_auto_enrichment_configs__config_id__delete",
+        "list_pipeline_step_options_enrichment_lists__list_id__pipeline_step_options_get"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "AutoEnrichmentSettings",
+      "file": "components/auto-enrichment-settings.tsx",
+      "purpose": "Workspace-wide automatic enrichment for contacts and companies: on or off and the merge rule (keep edits, never overwrite, matched data wins). Per-field overrides are kept.",
+      "operations": [
+        "get_auto_enrichment_settings_enrichment_auto_enrichment_settings_get",
+        "update_auto_enrichment_settings_enrichment_auto_enrichment_settings__entity_type__put"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "EnrichmentActivity",
+      "file": "components/enrichment-activity.tsx",
+      "purpose": "Free analytics for a chosen window: records enriched, success rate, results over time, daily activity and the fields filled.",
+      "operations": [
+        "get_enrichment_metrics_enrichment_analytics_metrics_get",
+        "get_enrichment_trends_enrichment_analytics_trends_get",
+        "get_enrichment_daily_activity_enrichment_analytics_daily_activity_get",
+        "get_enrichment_field_distribution_enrichment_analytics_field_distribution_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [
@@ -151,6 +287,10 @@
     {
       "file": "lib/enrichment-types.ts",
       "purpose": "Credit prices, field and job vocabularies, preflight/job/pipeline shapes, estimateCredits and isJobTerminal."
+    },
+    {
+      "file": "lib/pipeline-types.ts",
+      "purpose": "List pipeline, run, estimate, template, auto-enrichment and analytics shapes plus pure helpers (step builders, ordering, change detection, percent)."
     }
   ],
   "recipes": [
@@ -192,7 +332,7 @@
     {
       "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.",
+      "description": "The workspace has credits for graph8-funded providers. There is no standalone balance read; a pipeline's price estimate returns available_credits beside the quote, and a run without enough credits fails with 402.",
       "verify": "A one-contact enrichment succeeds."
     }
   ],

package/blocks/enrichment/components/auto-enrichment-configs.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+/**
+ * AutoEnrichmentConfigs: the enrichments a list runs by itself. Each one enriches every record that is ADDED to the
+ * list from then on, with a provider waterfall or an AI group, and charges for it with nobody confirming each record.
+ *
+ * SDK operations, in order:
+ *   1. listAutoEnrichmentConfigs   GET    /enrichment/auto-enrichment/configs?audience_id   (read, free)  -> { configs[], total }
+ *   2. listPipelineStepOptions     GET    /enrichment/lists/{list_id}/pipeline-step-options  (read, free)  names the column each config uses
+ *        (and is exactly the set the API accepts for a new config: active, and global or available on this list)
+ *   3. getAutoEnrichmentConfig     GET    /enrichment/auto-enrichment/configs/{config_id}    (read, free)  loaded before Turn off or Delete is offered
+ *   4. createAutoEnrichmentConfig  POST   /enrichment/auto-enrichment/configs { audience_id, enrichment_type, column_id, trigger_on_insert }
+ *        (billable, ConfirmSpendDialog)
+ *   5. updateAutoEnrichmentConfig  PATCH  /enrichment/auto-enrichment/configs/{config_id} { trigger_on_insert }   (billable tier, ConfirmSpendDialog)
+ *   6. deleteAutoEnrichmentConfig  DELETE /enrichment/auto-enrichment/configs/{config_id}                          (destructive, ConfirmSpendDialog)
+ *
+ * What the confirm says is what the backend does: the trigger is an INSERT trigger. Records already on the list are
+ * not enriched when a config is created, and edits to a record do not re-run it. No per-record price is published for
+ * this call, so the confirm states that instead of showing a number.
+ */
+
+import { useState } from "react";
+import { Button, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useConfirmAction } from "@/g8/components/confirmed-action";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { itemsOf } from "../lib/pipeline-types";
+import type { AutoConfig, StepOption } from "../lib/pipeline-types";
+
+export interface AutoEnrichmentConfigsProps {
+  listId: number;
+  className?: string;
+}
+
+const day = (iso?: string | null) => (iso ? new Date(iso).toLocaleDateString(undefined, { dateStyle: "medium" }) : "");
+const ONGOING = "From now on, every record added to this list is enriched automatically and charged, with nobody confirming each one. Records already on the list are not touched, and editing a record does not run it again. The API publishes no per-record price for this, so no total is shown: check the provider costs on the Providers tab.";
+
+function ConfigRow({ config, label, onChanged }: { config: AutoConfig; label: string; onChanged: () => void }) {
+  const [open, setOpen] = useState(false);
+  const { ask, dialog, failure } = useConfirmAction();
+  const detail = useG8Query(async (signal) => (await g8Get<AutoConfig>(`/enrichment/auto-enrichment/configs/${config.id}`, undefined, { signal })).data, [config.id], { enabled: open });
+  const fresh = detail.data;
+  const toggle = (next: boolean) => ask({
+    tier: "billable",
+    title: `${next ? "Turn on" : "Turn off"} automatic enrichment with ${label}`,
+    confirmLabel: next ? "Turn on" : "Turn off",
+    description: next ? ONGOING : "New records added to this list will no longer be enriched with this. Records already enriched keep their values.",
+    run: () => g8Patch(`/enrichment/auto-enrichment/configs/${config.id}`, { trigger_on_insert: next }),
+    onDone: () => { void detail.refetch(); onChanged(); },
+  });
+  const remove = () => ask({
+    tier: "destructive",
+    title: `Delete automatic enrichment with ${label}`,
+    description: "New records will no longer be enriched with this. Values already written stay on the records.",
+    affected: 1,
+    tolerateStatus: [404],
+    run: () => g8Delete(`/enrichment/auto-enrichment/configs/${config.id}`),
+    onDone: onChanged,
+  });
+  return (
+    <li className="flex flex-col gap-2 px-4 py-3" data-testid="auto-config">
+      <div className="flex items-center justify-between gap-3">
+        <button type="button" className="min-w-0 text-left" aria-expanded={open} onClick={() => setOpen(!open)}>
+          <span className="block truncate text-sm font-medium">{label}</span>
+          <span className="block text-xs text-muted-foreground">{config.enrichment_type === "ai" ? "AI group" : "Provider waterfall"}</span>
+        </button>
+        <StatusPill tone={config.trigger_on_insert ? "positive" : "neutral"} dot>{config.trigger_on_insert ? "Enriching new records" : "Off"}</StatusPill>
+      </div>
+      {open ? (
+        <div className="flex flex-col gap-2 rounded-md border p-3">
+          {detail.error ? <ApiError error={detail.error} title="Could not load this setting" onRetry={() => void detail.refetch()} /> : null}
+          {detail.loading && !fresh ? <p className="text-sm text-muted-foreground">Loading...</p> : null}
+          {fresh ? <p className="text-xs text-muted-foreground">Added {day(fresh.created_at) || "on an unknown date"}. Applies to records added to the list; it does not re-run on edits.</p> : null}
+          <div className="flex gap-2">
+            <Button size="sm" variant="outline" disabled={!fresh} onClick={() => fresh && toggle(!fresh.trigger_on_insert)}>{fresh?.trigger_on_insert === false ? "Turn on" : "Turn off"}</Button>
+            <Button size="sm" variant="ghost" disabled={!fresh} onClick={remove}>Delete</Button>
+          </div>
+          {failure ? <ApiError error={failure} title="That did not go through" /> : null}
+        </div>
+      ) : null}
+      <ConfirmSpendDialog {...dialog} />
+    </li>
+  );
+}
+
+export function AutoEnrichmentConfigs({ listId, className }: AutoEnrichmentConfigsProps) {
+  const [pick, setPick] = useState("");
+  const [confirming, setConfirming] = useState(false);
+  const configs = useG8Query(async (signal) => itemsOf<AutoConfig>((await g8Get("/enrichment/auto-enrichment/configs", { audience_id: listId }, { signal })).data, "configs"), [listId]);
+  const options = useG8Query(async (signal) => itemsOf<StepOption>((await g8Get(`/enrichment/lists/${listId}/pipeline-step-options`, undefined, { signal })).data), [listId], { key: ["enrichment", "step-options", listId], staleTime: 30_000 });
+  const rows = configs.data ?? [];
+  const menu = options.data ?? [];
+  const labelOf = (c: AutoConfig) => menu.find((o) => o.config_ref === c.column_id && o.type === c.enrichment_type)?.name ?? "A column that is no longer available";
+  const free = menu.filter((o) => !rows.some((c) => c.column_id === o.config_ref && c.enrichment_type === o.type));
+  const chosen = free.find((o) => `${o.type}:${o.config_ref}` === pick);
+  const create = useG8Mutation(
+    async () => (await g8Post<AutoConfig>("/enrichment/auto-enrichment/configs", { audience_id: listId, enrichment_type: chosen?.type, column_id: chosen?.config_ref, trigger_on_insert: true })).data,
+    { onSuccess: () => { setConfirming(false); setPick(""); void configs.refetch(); }, onError: () => setConfirming(false) },
+  );
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <SectionCard title="Automatic enrichment for this list" description="Enrich every new record as it arrives. This spends credits without asking each time." flush>
+        {configs.error ? <div className="p-3"><ApiError error={configs.error} title="Could not load automatic enrichment" onRetry={() => void configs.refetch()} /></div> : null}
+        {!configs.error && configs.loading && !configs.data ? <p className="p-4 text-sm text-muted-foreground">Loading...</p> : null}
+        {!configs.error && configs.data && rows.length === 0 ? <EmptyState title="Nothing runs automatically" description="Pick a column below and new records on this list will be enriched as they are added." /> : null}
+        <ul className="divide-y">{(configs.error ? [] : rows).map((c) => <ConfigRow key={c.id} config={c} label={labelOf(c)} onChanged={() => void configs.refetch()} />)}</ul>
+      </SectionCard>
+
+      <SectionCard title="Add automatic enrichment" description="Choose what to run on each new record.">
+        <div className="flex flex-col gap-3">
+          {options.error ? <ApiError error={options.error} title="Could not load the columns you can use" onRetry={() => void options.refetch()} /> : null}
+          <div className="flex flex-col gap-1">
+            <Label htmlFor="ae-pick">Run on every new record</Label>
+            <select id="ae-pick" className="h-9 rounded-md border bg-background px-2 text-sm" value={pick} disabled={options.loading} onChange={(e) => setPick(e.target.value)}>
+              <option value="">{options.loading ? "Loading..." : free.length ? "Choose a column" : "Nothing left to add"}</option>
+              {free.map((o) => <option key={`${o.type}:${o.config_ref}`} value={`${o.type}:${o.config_ref}`}>{o.name}</option>)}
+            </select>
+          </div>
+          {create.error ? <ApiError error={create.error} title="Could not turn it on" /> : null}
+          <div><Button disabled={!chosen} onClick={() => setConfirming(true)}>Turn on for new records</Button></div>
+        </div>
+      </SectionCard>
+      <ConfirmSpendDialog open={confirming} tier="billable" title={`Enrich new records automatically with ${chosen?.name ?? "this column"}`} description={ONGOING}
+        confirmLabel="Turn on" confirming={create.loading} onConfirm={() => void create.mutate(undefined)} onCancel={() => setConfirming(false)} />
+    </div>
+  );
+}

package/blocks/enrichment/components/auto-enrichment-settings.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+/**
+ * AutoEnrichmentSettings: the workspace-wide switch and merge rule for automatic enrichment, one card for contacts and
+ * one for companies. The rule decides who wins when enriched data disagrees with what is on a record.
+ *
+ * SDK operations, in order:
+ *   1. getAutoEnrichmentSettings     GET /enrichment/auto-enrichment/settings                 (read, free)  -> { contact, company } each
+ *        { enabled, default_rule: sticky | user_wins | mashup_wins, per_field_overrides }
+ *   2. updateAutoEnrichmentSettings  PUT /enrichment/auto-enrichment/settings/{entity_type}   (billable, ConfirmSpendDialog)
+ *        sends enabled + default_rule + the per-field overrides it loaded, so saving one never wipes the others. The API
+ *        defaults `enabled` to true, so it is always sent explicitly.
+ *
+ * Save is disabled until the settings have loaded and while nothing changed. The confirm states the real effect (what
+ * the rule does, from the merge handler) and that graph8 grades turning this on as a billable change; the API publishes
+ * no price for it, so none is shown. Needs the settings permission: a 403 is shown as such, not as an empty card.
+ */
+
+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 { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Put } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import { MERGE_RULES, MERGE_RULE_COPY } from "../lib/pipeline-types";
+import type { AutoSettings, MergeRule } from "../lib/pipeline-types";
+
+const KINDS = [{ id: "contact", label: "Contacts" }, { id: "company", label: "Companies" }] as const;
+
+function KindCard({ settings, label, onSaved }: { settings: AutoSettings; label: string; onSaved: () => void }) {
+  const brand = useBrand();
+  const [enabled, setEnabled] = useState(settings.enabled);
+  const [rule, setRule] = useState<MergeRule>(settings.default_rule);
+  const [confirming, setConfirming] = useState(false);
+  const overrides = Object.keys(settings.per_field_overrides ?? {}).length;
+  const save = useG8Mutation(
+    () => g8Put(`/enrichment/auto-enrichment/settings/${settings.entity_type}`, { enabled, default_rule: rule, per_field_overrides: settings.per_field_overrides ?? {} }),
+    { onSuccess: () => { setConfirming(false); onSaved(); }, onError: () => setConfirming(false) },
+  );
+  const changed = enabled !== settings.enabled || rule !== settings.default_rule;
+  return (
+    <SectionCard title={label} actions={<StatusPill tone={settings.enabled ? "positive" : "neutral"} dot>{settings.enabled ? "On" : "Off"}</StatusPill>}>
+      <div className="flex flex-col gap-3">
+        <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={enabled} onChange={(e) => setEnabled(e.target.checked)} /> Enrich {label.toLowerCase()} automatically</label>
+        <fieldset className="flex flex-col gap-2" aria-label={`${label} merge rule`}>
+          <legend className="text-sm font-medium">When enriched data differs from the record</legend>
+          {MERGE_RULES.map((r) => (
+            <label key={r} className="flex items-start gap-2 text-sm">
+              <input type="radio" name={`rule-${settings.entity_type}`} className="mt-1" checked={rule === r} onChange={() => setRule(r)} />
+              <span><span className="font-medium">{MERGE_RULE_COPY[r].label}</span><span className="block text-xs text-muted-foreground">{MERGE_RULE_COPY[r].help}</span></span>
+            </label>
+          ))}
+        </fieldset>
+        {overrides ? <p className="text-xs text-muted-foreground">{plural(overrides, "field")} follow their own rule. Saving keeps them as they are.</p> : null}
+        {save.error ? <ApiError error={save.error} title={`Could not save ${label.toLowerCase()} settings`} /> : null}
+        <div><Button disabled={!changed} onClick={() => setConfirming(true)}>Save {label.toLowerCase()} settings</Button></div>
+      </div>
+      <ConfirmSpendDialog open={confirming} tier="billable" title={`Save ${label.toLowerCase()} settings`}
+        description={`${enabled ? `Automatic enrichment of ${label.toLowerCase()} will be ON` : `Automatic enrichment of ${label.toLowerCase()} will be OFF`}, with the rule "${MERGE_RULE_COPY[rule].label}": ${MERGE_RULE_COPY[rule].help} ${brand.linkLabel} treats turning this on as a billable change and publishes no price for it, so no total is shown.`}
+        confirmLabel="Save" confirming={save.loading} onConfirm={() => void save.mutate(undefined)} onCancel={() => setConfirming(false)} />
+    </SectionCard>
+  );
+}
+
+export function AutoEnrichmentSettings({ className }: { className?: string }) {
+  const q = useG8Query(async (signal) => (await g8Get<Partial<Record<"contact" | "company", AutoSettings>>>("/enrichment/auto-enrichment/settings", undefined, { signal })).data, []);
+  if (q.error) return <ApiError error={q.error} title="Could not load the workspace settings" onRetry={() => void q.refetch()} />;
+  if (!q.data) return <p className="text-sm text-muted-foreground">Loading settings...</p>;
+  return (
+    <div className={`grid gap-4 lg:grid-cols-2 ${className ?? ""}`}>
+      {KINDS.map((k) => {
+        const s = q.data?.[k.id];
+        return s ? <KindCard key={`${k.id}-${s.enabled}-${s.default_rule}`} settings={{ ...s, entity_type: k.id }} label={k.label} onSaved={() => void q.refetch()} /> : null;
+      })}
+    </div>
+  );
+}

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

@@ -12,8 +12,8 @@
  *   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
- *   After ConfirmSpendDialog (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):
+ *   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.
@@ -44,7 +44,7 @@ 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, FIELD_PROVIDERS, TARGET_FIELDS, estimateCredits, isJobTerminal, providersForField } 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";
 
@@ -99,7 +99,7 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders, defaultField = "
     { 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(async (): Promise<StartedRun> => {
@@ -204,7 +204,7 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders, defaultField = "
       {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>
+          <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>
@@ -221,8 +221,8 @@ function BulkEnrichCore({ listId, contactIds, defaultProviders, defaultField = "
         open={confirmOpen}
         tier="billable"
         title={`Enrich ${runnable.toLocaleString()} contacts: ${column.label.toLowerCase()}`}
-        description={`Providers in order: ${runProviders.join(", ")}${existing ? ` (the list's saved ${column.label.toLowerCase()} pipeline)` : ""}. 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}

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