@graph8/sdk 0.373.0 → 0.374.0

package/blocks/crm/components/tag-manager.tsx

@@ -0,0 +1,178 @@
+"use client";
+
+/**
+ * TagManager: the org's contact tags in one sheet. Create, rename, recolour, archive and restore a tag, delete one
+ * (optionally moving its contacts to another tag first) and merge several tags into one.
+ *
+ * SDK operations, in order:
+ *   1. listContactTags   GET /contacts/tags?include_archived=true            (read; every tag at once, with contact counts)
+ *   2. createContactTag  POST /contacts/tags { name, color, description }    (write; a duplicate name is refused by the API)
+ *   3. updateContactTag  PATCH /contacts/tags/{tag_id} { name, color, description, archived }   (write; omitted fields stay)
+ *   4. deleteContactTag  DELETE /contacts/tags/{tag_id}?reassign_to=...      (destructive, ConfirmSpendDialog)
+ *        Without `reassign_to` the API drops the assignments together with the tag; the contacts themselves stay.
+ *   5. mergeContactTags  POST /contacts/tags/merge { source_tag_ids, target_tag_id }   (destructive: the sources are
+ *        removed and their contacts get the target, ConfirmSpendDialog)
+ *
+ * Edit sends only what changed. A tag's description cannot be cleared (the API leaves a null field untouched), so
+ * the description is not offered as an editable field here; only name, colour and archive state are.
+ */
+
+import { useMemo, useState } from "react";
+import { Button, cn } from "@graph8/sdk/ui";
+import { Archive, GitMerge, Pencil, Plus, Trash2 } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Delete, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import { useContactTags } from "../hooks/use-contact-tags";
+import { HEX_COLOR, TAG_COLORS, isArchivedTag } from "../lib/record-actions";
+import type { ContactTag } from "../lib/record-actions";
+import { TagChip } from "./contact-tag-chips";
+
+export interface TagManagerProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Called after any change that can alter what the contact list shows. */
+  onChanged?: () => void;
+}
+
+function Swatches({ value, onChange, label }: { value: string; onChange: (c: string) => void; label: string }) {
+  return (
+    <span className="flex gap-1" role="radiogroup" aria-label={label}>
+      {TAG_COLORS.map((c) => <button key={c} type="button" role="radio" aria-checked={value === c} aria-label={`Colour ${c}`} onClick={() => onChange(c)} className={cn("size-5 rounded-full border-2", value === c ? "border-foreground" : "border-transparent")} style={{ backgroundColor: c }} />)}
+    </span>
+  );
+}
+
+export function TagManager({ open, onOpenChange, onChanged }: TagManagerProps) {
+  const all = useContactTags({ enabled: open, includeArchived: true });
+  const [name, setName] = useState("");
+  const [color, setColor] = useState<string>(TAG_COLORS[0]);
+  const [editing, setEditing] = useState<{ id: string; name: string; color: string } | null>(null);
+  const [picked, setPicked] = useState<ReadonlySet<string>>(new Set());
+  const [mergeInto, setMergeInto] = useState("");
+  const [confirmMerge, setConfirmMerge] = useState(false);
+  const [deleting, setDeleting] = useState<ContactTag | null>(null);
+  const [moveTo, setMoveTo] = useState("");
+  const done = () => { void all.refetch(); onChanged?.(); };
+  const keys = [["contact-tags"], ["contacts", "tags"], ["contacts", "list"]] as const;
+
+  const create = useG8Mutation((v: { name: string; color: string }) => g8Post("/contacts/tags", v), { invalidates: keys, onSuccess: () => { setName(""); done(); } });
+  const update = useG8Mutation((v: { id: string; body: Record<string, unknown> }) => g8Patch(`/contacts/tags/${v.id}`, v.body), { invalidates: keys, onSuccess: () => { setEditing(null); done(); } });
+  const remove = useG8Mutation((v: { id: string; reassignTo: string }) => g8Delete(`/contacts/tags/${v.id}`, v.reassignTo ? { query: { reassign_to: v.reassignTo } } : {}), {
+    invalidates: keys,
+    onSuccess: (_r, v) => { setDeleting(null); setMoveTo(""); setPicked((s) => { const n = new Set(s); n.delete(v.id); return n; }); done(); },
+  });
+  const merge = useG8Mutation((v: { sources: string[]; target: string }) => g8Post("/contacts/tags/merge", { source_tag_ids: v.sources, target_tag_id: v.target }), {
+    invalidates: keys,
+    onSuccess: () => { setConfirmMerge(false); setPicked(new Set()); setMergeInto(""); done(); },
+  });
+
+  const byId = useMemo(() => new Map(all.tags.map((t) => [t.id, t])), [all.tags]);
+  const sources = [...picked].filter((id) => byId.has(id));
+  const targets = all.tags.filter((t) => !picked.has(t.id) && !isArchivedTag(t));
+  const sourceContacts = sources.reduce((n, id) => n + (byId.get(id)?.contact_count ?? 0), 0);
+  const togglePick = (id: string) => setPicked((s) => { const n = new Set(s); if (!n.delete(id)) n.add(id); return n; });
+  const saveEdit = (t: ContactTag) => {
+    if (!editing) return;
+    const body: Record<string, unknown> = {};
+    if (editing.name.trim() && editing.name.trim() !== t.name) body.name = editing.name.trim();
+    if (HEX_COLOR.test(editing.color) && editing.color !== t.color) body.color = editing.color;
+    if (Object.keys(body).length === 0) { setEditing(null); return; }
+    void update.mutate({ id: t.id, body });
+  };
+  const deleteTargets = all.tags.filter((t) => t.id !== deleting?.id && !isArchivedTag(t));
+  const allCountsKnown = sources.every((id) => byId.get(id)?.contact_count != null);
+  const targetName = byId.get(mergeInto)?.name ?? "";
+
+  return (
+    <FormSheet open={open} onOpenChange={onOpenChange} title="Manage tags" description="Tags group contacts outside lists." width="lg" footer={<Button variant="ghost" onClick={() => onOpenChange(false)}>Close</Button>}>
+      <form className="flex flex-wrap items-center gap-2 border-b pb-3" onSubmit={(e) => { e.preventDefault(); if (name.trim()) void create.mutate({ name: name.trim(), color }); }}>
+        <input aria-label="Tag name" maxLength={50} placeholder="New tag" value={name} onChange={(e) => setName(e.target.value)} className="h-9 w-44 rounded-md border bg-background px-3 text-sm" />
+        <Swatches value={color} onChange={setColor} label="Tag colour" />
+        <Button type="submit" size="sm" loading={create.loading} disabled={!name.trim()}><Plus className="size-4" aria-hidden />Create tag</Button>
+      </form>
+      {create.error ? <ApiError error={create.error} title="Could not create the tag" /> : null}
+      {update.error ? <ApiError error={update.error} title="Could not save the tag" /> : null}
+      {all.error ? <ApiError error={all.error} title="Could not load tags" onRetry={() => void all.refetch()} /> : null}
+      {all.loading ? <p className="text-sm text-muted-foreground" role="status">Loading tags</p> : null}
+      {!all.loading && !all.error && all.tags.length === 0 ? <p className="py-6 text-center text-sm text-muted-foreground">No tags yet. Create the first one above.</p> : null}
+
+      {sources.length > 0 ? (
+        <div className="flex flex-wrap items-center gap-2 rounded-md border bg-muted/40 p-2 text-sm" role="status">
+          <span>{plural(sources.length, "tag")} selected</span>
+          <select aria-label="Merge into" className="h-8 rounded-md border bg-background px-2" value={mergeInto} onChange={(e) => setMergeInto(e.target.value)}>
+            <option value="">Merge into...</option>
+            {targets.map((t) => <option key={t.id} value={t.id}>{t.name}</option>)}
+          </select>
+          <Button size="sm" variant="outline" disabled={!mergeInto} onClick={() => setConfirmMerge(true)}><GitMerge className="size-4" aria-hidden />Merge</Button>
+          <Button size="sm" variant="ghost" onClick={() => setPicked(new Set())}>Clear</Button>
+        </div>
+      ) : null}
+      {merge.error ? <ApiError error={merge.error} title="Could not merge the tags" /> : null}
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the tag" /> : null}
+
+      <ul className="flex flex-col divide-y">
+        {all.tags.map((t) => (
+          <li key={t.id} className="flex flex-wrap items-center gap-2 py-2">
+            <input type="checkbox" aria-label={`Select ${t.name}`} checked={picked.has(t.id)} onChange={() => togglePick(t.id)} />
+            {editing?.id === t.id ? (
+              <form className="flex flex-wrap items-center gap-2" onSubmit={(e) => { e.preventDefault(); saveEdit(t); }}>
+                <input aria-label="Rename tag" maxLength={50} value={editing.name} onChange={(e) => setEditing({ ...editing, name: e.target.value })} className="h-8 w-40 rounded-md border bg-background px-2 text-sm" />
+                <Swatches value={editing.color} onChange={(c) => setEditing({ ...editing, color: c })} label="Edit colour" />
+                <Button type="submit" size="sm" loading={update.loading} disabled={!editing.name.trim()}>Save</Button>
+                <Button type="button" size="sm" variant="ghost" onClick={() => setEditing(null)}>Cancel</Button>
+              </form>
+            ) : (
+              <>
+                <span className={cn(isArchivedTag(t) && "opacity-60")}><TagChip tag={t} /></span>
+                {isArchivedTag(t) ? <span className="text-xs text-muted-foreground">Archived</span> : null}
+                <span className="text-xs tabular-nums text-muted-foreground">{t.contact_count == null ? "-" : plural(t.contact_count, "contact")}</span>
+                <span className="ml-auto flex gap-1">
+                  <Button size="sm" variant="ghost" aria-label={`Edit ${t.name}`} onClick={() => setEditing({ id: t.id, name: t.name, color: t.color && HEX_COLOR.test(t.color) ? t.color : TAG_COLORS[0] })}><Pencil className="size-4" aria-hidden /></Button>
+                  <Button size="sm" variant="ghost" aria-label={`${isArchivedTag(t) ? "Restore" : "Archive"} ${t.name}`} onClick={() => void update.mutate({ id: t.id, body: { archived: !isArchivedTag(t) } })}><Archive className="size-4" aria-hidden /></Button>
+                  <Button size="sm" variant="ghost" aria-label={`Delete ${t.name}`} onClick={() => { setDeleting(t); setMoveTo(""); }}><Trash2 className="size-4" aria-hidden /></Button>
+                </span>
+              </>
+            )}
+          </li>
+        ))}
+      </ul>
+
+      <ConfirmSpendDialog
+        open={confirmMerge}
+        tier="destructive"
+        title={`Merge ${plural(sources.length, "tag")} into ${targetName}`}
+        description={`${sources.map((id) => byId.get(id)?.name).filter(Boolean).join(", ")} will be removed. ${allCountsKnown ? `Their ${plural(sourceContacts, "contact")} get` : "Their contacts get"} ${targetName} instead; contacts that already have it keep one copy.`}
+        affected={allCountsKnown ? sourceContacts : undefined}
+        confirmLabel="Merge tags"
+        confirming={merge.loading}
+        onConfirm={() => void merge.mutate({ sources, target: mergeInto })}
+        onCancel={() => setConfirmMerge(false)}
+      />
+      <ConfirmSpendDialog
+        open={deleting != null}
+        tier="destructive"
+        title={`Delete the tag ${deleting?.name ?? ""}`}
+        description={
+          <div className="flex flex-col gap-2">
+            <p>{moveTo ? `${deleting?.contact_count == null ? "Its contacts" : `Its ${plural(deleting.contact_count, "contact")}`} get ${byId.get(moveTo)?.name ?? "the other tag"} first.` : `It is removed from ${deleting?.contact_count == null ? "its contacts" : plural(deleting.contact_count, "contact")}. The contacts themselves stay.`}</p>
+            <label className="flex items-center gap-2 text-sm">Move its contacts to
+              <select aria-label="Move contacts to" className="h-8 rounded-md border bg-background px-2" value={moveTo} onChange={(e) => setMoveTo(e.target.value)}>
+                <option value="">No other tag</option>
+                {deleteTargets.map((t) => <option key={t.id} value={t.id}>{t.name}</option>)}
+              </select>
+            </label>
+          </div>
+        }
+        affected={deleting?.contact_count ?? undefined}
+        confirmLabel="Delete tag"
+        confirming={remove.loading}
+        onConfirm={() => deleting && void remove.mutate({ id: deleting.id, reassignTo: moveTo })}
+        onCancel={() => setDeleting(null)}
+      />
+    </FormSheet>
+  );
+}

