@graph8/sdk 0.361.0 → 0.370.0

package/blocks/crm/components/contacts-screen.tsx

@@ -0,0 +1,359 @@
+"use client";
+
+/**
+ * ContactsScreen: the finished contacts workspace. A searchable, filterable, sortable, paginated grid on the left;
+ * the open contact (timeline, notes, tasks, fields) beside it. No props are required.
+ *
+ * Composes: ScreenLayout, StatStrip, Toolbar, SplitView, DetailPanel, FormSheet (screen kit) with RecordForm,
+ * ActivityTimeline, NotesPanel, TaskList, ImportWizard and DedupeReview (this block).
+ *
+ * Flows: search and filter (name, title, seniority, country; debounced, latest request wins) - sort the loaded
+ * page - paginate - open a contact (deep link ?id=, full page with &view=full) - create a contact (a 409 opens the existing one) - edit - delete one
+ * or many (confirm, "N of M" report, 404 = already gone) - import a CSV/Excel file - review and merge duplicates -
+ * add notes and tasks - hand a contact to other blocks through the slot props.
+ *
+ * SDK operations: none of its own. listContacts, getContact, getActivityFeed, duplicateCounts are `read`;
+ * the forms, notes and tasks are `write`; deleteContact (rows, detail and bulk) is `destructive` and always goes
+ * through ConfirmSpendDialog. Nothing here sends a message to a person.
+ *
+ * Locked (masked) emails and phones show as Locked: save the contact to a list or enrich it to reveal them.
+ */
+
+import { useEffect, useMemo, useState } from "react";
+import type { ReactNode } from "react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { Building2, GitMerge, Lock, Plus, Trash2, Upload, Users } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+import { RecordLink } from "@/g8/components/screen/record-link";
+import { plural } from "@/g8/lib/plural";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Delete, g8Get } from "@/g8/lib/g8-client";
+import { useDebouncedValue } from "../hooks/use-debounced";
+import { usePageQuery } from "../hooks/use-page-query";
+import { contactName, errorStatus, isMasked, location } from "../lib/crm-types";
+import type { ContactRecord, ScreenActionContext } from "../lib/crm-types";
+import { Pager, SortHead, formatDay, sortRows, useBulkDelete, useRowSelection, useSort } from "../lib/screen-parts";
+import { ActivityTimeline } from "./activity-timeline";
+import { DedupeReview } from "./dedupe-review";
+import { ImportWizard } from "./import-wizard";
+import { NotesPanel } from "./notes-panel";
+import { RecordForm } from "./record-form";
+import { TaskList } from "./task-list";
+
+export interface ContactsScreenProps {
+  /** Only members of this list. */
+  listId?: number;
+  pageSize?: number;
+  /** Buttons at the end of each row (enrich, add to list...). */
+  renderRowActions?: (row: ContactRecord, ctx: ScreenActionContext) => ReactNode;
+  /** Buttons in the open contact's header. */
+  renderDetailActions?: (contact: ContactRecord, ctx: ScreenActionContext) => ReactNode;
+  /** Extra tabs on the open contact. */
+  extraDetailTabs?: Array<{ id: string; label: string; render: (contact: ContactRecord) => ReactNode }>;
+  /** Extra buttons in the page header, before "New contact". */
+  toolbarActions?: ReactNode;
+  /** Extra bulk actions next to Delete (add to list, enrich, enroll...). */
+  renderBulkActions?: (selection: { ids: number[]; rows: ContactRecord[]; clear: () => void }) => ReactNode;
+  /** Called with a company id from the contact panel ("Open company"). Without it the button is hidden. */
+  onOpenCompany?: (companyId: number) => void;
+  className?: string;
+}
+
+interface Filters { name: string; job_title: string; seniority_level: string; country: string }
+const NO_FILTERS: Filters = { name: "", job_title: "", seniority_level: "", country: "" };
+const SENIORITY = ["C-Suite", "VP", "Director", "Manager"];
+
+function sortValue(row: ContactRecord, key: string): string | null | undefined {
+  if (key === "name") return contactName(row);
+  if (key === "title") return row.job_title;
+  if (key === "company") return row.company_name;
+  if (key === "location") return location(row);
+  return null;
+}
+
+function Locked() {
+  return <span className="inline-flex items-center gap-1 italic text-muted-foreground" title="Locked: save to a list or enrich to reveal"><Lock className="size-3" aria-hidden />Locked</span>;
+}
+function Cell({ value }: { value?: string | null }) {
+  return isMasked(value) ? <Locked /> : <>{value || <span className="text-muted-foreground">-</span>}</>;
+}
+
+export function ContactsScreen(props: ContactsScreenProps) {
+  const { listId, pageSize = 25 } = props;
+  const [idParam, setIdParamRaw] = useUrlState("id");
+  const [view, setView] = useUrlState("view");
+  const full = view === "full" && idParam != null && idParam !== "";
+  /** Changing or clearing the open record also leaves the full-page view. */
+  const setIdParam = (v: string | null): void => { if (v == null) setView(null); setIdParamRaw(v); };
+  const parsedId = idParam ? Number(idParam) : null;
+  /** A malformed deep link (`?id=abc`) opens nothing instead of fetching /contacts/NaN. */
+  const openId = parsedId != null && Number.isFinite(parsedId) ? parsedId : null;
+  const [draft, setDraft] = useState<Filters>(NO_FILTERS);
+  const filters = useDebouncedValue(draft);
+  const [sheet, setSheet] = useState<"new" | "import" | "dupes" | null>(null);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+  const [note, setNote] = useState<string | null>(null);
+  const { sort, toggle: toggleSort } = useSort();
+
+  const list = usePageQuery<ContactRecord>(
+    (page, signal) => g8Get<ContactRecord[]>("/contacts", { page, limit: pageSize, list_id: listId, ...Object.fromEntries(Object.entries(filters).filter(([, v]) => v)) }, { signal }),
+    [listId, filters],
+    pageSize,
+    ["contacts", "list", "screen"],
+  );
+  const dupes = useG8Query((signal) => g8Get<{ pending?: number; count?: number }>("/duplicates/counts", { entity_type: "contact" }, { signal }), [], { key: ["duplicates", "counts", "contact"] });
+  const selection = useRowSelection<ContactRecord>(`${listId}|${JSON.stringify(filters)}`);
+  const rows = useMemo(() => sortRows(list.rows, sort, sortValue), [list.rows, sort]);
+  const hasFilters = Object.values(draft).some(Boolean);
+  const pending = dupes.data?.data.pending ?? dupes.data?.data.count;
+  const lockedOnPage = list.rows.filter((r) => isMasked(r.work_email)).length;
+
+  const bulk = useBulkDelete("/contacts", (gone, total) => {
+    selection.drop(gone);
+    setConfirmDelete(false);
+    setNote(gone.length < total ? `Deleted ${gone.length} of ${total}. ${total - gone.length} could not be deleted; they are still selected.` : null);
+    if (openId != null && gone.includes(openId)) setIdParam(null);
+    void list.refetch();
+    void dupes.refetch();
+  });
+  const allOnPage = rows.length > 0 && rows.every((r) => selection.selected.has(r.id));
+  const reload = () => { void list.refetch(); void dupes.refetch(); };
+  const set = (key: keyof Filters, v: string) => setDraft((f) => ({ ...f, [key]: v }));
+
+  useEffect(() => { setNote(null); }, [filters, listId]);
+
+  return (
+    <ScreenLayout
+      className={props.className}
+      title="Contacts"
+      description="Everyone you sell to, with their history, notes and follow-ups."
+      icon={<Users className="size-5" aria-hidden />}
+      actions={
+        <>
+          {props.toolbarActions}
+          <Button variant="outline" size="sm" onClick={() => setSheet("dupes")}><GitMerge className="size-4" aria-hidden />Duplicates{pending ? ` (${pending})` : ""}</Button>
+          <Button variant="outline" size="sm" onClick={() => setSheet("import")}><Upload className="size-4" aria-hidden />Import</Button>
+          <Button size="sm" onClick={() => setSheet("new")}><Plus className="size-4" aria-hidden />New contact</Button>
+        </>
+      }
+      stats={[
+        { label: "Contacts", value: list.loading && list.total === 0 ? "-" : list.total.toLocaleString(), hint: hasFilters ? "Matching the filters" : listId ? "In this list" : "In your workspace" },
+        { label: "Possible duplicates", value: pending ?? "-", tone: pending ? "warning" : "neutral", hint: "Review and merge" },
+        { label: "Locked on this page", value: lockedOnPage, hint: "Save to a list or enrich to reveal" },
+      ]}
+    >
+      <SplitView
+        detailOpen={openId != null}
+        expanded={full}
+        onExpandedChange={(e) => setView(e ? "full" : null)}
+        onCloseDetail={() => setIdParam(null)}
+        detailWidth="lg"
+        list={
+          <div className="flex flex-col gap-3">
+            <Toolbar
+              search={{ value: draft.name, onChange: (v) => set("name", v), placeholder: "Search contacts by name" }}
+              filters={
+                <>
+                  <input aria-label="Filter by job title" placeholder="Job title" className="h-9 w-36 rounded-md border bg-background px-3 text-sm" value={draft.job_title} onChange={(e) => set("job_title", e.target.value)} />
+                  <select aria-label="Filter by seniority" className="h-9 rounded-md border bg-background px-2 text-sm" value={draft.seniority_level} onChange={(e) => set("seniority_level", e.target.value)}>
+                    <option value="">Any seniority</option>
+                    {SENIORITY.map((s) => <option key={s} value={s}>{s}</option>)}
+                  </select>
+                  <input aria-label="Filter by country" placeholder="Country" className="h-9 w-32 rounded-md border bg-background px-3 text-sm" value={draft.country} onChange={(e) => set("country", e.target.value)} />
+                  {hasFilters ? <Button variant="ghost" size="sm" onClick={() => setDraft(NO_FILTERS)}>Clear filters</Button> : null}
+                </>
+              }
+            />
+
+            {selection.ids.length > 0 ? (
+              <div className="flex flex-wrap items-center gap-2 rounded-md border bg-muted/40 px-3 py-2 text-sm" role="status">
+                <span className="tabular-nums">{selection.ids.length} selected</span>
+                {props.renderBulkActions?.({ ids: selection.ids, rows: selection.rows, clear: selection.clear })}
+                <Button variant="destructive" size="sm" onClick={() => setConfirmDelete(true)}><Trash2 className="size-4" aria-hidden />Delete {selection.ids.length}</Button>
+                <Button variant="ghost" size="sm" onClick={selection.clear}>Clear selection</Button>
+              </div>
+            ) : null}
+            {list.error ? <ApiError error={list.error} title="Could not load contacts" onRetry={() => void list.refetch()} /> : null}
+            {note ? <p role="alert" className="text-sm text-destructive">{note}</p> : null}
+
+            <div className="overflow-hidden rounded-md border">
+              <Table>
+                <TableHeader>
+                  <TableRow>
+                    <TableHead className="w-8"><input type="checkbox" aria-label="Select page" checked={allOnPage} onChange={() => selection.togglePage(rows)} /></TableHead>
+                    <SortHead label="Name" sortKey="name" sort={sort} onSort={toggleSort} />
+                    <SortHead label="Title" sortKey="title" sort={sort} onSort={toggleSort} />
+                    <SortHead label="Company" sortKey="company" sort={sort} onSort={toggleSort} />
+                    <TableHead>Email</TableHead>
+                    <SortHead label="Location" sortKey="location" sort={sort} onSort={toggleSort} />
+                    {props.renderRowActions ? <TableHead className="w-8"><span className="sr-only">Actions</span></TableHead> : null}
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  {list.loading && rows.length === 0
+                    ? Array.from({ length: 6 }, (_, i) => <TableRow key={`sk${i}`}><TableCell colSpan={6 + (props.renderRowActions ? 1 : 0)}><Skeleton className="h-6 w-full" /></TableCell></TableRow>)
+                    : rows.map((row) => {
+                        const name = contactName(row);
+                        return (
+                          <TableRow key={row.id} data-testid={`contact-row-${row.id}`} data-state={row.id === openId ? "selected" : undefined} className="cursor-pointer" {...rowActivationProps(() => setIdParam(String(row.id)))}>
+                            <TableCell onClick={(e) => e.stopPropagation()}>
+                              <input type="checkbox" aria-label={`Select ${name}`} checked={selection.selected.has(row.id)} onChange={() => selection.toggle(row)} />
+                            </TableCell>
+                            <TableCell>
+                              <span className="flex items-center gap-2 font-medium"><EntityAvatar name={name} kind="person" size="sm" /><RecordLink param="id" id={row.id} onOpen={() => setIdParam(String(row.id))}>{name}</RecordLink></span>
+                            </TableCell>
+                            <TableCell><Cell value={row.job_title} /></TableCell>
+                            <TableCell><Cell value={row.company_name} /></TableCell>
+                            <TableCell><Cell value={row.work_email} /></TableCell>
+                            <TableCell><Cell value={location(row)} /></TableCell>
+                            {props.renderRowActions ? <TableCell onClick={(e) => e.stopPropagation()}>{props.renderRowActions(row, { reload })}</TableCell> : null}
+                          </TableRow>
+                        );
+                      })}
+                </TableBody>
+              </Table>
+              {!list.loading && !list.error && rows.length === 0 ? (
+                <EmptyState
+                  title={hasFilters ? "No contacts match these filters" : "No contacts yet"}
+                  description={hasFilters ? "Try fewer filters." : "Add your first contact or import a file."}
+                  action={hasFilters ? <Button variant="outline" onClick={() => setDraft(NO_FILTERS)}>Clear filters</Button> : <Button onClick={() => setSheet("new")}>New contact</Button>}
+                />
+              ) : null}
+              <Pager page={list.page} pageCount={list.pageCount} total={list.total} noun="contacts" hasNext={list.hasNext} loading={list.loading} onPage={list.setPage} />
+            </div>
+            {sort ? <p className="text-xs text-muted-foreground">Sorted within this page only.</p> : null}
+          </div>
+        }
+        detail={openId != null ? (
+          <ContactPanel key={openId} full={full} setFull={(v) => setView(v ? "full" : null)} contactId={openId} seed={list.rows.find((r) => r.id === openId)} onClose={() => setIdParam(null)} onChanged={reload} onDeleted={() => { setIdParam(null); reload(); }}
+            onOpenCompany={props.onOpenCompany} renderActions={props.renderDetailActions} extraTabs={props.extraDetailTabs} />
+        ) : null}
+      />
+
+      <FormSheet open={sheet === "new"} onOpenChange={(o) => setSheet(o ? "new" : null)} title="New contact" description="A name, an email or a LinkedIn URL is enough.">
+        <RecordForm entity="contact" listId={listId} onCancel={() => setSheet(null)}
+          onSaved={({ id }) => { setSheet(null); reload(); if (id != null) setIdParam(String(id)); }}
+          onDuplicate={(existing) => { setSheet(null); if (existing != null) setIdParam(String(existing)); }} />
+      </FormSheet>
+      <FormSheet open={sheet === "import"} onOpenChange={(o) => setSheet(o ? "import" : null)} title="Import contacts" description="Upload a CSV or Excel file, map the columns and choose where they go.">
+        <ImportWizard listId={listId} onImported={reload} />
+      </FormSheet>
+      <FormSheet open={sheet === "dupes"} onOpenChange={(o) => setSheet(o ? "dupes" : null)} title="Duplicate contacts" description="Merge pairs, or mark them as not duplicates.">
+        <DedupeReview entity="contact" onChanged={reload} />
+      </FormSheet>
+
+      <ConfirmSpendDialog
+        open={confirmDelete}
+        tier="destructive"
+        title={`Delete ${plural(selection.ids.length, "contact")}`}
+        description="They are removed from every list and sequence."
+        affected={selection.ids.length}
+        confirming={bulk.loading}
+        onConfirm={() => void bulk.mutate(selection.ids)}
+        onCancel={() => setConfirmDelete(false)}
+      />
+    </ScreenLayout>
+  );
+}
+
+interface ContactPanelProps {
+  full: boolean;
+  setFull: (full: boolean) => void;
+  contactId: number;
+  /** The list row, for fields the detail answer lacks (owner). */
+  seed?: ContactRecord;
+  onClose: () => void;
+  onChanged: () => void;
+  onDeleted: () => void;
+  onOpenCompany?: (companyId: number) => void;
+  renderActions?: ContactsScreenProps["renderDetailActions"];
+  extraTabs?: ContactsScreenProps["extraDetailTabs"];
+}
+
+function ContactPanel({ full, setFull, contactId, seed, onClose, onChanged, onDeleted, onOpenCompany, renderActions, extraTabs = [] }: ContactPanelProps) {
+  const [editing, setEditing] = useState(false);
+  const [confirm, setConfirm] = useState(false);
+  const [feedKey, setFeedKey] = useState(0);
+  const query = useG8Query((signal) => g8Get<ContactRecord>(`/contacts/${contactId}`, { include_custom_fields: true }, { signal }), [contactId], {
+    key: ["contacts", "detail", contactId],
+    // The row the contact was opened from paints the panel at once; the full record replaces it.
+    placeholderData: seed ? { data: seed } : undefined,
+  });
+  /** Edit, delete and slot actions wait for the full record: a list row must never seed the edit form. */
+  const partial = query.isPlaceholderData === true;
+  const remove = useG8Mutation(async () => {
+    try { await g8Delete(`/contacts/${contactId}`); } catch (e) { if (errorStatus(e) !== 404) throw e; }
+  }, { invalidates: [["contacts", "list"]], onSuccess: () => { setConfirm(false); onDeleted(); } });
+  const bump = () => setFeedKey((k) => k + 1);
+
+  if (query.loading && !query.data) return <div className="flex flex-col gap-3 p-4"><Skeleton className="h-14 w-full" /><Skeleton className="h-40 w-full" /></div>;
+  // A failed full record must not leave the list row on screen with every action disabled.
+  if (query.error && (!query.data || partial)) return <div className="p-4"><ApiError error={query.error} title="Could not load this contact" onRetry={() => void query.refetch()} /></div>;
+  const contact = query.data!.data;
+  const name = contactName(contact);
+  const val = (v?: string | null): ReactNode => (isMasked(v) ? <Locked /> : v || <span className="text-muted-foreground">-</span>);
+
+  const overview = (
+    <KeyValueList columns={2} items={[
+      { label: "Work email", value: val(contact.work_email) },
+      { label: "Direct phone", value: val(contact.direct_phone) },
+      { label: "Mobile phone", value: val(contact.mobile_phone) },
+      { label: "LinkedIn", value: val(contact.linkedin_url) },
+      { label: "Seniority", value: val(contact.seniority_level) },
+      { label: "Department", value: val(contact.job_department) },
+      { label: "Location", value: val(location(contact)) },
+      { label: "Owner", value: val(contact.owner_name ?? seed?.owner_name) },
+      { label: "Added", value: val(formatDay(contact.created_at)) },
+      ...Object.entries(contact.custom_fields ?? {}).map(([k, v]) => ({ label: k, value: val(v) })),
+      ...(contact.about ? [{ label: "About", value: contact.about }] : []),
+    ]} />
+  );
+
+  return (
+    <>
+      <DetailPanel
+        title={name}
+        subtitle={[contact.job_title, contact.company?.name ?? contact.company_name].filter(Boolean).join(" at ") || "No title or company"}
+        avatar={<EntityAvatar name={name} kind="person" size="lg" />}
+        badges={isMasked(contact.work_email) ? <StatusPill tone="warning" dot>Locked email</StatusPill> : undefined}
+        onClose={onClose}
+        onExpand={full ? undefined : () => setFull(true)}
+        onCollapse={full ? () => setFull(false) : undefined}
+        actions={
+          <>
+            {partial ? null : renderActions?.(contact, { reload: () => { void query.refetch(); bump(); onChanged(); } })}
+            {contact.company?.id && onOpenCompany ? <Button variant="outline" size="sm" onClick={() => onOpenCompany(contact.company!.id as number)}><Building2 className="size-4" aria-hidden />Open company</Button> : null}
+            <Button variant="outline" size="sm" disabled={partial} title={partial ? "Loading the full record" : undefined} onClick={() => setEditing(true)}>Edit</Button>
+            <Button variant="destructive" size="sm" disabled={partial} onClick={() => setConfirm(true)}>Delete</Button>
+          </>
+        }
+        tabs={[
+          { id: "overview", label: "Overview", content: overview },
+          { id: "activity", label: "Activity", content: <ActivityTimeline entityType="contact" entityId={contactId} refreshKey={feedKey} /> },
+          { id: "notes", label: "Notes", content: <NotesPanel entity="contact" entityId={contactId} onChanged={bump} /> },
+          { id: "tasks", label: "Tasks", content: <TaskList entity="contact" entityId={contactId} onChanged={bump} /> },
+          ...(partial ? [] : extraTabs).map((t) => ({ id: t.id, label: t.label, content: t.render(contact) })),
+        ]}
+      />
+      {remove.error ? <div className="p-4"><ApiError error={remove.error} title="Could not delete the contact" /></div> : null}
+      <FormSheet open={editing && !partial} onOpenChange={setEditing} title={`Edit ${name}`}>
+        <RecordForm entity="contact" record={contact} onCancel={() => setEditing(false)} onSaved={() => { setEditing(false); void query.refetch(); bump(); onChanged(); }} />
+      </FormSheet>
+      <ConfirmSpendDialog open={confirm} tier="destructive" title={`Delete ${name}`} description="The contact is removed from every list and sequence." affected={1}
+        confirming={remove.loading} onConfirm={() => void remove.mutate(undefined)} onCancel={() => setConfirm(false)} />
+    </>
+  );
+}

