@graph8/sdk 0.370.0 → 0.374.0

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

@@ -0,0 +1,85 @@
+"use client";
+
+/**
+ * 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, 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)
+ *   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 { 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, g8Post } from "@/g8/lib/g8-client";
+
+export interface ContactLookupLinkProps {
+  /** The person's email. Nothing is looked up (and nothing rendered) without one. */
+  email?: string | null;
+  /** Called with the CRM contact id when the button is clicked. */
+  onOpen: (contactId: number) => void;
+  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;
+}
+
+/** 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) 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 />
+      {label}
+    </Button>
+  );
+}

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>
+  );
+}