package/blocks/crm/components/unlock-info-button.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+/**
+ * UnlockInfoButton: unlock the locked contacts of a selection. Counts what it will charge for, shows that count and
+ * cost in ConfirmSpendDialog, and sends exactly that set.
+ *
+ * SDK operations, behind ConfirmSpendDialog (billable, scope enrichment:run):
+ *   1. unlockContactInfo   POST /contacts/unlock-info { contact_ids }       1 credit per newly unlocked contact
+ *        Only locked contacts are counted and sent (a masked email or phone). The answer's `credits_charged` is shown.
+ *        At most 1000 per call, so a larger selection unlocks the first 1000 and says so before the confirm.
+ *
+ * The confirm is disabled while its request runs, and a failed call keeps the selection so the person can retry.
+ */
+
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { Unlock } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import type { ContactRecord } from "../lib/crm-types";
+import { MAX_PAID_BATCH, UNLOCK_CREDITS_PER_CONTACT, isLockedContact, unlockTargets } from "../lib/record-actions";
+
+export interface PaidActionProps {
+  rows: ReadonlyArray<ContactRecord>;
+  onDone?: () => void;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+  className?: string;
+  /** Start with the confirm open and render no trigger (the row actions dialog opens it). */
+  defaultOpen?: boolean;
+  onClosed?: () => void;
+}
+
+export function UnlockInfoButton({ rows, onDone, variant = "outline", size = "sm", className, defaultOpen = false, onClosed }: PaidActionProps) {
+  const [open, setOpen] = useState(defaultOpen);
+  const [charged, setCharged] = useState<number | null | undefined>(undefined);
+  const targets = unlockTargets(rows);
+  const lockedTotal = rows.filter(isLockedContact).length;
+  const already = rows.length - lockedTotal;
+
+  const unlock = useG8Mutation(async (ids: number[]) => {
+    const res = await g8Post<{ credits_charged?: number }>("/contacts/unlock-info", { contact_ids: ids });
+    return typeof res.data?.credits_charged === "number" ? res.data.credits_charged : null;
+  }, {
+    invalidates: [["contacts", "list"], ["contacts", "detail"], ["contacts", "record"]],
+    onSuccess: (n) => { setOpen(false); setCharged(n); onDone?.(); onClosed?.(); },
+  });
+
+  return (
+    <>
+      {defaultOpen ? null : (
+        <Button className={className} variant={variant} size={size} disabled={targets.length === 0} title={targets.length === 0 ? "None of the selected contacts is locked" : undefined} onClick={() => { setCharged(undefined); unlock.reset(); setOpen(true); }}>
+          <Unlock className="size-4" aria-hidden />Unlock info
+        </Button>
+      )}
+      {charged !== undefined ? <span role="status" className="text-xs text-muted-foreground">{charged == null ? "Unlocked." : `Unlocked. ${charged.toLocaleString()} ${charged === 1 ? "credit" : "credits"} charged.`}</span> : null}
+      {unlock.error && !open ? <ApiError compact error={unlock.error} title="Could not unlock the contacts" /> : null}
+      <ConfirmSpendDialog
+        open={open}
+        tier="billable"
+        title={`Unlock ${plural(targets.length, "contact")}`}
+        description={
+          <>
+            Reveals the withheld email and phone numbers. Each newly unlocked contact costs {UNLOCK_CREDITS_PER_CONTACT} credit; contacts that are already unlocked are not charged again.
+            {already > 0 ? ` ${plural(already, "selected contact")} ${already === 1 ? "is" : "are"} already unlocked and left out.` : ""}
+            {lockedTotal > MAX_PAID_BATCH ? ` Only the first ${MAX_PAID_BATCH.toLocaleString()} locked contacts are unlocked in one go.` : ""}
+            {unlock.error ? <span role="alert" className="mt-2 block text-destructive">The unlock failed. You can try again.</span> : null}
+          </>
+        }
+        estimatedCredits={targets.length * UNLOCK_CREDITS_PER_CONTACT}
+        affected={targets.length}
+        confirmLabel="Unlock"
+        confirming={unlock.loading}
+        onConfirm={() => void unlock.mutate(targets.map((t) => t.id))}
+        onCancel={() => { setOpen(false); onClosed?.(); }}
+      />
+    </>
+  );
+}