package/blocks/crm/components/dedupe-review.tsx

@@ -29,6 +29,7 @@ import { useJobPoll } from "@/g8/hooks/use-job-poll";
 import { usePaginated } from "@/g8/hooks/use-paginated";
 import { g8Get, g8Post } from "@/g8/lib/g8-client";
 import { isMasked } from "../lib/crm-types";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface DedupeReviewProps {
   entity: "contact" | "company";
@@ -49,10 +50,11 @@ const CRITERIA = [
 function side(pair: Pair, s: "a" | "b", entity: "contact" | "company") {
   const name = entity === "contact" ? [pair[`${s}_first_name`], pair[`${s}_last_name`]].filter(Boolean).join(" ") : String(pair[`${s}_name`] ?? "");
   const lines = entity === "contact" ? [pair[`${s}_email`], pair[`${s}_phone`], pair[`${s}_owner_name`]] : [pair[`${s}_domain`], pair[`${s}_industry`], pair[`${s}_owner_name`]];
-  return { id: pair[`${s}_id`] as number, name: name || "Unnamed", lines: lines.filter(Boolean).map((l) => (isMasked(l) ? "Locked" : String(l))) };
+  return { id: pair[`${s}_id`] as number, name: name || String([pair[`${s}_email`], pair[`${s}_domain`]].find((v) => v && !isMasked(v)) ?? `#${pair[`${s}_id`]}`), lines: lines.filter(Boolean).map((l) => (isMasked(l) ? "Locked" : String(l))) };
 }
 
 export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps) {
+  const brand = useBrand();
   const plural = entity === "contact" ? "contacts" : "companies";
   const [merging, setMerging] = useState<{ pair: Pair; keep: "a" | "b" } | null>(null);
   const [picked, setPicked] = useState<Set<string>>(new Set());
@@ -73,9 +75,9 @@ export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps
   const merge = useG8Mutation((v: { pair: Pair; keep: "a" | "b" }) => {
     const keepId = v.pair[`${v.keep}_id`], dropId = v.pair[`${v.keep === "a" ? "b" : "a"}_id`];
     return g8Post(`/${plural}/${keepId}/merge`, { secondary_id: dropId, suggestion_id: v.pair.suggestion_id });
-  }, { onSuccess: (_r, v) => { dropPick(v.pair.suggestion_id); setMerging(null); refreshAll(); } });
-  const reject = useG8Mutation((id: string) => { setBusy(id); return g8Post(`/duplicates/${id}/reject`, {}); }, { onSuccess: (_r, id) => { dropPick(id); setBusy(null); refreshAll(); }, onError: () => setBusy(null) });
-  const undo = useG8Mutation((id: string) => { setBusy(id); return g8Post(`/duplicates/undo-merge/${id}`, {}); }, { onSuccess: () => { setBusy(null); refreshAll(); }, onError: () => setBusy(null) });
+  }, { invalidates: [plural, "duplicates"], onSuccess: (_r, v) => { dropPick(v.pair.suggestion_id); setMerging(null); refreshAll(); } });
+  const reject = useG8Mutation((id: string) => { setBusy(id); return g8Post(`/duplicates/${id}/reject`, {}); }, { invalidates: ["duplicates"], onSuccess: (_r, id) => { dropPick(id); setBusy(null); refreshAll(); }, onError: () => setBusy(null) });
+  const undo = useG8Mutation((id: string) => { setBusy(id); return g8Post(`/duplicates/undo-merge/${id}`, {}); }, { invalidates: [plural, "duplicates"], onSuccess: () => { setBusy(null); refreshAll(); }, onError: () => setBusy(null) });
   const bulk = useG8Mutation(() => g8Post<{ run_id: string }>("/duplicates/bulk-merge", { suggestion_ids: [...picked], criterion }), {
     onSuccess: (r) => { setBulkOpen(false); setRunId(r.data.run_id); },
   });
