@graph8/sdk 0.370.0 → 0.374.0

package/blocks/enrichment/block.json

@@ -8,31 +8,64 @@
     "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"
+    "lists",
+    "pickers"
   ],
   "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": [
@@ -68,11 +101,13 @@
     {
       "name": "BulkEnrichPanel",
       "file": "components/bulk-enrich-panel.tsx",
-      "purpose": "Fill a field for many contacts of a list: free preflight, credit estimate in ConfirmSpendDialog, start the job, poll it with useJobPoll, cancel. With no props it is a whole page (pick a list, tick contacts).",
+      "purpose": "Fill a field for many contacts of a list: free preflight, credit estimate in ConfirmSpendDialog, create or reuse the field's pipeline and run it, poll it with useJobPoll, cancel. With no props it is a whole page (pick a list, tick contacts).",
       "operations": [
         "list_enrichment_providers_enrichment_providers_get",
+        "list_waterfall_configs_enrichment_waterfall_configs_get",
         "preflight_enrichment_enrichment_preflight_post",
-        "start_enrichment_enrichment_enrich_post",
+        "create_default_waterfall_config_enrichment_waterfall_configs_post",
+        "run_waterfall_pipeline_enrichment_waterfall_enrich_post",
         "get_enrichment_job_enrichment_jobs__job_id__get",
         "cancel_enrichment_job_enrichment_jobs__job_id__cancel_post",
         "list_lists_lists_get",
@@ -107,22 +142,135 @@
     {
       "name": "EnrichmentScreen",
       "file": "components/enrichment-screen.tsx",
-      "purpose": "Finished enrichment page: enrich a list, one-off lookups and email verification, pipelines and the provider catalog.",
-      "operations": [],
-      "tiers": []
+      "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",
+        "list_active_enrichment_jobs_enrichment_active_jobs_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     },
     {
       "name": "EnrichmentJobDetail",
       "file": "components/enrichment-job-detail.tsx",
-      "purpose": "One bulk enrichment job: live progress, counts, credits, warnings, provider errors and cancel.",
+      "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": [
@@ -139,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": [
@@ -150,7 +302,7 @@
     {
       "file": "recipes/bulk-enrich-and-poll.ts",
       "title": "Enrich many contacts of a list and wait for the job",
-      "when": "Filling work emails or phones for a list. Order: preflight (free: counts, missing provider keys and the credit quote) -> a human approves the quote -> start the job -> poll it (the API has no streams or webhook for completion) -> read provider errors if nothing was written. Contact ids must be on the list; ids not on it are skipped and not charged. Never enrich contacts you only have as masked search results: save them to a list first."
+      "when": "Filling work emails or phones for a list. Order: preflight (free: counts, missing provider keys and the credit quote) -> a human approves the quote -> create or reuse the field's pipeline and run it -> poll it (the API has no streams or webhook for completion) -> read provider errors if nothing was written. Contact ids must be on the list; ids not on it are skipped and not charged. Never enrich contacts you only have as masked search results: save them to a list first."
     },
     {
       "file": "recipes/waterfall-pipeline.ts",
@@ -180,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."
     }
   ],
@@ -201,7 +353,7 @@
   "defaults": [
     {
       "decision": "Providers a bulk run tries",
-      "default": "prospeo then dropcontact (the API's own default), filtered to those in the provider catalog; editable in the panel",
+      "default": "The API's own per field (work email: prospeo then dropcontact; phones: leadmagic, prospeo, apollo), kept to providers in the catalog that the field supports; editable in the panel. A list that already has a pipeline for the field runs with that pipeline's providers",
       "askHuman": false
     },
     {

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