@graph8/sdk 0.308.1 → 0.357.0

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

@@ -0,0 +1,164 @@
+"use client";
+
+/**
+ * DedupeReview: work through pending duplicate suggestions for contacts or
+ * companies. Merge one pair by choosing the record to keep, mark a pair as "not
+ * duplicates", merge many with a rule (polled to completion), and undo recent merges.
+ *
+ * SDK operations, in order:
+ *   1. duplicateCounts     GET  /duplicates/counts?entity_type            (read)         badge
+ *   2. listDuplicates      GET  /duplicates?entity_type&status=pending&cursor   (read)   pairs, cursor-paginated
+ *   3. rejectSuggestion    POST /duplicates/{suggestion_id}/reject         (write)       "not duplicates"
+ *   4. mergeContact | mergeCompany   POST /contacts/{keep}/merge | /companies/{keep}/merge   (destructive, ConfirmSpendDialog)
+ *   5. startBulkMerge      POST /duplicates/bulk-merge  -> run_id          (write, needs contacts:delete) behind ConfirmSpendDialog
+ *      getBulkMergeStatus  GET  /duplicates/bulk-merge/{run_id}            (read)        polled with useJobPoll until `completed`
+ *   6. listRecentMerges    GET  /duplicates/recent-merges                  (read)
+ *      undoMerge           POST /duplicates/undo-merge/{id}                (write)       only rows with can_undo
+ *
+ * A merge is destructive: the record that is not kept stops existing (undo is possible for 30 days).
+ */
+
+import { useState } from "react";
+import { Button, Tabs, TabsContent, TabsList, TabsTrigger } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+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";
+
+export interface DedupeReviewProps {
+  entity: "contact" | "company";
+  /** Called after a merge or undo, so tables can reload. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+type Pair = Record<string, string | number | null | undefined> & { suggestion_id: string; a_id: number; b_id: number; confidence?: string };
+interface MergeRow { id: string; primary_name?: string | null; secondary_name?: string | null; merged_at?: string | null; undone_at?: string | null; can_undo: boolean }
+interface BulkRun { status: "running" | "completed"; total: number; merged: number; blocked: number; stale: number }
+
+const CRITERIA = [
+  ["most_recent_engagement", "Most recent engagement"], ["oldest_engagement", "Oldest engagement"],
+  ["created_first", "Created first"], ["created_last", "Created last"], ["most_recently_updated", "Most recently updated"],
+] as const;
+
+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))) };
+}
+
+export function DedupeReview({ entity, onChanged, className }: DedupeReviewProps) {
+  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());
+  const [criterion, setCriterion] = useState<(typeof CRITERIA)[number][0]>("most_recent_engagement");
+  const [bulkOpen, setBulkOpen] = useState(false);
+  const [runId, setRunId] = useState<string | null>(null);
+
+  const counts = useG8Query((signal) => g8Get<{ pending?: number; count?: number }>("/duplicates/counts", { entity_type: entity }, { signal }), [entity]);
+  const pairs = usePaginated<Pair>(async (cursor, signal) => {
+    const res = await g8Get<{ items: Pair[]; next_cursor?: string | null }>("/duplicates", { entity_type: entity, status: "pending", limit: 25, cursor }, { signal });
+    return { data: res.data.items ?? [], pagination: { next_cursor: res.data.next_cursor ?? null } };
+  }, [entity]);
+  const recent = useG8Query((signal) => g8Get<MergeRow[]>("/duplicates/recent-merges", { entity_type: entity, limit: 25 }, { signal }), [entity]);
+  const [busy, setBusy] = useState<string | null>(null);
+  const dropPick = (id: string | undefined) => id && setPicked((p) => { const n = new Set(p); n.delete(id); return n; });
+  const refreshAll = () => { void pairs.reload(); void counts.refetch(); void recent.refetch(); onChanged?.(); };
+
+  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) });
+  const bulk = useG8Mutation(() => g8Post<{ run_id: string }>("/duplicates/bulk-merge", { suggestion_ids: [...picked], criterion }), {
+    onSuccess: (r) => { setBulkOpen(false); setRunId(r.data.run_id); },
+  });
+  const run = useJobPoll<BulkRun>(
+    async (signal) => (await g8Get<BulkRun>(`/duplicates/bulk-merge/${runId}`, undefined, { signal })).data,
+    { enabled: runId != null, isTerminal: (s) => s.status === "completed", onDone: () => { setPicked(new Set()); setRunId(null); refreshAll(); } },
+  );
+
+  const pending = counts.data?.data.pending ?? counts.data?.data.count;
+  const togglePick = (id: string) => setPicked((p) => { const n = new Set(p); if (!n.delete(id)) n.add(id); return n; });
+  const mergeError = merge.error ?? reject.error ?? undo.error ?? bulk.error;
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <Tabs defaultValue="pending">
+        <TabsList>
+          <TabsTrigger value="pending">Suggestions{pending != null ? ` (${pending})` : ""}</TabsTrigger>
+          <TabsTrigger value="recent">Recent merges</TabsTrigger>
+        </TabsList>
+
+        <TabsContent value="pending" className="flex flex-col gap-3 pt-3">
+          {picked.size > 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>{picked.size} pairs selected, keep the record with</span>
+              <select aria-label="Merge rule" className="h-8 rounded-md border bg-background px-2" value={criterion} onChange={(e) => setCriterion(e.target.value as typeof criterion)}>
+                {CRITERIA.map(([v, l]) => <option key={v} value={v}>{l}</option>)}
+              </select>
+              <Button size="sm" variant="destructive" loading={run.polling} onClick={() => setBulkOpen(true)}>Merge selected</Button>
+            </div>
+          ) : null}
+          {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.items.map((pair) => (
+            <div key={pair.suggestion_id} className="rounded-md border p-3" data-testid="duplicate-pair">
+              <div className="grid grid-cols-1 gap-3 sm:grid-cols-[auto_1fr_1fr]">
+                <input type="checkbox" aria-label="Select pair" checked={picked.has(pair.suggestion_id)} onChange={() => togglePick(pair.suggestion_id)} />
+                {(["a", "b"] as const).map((s) => {
+                  const r = side(pair, s, entity);
+                  return (
+                    <div key={s}>
+                      <p className="text-sm font-medium">{r.name}</p>
+                      {r.lines.map((l) => <p key={l} className="text-xs text-muted-foreground">{l}</p>)}
+                      <Button className="mt-2" size="sm" variant="outline" onClick={() => setMerging({ pair, keep: s })}>Keep this one</Button>
+                    </div>
+                  );
+                })}
+              </div>
+              <div className="mt-2 flex justify-end">
+                <Button size="sm" variant="ghost" loading={reject.loading && busy === pair.suggestion_id} onClick={() => void reject.mutate(pair.suggestion_id)}>Not duplicates</Button>
+              </div>
+            </div>
+          ))}
+          {pairs.hasMore ? <Button variant="outline" size="sm" loading={pairs.loadingMore} onClick={() => void pairs.loadMore()}>Load more</Button> : null}
+        </TabsContent>
+
+        <TabsContent value="recent" className="flex flex-col gap-2 pt-3">
+          {recent.error ? <ApiError error={recent.error} title="Could not load recent merges" onRetry={() => void recent.refetch()} /> : null}
+          {(recent.data?.data ?? []).length === 0 && !recent.loading ? <EmptyState title="No merges yet" /> : null}
+          {(recent.data?.data ?? []).map((m) => (
+            <div key={m.id} className="flex items-center justify-between rounded-md border p-3 text-sm">
+              <span>{m.secondary_name ?? "Record"} merged into {m.primary_name ?? "record"}{m.merged_at ? `, ${new Date(m.merged_at).toLocaleDateString()}` : ""}{m.undone_at ? " (undone)" : ""}</span>
+              {m.can_undo ? <Button size="sm" variant="outline" loading={undo.loading && busy === m.id} onClick={() => void undo.mutate(m.id)}>Undo</Button> : null}
+            </div>
+          ))}
+        </TabsContent>
+      </Tabs>
+
+      <ConfirmSpendDialog
+        open={merging != null}
+        tier="destructive"
+        title={merging ? `Keep ${side(merging.pair, merging.keep, entity).name}` : ""}
+        description={merging ? `${side(merging.pair, merging.keep === "a" ? "b" : "a", entity).name} is merged into it and stops existing. You can undo for 30 days.` : undefined}
+        affected={1}
+        confirmLabel="Merge"
+        confirming={merge.loading}
+        onConfirm={() => merging && void merge.mutate(merging)}
+        onCancel={() => setMerging(null)}
+      />
+      <ConfirmSpendDialog open={bulkOpen} tier="destructive" title={`Merge ${picked.size} pairs`} description="The surviving record of each pair is chosen by the rule you picked."
+        affected={picked.size} confirmLabel="Merge" confirming={bulk.loading} onConfirm={() => void bulk.mutate(undefined)} onCancel={() => setBulkOpen(false)} />
+    </div>
+  );
+}

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

@@ -0,0 +1,193 @@
+"use client";
+
+/**
+ * ImportWizard: bring a CSV or Excel file into a list in four steps:
+ * upload, map columns (with a live preview), choose destination and policy, import.
+ *
+ * SDK operations, in order:
+ *   1. uploadImportFile    POST /imports                       (write)  multipart `file`; returns datafile_id, row_count, columns
+ *   2. previewImportFile   POST /imports/{datafile_id}/preview (read)   body = the column mapping you intend to import with
+ *   3. listLists           GET  /lists                         (read)   destination picker
+ *      createList          POST /lists                         (write)  optional "new list"
+ *   4. importContacts      POST /imports/{datafile_id}/contacts (write) list_id, column_mapping, update_policy, enrich_from_graph8
+ *
+ * The importer drops columns it cannot recognise SILENTLY, so the mapping is always sent
+ * explicitly and previewed first. `update_policy` defaults to autofill here (the API default,
+ * override, replaces existing values): choosing override, or enriching from graph8, goes
+ * through ConfirmSpendDialog before anything is written.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input, Label, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+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";
+
+export interface ImportWizardProps {
+  /** Largest file accepted. Default 5 MiB: the /api/g8 proxy rejects bigger bodies (raise maxBodyBytes there first). */
+  maxBytes?: number;
+  /** Preselect a destination and skip the picker. */
+  listId?: number;
+  onImported?: (result: ImportResult) => void;
+  className?: string;
+}
+
+export interface ImportResult { imported?: number | null; updated?: number | null; skipped?: number | null; failed?: number | null; list_id?: number | null }
+interface Upload { datafile_id: string; row_count?: number | null; columns: string[] }
+interface Preview { rows: Array<Record<string, unknown>>; total: number }
+interface ListOption { id: number; title: string; type?: string | null }
+
+export const IMPORT_TARGETS: Array<{ value: string; label: string }> = [
+  { value: "CONTACT_FIRST_NAME", label: "First name" }, { value: "CONTACT_LAST_NAME", label: "Last name" },
+  { value: "CONTACT_WORK_EMAIL", label: "Work email" }, { value: "CONTACT_PERSONAL_EMAILS", label: "Personal email" },
+  { value: "CONTACT_DIRECT_PHONE", label: "Direct phone" }, { value: "CONTACT_MOBILE_PHONE", label: "Mobile phone" },
+  { value: "CONTACT_JOB_TITLE", label: "Job title" }, { value: "CONTACT_JOB_DEPARTMENT", label: "Department" },
+  { value: "CONTACT_SENIORITY_LEVEL", label: "Seniority" }, { value: "CONTACT_LINKEDIN_URL", label: "LinkedIn URL" },
+  { value: "CONTACT_CITY", label: "City" }, { value: "CONTACT_STATE", label: "State" },
+  { value: "CONTACT_COUNTRY", label: "Country" }, { value: "COMPANY_DOMAIN", label: "Company domain" },
+];
+
+const GUESSES: Array<[RegExp, string]> = [
+  [/^(work[\s_-]?)?e-?mail/i, "CONTACT_WORK_EMAIL"], [/first/i, "CONTACT_FIRST_NAME"], [/last|surname/i, "CONTACT_LAST_NAME"],
+  [/title|position/i, "CONTACT_JOB_TITLE"], [/linkedin/i, "CONTACT_LINKEDIN_URL"], [/mobile|cell/i, "CONTACT_MOBILE_PHONE"],
+  [/phone/i, "CONTACT_DIRECT_PHONE"], [/seniority|level/i, "CONTACT_SENIORITY_LEVEL"], [/department/i, "CONTACT_JOB_DEPARTMENT"],
+  [/city/i, "CONTACT_CITY"], [/state|region/i, "CONTACT_STATE"], [/country/i, "CONTACT_COUNTRY"], [/domain|website/i, "COMPANY_DOMAIN"],
+];
+
+/** A first guess at where each file column goes; every target is used at most once. */
+export function guessMapping(columns: string[]): Record<string, string> {
+  const used = new Set<string>();
+  const out: Record<string, string> = {};
+  for (const col of columns) {
+    const hit = GUESSES.find(([re, target]) => re.test(col) && !used.has(target));
+    if (hit) { out[col] = hit[1]; used.add(hit[1]); }
+  }
+  return out;
+}
+
+export function ImportWizard({ listId, onImported, maxBytes = 5 * 1024 * 1024, className }: ImportWizardProps) {
+  const [tooBig, setTooBig] = useState<string | null>(null);
+  const [upload, setUpload] = useState<Upload | null>(null);
+  const [mapping, setMapping] = useState<Record<string, string>>({});
+  const [destination, setDestination] = useState<number | undefined>(listId);
+  const [newListTitle, setNewListTitle] = useState("");
+  const [policy, setPolicy] = useState<"autofill" | "override">("autofill");
+  const [enrich, setEnrich] = useState(false);
+  const [confirmOpen, setConfirmOpen] = useState(false);
+  const [result, setResult] = useState<ImportResult | null>(null);
+
+  const lists = useG8Query((signal) => g8Get<ListOption[]>("/lists", { limit: 200 }, { signal }), [], { enabled: upload != null && listId == null });
+  const send = useG8Mutation((file: File) => { const body = new FormData(); body.append("file", file); return g8Post<Upload>("/imports", body); }, {
+    onSuccess: (r) => { setUpload(r.data); setMapping(guessMapping(r.data.columns ?? [])); },
+  });
+  const preview = useG8Mutation((m: Record<string, string>) => g8Post<Preview>(`/imports/${upload!.datafile_id}/preview`, m, { query: { page: 1, limit: 5 } }));
+  const createList = useG8Mutation((title: string) => g8Post<{ id: number }>("/lists", { title, type: "contacts" }));
+  const run = useG8Mutation(async () => {
+    let target = destination;
+    if (target == null && newListTitle.trim()) {
+      target = (await createList.mutateAsync(newListTitle.trim())).data.id;
+      setDestination(target); // a failed import must retry into THIS list, not create a second one
+    }
+    const res = await g8Post<ImportResult>(`/imports/${upload!.datafile_id}/contacts`, { list_id: target, column_mapping: mapping, update_policy: policy, enrich_from_graph8: enrich });
+    return res.data;
+  }, { onSuccess: (r) => { setConfirmOpen(false); setResult(r); onImported?.(r); } });
+
+  useEffect(() => { if (upload) void preview.mutate(mapping); }, [upload, mapping]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const mapped = Object.values(mapping).filter(Boolean);
+  const hasIdentity = mapped.includes("CONTACT_WORK_EMAIL") || mapped.includes("CONTACT_LINKEDIN_URL");
+  const ready = upload != null && hasIdentity && (destination != null || newListTitle.trim().length > 0);
+  const needsConfirm = policy === "override" || enrich;
+  const rows = upload?.row_count ?? preview.data?.data.total ?? 0;
+
+  if (result) {
+    return (
+      <div className={`flex flex-col gap-3 ${className ?? ""}`} role="status">
+        <h3 className="text-base font-semibold">Import finished</h3>
+        <p className="text-sm">{result.imported ?? 0} new, {result.updated ?? 0} updated, {result.skipped ?? 0} skipped, {result.failed ?? 0} failed.</p>
+        <Button variant="outline" onClick={() => { setResult(null); setUpload(null); setMapping({}); setDestination(listId); setNewListTitle(""); setPolicy("autofill"); setEnrich(false); run.reset(); preview.reset(); }}>Import another file</Button>
+      </div>
+    );
+  }
+  return (
+    <div className={`flex flex-col gap-5 ${className ?? ""}`}>
+      <section className="flex flex-col gap-2">
+        <Label htmlFor="import-file">1. File (CSV or Excel, up to {Math.round(maxBytes / 1024 / 1024)} MB)</Label>
+        <Input id="import-file" type="file" accept=".csv,.xlsx,.xls" onChange={(e) => {
+          const f = e.target.files?.[0];
+          if (!f) return;
+          if (f.size > maxBytes) return setTooBig(`${f.name} is ${(f.size / 1024 / 1024).toFixed(1)} MB. Files over ${Math.round(maxBytes / 1024 / 1024)} MB need a higher maxBodyBytes in the /api/g8 route (see the block README), or a server-side import.`);
+          setTooBig(null);
+          void send.mutate(f);
+        }} />
+        {tooBig ? <p role="alert" className="text-sm text-destructive">{tooBig}</p> : null}
+        {send.loading ? <p className="text-sm text-muted-foreground">Uploading...</p> : null}
+        {send.error ? <ApiError error={send.error} title="Could not read that file" /> : null}
+      </section>
+
+      {upload ? (
+        <>
+          <section className="flex flex-col gap-2">
+            <h3 className="text-sm font-medium">2. Map columns ({upload.row_count ?? "?"} rows)</h3>
+            <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+              {upload.columns.map((col) => (
+                <label key={col} className="flex items-center justify-between gap-2 text-sm">
+                  <span className="truncate font-medium">{col}</span>
+                  <select aria-label={`Map ${col}`} className="h-9 w-48 rounded-md border bg-background px-2" value={mapping[col] ?? ""}
+                    onChange={(e) => setMapping((m) => { const next = { ...m }; if (e.target.value) next[col] = e.target.value; else delete next[col]; return next; })}>
+                    <option value="">Skip this column</option>
+                    {IMPORT_TARGETS.map((t) => <option key={t.value} value={t.value}>{t.label}</option>)}
+                  </select>
+                </label>
+              ))}
+            </div>
+            {!hasIdentity ? <p role="alert" className="text-sm text-destructive">Map a work email or a LinkedIn URL column so contacts can be matched.</p> : null}
+            {preview.error ? <ApiError error={preview.error} title="Could not preview the file" /> : null}
+            {preview.data?.data.rows.length ? (
+              <div className="overflow-x-auto rounded-md border">
+                <Table>
+                  <TableHeader><TableRow>{Object.keys(preview.data.data.rows[0]).map((k) => <TableHead key={k}>{k}</TableHead>)}</TableRow></TableHeader>
+                  <TableBody>{preview.data.data.rows.map((r, i) => <TableRow key={i}>{Object.values(r).map((v, j) => <TableCell key={j}>{String(v ?? "")}</TableCell>)}</TableRow>)}</TableBody>
+                </Table>
+              </div>
+            ) : null}
+          </section>
+
+          <section className="flex flex-col gap-3">
+            <h3 className="text-sm font-medium">3. Destination and rules</h3>
+            {listId == null ? (
+              <div className="flex flex-wrap items-center gap-2">
+                <select aria-label="Destination list" className="h-9 rounded-md border bg-background px-2 text-sm" value={destination ?? ""} onChange={(e) => setDestination(e.target.value ? Number(e.target.value) : undefined)}>
+                  <option value="">New list...</option>
+                  {(lists.data?.data ?? []).filter((l) => !l.type || l.type === "contacts").map((l) => <option key={l.id} value={l.id}>{l.title}</option>)}
+                </select>
+                {destination == null ? <Input aria-label="New list name" placeholder="New list name" className="w-56" value={newListTitle} onChange={(e) => setNewListTitle(e.target.value)} /> : null}
+              </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>
+          </section>
+
+          {run.error ? <ApiError error={run.error} title="The import failed" /> : null}
+          <div className="flex justify-end">
+            <Button disabled={!ready} loading={run.loading && !confirmOpen} onClick={() => (needsConfirm ? setConfirmOpen(true) : void run.mutate(undefined))}>Import {rows.toLocaleString()} rows</Button>
+          </div>
+        </>
+      ) : null}
+
+      <ConfirmSpendDialog
+        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."}
+        affected={enrich ? undefined : rows}
+        confirming={run.loading}
+        confirmLabel="Import"
+        onConfirm={() => void run.mutate(undefined)}
+        onCancel={() => setConfirmOpen(false)}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,112 @@
+"use client";
+
+/**
+ * NotesPanel: list, add, edit and delete notes on a contact or a company.
+ *
+ * SDK operations, in order:
+ *   1. listNotes | listCompanyNotes          GET    /contacts/{id}/notes | /companies/{id}/notes   (read)
+ *   2. createNote | createCompanyNote        POST   same path                                      (write)
+ *   3. updateNote                            PATCH  /notes/{note_id}                               (write)
+ *   4. deleteNote                            DELETE /notes/{note_id}                               (destructive, ConfirmSpendDialog)
+ *
+ * `read_only` notes (projected from synced CRM activity) cannot be edited or deleted.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+
+export interface NoteItem {
+  id: string;
+  content: string;
+  created_by_name?: string | null;
+  created_by?: string | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+  read_only?: boolean;
+}
+
+export interface NotesPanelProps {
+  entity: "contact" | "company";
+  entityId: number;
+  /** Called after any write, so a sibling ActivityTimeline can reload. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+export function NotesPanel({ entity, entityId, onChanged, className }: NotesPanelProps) {
+  const base = `/${entity === "contact" ? "contacts" : "companies"}/${entityId}/notes`;
+  const [draft, setDraft] = useState("");
+  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 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 items = (notes.data?.data ?? []) as NoteItem[];
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <form
+        className="flex flex-col gap-2"
+        onSubmit={(e) => { e.preventDefault(); if (draft.trim()) void add.mutate(draft.trim()); }}
+      >
+        <Textarea aria-label="New note" placeholder="Write a note" rows={3} value={draft} onChange={(e) => setDraft(e.target.value)} />
+        <div className="flex justify-end"><Button type="submit" size="sm" loading={add.loading} disabled={!draft.trim()}>Add note</Button></div>
+      </form>
+      {add.error ? <ApiError error={add.error} title="Could not add the note" /> : null}
+      {edit.error ? <ApiError error={edit.error} title="Could not save the note" /> : null}
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the note" /> : null}
+      {notes.error ? <ApiError error={notes.error} title="Could not load notes" onRetry={() => void notes.refetch()} /> : null}
+      {notes.loading && !notes.data ? <Skeleton className="h-16 w-full" /> : null}
+      {!notes.loading && !notes.error && items.length === 0 ? <EmptyState title="No notes yet" description="Notes are visible to everyone who can see this record." /> : null}
+
+      <ul className="flex flex-col gap-2">
+        {items.map((n) => (
+          <li key={n.id} className="rounded-md border p-3" data-testid="note-item">
+            {editing?.id === n.id ? (
+              <div className="flex flex-col gap-2">
+                <Textarea aria-label="Edit note" rows={3} value={editing.content} onChange={(e) => setEditing({ id: n.id, content: e.target.value })} />
+                <div className="flex justify-end gap-2">
+                  <Button variant="ghost" size="sm" onClick={() => setEditing(null)}>Cancel</Button>
+                  <Button size="sm" loading={edit.loading} disabled={!editing.content.trim()} onClick={() => void edit.mutate(editing)}>Save</Button>
+                </div>
+              </div>
+            ) : (
+              <>
+                <p className="whitespace-pre-wrap text-sm">{n.content}</p>
+                <div className="mt-2 flex items-center justify-between text-xs text-muted-foreground">
+                  <span>{n.created_by_name ?? n.created_by ?? "Unknown"}{n.created_at ? `, ${new Date(n.created_at).toLocaleString()}` : ""}</span>
+                  {n.read_only ? <span>Synced, read only</span> : (
+                    <span className="flex gap-1">
+                      <Button variant="ghost" size="sm" onClick={() => setEditing({ id: n.id, content: n.content })}>Edit</Button>
+                      <Button variant="ghost" size="sm" onClick={() => setDeleting(n)}>Delete</Button>
+                    </span>
+                  )}
+                </div>
+              </>
+            )}
+          </li>
+        ))}
+      </ul>
+
+      <ConfirmSpendDialog
+        open={deleting != null}
+        tier="destructive"
+        title="Delete this note"
+        description={deleting?.content.slice(0, 120)}
+        affected={1}
+        confirming={remove.loading}
+        onConfirm={() => deleting && void remove.mutate(deleting.id)}
+        onCancel={() => setDeleting(null)}
+      />
+    </div>
+  );
+}