package/blocks/crm/components/verify-email-button.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+/**
+ * VerifyEmailButton: verify the work emails of a selection. Counts what it will charge for, shows that count and cost
+ * in ConfirmSpendDialog, and sends exactly that set.
+ *
+ * SDK operations, behind ConfirmSpendDialog (billable, scope enrichment:run):
+ *   1. verifyContactEmails POST /contacts/verify-email { contact_pks }      about 1 credit per verified email
+ *        Only contacts with a real (not locked, not empty) work email are counted and sent: the "***" placeholder is never
+ *        sent. Already verified emails come back as `already_verified` and inconclusive checks are not stored or
+ *        charged; the result line states what was charged (`charged_credits`) rather than the estimate. At most 1000.
+ *
+ * The confirm is disabled while its request runs, and a failed call keeps the selection so the person can retry.
+ */
+
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { MailCheck } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import type { ContactRecord } from "../lib/crm-types";
+import { MAX_PAID_BATCH, VERIFY_CREDITS_PER_EMAIL, verifySummary, verifyTargets } from "../lib/record-actions";
+import type { VerifyRow } from "../lib/record-actions";
+
+export interface PaidActionProps {
+  rows: ReadonlyArray<ContactRecord>;
+  onDone?: () => void;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+  className?: string;
+  /** Start with the confirm open and render no trigger (the row actions dialog opens it). */
+  defaultOpen?: boolean;
+  onClosed?: () => void;
+}
+
+/** A list answer that is a bare array or an envelope with the list under a common key. */
+function anyRows<T>(data: unknown): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const o = data as Record<string, unknown> | null | undefined;
+  for (const k of ["items", "results", "contacts", "data"]) if (Array.isArray(o?.[k])) return o![k] as T[];
+  return [];
+}
+
+export function VerifyEmailButton({ rows, onDone, variant = "outline", size = "sm", className, defaultOpen = false, onClosed }: PaidActionProps) {
+  const [open, setOpen] = useState(defaultOpen);
+  const [summary, setSummary] = useState<string | null>(null);
+  // One filter, used for the count, the cost and the request body.
+  const targets = verifyTargets(rows);
+  const left = rows.length - targets.length;
+
+  const verify = useG8Mutation(async (ids: number[]) => {
+    const res = await g8Post<unknown>("/contacts/verify-email", { contact_pks: ids });
+    return anyRows<VerifyRow>(res.data);
+  }, {
+    invalidates: [["contacts", "list"], ["contacts", "detail"], ["contacts", "record"]],
+    onSuccess: (out) => { setOpen(false); setSummary(verifySummary(out)); onDone?.(); onClosed?.(); },
+  });
+
+  return (
+    <>
+      {defaultOpen ? null : (
+        <Button className={className} variant={variant} size={size} disabled={targets.length === 0} title={targets.length === 0 ? "None of the selected contacts has an unlocked work email" : undefined} onClick={() => { setSummary(null); verify.reset(); setOpen(true); }}>
+          <MailCheck className="size-4" aria-hidden />Verify email
+        </Button>
+      )}
+      {summary ? <span role="status" className="text-xs text-muted-foreground">{summary}</span> : null}
+      {verify.error && !open ? <ApiError compact error={verify.error} title="Could not verify the emails" /> : null}
+      <ConfirmSpendDialog
+        open={open}
+        tier="billable"
+        title={`Verify ${plural(targets.length, "email")}`}
+        description={
+          <>
+            Checks whether each address can receive mail and stores the answer on the contact. Already verified emails and inconclusive checks are not charged.
+            {left > 0 ? ` ${plural(left, "selected contact")} ${left === 1 ? "has" : "have"} no unlocked email and ${left === 1 ? "is" : "are"} left out.` : ""}
+            {rows.filter((r) => !!r.work_email).length > MAX_PAID_BATCH ? ` Only the first ${MAX_PAID_BATCH.toLocaleString()} are verified in one go.` : ""}
+            {verify.error ? <span role="alert" className="mt-2 block text-destructive">The check failed. Nothing was charged for the failed call; you can try again.</span> : null}
+          </>
+        }
+        estimatedCredits={targets.length * VERIFY_CREDITS_PER_EMAIL}
+        affected={targets.length}
+        confirmLabel="Verify"
+        confirming={verify.loading}
+        onConfirm={() => void verify.mutate(targets.map((t) => t.id))}
+        onCancel={() => { setOpen(false); onClosed?.(); }}
+      />
+    </>
+  );
+}
+

