@graph8/sdk 0.362.0 → 0.373.0

package/blocks/deals/components/deal-contacts-editor.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+/**
+ * DealContactsEditor: the buying committee of one deal. Add a contact (with an optional role), change a role, make
+ * a contact the primary one, and remove a contact. The list itself is DealContactsTab; open a row for the full CRM record.
+ *
+ * SDK operations, in order:
+ *   1. GET    /deals/{id}                              (deals.getDeal)               read  - the contacts, roles and primary (via DealContactsTab)
+ *   2. GET    /contacts?name=                          (crm contacts.listContacts)   read  - find a contact to add
+ *   3. POST   /deals/{id}/contacts { person_id, role } (deals.addDealContact)        write - the contact must work at the deal's company
+ *   4. PUT    /deals/{id}/contacts/{contact_id} { role } (deals.setDealContactRole)  write - null clears the role
+ *   5. PUT    /deals/{id}/contacts/{person_id}/primary (deals.setPrimaryDealContact) write
+ *   6. DELETE /deals/{id}/contacts/{person_id}         (deals.removeDealContact)     DESTRUCTIVE -> ConfirmSpendDialog first
+ * Roles are champion, decision_maker, influencer, blocker, coach and end_user. A deal keeps at least one contact:
+ * the API refuses to remove the last one and the message is shown.
+ */
+import { useState } from "react";
+import { Search } from "lucide-react";
+import { Button, Input } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useDebouncedValue } from "@/g8/crm/hooks/use-debounced";
+import { contactName, type ContactRecord } from "@/g8/crm/lib/crm-types";
+import { dataOf, type Deal, type DealContact } from "../lib/deals-types";
+import { CONTACT_ROLES, roleLabel } from "../lib/deal-extras";
+import { DealContactsTab } from "./deal-related";
+
+export interface DealContactsEditorProps {
+  dealId: string;
+  /** Called after any change, so a screen can refresh its numbers. */
+  onChanged?: () => void;
+  /** Open a contact in your contacts screen (see DealContactsTab). */
+  onOpenContact?: (contactId: number) => void;
+  /** Open a contact's company in your companies screen. */
+  onOpenCompany?: (companyId: number) => void;
+  className?: string;
+}
+
+function AddContact({ dealId, existing, onAdded }: { dealId: string; existing: ReadonlySet<number>; onAdded: () => void }) {
+  const [text, setText] = useState("");
+  const [role, setRole] = useState("");
+  const term = useDebouncedValue(text.trim());
+  const found = useG8Query(async (signal) => (await g8Get<ContactRecord[]>("/contacts", { name: term, limit: 8, page: 1 }, { signal })).data ?? [], [term], { enabled: term.length > 1 });
+  const add = useG8Mutation(
+    (c: ContactRecord) => g8Post(`/deals/${encodeURIComponent(dealId)}/contacts`, { person_id: String(c.id), ...(role ? { role } : {}) }),
+    { invalidates: [["deals", "detail", dealId], ["deals", "list"]], onSuccess: () => { setText(""); setRole(""); onAdded(); } },
+  );
+  const choices = (found.data ?? []).filter((c) => !existing.has(c.id));
+  return (
+    <div className="space-y-2">
+      <div className="flex flex-wrap items-end gap-2">
+        <div className="relative min-w-48 flex-1">
+          <Search className="pointer-events-none absolute left-2 top-2.5 size-4 text-muted-foreground" aria-hidden />
+          <Input aria-label="Add a contact to this deal" className="pl-8" placeholder="Search contacts to add" value={text} onChange={(e) => setText(e.target.value)} />
+        </div>
+        <select aria-label="Role for the new contact" className="h-9 rounded-md border bg-background px-2 text-sm" value={role} onChange={(e) => setRole(e.target.value)}>
+          <option value="">No role</option>
+          {CONTACT_ROLES.map((r) => <option key={r} value={r}>{roleLabel(r)}</option>)}
+        </select>
+      </div>
+      {add.error ? <ApiError error={add.error} title="Could not add the contact" /> : null}
+      {found.error ? <ApiError error={found.error} title="Could not search contacts" /> : null}
+      {term.length > 1 && !found.loading && !found.error && choices.length === 0 ? <p className="text-xs text-muted-foreground">No other contacts match.</p> : null}
+      <ul className="divide-y rounded-md border empty:hidden" aria-label="Contacts to add">
+        {choices.map((c) => (
+          <li key={c.id}>
+            <button type="button" className="flex w-full items-center gap-2 p-2 text-left text-sm hover:bg-muted disabled:opacity-60" disabled={add.loading} aria-label={`Add ${contactName(c)}`} onClick={() => void add.mutate(c)}>
+              <EntityAvatar name={contactName(c)} size="sm" />
+              <span className="font-medium">{contactName(c)}</span>
+              <span className="text-xs text-muted-foreground">{[c.job_title, c.company_name].filter(Boolean).join(" at ")}</span>
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+export function DealContactsEditor({ dealId, onChanged, onOpenContact, onOpenCompany, className }: DealContactsEditorProps) {
+  const base = `/deals/${encodeURIComponent(dealId)}/contacts`;
+  const [busyId, setBusyId] = useState<number | null>(null);
+  const [removing, setRemoving] = useState<DealContact | null>(null);
+  // Same query key as DealContactsTab: one request, and the ids already on the deal are hidden from the search results.
+  const deal = useG8Query(async (signal) => dataOf<Deal>(await g8Get(`/deals/${encodeURIComponent(dealId)}`, undefined, { signal })), [dealId], { key: ["deals", "detail", dealId] });
+  const existing = new Set((deal.data?.contacts ?? []).map((c) => c.id));
+  const done = () => onChanged?.();
+  const refresh = [["deals", "detail", dealId], ["deals", "list"]] as const;
+
+  const role = useG8Mutation(async (v: { contact: DealContact; role: string }) => {
+    setBusyId(v.contact.id);
+    try { await g8Put(`${base}/${v.contact.id}`, { role: v.role || null }); } finally { setBusyId(null); }
+  }, { invalidates: refresh, onSuccess: done });
+  const primary = useG8Mutation(async (c: DealContact) => {
+    setBusyId(c.id);
+    try { await g8Put(`${base}/${encodeURIComponent(String(c.id))}/primary`); } finally { setBusyId(null); }
+  }, { invalidates: refresh, onSuccess: done });
+  const remove = useG8Mutation(async (c: DealContact) => {
+    setBusyId(c.id);
+    try { await g8Delete(`${base}/${encodeURIComponent(String(c.id))}`); } finally { setBusyId(null); }
+  }, { invalidates: refresh, onSuccess: () => { setRemoving(null); done(); }, onError: () => setRemoving(null) });
+  const failure = role.error ?? primary.error ?? remove.error;
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`}>
+      <AddContact dealId={dealId} existing={existing} onAdded={done} />
+      {failure ? <ApiError error={failure} title="That contact change failed" /> : null}
+      <DealContactsTab
+        dealId={dealId}
+        onOpenContact={onOpenContact}
+        onOpenCompany={onOpenCompany}
+        renderContactActions={(c, deal) => {
+          const isPrimary = deal.primary_contact?.id === c.id;
+          const name = c.name || c.email || `contact ${c.id}`;
+          const options = c.role && !CONTACT_ROLES.includes(c.role as (typeof CONTACT_ROLES)[number]) ? [c.role, ...CONTACT_ROLES] : CONTACT_ROLES;
+          return (
+            <span className="flex shrink-0 items-center gap-1">
+              <select aria-label={`Role of ${name}`} className="h-8 rounded-md border bg-background px-1 text-xs" disabled={busyId === c.id} value={c.role ?? ""} onChange={(e) => void role.mutate({ contact: c, role: e.target.value })}>
+                <option value="">No role</option>
+                {options.map((r) => <option key={r} value={r}>{roleLabel(r)}</option>)}
+              </select>
+              <Button size="sm" variant="ghost" disabled={isPrimary || busyId === c.id} aria-label={`Make ${name} primary`} onClick={() => void primary.mutate(c)}>{isPrimary ? "Primary" : "Make primary"}</Button>
+              <Button size="sm" variant="ghost" disabled={busyId === c.id} aria-label={`Remove ${name}`} onClick={() => setRemoving(c)}>Remove</Button>
+            </span>
+          );
+        }}
+      />
+      <ConfirmSpendDialog open={removing != null} tier="destructive" title={`Remove ${removing?.name || removing?.email || "this contact"} from the deal?`} description="The contact stays in your CRM; only the link to this deal is removed." confirmLabel="Remove contact" affected={1} confirming={remove.loading} onConfirm={() => removing && void remove.mutate(removing)} onCancel={() => setRemoving(null)} />
+    </div>
+  );
+}

package/blocks/deals/components/deal-detail.tsx

@@ -12,7 +12,7 @@
  *   5. DELETE /deals/{id}                      (deals.deleteDeal)       DESTRUCTIVE -> ConfirmSpendDialog first
  * Compose notes, tasks and the activity timeline from the crm block under `children`.
  */
-import { useEffect, useState, type ReactNode } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
 import { Button, Input, Label, Skeleton, Textarea } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
@@ -21,6 +21,7 @@ import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { usePipelines } from "../hooks/use-pipelines";
 import { dataOf, formatMoney, type Deal } from "../lib/deals-types";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface DealDetailProps {
   /** Edit this deal; omit to create one. */
@@ -53,6 +54,7 @@ function fromDeal(d: Deal): Form {
 }
 
 export function DealDetail({ dealId, ownerId, contactIds = [], pipelineId, allowDuplicate, onSaved, onDeleted, children, className }: DealDetailProps) {
+  const brand = useBrand();
   const { pipelines, defaultPipeline } = usePipelines();
   const [form, setForm] = useState<Form>(EMPTY);
   const [confirmDelete, setConfirmDelete] = useState(false);
@@ -60,14 +62,23 @@ export function DealDetail({ dealId, ownerId, contactIds = [], pipelineId, allow
   const [createdId, setCreatedId] = useState<string | null>(null);
   const [createdRevision, setCreatedRevision] = useState<number | null>(null);
   const effectiveId = dealId ?? createdId ?? undefined;
-  const deal = useG8Query(async (signal) => dataOf<Deal>(await g8Get(`/deals/${encodeURIComponent(dealId as string)}`, undefined, { signal })), [dealId], { enabled: Boolean(dealId) });
-  const history = useG8Query(async (signal) => dataOf<{ items?: HistoryItem[] }>(await g8Get(`/deals/${encodeURIComponent(dealId as string)}/history`, { limit: 20 }, { signal })).items ?? [], [dealId], { enabled: Boolean(dealId) });
-  useEffect(() => { if (deal.data) setForm(fromDeal(deal.data)); }, [deal.data]);
-  // A different deal (or create mode again) must not show the previous one's fields.
-  useEffect(() => { setForm(EMPTY); setCreatedId(null); setCreatedRevision(null); setConfirmDelete(false); }, [dealId]);
+  const deal = useG8Query(async (signal) => dataOf<Deal>(await g8Get(`/deals/${encodeURIComponent(dealId as string)}`, undefined, { signal })), [dealId], {
+    enabled: Boolean(dealId),
+    key: ["deals", "detail", dealId ?? null],
+    // The form is seeded from this record: never swap it under someone typing on a window refocus.
+    refetchOnFocus: false,
+  });
+  const history = useG8Query(async (signal) => dataOf<{ items?: HistoryItem[] }>(await g8Get(`/deals/${encodeURIComponent(dealId as string)}/history`, { limit: 20 }, { signal })).items ?? [], [dealId], { enabled: Boolean(dealId), key: ["deals", "history", dealId ?? null] });
+  // Unsaved edits win over a refreshed record (focus, invalidation from a board move, refetch): only an
+  // untouched form follows the server. Saving or switching deals makes the form untouched again.
+  const dirty = useRef(false);
+  // A different deal (or create mode again) must not show the previous one's fields. Declared BEFORE the
+  // seeding effect so that, when the record is already cached, the reset runs first and the seed wins.
+  useEffect(() => { dirty.current = false; setForm(EMPTY); setCreatedId(null); setCreatedRevision(null); setConfirmDelete(false); }, [dealId]);
+  useEffect(() => { if (deal.data && !dirty.current) setForm(fromDeal(deal.data)); }, [deal.data]);
 
   const pipeline = pipelines.find((p) => p.id === (deal.data?.pipeline_id ?? pipelineId)) ?? defaultPipeline;
-  const set = <K extends keyof Form>(k: K, v: Form[K]) => setForm((f) => ({ ...f, [k]: v }));
+  const set = <K extends keyof Form>(k: K, v: Form[K]) => { dirty.current = true; setForm((f) => ({ ...f, [k]: v })); };
 
   const save = useG8Mutation(async () => {
     const body = {
@@ -81,11 +92,12 @@ export function DealDetail({ dealId, ownerId, contactIds = [], pipelineId, allow
       ? await g8Patch(`/deals/${encodeURIComponent(effectiveId)}`, { ...body, expected_revision: (dealId ? deal.data?.revision : createdRevision) ?? undefined })
       : await g8Post("/deals", { ...body, owner_id: ownerId, contact_ids: contactIds, allow_duplicate: allowDuplicate || undefined, pipeline_id: pipeline?.id, amount: body.amount ?? undefined, close_date: body.close_date ?? undefined });
     return dataOf<Deal>(env);
-  }, { onSuccess: (saved) => { if (!dealId && saved.id) { setCreatedId(saved.id); setCreatedRevision(saved.revision ?? null); } if (dealId) { void deal.refetch(); void history.refetch(); } onSaved?.(saved); } });
-  const remove = useG8Mutation(async () => { await g8Delete(`/deals/${encodeURIComponent(dealId as string)}`); }, { onSuccess: () => { setConfirmDelete(false); onDeleted?.(dealId as string); }, onError: () => setConfirmDelete(false) });
+  }, { invalidates: [["deals", "list"], ["deals", "history"]], onSuccess: (saved) => { dirty.current = false; if (!dealId && saved.id) { setCreatedId(saved.id); setCreatedRevision(saved.revision ?? null); } if (dealId) { void deal.refetch(); void history.refetch(); } onSaved?.(saved); } });
+  const remove = useG8Mutation(async () => { await g8Delete(`/deals/${encodeURIComponent(dealId as string)}`); }, { invalidates: [["deals", "list"]], onSuccess: () => { setConfirmDelete(false); onDeleted?.(dealId as string); }, onError: () => setConfirmDelete(false) });
 
   if (deal.error) return <ApiError error={deal.error} title="Could not load the deal" onRetry={() => void deal.refetch()} />;
-  if (dealId && deal.loading && !deal.data) return <Skeleton className="h-56 w-full" aria-label="Loading deal" />;
+  // The hook keeps the previous deal's data while the next loads: wait for THIS deal, so a blank form is never shown (or saved) over it.
+  if (dealId && (!deal.data || String(deal.data.id) !== String(dealId))) return <Skeleton className="h-56 w-full" aria-label="Loading deal" />;
   const d = deal.data;
   const canCreate = Boolean(ownerId);
 
@@ -105,7 +117,7 @@ export function DealDetail({ dealId, ownerId, contactIds = [], pipelineId, allow
           </div>
         </div>
         <div className="space-y-1"><Label htmlFor="deal-desc">Description</Label><Textarea id="deal-desc" rows={3} value={form.description} onChange={(e) => set("description", e.target.value)} /></div>
-        {!dealId && !canCreate ? <p className="text-sm text-muted-foreground">Pass ownerId (a graph8 user id) to create deals: the API requires an owner.</p> : null}
+        {!dealId && !canCreate ? <p className="text-sm text-muted-foreground">Pass ownerId (a {brand.linkLabel} user id) to create deals: the API requires an owner.</p> : null}
         {save.error ? <ApiError error={save.error} title="Could not save the deal" /> : null}
         {remove.error ? <ApiError error={remove.error} title="Could not delete the deal" /> : null}
         <div className="flex justify-between">
@@ -116,14 +128,14 @@ export function DealDetail({ dealId, ownerId, contactIds = [], pipelineId, allow
 
       {d ? (
         <section aria-label="Contacts" className="space-y-1 text-sm">
-          <h3 className="font-semibold">Contacts ({d.contact_count ?? d.contacts?.length ?? 0})</h3>
+          <h3 className="font-medium">Contacts ({d.contact_count ?? d.contacts?.length ?? 0})</h3>
           {(d.contacts ?? []).map((c) => <p key={c.id}>{c.name ?? c.email}{c.role ? ` · ${c.role}` : ""}{d.primary_contact?.id === c.id ? " (primary)" : ""}</p>)}
           <p className="text-muted-foreground">Owner: {d.owner_name ?? d.owner_email ?? "none"} · {formatMoney(d.amount, d.currency)}</p>
         </section>
       ) : null}
       {dealId ? (
         <section aria-label="Stage history" className="space-y-1 text-sm">
-          <h3 className="font-semibold">Stage history</h3>
+          <h3 className="font-medium">Stage history</h3>
           {history.error ? <ApiError error={history.error} title="Could not load history" onRetry={() => void history.refetch()} /> : null}
           {(history.data ?? []).length === 0 && !history.loading ? <p className="text-muted-foreground">No stage changes yet.</p> : null}
           {(history.data ?? []).map((h, i) => <p key={i}>{h.from_stage_name ?? "New"} to {h.to_stage_name ?? "unknown"} <span className="text-muted-foreground">{h.changed_at ?? h.created_at ?? ""}</span></p>)}

package/blocks/deals/components/deal-filters.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+/**
+ * DealFilterBar: the deal list filters beside the search box: owner, stage, outcome, stale, activity, close-date
+ * range and "no contact". It only edits a DealFilterState; `filterQuery(state)` turns that into the `usePipelineDeals`
+ * filters (GET /deals owner_id, stage_id, outcome, stale_before, has_activity, close_after, close_before, has_contact).
+ *
+ * SDK operations: none directly (the owners come from the deals block's useDefaultOwner: GET /team-members).
+ * Dates are date-only (YYYY-MM-DD); the "to" date is inclusive, the API's close_before is exclusive, so
+ * `filterQuery` adds one day in UTC.
+ */
+import { Button } from "@graph8/sdk/ui";
+import { NO_FILTERS, filtersActive, type DealFilterState } from "../lib/deal-extras";
+import type { Stage } from "../lib/deals-types";
+import type { OwnerOption } from "../hooks/use-default-owner";
+
+export interface DealFilterBarProps {
+  value: DealFilterState;
+  onChange: (next: DealFilterState) => void;
+  stages: Stage[];
+  owners: OwnerOption[];
+  className?: string;
+}
+
+const SELECT = "h-9 rounded-md border bg-background px-2 text-sm";
+const DATE = "h-9 rounded-md border bg-background px-2 text-sm";
+
+export function DealFilterBar({ value, onChange, stages, owners, className }: DealFilterBarProps) {
+  const set = <K extends keyof DealFilterState>(key: K, v: DealFilterState[K]) => onChange({ ...value, [key]: v });
+  return (
+    <div className={`flex flex-wrap items-center gap-2 ${className ?? ""}`} role="group" aria-label="Deal filters">
+      <select aria-label="Filter by owner" className={SELECT} value={value.ownerId} onChange={(e) => set("ownerId", e.target.value)}>
+        <option value="">Any owner</option>
+        {owners.map((o) => <option key={o.id} value={o.id}>{o.name}</option>)}
+      </select>
+      <select aria-label="Filter by stage" className={SELECT} value={value.stageId} onChange={(e) => set("stageId", e.target.value)}>
+        <option value="">Any stage</option>
+        {stages.map((s) => <option key={s.id} value={s.id}>{s.name}</option>)}
+      </select>
+      <select aria-label="Filter by outcome" className={SELECT} value={value.outcome} onChange={(e) => set("outcome", e.target.value as DealFilterState["outcome"])}>
+        <option value="">Open, won and lost</option>
+        <option value="open">Open</option>
+        <option value="won">Won</option>
+        <option value="lost">Lost</option>
+      </select>
+      <select aria-label="Filter by staleness" className={SELECT} value={value.staleDays} onChange={(e) => set("staleDays", e.target.value as DealFilterState["staleDays"])}>
+        <option value="">Any activity age</option>
+        {(["7", "14", "30", "60", "90"] as const).map((d) => <option key={d} value={d}>Stale {d}+ days</option>)}
+      </select>
+      <select aria-label="Filter by activity" className={SELECT} value={value.activity} onChange={(e) => set("activity", e.target.value as DealFilterState["activity"])}>
+        <option value="">With or without activity</option>
+        <option value="yes">Has activity</option>
+        <option value="no">No activity</option>
+      </select>
+      <label className="flex items-center gap-1 text-xs text-muted-foreground">Closes from
+        <input aria-label="Close date from" type="date" className={DATE} value={value.closeFrom} max={value.closeTo || undefined} onChange={(e) => set("closeFrom", e.target.value)} />
+      </label>
+      <label className="flex items-center gap-1 text-xs text-muted-foreground">to
+        <input aria-label="Close date to" type="date" className={DATE} value={value.closeTo} min={value.closeFrom || undefined} onChange={(e) => set("closeTo", e.target.value)} />
+      </label>
+      <label className="flex items-center gap-1 text-sm"><input type="checkbox" checked={value.orphaned} onChange={(e) => set("orphaned", e.target.checked)} />No contact</label>
+      {filtersActive(value) ? <Button size="sm" variant="ghost" onClick={() => onChange(NO_FILTERS)}>Clear filters</Button> : null}
+    </div>
+  );
+}

package/blocks/deals/components/deal-line-items.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+/**
+ * DealLineItems: the products on a deal: add, edit and remove lines, with per-line totals and the deal total.
+ *
+ * SDK operations, in order:
+ *   1. GET /deals/{id}/line-items                 (deals.listDealLineItems)     read  - lines, derived amount, quote mismatch flag
+ *   2. PUT /deals/{id}/line-items { line_items }  (deals.replaceDealLineItems)  write - sends the FULL desired set (an empty list clears them)
+ * Money: unit prices are typed in dollars and sent as whole CENTS; the server recomputes each line total from
+ * unit price, quantity and discount. The editor appears only after the lines loaded, and Save stays disabled until
+ * something changed, so a record that has not loaded is never overwritten. Fields the screen does not show (catalog
+ * ids, description, billing frequency) are carried over untouched.
+ */
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Plus, Trash2 } from "lucide-react";
+import { Button, Input, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Get, g8Put } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { dataOf } from "../lib/deals-types";
+import { centsToDollarsText, dollarsToCents, formatCents, lineTotalCents, type DealLineItem, type LineItemsPayload } from "../lib/deal-extras";
+
+export interface DealLineItemsProps {
+  dealId: string;
+  /** Called after the lines were saved, so a screen can refresh the deal amount. */
+  onSaved?: () => void;
+  className?: string;
+}
+
+interface Row {
+  key: string;
+  base: DealLineItem | null;
+  name: string;
+  quantity: string;
+  price: string;
+  discount: string;
+}
+
+const FREQUENCIES: Array<[string, string]> = [["one_time", "One time"], ["month", "Monthly"], ["quarter", "Quarterly"], ["year", "Yearly"]];
+let keyCounter = 0;
+const nextKey = () => `row-${keyCounter++}`;
+
+const rowFrom = (li: DealLineItem): Row => ({ key: li.id ?? nextKey(), base: li, name: li.product_name, quantity: String(li.quantity), price: centsToDollarsText(li.unit_amount), discount: String(li.discount_pct ?? 0) });
+const blankRow = (): Row => ({ key: nextKey(), base: null, name: "", quantity: "1", price: "", discount: "0" });
+
+/** The line a row stands for, or null while a field is invalid. */
+function parse(r: Row, sortOrder: number): DealLineItem | null {
+  const cents = dollarsToCents(r.price);
+  const quantity = Number(r.quantity);
+  const discount = Number(r.discount === "" ? 0 : r.discount);
+  if (!r.name.trim() || cents == null || cents > 1_000_000_000 || !Number.isInteger(quantity) || quantity < 1 || quantity > 10_000 || !Number.isFinite(discount) || discount < 0 || discount > 100) return null;
+  const { id: _id, ...kept } = (r.base ?? {}) as DealLineItem & { line_total?: number };
+  const { line_total: _total, ...carried } = kept as DealLineItem & { line_total?: number };
+  return { ...carried, product_name: r.name.trim(), quantity, unit_amount: cents, discount_pct: discount, sort_order: sortOrder };
+}
+
+export function DealLineItems({ dealId, onSaved, className }: DealLineItemsProps) {
+  const q = useG8Query(async (signal) => dataOf<LineItemsPayload>(await g8Get(`/deals/${encodeURIComponent(dealId)}/line-items`, undefined, { signal })), [dealId], { key: ["deals", "line-items", dealId], refetchOnFocus: false });
+  const [rows, setRows] = useState<Row[]>([]);
+  const baseline = useRef("[]");
+  const dirty = useRef(false);
+  // A different deal must not show the previous deal's lines.
+  useEffect(() => { dirty.current = false; setRows([]); baseline.current = "[]"; }, [dealId]);
+  // Unsaved edits win over a refreshed record: only an untouched editor follows the server.
+  useEffect(() => {
+    if (!q.data || dirty.current) return;
+    const next = (q.data.line_items ?? []).map(rowFrom);
+    setRows(next);
+    baseline.current = JSON.stringify(next.map((r) => [r.name, r.quantity, r.price, r.discount]));
+  }, [q.data]);
+
+  const edit = (key: string, change: Partial<Row>) => { dirty.current = true; setRows((all) => all.map((r) => (r.key === key ? { ...r, ...change } : r))); };
+  const parsed = rows.map((r, i) => parse(r, i));
+  const valid = parsed.every((p) => p !== null);
+  const changed = JSON.stringify(rows.map((r) => [r.name, r.quantity, r.price, r.discount])) !== baseline.current;
+  const currency = q.data?.currency;
+  const total = useMemo(() => parsed.reduce((sum, p) => sum + (p ? lineTotalCents(p) : 0), 0), [parsed]);
+
+  const save = useG8Mutation(
+    () => g8Put(`/deals/${encodeURIComponent(dealId)}/line-items`, { line_items: parsed as DealLineItem[] }),
+    { invalidates: [["deals", "line-items", dealId], ["deals", "detail", dealId], ["deals", "list"]], onSuccess: () => { dirty.current = false; void q.refetch(); onSaved?.(); } },
+  );
+
+  if (q.error) return <ApiError error={q.error} title="Could not load the line items" onRetry={() => void q.refetch()} />;
+  if (!q.data) return <Skeleton className="h-32 w-full" aria-label="Loading line items" />;
+  return (
+    <form className={`space-y-3 ${className ?? ""}`} onSubmit={(e) => { e.preventDefault(); if (changed && valid) void save.mutate(undefined); }}>
+      {q.data.amount_mismatch ? (
+        <p role="status" className="rounded-md border border-dashed p-3 text-sm text-muted-foreground">
+          The deal amount ({q.data.amount ?? 0}) and its linked quote ({q.data.linked_quote_total ?? 0}) disagree.
+        </p>
+      ) : null}
+      {rows.length === 0 ? <p className="text-sm text-muted-foreground">No line items yet. Add the products this deal is for.</p> : null}
+      <ul className="space-y-2" aria-label="Line items">
+        {rows.map((r, i) => {
+          const line = parsed[i];
+          return (
+            <li key={r.key} className="grid gap-2 rounded-md border p-2 sm:grid-cols-[1fr_5rem_7rem_5rem_7rem_auto] sm:items-center">
+              <Input aria-label={`Product ${i + 1}`} placeholder="Product" value={r.name} onChange={(e) => edit(r.key, { name: e.target.value })} />
+              <Input aria-label={`Quantity ${i + 1}`} type="number" min={1} max={10000} step={1} value={r.quantity} onChange={(e) => edit(r.key, { quantity: e.target.value })} />
+              <Input aria-label={`Unit price ${i + 1}`} type="number" min={0} step="0.01" placeholder="0.00" value={r.price} onChange={(e) => edit(r.key, { price: e.target.value })} />
+              <Input aria-label={`Discount percent ${i + 1}`} type="number" min={0} max={100} step="any" value={r.discount} onChange={(e) => edit(r.key, { discount: e.target.value })} />
+              <span className="text-right text-sm tabular-nums" aria-label={`Line total ${i + 1}`}>{line ? formatCents(lineTotalCents(line), currency) : "-"}</span>
+              <Button type="button" size="sm" variant="ghost" aria-label={`Remove line ${i + 1}`} onClick={() => { dirty.current = true; setRows((all) => all.filter((x) => x.key !== r.key)); }}><Trash2 className="size-4" aria-hidden /></Button>
+              {r.base?.billing_frequency && r.base.billing_frequency !== "one_time" ? <span className="text-xs text-muted-foreground sm:col-span-6">{FREQUENCIES.find(([v]) => v === r.base?.billing_frequency)?.[1] ?? r.base.billing_frequency} billing</span> : null}
+            </li>
+          );
+        })}
+      </ul>
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <Button type="button" size="sm" variant="outline" onClick={() => { dirty.current = true; setRows((all) => [...all, blankRow()]); }}><Plus className="size-4" aria-hidden />Add line</Button>
+        <p className="text-sm font-semibold tabular-nums" data-testid="line-items-total">Total {formatCents(total, currency)}</p>
+      </div>
+      {!valid ? <p className="text-xs text-muted-foreground">Each line needs a product, a whole quantity from 1 to 10,000, a price and a discount from 0 to 100.</p> : null}
+      {save.error ? <ApiError error={save.error} title="Could not save the line items" /> : null}
+      <div className="flex justify-end"><Button type="submit" loading={save.loading} disabled={!changed || !valid}>Save line items</Button></div>
+    </form>
+  );
+}

package/blocks/deals/components/deal-notes-tab.tsx

@@ -0,0 +1,97 @@
+"use client";
+
+/**
+ * DealNotesTab: list, add, edit and delete the notes of one deal.
+ *
+ * SDK operations, in order:
+ *   1. GET    /deals/{id}/notes              (notes.listDealNotes)    read
+ *   2. POST   /deals/{id}/notes { content }  (notes.createDealNote)   write
+ *   3. PUT    /deals/{id}/notes/{note_id}    (deals.updateDealNote)   write - only when the text changed
+ *   4. DELETE /deals/{id}/notes/{note_id}    (deals.deleteDealNote)   DESTRUCTIVE -> ConfirmSpendDialog first
+ * A `read_only` note (projected from synced CRM activity) can be neither edited nor deleted.
+ */
+import { useState } from "react";
+import { StickyNote } from "lucide-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 { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { rowsOf, type DealNote } from "../lib/deal-extras";
+
+export interface DealNotesTabProps {
+  dealId: string;
+  /** Called after any write, so a sibling activity timeline can reload. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+const when = (iso: string | null | undefined): string => (iso ? new Date(iso).toLocaleString() : "");
+
+export function DealNotesTab({ dealId, onChanged, className }: DealNotesTabProps) {
+  const base = `/deals/${encodeURIComponent(dealId)}/notes`;
+  const [draft, setDraft] = useState("");
+  const [editing, setEditing] = useState<{ id: string; original: string; content: string } | null>(null);
+  const [deleting, setDeleting] = useState<DealNote | null>(null);
+  const [busyId, setBusyId] = useState<string | null>(null);
+  const notes = useG8Query(async (signal) => rowsOf<DealNote>(await g8Get(base, undefined, { signal })), [dealId], { key: ["deals", "notes", dealId] });
+  const changed = () => { void notes.refetch(); onChanged?.(); };
+
+  const add = useG8Mutation((content: string) => g8Post(base, { content }), { invalidates: [["deals", "notes", dealId]], onSuccess: () => { setDraft(""); changed(); } });
+  const edit = useG8Mutation(async (v: { id: string; content: string }) => {
+    setBusyId(v.id);
+    try { await g8Put(`${base}/${encodeURIComponent(v.id)}`, { content: v.content }); } finally { setBusyId(null); }
+  }, { invalidates: [["deals", "notes", dealId]], onSuccess: () => { setEditing(null); changed(); } });
+  const remove = useG8Mutation(async (id: string) => {
+    setBusyId(id);
+    try { await g8Delete(`${base}/${encodeURIComponent(id)}`); } finally { setBusyId(null); }
+  }, { invalidates: [["deals", "notes", dealId]], onSuccess: () => { setDeleting(null); changed(); }, onError: () => setDeleting(null) });
+
+  const items = notes.data ?? [];
+  const unchanged = editing ? editing.content.trim() === editing.original.trim() : true;
+  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" rows={3} placeholder="Write a note about this deal" 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" aria-label="Loading notes" /> : null}
+      {!notes.loading && !notes.error && items.length === 0 ? <EmptyState icon={<StickyNote className="size-8" />} title="No notes yet" description="Capture what was said, decided or promised." /> : null}
+      <ul className="flex flex-col gap-2" aria-label="Deal notes">
+        {items.map((n) => (
+          <li key={n.id} className="rounded-md border p-3 text-sm" data-testid="deal-note">
+            {editing?.id === n.id ? (
+              <form className="flex flex-col gap-2" onSubmit={(e) => { e.preventDefault(); if (!unchanged && editing.content.trim()) void edit.mutate({ id: n.id, content: editing.content.trim() }); }}>
+                <Textarea aria-label="Edit note" rows={3} value={editing.content} onChange={(e) => setEditing({ ...editing, content: e.target.value })} />
+                <div className="flex justify-end gap-2">
+                  <Button type="button" size="sm" variant="outline" onClick={() => setEditing(null)}>Cancel</Button>
+                  <Button type="submit" size="sm" loading={busyId === n.id && edit.loading} disabled={unchanged || !editing.content.trim()}>Save note</Button>
+                </div>
+              </form>
+            ) : (
+              <>
+                <p className="whitespace-pre-wrap">{n.content}</p>
+                <div className="mt-2 flex items-center justify-between gap-2 text-xs text-muted-foreground">
+                  <span>{[n.created_by_name, when(n.updated_at ?? n.created_at)].filter(Boolean).join(" · ")}{n.read_only ? " · synced, read only" : ""}</span>
+                  {n.read_only ? null : (
+                    <span className="flex gap-1">
+                      <Button size="sm" variant="ghost" aria-label={`Edit note: ${n.content.slice(0, 30)}`} onClick={() => setEditing({ id: n.id, original: n.content, content: n.content })}>Edit</Button>
+                      <Button size="sm" variant="ghost" aria-label={`Delete note: ${n.content.slice(0, 30)}`} loading={busyId === n.id && remove.loading} onClick={() => setDeleting(n)}>Delete</Button>
+                    </span>
+                  )}
+                </div>
+              </>
+            )}
+          </li>
+        ))}
+      </ul>
+      <ConfirmSpendDialog open={deleting != null} tier="destructive" title="Delete this note?" description={deleting?.content.slice(0, 160)} confirmLabel="Delete note" affected={1} confirming={remove.loading} onConfirm={() => deleting && void remove.mutate(deleting.id)} onCancel={() => setDeleting(null)} />
+    </div>
+  );
+}

package/blocks/deals/components/deal-related.tsx

@@ -8,11 +8,12 @@
  *   DealContactsTab: GET /deals/{id}                    (deals.getDeal)    read - the deal's contacts and roles
  *                    GET /contacts/{id} ...             (crm ContactDetail, in a side sheet)
  *   DealQuotesTab:   GET /quotes?deal_id=&page=&limit   (quotes.listQuotes) read - needs the quotes:read scope
+ *                    (`actions` renders above the list: pass the quotes block's CreateQuoteFromDeal there)
  * Nothing here is billable, external or destructive.
  */
-import { useState } from "react";
+import { useState, type ReactNode } from "react";
 import { FileText, Users } from "lucide-react";
-import { Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { Button, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
 import { EmptyState } from "@/g8/components/empty-state";
 import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
@@ -20,11 +21,21 @@ import { StatusPill, toneForStatus, humanizeStatus } from "@/g8/components/scree
 import { g8Get } from "@/g8/lib/g8-client";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { ContactDetail } from "@/g8/crm/components/contact-detail";
-import { dataOf, type Deal } from "../lib/deals-types";
+import { dataOf, type Deal, type DealContact } from "../lib/deals-types";
 
-export function DealContactsTab({ dealId }: { dealId: string }) {
+/** `renderContactActions` adds controls beside each contact (DealContactsEditor uses it for role, primary and remove). */
+export interface DealContactsTabProps {
+  dealId: string;
+  renderContactActions?: (contact: DealContact, deal: Deal) => ReactNode;
+  /** Open the person in your contacts screen (adds an "Open in contacts" button to the contact sheet). */
+  onOpenContact?: (contactId: number) => void;
+  /** Forwarded to the contact sheet's "Open company" button. */
+  onOpenCompany?: (companyId: number) => void;
+}
+
+export function DealContactsTab({ dealId, renderContactActions, onOpenContact, onOpenCompany }: DealContactsTabProps) {
   const [open, setOpen] = useState<number | null>(null);
-  const q = useG8Query(async (signal) => dataOf<Deal>(await g8Get(`/deals/${encodeURIComponent(dealId)}`, undefined, { signal })), [dealId]);
+  const q = useG8Query(async (signal) => dataOf<Deal>(await g8Get(`/deals/${encodeURIComponent(dealId)}`, undefined, { signal })), [dealId], { key: ["deals", "detail", dealId] });
   if (q.error) return <ApiError error={q.error} title="Could not load the deal's contacts" onRetry={() => void q.refetch()} />;
   if (!q.data) return <Skeleton className="h-24 w-full" aria-label="Loading contacts" />;
   const contacts = q.data.contacts ?? [];
@@ -33,7 +44,7 @@ export function DealContactsTab({ dealId }: { dealId: string }) {
     <>
       <ul className="divide-y rounded-md border" aria-label="Deal contacts">
         {contacts.map((c) => (
-          <li key={c.id}>
+          <li key={c.id} className={renderContactActions ? "flex items-center gap-2 pr-2" : undefined}>
             <button type="button" className="flex w-full items-center gap-3 p-3 text-left hover:bg-muted" onClick={() => setOpen(c.id)}>
               <EntityAvatar name={c.name || c.email || "Contact"} size="md" />
               <span className="min-w-0 flex-1">
@@ -43,13 +54,19 @@ export function DealContactsTab({ dealId }: { dealId: string }) {
               {c.role ? <StatusPill tone="neutral">{humanizeStatus(c.role)}</StatusPill> : null}
               {q.data?.primary_contact?.id === c.id ? <StatusPill tone="info">Primary</StatusPill> : null}
             </button>
+            {renderContactActions && q.data ? renderContactActions(c, q.data) : null}
           </li>
         ))}
       </ul>
       <Sheet open={open != null} onOpenChange={(o) => { if (!o) setOpen(null); }}>
         <SheetContent className="w-full overflow-y-auto sm:max-w-2xl">
           <SheetHeader><SheetTitle>Contact</SheetTitle><SheetDescription>The full CRM record.</SheetDescription></SheetHeader>
-          {open != null ? <ContactDetail contactId={open} /> : null}
+          {open != null ? (
+            <>
+              {onOpenContact ? <div className="px-4"><Button size="sm" variant="outline" onClick={() => onOpenContact(open)}>Open in contacts</Button></div> : null}
+              <ContactDetail contactId={open} onOpenCompany={onOpenCompany} />
+            </>
+          ) : null}
         </SheetContent>
       </Sheet>
     </>
@@ -58,16 +75,19 @@ export function DealContactsTab({ dealId }: { dealId: string }) {
 
 interface QuoteRow { id: string; title?: string | null; quote_number?: string | null; status?: string | null; total?: number | null; currency?: string | null }
 
-export function DealQuotesTab({ dealId, onOpenQuote }: { dealId: string; onOpenQuote?: (quoteId: string) => void }) {
+/** `actions` renders above the list, for example the quotes block's "Create quote from this deal" button. */
+export function DealQuotesTab({ dealId, onOpenQuote, actions, refreshKey }: { dealId: string; onOpenQuote?: (quoteId: string) => void; actions?: ReactNode; refreshKey?: number }) {
   const q = useG8Query(async (signal) => {
     const env = await g8Get("/quotes", { deal_id: dealId, page: 1, limit: 50 }, { signal });
     const inner = dataOf<{ items?: QuoteRow[] } | QuoteRow[]>(env);
     return Array.isArray(inner) ? inner : (inner.items ?? []);
-  }, [dealId]);
+  }, [dealId, refreshKey]);
   if (q.error) return <ApiError error={q.error} title="Could not load quotes" onRetry={() => void q.refetch()} />;
   if (!q.data) return <Skeleton className="h-24 w-full" aria-label="Loading quotes" />;
-  if (q.data.length === 0) return <EmptyState icon={<FileText className="size-8" />} title="No quotes for this deal" description="Create one from the Quotes screen." />;
+  if (q.data.length === 0) return <div className="space-y-3">{actions}<EmptyState icon={<FileText className="size-8" />} title="No quotes for this deal" description="Create one from the Quotes screen." /></div>;
   return (
+    <div className="space-y-3">
+    {actions}
     <Table>
       <TableHeader><TableRow><TableHead>Quote</TableHead><TableHead>Status</TableHead><TableHead className="text-right">Total</TableHead></TableRow></TableHeader>
       <TableBody>
@@ -83,5 +103,6 @@ export function DealQuotesTab({ dealId, onOpenQuote }: { dealId: string; onOpenQ
         ))}
       </TableBody>
     </Table>
+    </div>
   );
 }