@graph8/sdk 0.373.0 → 0.374.0

package/blocks/crm/components/bulk-update.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+/**
+ * BulkUpdateButton: set ONE field to the same value on every selected contact (job title, department, seniority, city,
+ * state, country). A dialog asks for the field and the value and says how many contacts change.
+ *
+ * SDK operations:
+ *   1. bulkUpdateContacts  POST /contacts/bulk-update  [{ id, CONTACT_<FIELD>: value }, ...]   (write)
+ *        The body is one object per contact. The API authorises the WHOLE set before the first write, so a contact the
+ *        key cannot write refuses the whole chunk; failures after that are reported per contact in `errors`, not as an
+ *        HTTP error. The selection is sent in chunks of 100 with Promise.allSettled so one refused chunk does not hide
+ *        the others, and the dialog reports "N of M updated".
+ *
+ * The value is required: the API gives no documented way to clear a field in bulk, so clearing is not offered (use the
+ * contact's own Edit form). The owner and tags have their own actions.
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "@graph8/sdk/ui";
+import { ListChecks } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import { BULK_FIELDS } from "../lib/record-actions";
+import type { BulkFieldKey } from "../lib/record-actions";
+
+const CHUNK = 100;
+
+export interface BulkUpdateButtonProps {
+  contactIds: ReadonlyArray<number>;
+  /** Called with the ids that were updated, so the screen can refetch. */
+  onDone?: (updated: number[]) => void;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+  className?: string;
+}
+
+interface BulkResult { updated: number[]; failed: Array<{ id: number; error: string }>; refusedChunks: number }
+
+/** `{ updated, errors: [{ id, error }] }` from one chunk; ids not named as failed count as updated. */
+export function chunkOutcome(ids: number[], data: unknown): { ok: number[]; failed: Array<{ id: number; error: string }> } {
+  const errors = ((data as { errors?: Array<{ id?: unknown; error?: unknown }> } | null)?.errors ?? [])
+    .map((e) => ({ id: Number(e.id), error: String(e.error ?? "Update failed.") }))
+    .filter((e) => Number.isFinite(e.id));
+  const bad = new Set(errors.map((e) => e.id));
+  return { ok: ids.filter((id) => !bad.has(id)), failed: errors };
+}
+
+export function BulkUpdateButton({ contactIds, onDone, variant = "outline", size = "sm", className }: BulkUpdateButtonProps) {
+  const [open, setOpen] = useState(false);
+  const [field, setField] = useState<BulkFieldKey>(BULK_FIELDS[0].key);
+  const [value, setValue] = useState("");
+  const [result, setResult] = useState<(BulkResult & { total: number; label: string }) | null>(null);
+  const label = BULK_FIELDS.find((f) => f.key === field)?.label ?? field;
+
+  const run = useG8Mutation(async (v: { ids: number[]; field: BulkFieldKey; value: string }): Promise<BulkResult> => {
+    const chunks: number[][] = [];
+    for (let i = 0; i < v.ids.length; i += CHUNK) chunks.push(v.ids.slice(i, i + CHUNK));
+    const settled = await Promise.allSettled(chunks.map((ids) => g8Post("/contacts/bulk-update", ids.map((id) => ({ id, [v.field]: v.value })))));
+    const out: BulkResult = { updated: [], failed: [], refusedChunks: 0 };
+    settled.forEach((s, i) => {
+      if (s.status === "rejected") { out.refusedChunks += 1; return; }
+      const o = chunkOutcome(chunks[i], s.value.data);
+      out.updated.push(...o.ok);
+      out.failed.push(...o.failed);
+    });
+    if (out.updated.length === 0 && out.refusedChunks === chunks.length && settled[0]?.status === "rejected") throw (settled[0] as PromiseRejectedResult).reason;
+    return out;
+  }, {
+    invalidates: [["contacts", "list"], ["contacts", "detail"], ["contacts", "record"]],
+    onSuccess: (r, v) => { setResult({ ...r, total: v.ids.length, label }); onDone?.(r.updated); },
+  });
+
+  const close = () => { setOpen(false); setValue(""); setResult(null); run.reset(); };
+  const count = contactIds.length;
+  const trimmed = value.trim();
+
+  return (
+    <>
+      <Button className={className} variant={variant} size={size} disabled={count === 0} onClick={() => setOpen(true)}><ListChecks className="size-4" aria-hidden />Bulk edit</Button>
+      <Dialog open={open} onOpenChange={(o) => (o ? setOpen(true) : close())}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Edit {plural(count, "contact")}</DialogTitle>
+            <DialogDescription>The same value is written to every selected contact. Existing values are replaced.</DialogDescription>
+          </DialogHeader>
+          {result ? (
+            <div role="status" className="text-sm">
+              <p className="font-medium">Updated {result.updated.length.toLocaleString()} of {result.total.toLocaleString()} ({result.label}).</p>
+              {result.failed.length > 0 ? <p className="mt-1 text-destructive">{plural(result.failed.length, "contact")} could not be updated: {[...new Set(result.failed.map((f) => f.error))].join("; ")}</p> : null}
+              {result.refusedChunks > 0 ? <p className="mt-1 text-destructive">{plural(result.refusedChunks, "batch", "batches")} of up to {CHUNK} was refused by the server. Those contacts are unchanged.</p> : null}
+            </div>
+          ) : (
+            <div className="flex flex-col gap-3">
+              <label className="flex flex-col gap-1 text-sm">Field
+                <select className="h-9 rounded-md border bg-background px-2" value={field} onChange={(e) => setField(e.target.value as BulkFieldKey)}>
+                  {BULK_FIELDS.map((f) => <option key={f.key} value={f.key}>{f.label}</option>)}
+                </select>
+              </label>
+              <label className="flex flex-col gap-1 text-sm">New value
+                <input className="h-9 rounded-md border bg-background px-3" maxLength={200} value={value} onChange={(e) => setValue(e.target.value)} />
+              </label>
+              {run.error ? <ApiError error={run.error} title="Could not update the contacts" /> : null}
+            </div>
+          )}
+          <DialogFooter>
+            {result ? <Button onClick={close}>Done</Button> : (
+              <>
+                <Button variant="ghost" onClick={close}>Cancel</Button>
+                <Button loading={run.loading} disabled={!trimmed || count === 0} onClick={() => void run.mutate({ ids: [...contactIds], field, value: trimmed })}>Update {plural(count, "contact")}</Button>
+              </>
+            )}
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

package/blocks/crm/components/contact-documents-tab.tsx

@@ -0,0 +1,144 @@
+"use client";
+
+/**
+ * ContactDocumentsTab: the AI documents graph8 writes about ONE contact (outreach personalization, conversation prep,
+ * stakeholder intel, career timeline, relationship map, persona value prop, engagement digest). Shows which exist, which
+ * are being written, which failed; generate one, regenerate one, generate all, and read a finished one.
+ *
+ * SDK operations, in order:
+ *   1. getContactGenerationStatus  GET /contacts/{id}/documents/generation-status   (read; polled every 4 s while a document is generating)
+ *   2. getContactDocument          GET /contacts/{id}/documents/types/{doc_type}    (read, when "View" is opened)
+ *   3. generateContactDocument     POST /contacts/{id}/documents/types/{doc_type}/generate        (billable, ConfirmSpendDialog)
+ *   4. regenerateContactDocument   POST /contacts/{id}/documents/types/{doc_type}/regenerate      (billable, ConfirmSpendDialog)
+ *   5. generateAllContactDocuments POST /contacts/{id}/documents/generate-all                      (billable, ConfirmSpendDialog)
+ *
+ * Every document is a model call. graph8 publishes no price for them, so the confirm says that instead of showing an
+ * invented number. Regenerate replaces the stored text (and any inline edits to it), which the confirm states. The
+ * three writes only queue the work; the tab then follows the status until nothing is generating.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle } from "@graph8/sdk/ui";
+import { FileText, RefreshCw, Sparkles } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { formatDay } from "../lib/screen-parts";
+
+/** The seven synthesis documents the API generates (campaign_builder/models/contact_documents.py CONTACT_SYNTHESIS_STEPS). */
+export const CONTACT_DOC_TYPES = [
+  "outreach_personalization", "conversation_prep", "stakeholder_intel", "career_trigger_timeline", "relationship_map", "persona_value_prop", "engagement_digest",
+] as const;
+
+interface DocStatus { id?: string; doc_type: string; status?: string; title?: string | null; folder?: string | null; updated_at?: string | null }
+interface GenStatus { is_generating?: boolean; total?: number; ready?: number; generating?: number; failed?: number; documents?: DocStatus[] }
+
+const humanize = (t: string) => t.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+type Step = { kind: "generate" | "regenerate"; docType: string } | { kind: "all" };
+
+function pill(status: string | undefined) {
+  if (status === "completed") return <StatusPill tone="positive" dot>Ready</StatusPill>;
+  if (status === "failed") return <StatusPill tone="negative" dot>Failed</StatusPill>;
+  if (status === "pending" || status === "generating" || status === "queued" || status === "running") return <StatusPill tone="info" dot>Writing</StatusPill>;
+  return <StatusPill tone="neutral" dot>Not written</StatusPill>;
+}
+
+export function ContactDocumentsTab({ contactId, contactName }: { contactId: number; contactName: string }) {
+  const [step, setStep] = useState<Step | null>(null);
+  const [viewing, setViewing] = useState<string | null>(null);
+  const status = useG8Query((signal) => g8Get<GenStatus>(`/contacts/${contactId}/documents/generation-status`, undefined, { signal }), [contactId], { key: ["contacts", "documents", contactId] });
+  const gen = status.data?.data;
+  const generating = gen?.is_generating === true;
+
+  // Follow a running generation; stop when nothing is generating any more.
+  useEffect(() => {
+    if (!generating) return;
+    const t = setTimeout(() => void status.refetch(), 4000);
+    return () => clearTimeout(t);
+  }, [generating, status.updatedAt]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const run = useG8Mutation(async (s: Step) => {
+    const base = `/contacts/${contactId}/documents`;
+    if (s.kind === "all") await g8Post(`${base}/generate-all`);
+    else if (s.kind === "generate") await g8Post(`${base}/types/${s.docType}/generate`);
+    else await g8Post(`${base}/types/${s.docType}/regenerate`);
+  }, { invalidates: [["contacts", "documents", contactId]], onSuccess: () => { setStep(null); void status.refetch(); } });
+
+  const docs = new Map((gen?.documents ?? []).map((d) => [d.doc_type, d]));
+  const types = [...CONTACT_DOC_TYPES, ...[...docs.keys()].filter((t) => !(CONTACT_DOC_TYPES as readonly string[]).includes(t))];
+
+  if (status.loading && !status.data) return <p className="p-2 text-sm text-muted-foreground" role="status">Loading documents</p>;
+  if (status.error && !status.data) return <ApiError error={status.error} title="Could not load the documents" onRetry={() => void status.refetch()} />;
+
+  const title = step?.kind === "all" ? `Write all documents for ${contactName}` : step ? `${step.kind === "generate" ? "Write" : "Rewrite"} "${humanize(step.docType)}" for ${contactName}` : "";
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex items-center justify-between gap-2">
+        <p className="text-sm text-muted-foreground">{gen?.ready ?? 0} of {gen?.total ?? CONTACT_DOC_TYPES.length} written{generating ? ", writing now" : ""}{gen?.failed ? `, ${gen.failed} failed` : ""}.</p>
+        <Button size="sm" variant="outline" disabled={generating || run.loading} onClick={() => { run.reset(); setStep({ kind: "all" }); }}><Sparkles className="size-4" aria-hidden />Write all</Button>
+      </div>
+      {status.error ? <ApiError compact error={status.error} title="Could not refresh the status" onRetry={() => void status.refetch()} /> : null}
+      <ul className="flex flex-col divide-y rounded-md border">
+        {types.map((t) => {
+          const d = docs.get(t);
+          const busy = d?.status === "pending" || d?.status === "generating" || d?.status === "queued" || d?.status === "running";
+          const ready = d?.status === "completed";
+          return (
+            <li key={t} className="flex flex-wrap items-center gap-2 px-3 py-2" data-testid={`contact-doc-${t}`}>
+              <FileText className="size-4 text-muted-foreground" aria-hidden />
+              <span className="text-sm font-medium">{d?.title || humanize(t)}</span>
+              {pill(d?.status)}
+              {d?.updated_at ? <span className="text-xs text-muted-foreground">{formatDay(d.updated_at)}</span> : null}
+              <span className="ml-auto flex gap-1">
+                {ready ? <Button size="sm" variant="ghost" onClick={() => setViewing(t)}>View</Button> : null}
+                <Button size="sm" variant="outline" disabled={busy || run.loading} aria-label={`${ready ? "Rewrite" : "Write"} ${humanize(t)}`} onClick={() => { run.reset(); setStep({ kind: ready ? "regenerate" : "generate", docType: t }); }}>
+                  <RefreshCw className="size-4" aria-hidden />{ready ? "Rewrite" : d?.status === "failed" ? "Try again" : "Write"}
+                </Button>
+              </span>
+            </li>
+          );
+        })}
+      </ul>
+      <ContactDocumentSheet contactId={contactId} docType={viewing} onClose={() => setViewing(null)} />
+      <ConfirmSpendDialog
+        open={step != null}
+        tier="billable"
+        title={title}
+        description={
+          <>
+            Each document is written by an AI model and charged to your credits. No price is published for a document, so no estimate is shown.
+            {step?.kind === "regenerate" ? " The current text, including any edits you made to it, is replaced." : ""}
+            {step?.kind === "all" ? ` Writing all ${CONTACT_DOC_TYPES.length} documents again replaces the ones that exist, and each one is charged.` : ""}
+            {run.error ? <span role="alert" className="mt-2 block text-destructive">It could not be started. Nothing was queued; you can try again.</span> : null}
+          </>
+        }
+        affected={step?.kind === "all" ? CONTACT_DOC_TYPES.length : step ? 1 : undefined}
+        confirmLabel="Write"
+        confirming={run.loading}
+        onConfirm={() => step && void run.mutate(step)}
+        onCancel={() => setStep(null)}
+      />
+    </div>
+  );
+}
+
+function ContactDocumentSheet({ contactId, docType, onClose }: { contactId: number; docType: string | null; onClose: () => void }) {
+  const doc = useG8Query((signal) => g8Get<{ title?: string; content?: string | null }>(`/contacts/${contactId}/documents/types/${docType}`, undefined, { signal }), [contactId, docType], { enabled: docType != null, key: ["contacts", "documents", contactId, docType ?? ""] });
+  const d = docType ? doc.data?.data : undefined;
+  return (
+    <Sheet open={docType != null} onOpenChange={(o) => (o ? undefined : onClose())}>
+      <SheetContent className="sm:max-w-xl overflow-y-auto">
+        <SheetHeader>
+          <SheetTitle>{d?.title || (docType ? humanize(docType) : "")}</SheetTitle>
+          <SheetDescription>Written by an AI model from this contact's record and activity.</SheetDescription>
+        </SheetHeader>
+        {doc.loading && !d ? <p className="p-4 text-sm text-muted-foreground" role="status">Loading</p> : null}
+        {doc.error ? <div className="p-4"><ApiError error={doc.error} title="Could not load the document" onRetry={() => void doc.refetch()} /></div> : null}
+        {d ? <div className="whitespace-pre-wrap p-4 text-sm">{d.content || "This document has no text yet."}</div> : null}
+      </SheetContent>
+    </Sheet>
+  );
+}

package/blocks/crm/components/contact-insights-tab.tsx

@@ -0,0 +1,118 @@
+"use client";
+
+/**
+ * ContactInsightsTab: what graph8 knows about a contact's buying signals, and a suggested next step.
+ *
+ * SDK operations, in order:
+ *   1. getContactSignals     GET /contacts/{id}/signals          (read) signal score, trend and the last 30 days of intent,
+ *                                                                page visits, email engagement, forms and bookings.
+ *   2. getContactNextBestStep GET /contacts/{id}/next-best-step  (BILLABLE although it is a GET, ConfirmSpendDialog)
+ *        A model writes the suggestion on a cache miss, and the cache key includes the contact's engagement, so new
+ *        activity makes the next ask a paid one again. It is therefore a button behind a confirm, never loaded on open.
+ *        graph8 publishes no price for it, so the confirm says that instead of showing a number.
+ *
+ * The suggestion is shown as written (action, why, confidence); nothing is executed for the person. A null answer (no
+ * context to base it on) says so.
+ */
+
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { Lightbulb } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+
+interface Signals {
+  signal_score?: number | null;
+  signal_trend?: string | null;
+  keyword_intents?: Array<{ keyword?: string; page_url?: string }>;
+  topic_intents?: unknown[];
+  page_visits?: Array<{ page_url?: string; visit_count?: number }>;
+  email_engagement?: unknown[];
+  form_submissions?: unknown[];
+  meeting_bookings?: unknown[];
+  intent_pages?: unknown[];
+}
+interface NextStep { action?: string; action_type?: string; reasoning?: string[]; confidence?: number }
+
+const count = (v: unknown) => (Array.isArray(v) ? v.length : 0);
+const humanize = (t: string) => t.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+
+export function ContactInsightsTab({ contactId }: { contactId: number }) {
+  const [confirm, setConfirm] = useState(false);
+  const signals = useG8Query((signal) => g8Get<Signals>(`/contacts/${contactId}/signals`, undefined, { signal }), [contactId], { key: ["contacts", "signals", contactId] });
+  const next = useG8Mutation(async () => {
+    const res = await g8Get<NextStep | null>(`/contacts/${contactId}/next-best-step`);
+    return res.data ?? null;
+  }, { onSuccess: () => setConfirm(false) });
+  const s = signals.data?.data;
+  const card = next.data;
+
+  return (
+    <div className="flex flex-col gap-4">
+      <section aria-label="Next best step" className="flex flex-col gap-2 rounded-md border p-3">
+        <div className="flex items-center justify-between gap-2">
+          <h3 className="flex items-center gap-2 text-sm font-medium"><Lightbulb className="size-4" aria-hidden />Next best step</h3>
+          <Button size="sm" variant="outline" disabled={next.loading} onClick={() => { next.reset(); setConfirm(true); }}>{card !== undefined ? "Suggest again" : "Suggest a next step"}</Button>
+        </div>
+        {next.error && !confirm ? <ApiError error={next.error} title="Could not get a suggestion" /> : null}
+        {card === null ? <p className="text-sm text-muted-foreground" role="status">There is not enough on this contact to suggest a step yet.</p> : null}
+        {card ? (
+          <div className="flex flex-col gap-1 text-sm" role="status">
+            <p className="font-medium">{card.action}</p>
+            <div className="flex items-center gap-2">
+              {card.action_type ? <StatusPill tone="info">{humanize(card.action_type)}</StatusPill> : null}
+              {typeof card.confidence === "number" ? <span className="text-xs text-muted-foreground">Confidence {Math.round(card.confidence * 100)}%</span> : null}
+            </div>
+            {card.reasoning?.length ? <ul className="list-disc pl-5 text-muted-foreground">{card.reasoning.map((r, i) => <li key={i}>{r}</li>)}</ul> : null}
+          </div>
+        ) : null}
+        {card === undefined && !next.error ? <p className="text-xs text-muted-foreground">Written by an AI model from this contact's activity. It costs credits, so it only runs when you ask.</p> : null}
+      </section>
+
+      <section aria-label="Signals" className="flex flex-col gap-2">
+        <h3 className="text-sm font-medium">Signals, last 30 days</h3>
+        {signals.loading && !s ? <p className="text-sm text-muted-foreground" role="status">Loading signals</p> : null}
+        {signals.error ? <ApiError error={signals.error} title="Could not load signals" onRetry={() => void signals.refetch()} /> : null}
+        {s ? (
+          <>
+            <KeyValueList columns={2} items={[
+              { label: "Signal score", value: s.signal_score ?? <span className="text-muted-foreground">-</span> },
+              { label: "Trend", value: s.signal_trend ? humanize(s.signal_trend) : <span className="text-muted-foreground">-</span> },
+              { label: "Keyword intents", value: count(s.keyword_intents) },
+              { label: "Topic intents", value: count(s.topic_intents) },
+              { label: "Pages visited", value: count(s.page_visits) },
+              { label: "Email engagement", value: count(s.email_engagement) },
+              { label: "Form submissions", value: count(s.form_submissions) },
+              { label: "Meeting bookings", value: count(s.meeting_bookings) },
+            ]} />
+            {s.page_visits?.length ? (
+              <ul className="text-sm text-muted-foreground">{s.page_visits.slice(0, 5).map((p, i) => <li key={`${p.page_url}-${i}`} className="truncate">{p.page_url}{p.visit_count ? ` (${p.visit_count})` : ""}</li>)}</ul>
+            ) : null}
+          </>
+        ) : null}
+      </section>
+
+      <ConfirmSpendDialog
+        open={confirm}
+        tier="billable"
+        title="Suggest a next step"
+        description={
+          <>
+            An AI model writes the suggestion from this contact's activity and charges your credits. A recent suggestion for the same activity is reused. No price is published for it, so no estimate is shown.
+            {next.error ? <span role="alert" className="mt-2 block text-destructive">The suggestion could not be made. You can try again.</span> : null}
+          </>
+        }
+        affected={1}
+        confirmLabel="Suggest"
+        confirming={next.loading}
+        onConfirm={() => void next.mutate(undefined)}
+        onCancel={() => setConfirm(false)}
+      />
+    </div>
+  );
+}

package/blocks/crm/components/contact-lookup-link.tsx

@@ -4,17 +4,22 @@
  * ContactLookupLink: "Open contact" for something that only knows a person's email (an inbox thread, a meeting
  * attendee, a visitor). It looks the email up in your CRM and, when exactly one contact has it, shows a button that
  * calls `onOpen(contactId)` (route to your contacts screen: `router.push("/contacts?id=" + id)`). When nobody has that
- * email it renders nothing, so a thread from a stranger gets no dead button.
+ * email it renders nothing, so a thread from a stranger gets no dead button, unless `createIfMissing` is set: then a
+ * stranger gets an "Add to contacts" button that creates the contact from the email (and name, when you pass one) and
+ * opens it.
  *
  * SDK operations, in order:
- *   1. listContacts  GET /contacts?email=<email>&limit=2   (read)
+ *   1. listContacts    GET  /contacts?email=<email>&limit=2   (read)
+ *   2. createContacts  POST /contacts                         (write; only after "Add to contacts" is clicked)
  * Nothing here is billable, external or destructive.
  */
 
 import { Button } from "@graph8/sdk/ui";
-import { UserRound } from "lucide-react";
+import { UserPlus, UserRound } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
-import { g8Get } from "@/g8/lib/g8-client";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
 
 export interface ContactLookupLinkProps {
   /** The person's email. Nothing is looked up (and nothing rendered) without one. */
@@ -24,17 +29,53 @@ export interface ContactLookupLinkProps {
   label?: string;
   variant?: "default" | "outline" | "secondary" | "ghost";
   size?: "default" | "sm";
+  /** Offer to create the contact when nobody has this email. Pass the sender's name to prefill it. */
+  createIfMissing?: boolean | { firstName?: string | null; lastName?: string | null };
+  /** Called with the new contact's id after it was created (before `onOpen`). */
+  onCreated?: (contactId: number) => void;
 }
 
-export function ContactLookupLink({ email, onOpen, label = "Open contact", variant = "outline", size = "sm" }: ContactLookupLinkProps) {
+/** Splits "Maya Chen" into first and last name; a single word is a first name. */
+export function splitName(name: string | null | undefined): { firstName?: string; lastName?: string } {
+  const parts = (name ?? "").trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return {};
+  return parts.length === 1 ? { firstName: parts[0] } : { firstName: parts[0], lastName: parts.slice(1).join(" ") };
+}
+
+export function ContactLookupLink({ email, onOpen, label = "Open contact", variant = "outline", size = "sm", createIfMissing, onCreated }: ContactLookupLinkProps) {
   const address = email?.trim().toLowerCase() ?? "";
   const q = useG8Query(
     async (signal) => ((await g8Get<Array<{ id: number; work_email?: string | null }>>("/contacts", { email: address, limit: 2, page: 1 }, { signal })).data ?? []),
     [address],
     { enabled: address.includes("@"), key: ["contacts", "by-email", address] },
   );
+  const create = useG8Mutation(
+    async () => {
+      const name = typeof createIfMissing === "object" ? createIfMissing : {};
+      const env = await g8Post<{ contact_id?: number | null }>("/contacts", { work_email: address, first_name: name.firstName || undefined, last_name: name.lastName || undefined });
+      const id = (env.data as { contact_id?: number | null } | undefined)?.contact_id;
+      // Never open a guess: when the API sent no id, look the new contact up instead.
+      if (id != null) return id;
+      const again = (await g8Get<Array<{ id: number }>>("/contacts", { email: address, limit: 1, page: 1 })).data ?? [];
+      return again[0]?.id ?? null;
+    },
+    { invalidates: [["contacts"]], onError: (err) => { if ((err as { status?: number }).status === 409) void q.refetch(); }, onSuccess: (id) => { if (id != null) { onCreated?.(id); onOpen(id); } } },
+  );
   const match = (q.data ?? []).find((c) => !c.work_email || c.work_email.toLowerCase() === address);
-  if (!address || !match) return null;
+  if (!address) return null;
+  if (!match) {
+    // Only offer to create once the lookup has really answered "nobody": never while loading or after an error.
+    if (!createIfMissing || q.loading || q.error || q.data === undefined) return null;
+    return (
+      <>
+        <Button size={size} variant={variant} loading={create.loading} onClick={() => void create.mutate(undefined)}>
+          <UserPlus className="mr-1 size-4" aria-hidden />
+          Add to contacts
+        </Button>
+        {create.error ? <ApiError error={create.error} title="Could not add the contact" onRetry={create.reset} /> : null}
+      </>
+    );
+  }
   return (
     <Button size={size} variant={variant} onClick={() => onOpen(match.id)}>
       <UserRound className="mr-1 size-4" aria-hidden />

package/blocks/crm/components/contact-row-actions.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+/**
+ * ContactRowActions: the "..." button at the end of a contact row. It opens a small dialog for that ONE contact with
+ * the record actions (tags, verify email, unlock info). Each action is the same component the bulk bar
+ * and the detail panel use, so a row, a selection and the open contact behave identically.
+ *
+ * SDK operations: none of its own. The actions it hosts call assign/unassignContactTags
+ * (write), verifyContactEmails (billable) and unlockContactInfo (billable); the paid ones keep their own
+ * ConfirmSpendDialog. Also exported for apps that render their own table through ContactTable's row slot.
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from "@graph8/sdk/ui";
+import { MoreHorizontal } from "lucide-react";
+import { contactName } from "../lib/crm-types";
+import type { ContactRecord } from "../lib/crm-types";
+import { UnlockInfoButton } from "./unlock-info-button";
+import { VerifyEmailButton } from "./verify-email-button";
+import { TagAssignButton } from "./tag-assign";
+
+export function ContactRowActions({ row, onDone }: { row: ContactRecord; onDone?: () => void }) {
+  const [open, setOpen] = useState(false);
+  const name = contactName(row);
+  return (
+    <>
+      <Button variant="ghost" size="sm" aria-label={`Actions for ${name}`} onClick={() => setOpen(true)}><MoreHorizontal className="size-4" aria-hidden /></Button>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>{name}</DialogTitle>
+            <DialogDescription>Actions for this contact.</DialogDescription>
+          </DialogHeader>
+          <div className="flex flex-wrap items-center gap-2">
+            <TagAssignButton contactIds={[row.id]} onDone={() => onDone?.()} />
+            <VerifyEmailButton rows={[row]} onDone={onDone} />
+            <UnlockInfoButton rows={[row]} onDone={onDone} />
+          </div>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

package/blocks/crm/components/contact-tag-chips.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+/**
+ * ContactTagChips: the tags on ONE contact as chips, with a remove button on each and an "Add tag" picker that can also
+ * create a tag on the spot. Used in the contact panel's Overview.
+ *
+ * SDK operations, in order:
+ *   1. getContactTagIds   GET /contacts/{contact_id}/tags    (read)   -> { tag_ids }
+ *   2. listContactTags    GET /contacts/tags                 (read)   names and colours, via useContactTags
+ *   3. assignContactTags  POST /contacts/tags/assign   { tag_ids, contact_ids: [id] }   (write, idempotent)
+ *   4. unassignContactTags POST /contacts/tags/unassign { tag_ids, contact_ids: [id] }  (write; the tag itself survives)
+ *   5. createContactTag   POST /contacts/tags { name, color }   (write) only from "Create tag", then assigned
+ *
+ * Removing a chip is immediate and reversible (add the tag again), so it needs no confirmation. A tag id that the
+ * list does not know (archived since) is shown as "Archived tag" rather than a raw id.
+ */
+
+import { useRef, useState } from "react";
+import { Button, cn } from "@graph8/sdk/ui";
+import { Plus, Tag, X } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+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 { useContactTags } from "../hooks/use-contact-tags";
+import { HEX_COLOR, TAG_COLORS } from "../lib/record-actions";
+import type { ContactTag } from "../lib/record-actions";
+
+/** One tag as a chip: a colour dot and the name. The colour is the tag's own (data), never a theme colour. */
+export function TagChip({ tag, onRemove, disabled }: { tag: Pick<ContactTag, "name" | "color">; onRemove?: () => void; disabled?: boolean }) {
+  const color = tag.color && HEX_COLOR.test(tag.color) ? tag.color : undefined;
+  return (
+    <span className="inline-flex items-center gap-1.5 rounded-full border bg-background px-2 py-0.5 text-xs font-medium">
+      <span aria-hidden className={cn("size-2 rounded-full", color ? "" : "bg-muted-foreground")} style={color ? { backgroundColor: color } : undefined} />
+      {tag.name}
+      {onRemove ? (
+        <button type="button" aria-label={`Remove tag ${tag.name}`} disabled={disabled} onClick={onRemove} className="-mr-1 rounded-full p-0.5 text-muted-foreground hover:text-foreground disabled:opacity-50">
+          <X className="size-3" aria-hidden />
+        </button>
+      ) : null}
+    </span>
+  );
+}
+
+export interface ContactTagChipsProps {
+  contactId: number;
+  /** Called after a tag was added, removed or created (refresh the list that shows tags). */
+  onChanged?: () => void;
+}
+
+export function ContactTagChips({ contactId, onChanged }: ContactTagChipsProps) {
+  const [adding, setAdding] = useState(false);
+  const [newName, setNewName] = useState("");
+  const [color, setColor] = useState<string>(TAG_COLORS[0]);
+  const all = useContactTags();
+  const ids = useG8Query((signal) => g8Get<{ tag_ids?: string[] }>(`/contacts/${contactId}/tags`, undefined, { signal }), [contactId], { key: ["contacts", "tags", contactId] });
+  const assigned = ids.data?.data?.tag_ids ?? [];
+  const byId = new Map(all.tags.map((t) => [t.id, t]));
+  const free = all.tags.filter((t) => !assigned.includes(t.id));
+
+  const write = useG8Mutation(async (v: { op: "assign" | "unassign"; tagId: string }) => {
+    const body = { tag_ids: [v.tagId], contact_ids: [contactId] };
+    if (v.op === "assign") await g8Post("/contacts/tags/assign", body);
+    else await g8Post("/contacts/tags/unassign", body);
+  }, { invalidates: [["contacts", "tags", contactId], ["contact-tags"], ["contacts", "list"]], onSuccess: () => { void ids.refetch(); onChanged?.(); } });
+
+  /** The tag step 1 created, kept so a retry after a failed assign does not create it a second time. */
+  const made = useRef<{ name: string; id: string } | null>(null);
+  const create = useG8Mutation(async (v: { name: string; color: string }) => {
+    if (made.current?.name !== v.name) {
+      const res = await g8Post<ContactTag>("/contacts/tags", { name: v.name, color: v.color });
+      if (!res.data?.id) throw new Error("The tag was created but the server did not return its id. Pick it from the list.");
+      made.current = { name: v.name, id: res.data.id };
+    }
+    await g8Post("/contacts/tags/assign", { tag_ids: [made.current.id], contact_ids: [contactId] });
+    made.current = null;
+  }, { invalidates: [["contacts", "tags", contactId], ["contact-tags"], ["contacts", "list"]], onSuccess: () => { setNewName(""); setAdding(false); void ids.refetch(); onChanged?.(); } });
+
+  if (ids.loading && !ids.data) return <p className="text-sm text-muted-foreground" role="status">Loading tags</p>;
+  if (ids.error) return <ApiError compact error={ids.error} title="Could not load tags" onRetry={() => void ids.refetch()} />;
+
+  return (
+    <div className="flex flex-col gap-2" aria-label="Tags">
+      <div className="flex flex-wrap items-center gap-1.5">
+        <Tag className="size-3.5 text-muted-foreground" aria-hidden />
+        {assigned.length === 0 ? <span className="text-sm text-muted-foreground">No tags</span> : null}
+        {assigned.map((id) => <TagChip key={id} tag={byId.get(id) ?? { name: all.loaded ? "Archived tag" : "Tag" }} disabled={write.loading} onRemove={() => void write.mutate({ op: "unassign", tagId: id })} />)}
+        <Button variant="ghost" size="sm" onClick={() => setAdding((a) => !a)} aria-expanded={adding}><Plus className="size-3.5" aria-hidden />Add tag</Button>
+      </div>
+      {adding ? (
+        <div className="flex flex-col gap-2 rounded-md border p-2">
+          {all.error ? <ApiError compact error={all.error} title="Could not load the tag list" onRetry={() => void all.refetch()} /> : null}
+          {free.length > 0 ? (
+            <div className="flex flex-wrap gap-1.5" role="group" aria-label="Existing tags">
+              {free.map((t) => (
+                <button key={t.id} type="button" disabled={write.loading} onClick={() => void write.mutate({ op: "assign", tagId: t.id })} aria-label={`Add tag ${t.name}`} className="rounded-full hover:bg-muted disabled:opacity-50"><TagChip tag={t} /></button>
+              ))}
+            </div>
+          ) : <p className="text-xs text-muted-foreground">{all.loaded ? "Every tag is already on this contact." : "Loading tags"}</p>}
+          <form className="flex flex-wrap items-center gap-2" onSubmit={(e) => { e.preventDefault(); if (newName.trim()) void create.mutate({ name: newName.trim(), color }); }}>
+            <input aria-label="New tag name" maxLength={50} placeholder="New tag name" value={newName} onChange={(e) => setNewName(e.target.value)} className="h-8 w-40 rounded-md border bg-background px-2 text-sm" />
+            <span className="flex gap-1" role="radiogroup" aria-label="New tag colour">
+              {TAG_COLORS.map((c) => <button key={c} type="button" role="radio" aria-checked={color === c} aria-label={`Colour ${c}`} onClick={() => setColor(c)} className={cn("size-5 rounded-full border-2", color === c ? "border-foreground" : "border-transparent")} style={{ backgroundColor: c }} />)}
+            </span>
+            <Button type="submit" size="sm" variant="outline" loading={create.loading} disabled={!newName.trim()}>Create and add</Button>
+          </form>
+        </div>
+      ) : null}
+      {write.error ? <ApiError compact error={write.error} title="Could not change the tag" /> : null}
+      {create.error ? <ApiError compact error={create.error} title="Could not create the tag" /> : null}
+    </div>
+  );
+}