package/blocks/crm/hooks/use-contact-tags.ts

@@ -0,0 +1,29 @@
+"use client";
+
+/**
+ * useContactTags: the org's tag definitions (`GET /contacts/tags`), cached under ["contact-tags"] so every chip row, the
+ * assign dialog and the tag manager share one request and refresh together after a write.
+ *
+ * SDK operations: listContactTags (read). The list is not paged by the API (it answers every tag at once with a
+ * contact count), so there is no "first N" to disclose. Archived tags are left out unless asked for.
+ */
+
+import { useMemo } from "react";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { isArchivedTag, rowsOf } from "../lib/record-actions";
+import type { ContactTag } from "../lib/record-actions";
+
+export function useContactTags(options: { enabled?: boolean; includeArchived?: boolean } = {}) {
+  const { enabled = true, includeArchived = false } = options;
+  const query = useG8Query(
+    (signal) => g8Get<unknown>("/contacts/tags", includeArchived ? { include_archived: true } : undefined, { signal }),
+    [includeArchived],
+    { enabled, key: ["contact-tags", includeArchived ? "all" : "active"] },
+  );
+  const tags = useMemo(() => {
+    const rows = rowsOf<ContactTag>(query.data?.data, "tags").filter((t) => t && typeof t.id === "string" && t.id !== "");
+    return includeArchived ? rows : rows.filter((t) => !isArchivedTag(t));
+  }, [query.data, includeArchived]);
+  return { tags, loading: query.loading && !query.data, error: query.error, refetch: query.refetch, loaded: query.data != null };
+}

