@graph8/sdk 0.373.0 → 0.374.0

package/blocks/email-signatures/lib/signatures-types.ts

@@ -0,0 +1,392 @@
+"use client";
+
+/**
+ * Types, vocabularies and pure helpers for the email-signatures block.
+ *
+ * The vocabularies (block kinds, layouts, fonts, brand sources, policy modes, campaign statuses, source choices) are the
+ * contract's exact enums (signatures/domain/models.py), so a body built from them is accepted live. Read payloads stay
+ * open-shaped: a stored template or policy can carry keys a current strict model would reject, so every field is optional
+ * and a missing value is shown as unknown, never guessed.
+ * SDK operations: none.
+ */
+
+export const FONTS = ["Arial", "Verdana", "Georgia", "Tahoma"] as const;
+export type SignatureFont = (typeof FONTS)[number];
+
+export const LAYOUTS = [
+  { value: "classic-stacked", label: "Classic, stacked" },
+  { value: "photo-left", label: "Photo on the left" },
+  { value: "logo-left", label: "Logo on the left" },
+  { value: "two-column", label: "Two columns" },
+  { value: "compact-inline", label: "Compact, one line" },
+  { value: "banner-hero", label: "Banner on top" },
+] as const;
+export type SignatureLayout = (typeof LAYOUTS)[number]["value"];
+
+export const BRAND_SOURCES = [
+  { value: "brand_kit", label: "Use the brand kit colour and font when there is one" },
+  { value: "custom", label: "Always use the colour and font set here" },
+] as const;
+export type BrandSource = (typeof BRAND_SOURCES)[number]["value"];
+
+export const BLOCK_KINDS = [
+  { value: "identity", label: "Name and title", hint: "Who is signing. Every template needs one required, locked block of this kind." },
+  { value: "contact", label: "Contact details", hint: "Phone, email, address." },
+  { value: "photo", label: "Photo", hint: "A picture of the sender (an image address)." },
+  { value: "logo", label: "Logo", hint: "The company logo (an image address)." },
+  { value: "social", label: "Social links", hint: "LinkedIn, X or a personal site." },
+  { value: "cta", label: "Call to action", hint: "A link such as Book a call." },
+  { value: "banner", label: "Banner slot", hint: "An image that campaigns can replace. At most one optional banner per template." },
+  { value: "divider", label: "Divider", hint: "A thin line." },
+  { value: "disclaimer", label: "Disclaimer", hint: "Legal or confidentiality text." },
+  { value: "green_footer", label: "Green footer", hint: "A short environmental note." },
+  { value: "custom_html", label: "Custom HTML", hint: "Your own markup. The server removes anything unsafe." },
+] as const;
+export type BlockKind = (typeof BLOCK_KINDS)[number]["value"];
+
+export const POLICY_MODES = [
+  { value: "off", label: "Off", hint: "Nothing is managed. Mailboxes keep the signature they have." },
+  { value: "default", label: "Managed", hint: "Mailboxes get the assigned or default template; employees may change the parts you leave unlocked." },
+  { value: "enforced", label: "Enforced", hint: "Mailboxes get the template and employees cannot override it. Every active mailbox must already be assigned." },
+] as const;
+export type PolicyMode = (typeof POLICY_MODES)[number]["value"];
+
+export const COLD_VARIANTS = [
+  { value: "compact", label: "Compact (the essentials only)" },
+  { value: "full", label: "Full" },
+] as const;
+
+export const CAMPAIGN_STATUSES = [
+  { value: "draft", label: "Draft" },
+  { value: "scheduled", label: "Scheduled" },
+  { value: "paused", label: "Paused" },
+] as const;
+
+export const SOURCE_CHOICES = [
+  { value: "org", label: "The organisation or department default" },
+  { value: "template", label: "A named template" },
+  { value: "custom", label: "Its own signature (restores what it had before)" },
+] as const;
+export type SourceChoice = (typeof SOURCE_CHOICES)[number]["value"];
+
+/**
+ * The placeholders a block's text, link and image may use: `{{member.name}}`, with an optional fallback
+ * `{{member.title|Team}}`. There is no variables endpoint; this list mirrors what the signature renderer resolves
+ * (signatures/usecases/context.py). A required block with a placeholder that has no fallback fails to render for an employee
+ * whose directory entry lacks that value.
+ */
+export const VARIABLES: { token: string; label: string }[] = [
+  { token: "member.name", label: "Employee name" },
+  { token: "member.first_name", label: "First name" },
+  { token: "member.last_name", label: "Last name" },
+  { token: "member.title", label: "Job title" },
+  { token: "member.department", label: "Department" },
+  { token: "member.phone", label: "Phone" },
+  { token: "member.email", label: "Email" },
+  { token: "member.pronouns", label: "Pronouns" },
+  { token: "member.avatar_url", label: "Photo address" },
+  { token: "member.linkedin_url", label: "LinkedIn address" },
+  { token: "member.twitter_url", label: "X address" },
+  { token: "member.personal_website", label: "Personal website" },
+  { token: "mailbox.email", label: "Mailbox address" },
+  { token: "mailbox.display_name", label: "Mailbox display name" },
+  { token: "company.name", label: "Company name" },
+  { token: "company.logo_url", label: "Company logo address" },
+  { token: "company.address", label: "Company address" },
+  { token: "company.phone", label: "Company phone" },
+  { token: "company.website", label: "Company website" },
+  { token: "brand.primary_color", label: "Brand primary colour" },
+  { token: "brand.secondary_color", label: "Brand secondary colour" },
+  { token: "brand.accent_color", label: "Brand accent colour" },
+  { token: "brand.font", label: "Brand font" },
+];
+
+export const variableText = (token: string): string => `{{${token}}}`;
+
+/** One block of a template, exactly the fields the API stores (it forbids any other). */
+export interface TemplateBlock {
+  id: string;
+  kind: BlockKind;
+  text: string;
+  url: string;
+  image: string;
+  locked: boolean;
+  required: boolean;
+}
+
+export interface TemplateData {
+  name: string;
+  layout: SignatureLayout;
+  blocks: TemplateBlock[];
+  primary_color: string;
+  font: SignatureFont;
+  brand_source: BrandSource;
+}
+
+/** A stored template as the API returns it. `data` is open: a legacy row may lack fields. */
+export interface SignatureTemplate {
+  id: string;
+  version: number;
+  data: Partial<Omit<TemplateData, "blocks">> & { blocks?: Partial<TemplateBlock>[] };
+}
+
+export interface PolicyData {
+  mode: PolicyMode;
+  default_template_id: string | null;
+  department_templates: Record<string, string>;
+  allow_employee_overrides: boolean;
+  cold_sends_variant: "full" | "compact";
+  native_enabled: boolean;
+}
+
+export interface SignaturePolicy {
+  version: number;
+  data: Partial<PolicyData>;
+}
+
+export interface SignatureMember {
+  id: string;
+  name?: string | null;
+  email?: string | null;
+  department?: string | null;
+}
+
+export interface Assignment {
+  member_id?: string;
+  template_id?: string | null;
+  account_subject?: string;
+  send_as_email?: string;
+  integration_id?: string | null;
+  overrides?: Record<string, string>;
+  native_requested?: boolean;
+}
+
+/** One mailbox's signature deployment. `revision` is the concurrency token every per-mailbox write sends back. */
+export interface Deployment {
+  mailbox_id: number;
+  email?: string | null;
+  revision: number;
+  status?: string | null;
+  error?: string | null;
+  alert?: boolean;
+  assignment?: Assignment;
+  attempts?: number;
+  next_attempt?: string | null;
+  native_coverage?: string | null;
+  updated_at?: string | null;
+}
+
+export interface MailboxRecord {
+  id: number;
+  email?: string | null;
+  display_name?: string | null;
+  provider?: string | null;
+  is_archived?: boolean | null;
+}
+
+/** A mailbox with its signature deployment, when it has one. */
+export interface SignatureMailbox {
+  id: number;
+  email: string;
+  display_name?: string | null;
+  deployment?: Deployment;
+}
+
+export interface CampaignBlock extends Partial<TemplateBlock> {
+  kind?: BlockKind;
+}
+
+export interface CampaignData {
+  name?: string;
+  block?: CampaignBlock;
+  starts_at?: string;
+  ends_at?: string;
+  status?: string;
+  priority?: number;
+  mailbox_ids?: number[];
+  recipient_domains?: string[];
+  excluded_domains?: string[];
+  external_only?: boolean;
+  departments?: string[];
+  recipient_list_ids?: number[];
+  native_static?: boolean;
+}
+
+export interface SignatureCampaign {
+  id: string;
+  revision: number;
+  data: CampaignData;
+}
+
+export interface Artifact {
+  html: string;
+  plain: string;
+  digest?: string;
+  required_html?: string;
+  required_plain?: string;
+}
+
+export type PreviewVariant = "full" | "compact" | "campaign";
+export type TemplatePreview = Partial<Record<PreviewVariant, Artifact>>;
+
+export interface CampaignPreview {
+  html: string;
+  plain: string;
+  native_static: boolean;
+  matching?: Record<string, unknown> | null;
+}
+
+export interface ReportMetric {
+  kind: string;
+  mailbox_id?: number | null;
+  campaign_id?: string | null;
+  count: number;
+  source?: string | null;
+}
+
+export interface SignatureReport {
+  native_verifications?: number;
+  retention_days?: number;
+  metrics?: ReportMetric[];
+  tracking_available?: boolean;
+  limitations?: string[];
+}
+
+// ---------- templates ----------
+
+/** The blocks a new template starts with: the one required, locked identity block every template needs. */
+export function starterBlocks(): TemplateBlock[] {
+  return [{ id: "identity", kind: "identity", text: "{{member.name}}\n{{member.title}}", url: "", image: "", locked: true, required: true }];
+}
+
+/** The API's own defaults for a new template (signatures/domain/models.py Template), so a created body states what it stores. */
+export function blankTemplate(): TemplateData {
+  return { name: "", layout: "classic-stacked", blocks: starterBlocks(), primary_color: "#222222", font: "Arial", brand_source: "brand_kit" };
+}
+
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+
+/** A stored template as editable form state. Only known keys are kept: the API forbids any other on write. */
+export function draftFromTemplate(t: SignatureTemplate): TemplateData {
+  const d = t.data ?? {};
+  return {
+    name: str(d.name),
+    layout: LAYOUTS.some((l) => l.value === d.layout) ? (d.layout as SignatureLayout) : "classic-stacked",
+    blocks: (d.blocks ?? []).map((b) => ({
+      id: str(b.id),
+      kind: BLOCK_KINDS.some((k) => k.value === b.kind) ? (b.kind as BlockKind) : "custom_html",
+      text: str(b.text),
+      url: str(b.url),
+      image: str(b.image),
+      locked: Boolean(b.locked),
+      required: Boolean(b.required),
+    })),
+    primary_color: /^#[a-fA-F0-9]{6}$/.test(str(d.primary_color)) ? str(d.primary_color) : "#222222",
+    font: FONTS.includes(d.font as SignatureFont) ? (d.font as SignatureFont) : "Arial",
+    brand_source: d.brand_source === "custom" ? "custom" : "brand_kit",
+  };
+}
+
+/** A fresh, unique block id for a kind (`cta`, `cta-2`, ...). */
+export function nextBlockId(kind: string, blocks: readonly TemplateBlock[]): string {
+  const used = new Set(blocks.map((b) => b.id));
+  if (!used.has(kind)) return kind;
+  for (let n = 2; ; n++) if (!used.has(`${kind}-${n}`)) return `${kind}-${n}`;
+}
+
+/** The product rules the API enforces on a template, checked before a save so the person sees the reason at once. */
+export function templateProblems(t: TemplateData): string[] {
+  const out: string[] = [];
+  if (t.name.trim() === "") out.push("Give the template a name.");
+  if (t.name.length > 150) out.push("The name can be at most 150 characters.");
+  if (t.blocks.length === 0) out.push("Add at least one block.");
+  if (t.blocks.length > 30) out.push("A template can have at most 30 blocks.");
+  if (!t.blocks.some((b) => b.kind === "identity" && b.required)) out.push("A required identity block is necessary.");
+  if (t.blocks.some((b) => b.required && !b.locked)) out.push("Required blocks must be locked.");
+  if (t.blocks.filter((b) => b.kind === "banner" && !b.required).length > 1) out.push("Use at most one optional banner slot.");
+  if (new Set(t.blocks.map((b) => b.id)).size !== t.blocks.length) out.push("Block ids must be unique.");
+  if (t.blocks.some((b) => !/^[a-zA-Z0-9_-]{1,64}$/.test(b.id))) out.push("A block id can use letters, numbers, - and _ (up to 64).");
+  if (t.blocks.some((b) => b.text.length > 10000)) out.push("Block text can be at most 10,000 characters.");
+  if (t.blocks.some((b) => b.url.length > 2048 || b.image.length > 2048)) out.push("Links and image addresses can be at most 2,048 characters.");
+  return out;
+}
+
+export const sameTemplate = (a: TemplateData, b: TemplateData): boolean => JSON.stringify(a) === JSON.stringify(b);
+
+/** The name a template goes by in a menu. */
+export const templateName = (t: SignatureTemplate | undefined | null): string => (t?.data?.name ? String(t.data.name) : "Untitled template");
+
+// ---------- people and mailboxes ----------
+
+export const memberLabel = (m: SignatureMember | undefined | null): string => m?.name || m?.email || "Unknown person";
+
+/** Mailboxes the API lists, merged with the signature deployment each one has (a deployment alone is kept when the mailbox is not listed). */
+export function mergeMailboxes(records: MailboxRecord[], deployments: Deployment[]): SignatureMailbox[] {
+  const byId = new Map(deployments.map((d) => [d.mailbox_id, d]));
+  const out: SignatureMailbox[] = [];
+  for (const r of records) {
+    const deployment = byId.get(r.id);
+    byId.delete(r.id); // an archived mailbox is hidden, and must not come back through its deployment
+    if (r.is_archived) continue;
+    out.push({ id: r.id, email: r.email ?? "", display_name: r.display_name, deployment });
+  }
+  for (const d of byId.values()) out.push({ id: d.mailbox_id, email: d.email ?? "", deployment: d });
+  return out.sort((a, b) => a.email.localeCompare(b.email));
+}
+
+/** A deployment that graph8 manages (not given back to the mailbox's own signature). */
+export const isManaged = (d: Deployment | undefined): boolean => Boolean(d) && d!.status !== "restored";
+
+export function statusTone(d: Deployment): "positive" | "info" | "warning" | "negative" | "neutral" {
+  const s = String(d.status ?? "").toLowerCase();
+  if (d.alert) return s === "needs_assignment" || s === "drifted" ? "warning" : "negative";
+  if (["pending", "retrying", "leased"].includes(s)) return "info";
+  if (["restored", "management_off"].includes(s)) return "neutral";
+  if (["active", "applied", "installed", "synced", "ok"].includes(s)) return "positive";
+  return "neutral";
+}
+
+// ---------- policy ----------
+
+const POLICY_KEYS: (keyof PolicyData)[] = ["mode", "default_template_id", "department_templates", "allow_employee_overrides", "cold_sends_variant", "native_enabled"];
+
+/** Only the keys the API's policy model knows: a stored legacy key would be a 422 (it forbids extras). */
+export function knownPolicy(data: Partial<PolicyData> | undefined): Partial<PolicyData> {
+  const out: Record<string, unknown> = {};
+  for (const k of POLICY_KEYS) if (data && k in data && data[k] !== undefined) out[k] = data[k];
+  return out as Partial<PolicyData>;
+}
+
+// ---------- campaigns ----------
+
+/** `2026-10-01T09:30` for a datetime-local input, in the viewer's time zone, from an ISO instant. */
+export function toLocalInput(iso: string | undefined): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  const p = (n: number): string => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}T${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+/** The ISO instant (timezone-aware, as the API requires) for a datetime-local value, or undefined when it is empty or invalid. */
+export function fromLocalInput(local: string): string | undefined {
+  if (!local) return undefined;
+  const d = new Date(local);
+  return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+}
+
+export function formatWhen(iso: string | null | undefined): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? "" : d.toLocaleString(undefined, { dateStyle: "medium", timeStyle: "short" });
+}
+
+/** "a.com, b.com" -> ["a.com", "b.com"] (trimmed, lower-cased, no blanks, no repeats). */
+export function splitList(text: string): string[] {
+  return [...new Set(text.split(/[\s,;]+/).map((s) => s.trim().toLowerCase()).filter(Boolean))];
+}
+
+/** A 409 from a versioned write: someone else changed the record since it was read. */
+export function isConflict(error: unknown): boolean {
+  return (error as { status?: number } | null | undefined)?.status === 409;
+}