@@ -109,7 +111,7 @@ export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps
           {run.polling || run.status ? <p role="status" className="text-sm text-muted-foreground">Merging: {run.status?.merged ?? 0} of {run.status?.total ?? picked.size} done, {run.status?.blocked ?? 0} blocked.</p> : null}
           {mergeError ? <ApiError error={mergeError} title="That did not go through" /> : null}
           {pairs.error ? <ApiError error={pairs.error} title="Could not load duplicates" onRetry={() => void pairs.reload()} /> : null}
-          {!pairs.loading && !pairs.error && pairs.items.length === 0 ? <EmptyState title="No duplicates to review" description="New suggestions appear here when graph8 finds likely matches." /> : null}
+          {!pairs.loading && !pairs.error && pairs.items.length === 0 ? <EmptyState title="No duplicates to review" description={`New suggestions appear here when ${brand.linkLabel} finds likely matches.`} /> : null}
 
           {pairs.items.map((pair) => (
             <div key={pair.suggestion_id} className="rounded-md border p-3" data-testid="duplicate-pair">

package/blocks/crm/components/import-wizard.tsx

@@ -24,6 +24,7 @@ import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface ImportWizardProps {
   /** Largest file accepted. Default 5 MiB: the /api/g8 proxy rejects bigger bodies (raise maxBodyBytes there first). */
@@ -68,6 +69,7 @@ export function guessMapping(columns: string[]): Record<string, string> {
 }
 
 export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, className }: ImportWizardProps) {
+  const brand = useBrand();
   const [tooBig, setTooBig] = useState<string | null>(null);
   const [upload, setUpload] = useState<Upload | null>(null);
   const [mapping, setMapping] = useState<Record<string, string>>({});
@@ -167,7 +169,7 @@ export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, c
               </div>
             ) : null}
             <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={policy === "override"} onChange={(e) => setPolicy(e.target.checked ? "override" : "autofill")} /> Overwrite existing values (default only fills blanks)</label>
-            <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={enrich} onChange={(e) => setEnrich(e.target.checked)} /> Fill missing fields from graph8 (uses credits)</label>
+            <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={enrich} onChange={(e) => setEnrich(e.target.checked)} /> Fill missing fields from {brand.linkLabel} (uses credits)</label>
           </section>
 
           {run.error ? <ApiError error={run.error} title="The import failed" /> : null}
@@ -181,7 +183,7 @@ export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, c
         open={confirmOpen}
         tier={enrich ? "billable" : "destructive"}
         title={`Import ${rows.toLocaleString()} rows`}
-        description={policy === "override" ? "Matching contacts get their existing values replaced by the file." : "Missing fields are filled from graph8."}
+        description={policy === "override" ? "Matching contacts get their existing values replaced by the file." : `Missing fields are filled from ${brand.linkLabel}.`}
         affected={enrich ? undefined : rows}
         confirming={run.loading}
         confirmLabel="Import"

package/blocks/crm/components/notes-panel.tsx

@@ -45,11 +45,11 @@ export function NotesPanel({ entity, entityId, onChanged, className }: NotesPane
   const [editing, setEditing] = useState<{ id: string; content: string } | null>(null);
   const [deleting, setDeleting] = useState<NoteItem | null>(null);
 
-  const notes = useG8Query((signal) => g8Get<NoteItem[]>(base, undefined, { signal }), [base]);
+  const notes = useG8Query((signal) => g8Get<NoteItem[]>(base, undefined, { signal }), [base], { key: ["notes", entity, entityId] });
   const done = () => { void notes.refetch(); onChanged?.(); };
-  const add = useG8Mutation((content: string) => g8Post(base, { content }), { onSuccess: () => { setDraft(""); done(); } });
-  const edit = useG8Mutation((v: { id: string; content: string }) => g8Patch(`/notes/${v.id}`, { content: v.content }), { onSuccess: () => { setEditing(null); done(); } });
-  const remove = useG8Mutation((id: string) => g8Delete(`/notes/${id}`), { onSuccess: () => { setDeleting(null); done(); } });
+  const add = useG8Mutation((content: string) => g8Post(base, { content }), { invalidates: [["notes", entity, entityId]], onSuccess: () => { setDraft(""); done(); } });
+  const edit = useG8Mutation((v: { id: string; content: string }) => g8Patch(`/notes/${v.id}`, { content: v.content }), { invalidates: [["notes"]], onSuccess: () => { setEditing(null); done(); } });
+  const remove = useG8Mutation((id: string) => g8Delete(`/notes/${id}`), { invalidates: [["notes"]], onSuccess: () => { setDeleting(null); done(); } });
 
   const items = (notes.data?.data ?? []) as NoteItem[];
   return (

package/blocks/crm/components/record-form.tsx

@@ -35,6 +35,8 @@ export interface RecordFormProps {
   /** Create only: a contact with the same identity exists; receives its id. */
   onDuplicate?: (existingId: number | undefined) => void;
   onCancel?: () => void;
+  /** Create only: prefill base fields, for example `{ company_domain: "acme.com" }`. */
+  defaults?: Record<string, string>;
   /** Show the inline "Add custom field" control. Default true. */
   allowNewFields?: boolean;
   className?: string;
@@ -94,13 +96,13 @@ export function RecordForm(props: RecordFormProps) {
   const [newType, setNewType] = useState("text");
   const [validation, setValidation] = useState<string | null>(null);
 
-  const initial = initialValues(base, record, custom.fields);
+  const initial = { ...initialValues(base, record, custom.fields), ...(record ? {} : props.defaults ?? {}) };
   const value = (key: string) => edits[key] ?? initial[key] ?? "";
   const set = (key: string, v: string) => setEdits((e) => ({ ...e, [key]: v }));
 
   const addField = useG8Mutation(
     (title: string) => g8Post("/fields", { title, data_type: newType, entity: plural, list_id: listId ?? null }),
-    { onSuccess: () => { setNewTitle(""); void custom.refetch(); } },
+    { invalidates: ["fields"], onSuccess: () => { setNewTitle(""); void custom.refetch(); } },
   );
 
   const save = useG8Mutation(async () => {
@@ -126,7 +128,7 @@ export function RecordForm(props: RecordFormProps) {
       await g8Patch("/fields/values/batch", { entity: plural, rows: [{ record_id: id, fields: toWrite.map((f) => ({ column_id: f.id, value: value(`cf:${f.name}`) || null })) }] });
     }
     return { id: id as number, merged };
-  }, { onSuccess: (r) => props.onSaved?.(r) });
+  }, { invalidates: [plural], onSuccess: (r) => props.onSaved?.(r) });
 
   const submit = (event: FormEvent) => {
     event.preventDefault();

package/blocks/crm/components/task-list.tsx

@@ -51,14 +51,14 @@ export function TaskList({ entity, entityId, includeCompleted = false, onChanged
   const [showDone, setShowDone] = useState(includeCompleted);
   const [deleting, setDeleting] = useState<TaskItem | null>(null);
 
-  const tasks = useG8Query((signal) => g8Get<TaskItem[]>(base, { status: showDone ? undefined : "open" }, { signal }), [base, showDone]);
+  const tasks = useG8Query((signal) => g8Get<TaskItem[]>(base, { status: showDone ? undefined : "open" }, { signal }), [base, showDone], { key: ["tasks", "record", entity, entityId, { showDone }] });
   const done = () => { void tasks.refetch(); onChanged?.(); };
   const add = useG8Mutation(
     () => g8Post(base, { title: title.trim(), priority, ...(due ? { due_date: due } : {}) }),
-    { onSuccess: () => { setTitle(""); setDue(""); done(); } },
+    { invalidates: [["tasks"]], onSuccess: () => { setTitle(""); setDue(""); done(); } },
   );
-  const toggle = useG8Mutation((t: TaskItem) => g8Patch(`/tasks/${t.id}`, { status: t.status === "completed" ? "open" : "completed" }), { onSuccess: done });
-  const remove = useG8Mutation((id: string) => g8Delete(`/tasks/${id}`), { onSuccess: () => { setDeleting(null); done(); } });
+  const toggle = useG8Mutation((t: TaskItem) => g8Patch(`/tasks/${t.id}`, { status: t.status === "completed" ? "open" : "completed" }), { invalidates: [["tasks"]], onSuccess: done });
+  const remove = useG8Mutation((id: string) => g8Delete(`/tasks/${id}`), { invalidates: [["tasks"]], onSuccess: () => { setDeleting(null); done(); } });
 
   const items = (tasks.data?.data ?? []) as TaskItem[];
   return (