package/blocks/crm/lib/record-actions.ts

@@ -0,0 +1,102 @@
+"use client";
+
+/**
+ * Shared helpers for the CRM record actions (owner, tags, bulk update, verify, unlock, AI documents, next best step).
+ * Pure functions and types only: no operations of its own.
+ *
+ * Why the sets are computed here: a confirm dialog must COUNT exactly the set the request SENDS (#25642). Every paid
+ * action filters its selection once with one of these helpers and uses the SAME array for the count, the cost line
+ * and the request body.
+ */
+
+import { isMasked } from "./crm-types";
+import type { ContactRecord } from "./crm-types";
+
+/** One contact tag definition (`GET /contacts/tags`). The handler sends `archived_at`; the contract types `archived`. */
+export interface ContactTag {
+  id: string;
+  name: string;
+  color?: string | null;
+  description?: string | null;
+  contact_count?: number | null;
+  archived?: boolean | null;
+  archived_at?: string | null;
+  is_default?: boolean | null;
+}
+
+export function isArchivedTag(tag: ContactTag): boolean {
+  return tag.archived === true || (tag.archived_at != null && tag.archived_at !== "");
+}
+
+/** The API takes six-digit hex colours only (`^#[0-9A-Fa-f]{6}$`). */
+export const HEX_COLOR = /^#[0-9A-Fa-f]{6}$/;
+
+/**
+ * The tag palette offered in the tag manager. Free choice of a hex colour is also allowed; these are only the
+ * one-click choices, so no screen ever shows a raw colour input as its only control.
+ */
+export const TAG_COLORS = ["#2563EB", "#0F766E", "#B45309", "#B91C1C", "#6D28D9", "#475569"] as const;
+
+/** `POST /contacts/unlock-info` takes at most 1000 contact ids; `POST /contacts/verify-email` at most 1000 too. */
+export const MAX_PAID_BATCH = 1000;
+
+/** One credit per newly unlocked contact (contacts/interfaces/fastapi/router.py: "estimated_credits ... 1 credit per contact"). */
+export const UNLOCK_CREDITS_PER_CONTACT = 1;
+/** One credit per verified email (the same price the enrichment block shows for a single verification). */
+export const VERIFY_CREDITS_PER_EMAIL = 1;
+
+/** A contact with any masked email or phone: unlocking reveals it. */
+export function isLockedContact(row: Pick<ContactRecord, "work_email" | "direct_phone" | "mobile_phone">): boolean {
+  return isMasked(row.work_email) || isMasked(row.direct_phone) || isMasked(row.mobile_phone);
+}
+
+/** The contacts an unlock would charge for: only the locked ones, capped at the API's batch size. */
+export function unlockTargets(rows: ReadonlyArray<ContactRecord>): ContactRecord[] {
+  return rows.filter(isLockedContact).slice(0, MAX_PAID_BATCH);
+}
+
+/** The contacts with a real work email. A locked or empty email cannot be verified, and the "***" placeholder is never sent. */
+export function verifyTargets(rows: ReadonlyArray<ContactRecord>): ContactRecord[] {
+  return rows.filter((r) => !!r.work_email && r.work_email.trim() !== "" && !isMasked(r.work_email)).slice(0, MAX_PAID_BATCH);
+}
+
+/**
+ * Fields the bulk updater offers. Names are the contact's own columns (`bulk-update` only accepts `CONTACT_*` and `udo_*` keys); anything else, including the owner (own action) and tags (own action), is not editable here.
+ */
+export const BULK_FIELDS = [
+  { key: "CONTACT_JOB_TITLE", label: "Job title" },
+  { key: "CONTACT_JOB_DEPARTMENT", label: "Department" },
+  { key: "CONTACT_SENIORITY_LEVEL", label: "Seniority" },
+  { key: "CONTACT_CITY", label: "City" },
+  { key: "CONTACT_STATE", label: "State" },
+  { key: "CONTACT_COUNTRY", label: "Country" },
+] as const;
+export type BulkFieldKey = (typeof BULK_FIELDS)[number]["key"];
+
+/** The result rows of a verify call. */
+export interface VerifyRow {
+  contact_pk?: number;
+  outcome?: "verified" | "already_verified" | "inconclusive" | "not_verified" | null;
+  verification_result?: string | null;
+  charged_credits?: number;
+}
+
+/** "Verified 3, already verified 1, inconclusive 1 (not charged). 3 credits charged." */
+export function verifySummary(rows: ReadonlyArray<VerifyRow>): string {
+  const n = (o: string) => rows.filter((r) => r.outcome === o).length;
+  const parts = [
+    `Verified ${n("verified")}`,
+    n("already_verified") ? `already verified ${n("already_verified")}` : "",
+    n("inconclusive") ? `inconclusive ${n("inconclusive")} (not charged)` : "",
+    n("not_verified") ? `no answer for ${n("not_verified")} (not charged)` : "",
+  ].filter(Boolean);
+  const charged = rows.reduce((max, r) => Math.max(max, r.charged_credits ?? 0), 0);
+  return `${parts.join(", ")}. ${charged.toLocaleString()} ${charged === 1 ? "credit" : "credits"} charged.`;
+}
+
+/** The array inside an envelope `data` that is either the array itself or `{ <key>: [...] }`. */
+export function rowsOf<T>(data: unknown, key: string): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const inner = (data as Record<string, unknown> | null | undefined)?.[key];
+  return Array.isArray(inner) ? (inner as T[]) : [];
+}