package/blocks/email-signatures/recipes/assign-a-signature-to-a-new-hire.ts

@@ -0,0 +1,32 @@
+/**
+ * @title Give a new hire's mailbox a managed signature
+ * @when Onboarding. This is a TAKEOVER: the mailbox's current signature is captured for restore and replaced, so a person
+ * must have agreed (the API demands `confirm_takeover: true`). The employee account must be the employee's own directory email
+ * and the send-as address the mailbox address, so both are read, never typed. The mailbox's revision (0 when it has no
+ * assignment yet) is sent so a concurrent change answers 409 instead of being overwritten.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function assignSignature(employeeEmail: string): Promise<{ mailboxId: number; revision: number }> {
+  const members = await g8.api.signatures.listSignatureMembers({});
+  const member = members.data.find((m) => m.email?.toLowerCase() === employeeEmail.toLowerCase());
+  if (!member?.email) throw new Error(`${employeeEmail} is not in the directory`);
+
+  const mailboxes = await g8.api.gtmContext.listMailboxes({ query: { limit: 500 } });
+  const mailbox = (mailboxes.data as Array<{ id: number; email?: string | null }>).find((m) => m.email?.toLowerCase() === employeeEmail.toLowerCase());
+  if (!mailbox?.email) throw new Error(`No mailbox for ${employeeEmail}`);
+
+  const deployments = await g8.api.signatures.listSignatureDeployments({});
+  const current = (deployments.data as Array<{ mailbox_id: number; revision: number }>).find((d) => d.mailbox_id === mailbox.id);
+  const assignment = { member_id: member.id, account_subject: member.email, send_as_email: mailbox.email };
+
+  // A dry run against the mail provider: the account and the send-as address must resolve before anything is replaced.
+  await g8.api.signatures.previewSignatureSetup({ body: { mailbox_id: mailbox.id, data: assignment } });
+
+  const result = await g8.api.signatures.assignSignatureIdentity({
+    body: { mailbox_ids: [mailbox.id], expected_revisions: { [mailbox.id]: current?.revision ?? 0 }, confirm_takeover: true, data: assignment },
+  });
+  return { mailboxId: mailbox.id, revision: result.data[0].revision };
+}

package/blocks/email-signatures/recipes/create-a-template-and-make-it-default.ts

@@ -0,0 +1,35 @@
+/**
+ * @title Create a signature template and make it the organisation default
+ * @when Setting up managed signatures for the first time. Creating a template changes nothing on any mailbox. Making it the
+ * default changes what every mailbox that follows the organisation default SENDS, so have a person confirm that first. The
+ * policy is a separate document with its own version: set-default sends the POLICY version read from getSignatureSettings.
+ * Every template needs one required, locked identity block.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function createDefaultTemplate(name: string): Promise<{ templateId: string; policyVersion: number }> {
+  const created = await g8.api.signatures.createSignatureTemplate({
+    body: {
+      data: {
+        name,
+        layout: "classic-stacked",
+        font: "Arial",
+        primary_color: "#222222",
+        brand_source: "brand_kit",
+        blocks: [
+          { id: "identity", kind: "identity", text: "{{member.name}}\n{{member.title|Team}}", locked: true, required: true },
+          { id: "contact", kind: "contact", text: "{{member.email}} {{member.phone|}}" },
+        ],
+      },
+    },
+  });
+
+  const policy = await g8.api.signatures.getSignatureSettings({});
+  const made = await g8.api.signatures.setDefaultSignatureTemplate({
+    path: { template_id: created.data.id },
+    body: { version: policy.data.version },
+  });
+  return { templateId: created.data.id, policyVersion: made.data.version };
+}

package/blocks/email-signatures/recipes/signature-engagement-report.ts

@@ -0,0 +1,16 @@
+/**
+ * @title Report signature impressions and clicks by mailbox and campaign
+ * @when A weekly digest or a dashboard backend. Reads only. Treat the numbers with the report's own `limitations` and
+ * `tracking_available`: a natively installed signature reports no impressions, and without click tracking there are no clicks.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function signatureReport(): Promise<{ byKind: Record<string, number>; trackingAvailable: boolean; limitations: string[] }> {
+  const report = await g8.api.signatures.getSignatureReport({});
+  const data = report.data as { metrics?: Array<{ kind: string; count: number }>; tracking_available?: boolean; limitations?: string[] };
+  const byKind: Record<string, number> = {};
+  for (const m of data.metrics ?? []) byKind[m.kind] = (byKind[m.kind] ?? 0) + m.count;
+  return { byKind, trackingAvailable: Boolean(data.tracking_available), limitations: data.limitations ?? [] };
+}

package/blocks/enrichment/README.md

@@ -15,6 +15,15 @@ added in graph8 settings, so it links out). Every paid step goes through the con
 Also a **Jobs** tab (`?job=`, `EnrichmentJobDetail`: live progress, counts, credits, provider errors, cancel; the jobs running now come from `GET /enrichment/active-jobs` and jobs started this session are listed, so no id has to be pasted; an older job can still be opened by id) and a pipeline detail (`?pipeline=`: steps, credential status, missing keys). `?view=full` opens any detail full-page.
 Slots: `toolbarActions`, `renderDetailActions(contact)`, `extraDetailTabs`.
 
+Enrichment depth (slice 1) adds four tabs and job controls, all additive:
+
+- **List pipelines** (`?tab=list-pipelines&list=<id>`, open one with `?lp=<pipeline id>`): ordered chains of enrichment steps that run over a whole list. Start from a **template** (saved turned off; adding one the list already has resets it, confirmed) or build one in the sheet (steps come from the configs the list can use, in order, each can be turned off / fill only empty values / skip recently enriched records). Open a pipeline to **Run** it: the run is priced first by `POST .../pipelines/{id}/estimate` (free) for that exact list, and the confirm shows the estimate's `required_credits` (an upper bound: run conditions are ignored when pricing), the per-step records and your balance (`available_credits`). A run the estimate refuses shows the API's reason and never reaches the confirm. The run is polled with per-step progress, can be stopped, and finished runs are listed. Turn on/off and Delete are confirmed. Saving never runs a pipeline.
+- **Auto-enrichment** (`?tab=auto&list=<id>`): what a list enriches by itself as records are ADDED (an insert trigger: existing records are not touched, edits do not re-run it), with the workspace-wide switch and merge rule (keep edits and fill the rest / never overwrite / matched data wins) for contacts and companies. Every change is confirmed and says it spends credits with nobody confirming each record. The API publishes no per-record price for it, so no total is shown.
+- **Jobs** gain **Pause** (free, stops further charges) and **Resume** (confirmed; names the records still to enrich, not a credit figure the API does not quote). The state shown is re-read from the server after each.
+- **Activity** (`?tab=activity`): records enriched, success rate, results over time, daily activity and fields filled for a chosen window. Completed jobs only; the API's cost figure is its own estimate at a fixed rate, so it is not shown.
+
+A list's detail links here ("Enrich this list") in the apollo, clay and zoominfo stacks, through the lists block's `renderDetailActions` slot.
+
 Prerequisites: `crm` and `lists` installed, proxy allowlist `enrichment`, `lists`, `contacts`, `companies`; provider keys and credits as below.
 
 ## What you get
@@ -29,7 +38,7 @@ Prerequisites: `crm` and `lists` installed, proxy allowlist `enrichment`, `lists
 `BulkEnrichPanel` with no props is a complete page (choose a list, tick contacts, enrich), so it can be mounted as a
 route as is; give it `listId` and `contactIds` to embed it. For that reason this block depends on `lists`.
 
-Hook `useProviders()`; helpers in `lib/enrichment-types.ts` (`estimateCredits`, `isJobTerminal`, the price constants).
+Hook `useProviders()`; helpers in `lib/enrichment-types.ts` (`quotedCredits`, `isJobTerminal`, the price constants).
 
 ## Cost, in plain numbers (all billable steps are confirmed)
 
@@ -37,11 +46,20 @@ Hook `useProviders()`; helpers in `lib/enrichment-types.ts` (`estimateCredits`,
 |---|---|---|
 | Person or company lookup | 2 credits, **only if a match is found** (a miss is free) | `ConfirmSpendDialog` (billable) showing 2 credits |
 | Email verification | 1 credit | `ConfirmSpendDialog` (billable) |
-| Bulk enrichment | quoted by the preflight (`max_total_credits`, the most it can charge); flat 2 credits per record when the preflight cannot price it. Providers on your own key cost 0 | `ConfirmSpendDialog` (billable) with that estimate |
+| Bulk enrichment | quoted by the preflight (`max_total_credits`, the most it can charge); no total is shown, and the confirm says so, when the preflight cannot price the run. Providers on your own key cost 0 | `ConfirmSpendDialog` (billable) with that quote (or with no total when there is none) |
 | Create a waterfall pipeline | creating does not run it; running spends per the providers used | `ConfirmSpendDialog` |
 
-There is **no balance read** in the API. Every number shown is an estimate of what a run can cost, never a check that
-you can afford it; an under-funded run fails with 402.
+There is **no standalone balance read** in the API. Bulk-enrichment numbers are estimates of what a run can cost, never a
+check that you can afford it; an under-funded run fails with 402. The one place a balance appears is a list pipeline's price
+estimate (`available_credits`), which the run confirm shows beside the quote.
+
+| List pipeline action | Cost | Confirmed with |
+|---|---|---|
+| Save (create or edit) a pipeline | nothing: it is saved turned off and does not run | `ConfirmSpendDialog` (billable tier) saying so |
+| Turn on / off | nothing by itself: a pipeline runs when you run it | `ConfirmSpendDialog` (billable tier) saying so |
+| Run | the estimate's `required_credits` for this list and pipeline (an upper bound), per record per step | `ConfirmSpendDialog` (billable) showing that number |
+| Auto-enrichment (list or workspace) | every record added from then on, no price published | `ConfirmSpendDialog` (billable) stating the ongoing spend |
+| Resume a paused job | the records it had not reached | `ConfirmSpendDialog` (billable) naming how many |
 
 ## The flow, with the ids that pass between steps