package/blocks/deals/README.md

@@ -125,3 +125,4 @@ create), `deal.id` + `deal.revision` (card -> detail -> update/delete).
 ## Cross-block glue
 
 - `RecordDealsTab` (`components/record-deals-tab.tsx`): the deals of one contact or company (`GET /contacts/{id}/deals`, `GET /companies/{id}/deals`), each opening in the deals screen. Use it as an `extraDetailTabs` entry of `ContactsScreen` / `CompaniesScreen`. `DealsScreen` also takes optional `onOpenContact` / `onOpenCompany`: the Contacts tab gains "Open in contacts" and the contact sheet gains "Open company".
+- `CreateDealButton` (`components/create-deal-button.tsx`): "Create deal" for one contact. A sheet with the deal form already filled in from the contact and their company (linked contact, name "<company> - <contact>", owner from the key's person or a picker). `onCreated(dealId)` routes to the new deal. The company comes from the contact (the API derives it), and a company that already has a deal is refused until "Create another deal for this company" is ticked. Use it in `ContactsScreen.renderDetailActions`.

package/blocks/deals/block.json

@@ -31,6 +31,7 @@
     "delete_pipeline_pipelines__pipeline_id__delete",
     "delete_stage_pipelines__pipeline_id__stages__stage_id__delete",
     "get_company_deals_companies__company_id__deals_get",
+    "get_contact_contacts__contact_id__get",
     "get_contact_deals_contacts__contact_id__deals_get",
     "get_deal_analytics_deals_analytics_get",
     "get_deal_deals__deal_id__get",
@@ -261,6 +262,22 @@
       "tiers": [
         "read"
       ]
+    },
+    {
+      "name": "CreateDealButton",
+      "file": "components/create-deal-button.tsx",
+      "purpose": "\"Create deal\" for one contact: a sheet with the deal form prefilled from the contact and their company (linked contact, name \"<company> - <contact>\", owner, pipeline stage). Calls onCreated(dealId) so you can route to the new deal.",
+      "operations": [
+        "create_deal_deals_post",
+        "get_contact_contacts__contact_id__get",
+        "get_my_team_member_team_members_me_get",
+        "list_pipelines_deals_pipelines_get",
+        "list_team_members_team_members_get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
     }
   ],
   "hooks": [

package/blocks/deals/components/create-deal-button.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+/**
+ * CreateDealButton: "Create deal" for one contact. Opens a sheet with the deal form already filled in from the
+ * contact and their company: the deal is linked to the contact (the API derives the company from its contacts),
+ * named "<company> - <contact>", and owned by the API key's person (or a member you pick). Use it in
+ * `ContactsScreen.renderDetailActions`:
+ *   <CreateDealButton contactId={c.id} onCreated={(dealId) => router.push(`/deals?id=${dealId}`)} />
+ *
+ * SDK operations, in order:
+ *   1. getContact          GET  /contacts/{contact_id}          (read)   the name and company shown and used as the default deal name
+ *   2. getMyTeamMember     GET  /team-members/me                (read)   the owner; listTeamMembers (read) when the key has no person
+ *   3. listPipelines       GET  /deals/pipelines                (read)   the stage picker
+ *   4. createDeal          POST /deals                          (write)  once, retry-safe (a second save edits the same deal)
+ * A company that already has a deal answers 409; the sheet then offers "Create another deal for this company".
+ * Nothing here is billable, external or destructive.
+ */
+
+import { useState } from "react";
+import { Button, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, Skeleton } from "@graph8/sdk/ui";
+import { Handshake } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useDefaultOwner } from "../hooks/use-default-owner";
+import { dataOf } from "../lib/deals-types";
+import { DealDetail } from "./deal-detail";
+
+export interface CreateDealButtonProps {
+  /** The CRM contact the deal is for. */
+  contactId: number;
+  /** Called with the new deal's id after it was created (route to your deals screen). */
+  onCreated?: (dealId: string) => void;
+  label?: string;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+}
+
+interface ContactBits {
+  first_name?: string | null;
+  last_name?: string | null;
+  full_name?: string | null;
+  work_email?: string | null;
+  company_name?: string | null;
+  company?: { name?: string | null; domain?: string | null } | null;
+}
+
+export const contactLabel = (c: ContactBits | undefined | null, id: number): string =>
+  c?.full_name?.trim() || [c?.first_name, c?.last_name].filter(Boolean).join(" ").trim() || c?.work_email || `Contact ${id}`;
+export const companyLabelOf = (c: ContactBits | undefined | null): string => (c?.company?.name || c?.company_name || "").trim();
+
+function Form({ contactId, onCreated }: { contactId: number; onCreated?: (dealId: string) => void }) {
+  const owner = useDefaultOwner();
+  const contact = useG8Query(async (signal) => dataOf<ContactBits>(await g8Get(`/contacts/${contactId}`, undefined, { signal })), [contactId], { key: ["contacts", "deal-prefill", contactId] });
+  const [ownerId, setOwnerId] = useState<string | null>(null);
+  const [another, setAnother] = useState(false);
+  if (owner.loading || (contact.loading && !contact.data)) return <Skeleton className="h-24 w-full" aria-label="Loading the deal form" />;
+  if (contact.error) return <ApiError error={contact.error} title="Could not load the contact" onRetry={() => void contact.refetch()} />;
+  const effective = ownerId ?? owner.defaultOwner?.id ?? "";
+  if (!effective) return <ApiError error={owner.error ?? new Error("No team member found to own this deal.")} title="A deal needs an owner" onRetry={() => void owner.reload()} />;
+  const company = companyLabelOf(contact.data);
+  const person = contactLabel(contact.data, contactId);
+  return (
+    <div className="space-y-3">
+      <dl className="grid grid-cols-[auto,1fr] gap-x-3 gap-y-1 rounded-md border bg-muted/40 p-3 text-sm">
+        <dt className="text-muted-foreground">Contact</dt>
+        <dd className="font-medium">{person}</dd>
+        <dt className="text-muted-foreground">Company</dt>
+        <dd className="font-medium">{company || "None on this contact"}</dd>
+      </dl>
+      {owner.source === "first-member" ? (
+        <div className="space-y-1">
+          <label htmlFor="create-deal-owner" className="text-sm font-medium">Owner</label>
+          <select id="create-deal-owner" className="h-9 w-full rounded-md border bg-background px-2 text-sm" value={effective} onChange={(e) => setOwnerId(e.target.value)}>
+            {owner.owners.map((o) => <option key={o.id} value={o.id}>{o.name}{o.email && o.email !== o.name ? ` (${o.email})` : ""}</option>)}
+          </select>
+          <p className="text-xs text-muted-foreground">This key has no person of its own, so choose who owns the deal.</p>
+        </div>
+      ) : null}
+      <label className="flex items-center gap-2 text-sm">
+        <input type="checkbox" checked={another} onChange={(e) => setAnother(e.target.checked)} />
+        Create another deal for this company
+      </label>
+      <p className="text-xs text-muted-foreground">Leave this off and a company that already has a deal is refused, so you never create a duplicate by accident.</p>
+      <DealDetail ownerId={effective} contactIds={[contactId]} allowDuplicate={another} defaultName={[company, person].filter(Boolean).join(" - ")} onSaved={(deal) => { if (deal.id) onCreated?.(deal.id); }} />
+    </div>
+  );
+}
+
+export function CreateDealButton({ contactId, onCreated, label = "Create deal", variant = "outline", size = "sm" }: CreateDealButtonProps) {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button size={size} variant={variant} onClick={() => setOpen(true)}>
+        <Handshake className="mr-1 size-4" aria-hidden />
+        {label}
+      </Button>
+      <Sheet open={open} onOpenChange={setOpen}>
+        <SheetContent className="w-full overflow-y-auto sm:max-w-xl">
+          <SheetHeader>
+            <SheetTitle>Create deal</SheetTitle>
+            <SheetDescription>The deal is linked to this contact and their company.</SheetDescription>
+          </SheetHeader>
+          <div className="p-4">{open ? <Form key={contactId} contactId={contactId} onCreated={onCreated} /> : null}</div>
+        </SheetContent>
+      </Sheet>
+    </>
+  );
+}