@graph8/sdk 0.370.0 → 0.373.0

package/blocks/deals/README.md

@@ -11,19 +11,33 @@ compose under `DealDetail`'s `children`). Drag and drop needs `npm i @dnd-kit/co
 
 - Board and List views, search by name, a pipeline switcher when there is more than one pipeline.
 - Headline numbers: open deals, open value, estimated weighted value, won value.
-- Open a deal (board card or list row, deep link `?id=<deal id>`): Details (edit, stage history, confirmed delete) and
-  Activity tabs. Moving a card into a won or lost stage asks for the close date and amount first.
+- Open a deal (board card or list row, deep link `?id=<deal id>`): Details (edit, stage history, confirmed delete),
+  Contacts (add with a role, change a role, make primary, remove), Line items (add, edit, remove, totals), Notes (add,
+  edit, delete), Tasks (add, complete), Quotes and Activity tabs. Moving a card into a won or lost stage asks for the
+  close date and amount first.
+- **Close deal** (detail header): won or lost, with a close date, an amount for won, and a reason picked from the org's
+  close reasons (add one on the spot). **API gap:** no deal operation accepts a close reason (`closed_lost_reason` is
+  read only), so the reason is saved as a deal note, "Closed lost. Reason: Price". **Move to pipeline** is next to it.
+- Filters on Board and List: owner, stage, outcome (open, won, lost), stale (no activity for 7 to 90 days, or never),
+  activity, close-date range and "no contact". `filterQuery(state)` turns them into the `GET /deals` parameters.
+- Pipeline settings: create, rename, make default and delete (confirmed) pipelines, add or archive close reasons,
+  then the stage summary and StageEditor.
+- Quotes tab: the deal's quotes. To offer "Create quote from this deal", pass the quotes block's button:
+  `<DealsScreen renderQuoteActions={(deal) => <CreateQuoteFromDeal dealId={deal.id} />} />` (quotes depends on deals,
+  so the deals block cannot import it).
 - **New deal**: name, amount, close date, stage, an **owner** and **at least one contact**. The API requires both
   (`owner_id`, and `contact_ids` with one or more mashup contact ids that all work at one company; the older note that
   the list may be empty was wrong). A company that already has a deal is refused with 409 unless "Allow another deal"
   is ticked.
-- Forecast tab (totals, win rate, stuck deals, estimated weighted pipeline) and Pipeline settings tab (stage names,
-  probabilities, won/lost types, order, delete).
+- Forecast tab (totals, win rate, stuck deals, estimated weighted pipeline) and Pipeline settings tab (pipelines, close
+  reasons, stage names, probabilities, won/lost types, order, delete).
 - Slots for cross-block glue, all optional: `renderRowActions(deal)`, `renderDetailActions(deal)`,
   `extraDetailTabs`, `toolbarActions`. Example: add a Quotes tab with `<QuoteList dealId={deal.id} />`.
 
-Scopes the screen needs on top of the lists below: `team:read` (owner default and picker) and `contacts:read`
-(contact search). Proxy `allowedPrefixes` must include `deals`, `pipelines`, `team-members`, `contacts` (and `activity`
+Scopes the screen needs on top of the lists below: `team:read` (owner default and picker), `contacts:read`
+(contact search), `notes:read` and `notes:write` (Notes tab), `tasks:read` and `tasks:write` (Tasks tab) and
+`deals:delete` (remove a contact, delete a note, archive a close reason).
+Proxy `allowedPrefixes` must include `deals`, `pipelines`, `team-members`, `contacts`, `tasks` (and `activity`
 for the timeline).
 
 
@@ -107,3 +121,7 @@ create), `deal.id` + `deal.revision` (card -> detail -> update/delete).
 - `01-create-deal-and-advance.ts`: create, move, close as won.
 - `02-pipeline-report.ts`: totals, win rate, stall points, estimated weighted forecast.
 - `03-stale-deals-sweep.ts`: find neglected open deals, optionally flag them with one bulk write.
+
+## Cross-block glue
+
+- `RecordDealsTab` (`components/record-deals-tab.tsx`): the deals of one contact or company (`GET /contacts/{id}/deals`, `GET /companies/{id}/deals`), each opening in the deals screen. Use it as an `extraDetailTabs` entry of `ContactsScreen` / `CompaniesScreen`. `DealsScreen` also takes optional `onOpenContact` / `onOpenCompany`: the Contacts tab gains "Open in contacts" and the contact sheet gains "Open company".

package/blocks/deals/block.json

@@ -8,30 +8,56 @@
     "optimistic stage moves with rollback and closed-stage rules handled",
     "deal create, edit, stage history and confirmed delete",
     "stage editor: names, probabilities, won/lost types, order",
-    "forecast: totals, win rate, stuck deals and an estimated weighted pipeline"
+    "forecast: totals, win rate, stuck deals and an estimated weighted pipeline",
+    "deal notes, tasks, contacts with roles and primary, and line items with totals",
+    "close a deal as won or lost with a reason",
+    "create, rename, default and delete pipelines, and manage close reasons",
+    "list filters: owner, stage, outcome, stale, activity, close-date range, no contact"
   ],
   "dependsOn": [
     "crm"
   ],
   "operations": [
+    "add_deal_contact_deals__deal_id__contacts_post",
+    "archive_deal_close_reason_deals_close_reasons__reason_id__delete",
+    "create_deal_close_reason_deals_close_reasons_post",
     "create_deal_deals_post",
+    "create_deal_note_deals__deal_id__notes_post",
+    "create_global_task_tasks_post",
+    "create_pipeline_pipelines_post",
     "create_stage_pipelines__pipeline_id__stages_post",
     "delete_deal_deals__deal_id__delete",
+    "delete_deal_note_deals__deal_id__notes__note_id__delete",
+    "delete_pipeline_pipelines__pipeline_id__delete",
     "delete_stage_pipelines__pipeline_id__stages__stage_id__delete",
+    "get_company_deals_companies__company_id__deals_get",
+    "get_contact_deals_contacts__contact_id__deals_get",
     "get_deal_analytics_deals_analytics_get",
     "get_deal_deals__deal_id__get",
     "get_deal_stage_velocity_deals_stage_velocity_get",
     "get_my_team_member_team_members_me_get",
     "get_pipeline_pipelines__pipeline_id__get",
+    "list_all_tasks_tasks_get",
     "list_contacts_contacts_get",
+    "list_deal_close_reasons_deals_close_reasons_get",
     "list_deal_history_deals__deal_id__history_get",
+    "list_deal_line_items_deals__deal_id__line_items_get",
+    "list_deal_notes_deals__deal_id__notes_get",
     "list_deals_deals_get",
     "list_pipelines_deals_pipelines_get",
     "list_quotes_quotes_get",
     "list_team_members_team_members_get",
+    "move_deal_to_pipeline_deals__deal_id__pipeline_put",
+    "remove_deal_contact_deals__deal_id__contacts__person_id__delete",
     "reorder_stages_pipelines__pipeline_id__stages_reorder_put",
+    "replace_deal_line_items_deals__deal_id__line_items_put",
+    "set_deal_contact_role_deals__deal_id__contacts__contact_id__put",
+    "set_primary_deal_contact_deals__deal_id__contacts__person_id__primary_put",
     "update_deal_deals__deal_id__patch",
-    "update_stage_pipelines__pipeline_id__stages__stage_id__put"
+    "update_deal_note_deals__deal_id__notes__note_id__put",
+    "update_pipeline_pipelines__pipeline_id__put",
+    "update_stage_pipelines__pipeline_id__stages__stage_id__put",
+    "update_task_tasks__task_id__patch"
   ],
   "components": [
     {
@@ -120,6 +146,121 @@
       "tiers": [
         "read"
       ]
+    },
+    {
+      "name": "DealNotesTab",
+      "file": "components/deal-notes-tab.tsx",
+      "purpose": "Notes of one deal: list, add, edit (only when the text changed) and confirmed delete; synced notes are read only.",
+      "operations": [
+        "create_deal_note_deals__deal_id__notes_post",
+        "delete_deal_note_deals__deal_id__notes__note_id__delete",
+        "list_deal_notes_deals__deal_id__notes_get",
+        "update_deal_note_deals__deal_id__notes__note_id__put"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "DealTasksTab",
+      "file": "components/deal-tasks-tab.tsx",
+      "purpose": "Follow-up tasks linked to one deal: list (open or all), add with due date and priority, complete and reopen.",
+      "operations": [
+        "create_global_task_tasks_post",
+        "list_all_tasks_tasks_get",
+        "update_task_tasks__task_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "DealContactsEditor",
+      "file": "components/deal-contacts-editor.tsx",
+      "purpose": "Buying committee of one deal: add a contact with a role, change a role, make one primary, remove one (confirmed).",
+      "operations": [
+        "add_deal_contact_deals__deal_id__contacts_post",
+        "get_deal_deals__deal_id__get",
+        "list_contacts_contacts_get",
+        "remove_deal_contact_deals__deal_id__contacts__person_id__delete",
+        "set_deal_contact_role_deals__deal_id__contacts__contact_id__put",
+        "set_primary_deal_contact_deals__deal_id__contacts__person_id__primary_put"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "DealLineItems",
+      "file": "components/deal-line-items.tsx",
+      "purpose": "Products on a deal: add, edit and remove lines (dollars in, cents sent), per-line totals, the deal total and the quote-mismatch warning.",
+      "operations": [
+        "list_deal_line_items_deals__deal_id__line_items_get",
+        "replace_deal_line_items_deals__deal_id__line_items_put"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "DealActions",
+      "file": "components/close-deal-dialog.tsx",
+      "purpose": "Deal header actions: Close deal as won or lost with a reason (saved as a note, the API has no reason field), add close reasons, and Move to pipeline. CloseDealDialog is the dialog alone.",
+      "operations": [
+        "create_deal_close_reason_deals_close_reasons_post",
+        "create_deal_note_deals__deal_id__notes_post",
+        "list_deal_close_reasons_deals_close_reasons_get",
+        "move_deal_to_pipeline_deals__deal_id__pipeline_put",
+        "update_deal_deals__deal_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "PipelineEditor",
+      "file": "components/pipeline-editor.tsx",
+      "purpose": "Create, rename, make default and delete (confirmed) pipelines, and add or archive (confirmed) close reasons. Stages are edited by StageEditor.",
+      "operations": [
+        "archive_deal_close_reason_deals_close_reasons__reason_id__delete",
+        "create_deal_close_reason_deals_close_reasons_post",
+        "create_pipeline_pipelines_post",
+        "delete_pipeline_pipelines__pipeline_id__delete",
+        "list_deal_close_reasons_deals_close_reasons_get",
+        "list_pipelines_deals_pipelines_get",
+        "update_pipeline_pipelines__pipeline_id__put"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "DealFilterBar",
+      "file": "components/deal-filters.tsx",
+      "purpose": "List filters: owner, stage, outcome, stale (7 to 90 days), activity, close-date range and no contact. Pass filterQuery(state) to usePipelineDeals.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "RecordDealsTab",
+      "file": "components/record-deals-tab.tsx",
+      "purpose": "The deals linked to one contact or company, each opening in the deals screen; an extraDetailTabs entry for ContactsScreen and CompaniesScreen.",
+      "operations": [
+        "get_contact_deals_contacts__contact_id__deals_get",
+        "get_company_deals_companies__company_id__deals_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [
@@ -154,6 +295,10 @@
     {
       "file": "lib/deals-types.ts",
       "purpose": "Deal, pipeline and stage types, stage kind, money formatting, weighted-pipeline estimate and closed-stage error markers."
+    },
+    {
+      "file": "lib/deal-extras.ts",
+      "purpose": "Note, task, line-item and close-reason shapes, contact roles, money in cents, and the deal filter state with its GET /deals query."
     }
   ],
   "recipes": [
@@ -201,7 +346,11 @@
     "deals:delete",
     "deals:read",
     "deals:write",
+    "notes:read",
+    "notes:write",
     "quotes:read",
+    "tasks:read",
+    "tasks:write",
     "team:read"
   ],
   "defaults": [

package/blocks/deals/components/close-deal-dialog.tsx

@@ -0,0 +1,169 @@
+"use client";
+
+/**
+ * DealActions: the header actions of one deal: "Close deal" (won or lost, with a reason) and "Move to pipeline".
+ * CloseDealDialog is the dialog behind the first one and can be mounted on its own.
+ *
+ * SDK operations, in order:
+ *   1. GET  /deals/close-reasons?kind=won|lost           (deals.listDealCloseReasons)   read  - the reasons the org keeps
+ *      POST /deals/close-reasons { kind, label }         (deals.createDealCloseReason)  write - add a reason while closing
+ *   2. PATCH /deals/{id} { stage_id, close_date, amount?, expected_revision }  (deals.updateDeal)  write - the close itself
+ *   3. POST /deals/{id}/notes { content }                (notes.createDealNote)         write - records the reason on the deal
+ *   4. PUT  /deals/{id}/pipeline { target_pipeline_id }  (deals.moveDealToPipeline)     write
+ * API GAP: no deal operation accepts a close reason (`closed_lost_reason` is read-only on the deal), so the chosen
+ * reason is saved as a note, "Closed lost. Reason: Price", right after the stage moves. If the move succeeded but the
+ * note failed, the dialog says so and retries only the note (the deal is never closed twice).
+ * A won deal needs a close date and an amount; the API also needs an owner. Date-only values are sent as YYYY-MM-DD.
+ */
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogTitle, Input, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { g8Get, g8Patch, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { closedStageMarker, stageKind, type Deal, type Pipeline, type Stage } from "../lib/deals-types";
+import { reasonsOf } from "../lib/deal-extras";
+import { localToday } from "./pipeline-board";
+
+export interface CloseDealDialogProps {
+  deal: Deal;
+  /** The stages of the deal's pipeline. */
+  stages: Stage[];
+  open: boolean;
+  onClose: () => void;
+  /** Called once the deal is closed (and the reason recorded). */
+  onClosed?: () => void;
+}
+
+type Outcome = "won" | "lost";
+
+export function CloseDealDialog({ deal, stages, open, onClose, onClosed }: CloseDealDialogProps) {
+  const [outcome, setOutcome] = useState<Outcome>("won");
+  const [stageId, setStageId] = useState("");
+  const [date, setDate] = useState(deal.close_date?.slice(0, 10) ?? localToday());
+  const [amount, setAmount] = useState(deal.amount != null ? String(deal.amount) : "");
+  const [reasonId, setReasonId] = useState("");
+  const [newReason, setNewReason] = useState("");
+  // Retry-safe: once the stage move succeeded, a retry only records the reason.
+  const [moved, setMoved] = useState(false);
+  const targets = stages.filter((s) => stageKind(s) === outcome);
+  const stage = targets.find((s) => s.id === stageId) ?? targets[0];
+  const reasons = useG8Query(async (signal) => reasonsOf(await g8Get("/deals/close-reasons", { kind: outcome }, { signal })), [outcome], { enabled: open, key: ["deals", "close-reasons", outcome] });
+  const options = (reasons.data ?? []).filter((r) => !r.kind || r.kind === outcome);
+  const reason = options.find((r) => r.id === reasonId);
+
+  const addReason = useG8Mutation(async () => {
+    await g8Post("/deals/close-reasons", { kind: outcome, label: newReason.trim() });
+    const label = newReason.trim();
+    setNewReason("");
+    return label;
+  }, { invalidates: [["deals", "close-reasons"]], onSuccess: (label) => { void reasons.refetch().then((r) => { const found = r?.find((x) => x.label === label); if (found) setReasonId(found.id); }); } });
+
+  const close = useG8Mutation(async () => {
+    if (!moved) {
+      const body: Record<string, unknown> = { stage_id: stage?.id, close_date: date, expected_revision: deal.revision ?? undefined };
+      // Won always carries the amount (the API requires it); lost sends it only when it was changed.
+      if (amount !== "" && (outcome === "won" || Number(amount) !== deal.amount)) body.amount = Number(amount);
+      await g8Patch(`/deals/${encodeURIComponent(deal.id)}`, body);
+      setMoved(true);
+    }
+    if (reason) await g8Post(`/deals/${encodeURIComponent(deal.id)}/notes`, { content: `Closed ${outcome}. Reason: ${reason.label}` });
+  }, { invalidates: [["deals"]], onSuccess: () => { onClosed?.(); onClose(); } });
+
+  const valid = Boolean(stage) && Boolean(date) && (outcome !== "won" || amount !== "");
+  const marker = closedStageMarker(close.error);
+  return (
+    <Dialog open={open} onOpenChange={(o) => { if (!o && !close.loading) onClose(); }}>
+      <DialogContent>
+        <DialogTitle>Close "{deal.name ?? "this deal"}"</DialogTitle>
+        <DialogDescription>Moves the deal to a closed stage. The close date is required, and the amount for a won deal.</DialogDescription>
+        <form className="space-y-3" onSubmit={(e) => { e.preventDefault(); if (valid) void close.mutate(undefined); }}>
+          <div className="space-y-1">
+            <Label htmlFor="close-outcome">Outcome</Label>
+            <select id="close-outcome" className="h-9 w-full rounded-md border bg-background px-2 text-sm" disabled={moved} value={outcome} onChange={(e) => { setOutcome(e.target.value as Outcome); setStageId(""); setReasonId(""); }}>
+              <option value="won">Won</option>
+              <option value="lost">Lost</option>
+            </select>
+          </div>
+          {targets.length === 0 ? <p className="text-sm text-muted-foreground">This pipeline has no {outcome} stage. Add one under Pipeline settings (stage type "Closed {outcome}").</p> : null}
+          {targets.length > 1 ? (
+            <div className="space-y-1">
+              <Label htmlFor="close-stage">Stage</Label>
+              <select id="close-stage" className="h-9 w-full rounded-md border bg-background px-2 text-sm" disabled={moved} value={stage?.id ?? ""} onChange={(e) => setStageId(e.target.value)}>
+                {targets.map((s) => <option key={s.id} value={s.id}>{s.name}</option>)}
+              </select>
+            </div>
+          ) : null}
+          <div className="grid gap-3 sm:grid-cols-2">
+            <div className="space-y-1"><Label htmlFor="close-date">Close date</Label><Input id="close-date" type="date" disabled={moved} value={date} onChange={(e) => setDate(e.target.value)} /></div>
+            <div className="space-y-1"><Label htmlFor="close-amount">Amount{outcome === "won" ? "" : " (optional)"}</Label><Input id="close-amount" type="number" min={0} disabled={moved} value={amount} onChange={(e) => setAmount(e.target.value)} /></div>
+          </div>
+          <div className="space-y-1">
+            <Label htmlFor="close-reason">{outcome === "won" ? "Why did you win?" : "Why was it lost?"}</Label>
+            <select id="close-reason" className="h-9 w-full rounded-md border bg-background px-2 text-sm" value={reasonId} onChange={(e) => setReasonId(e.target.value)}>
+              <option value="">{reasons.loading ? "Loading reasons" : "No reason"}</option>
+              {options.map((r) => <option key={r.id} value={r.id}>{r.label}</option>)}
+            </select>
+            {reasons.error ? <ApiError error={reasons.error} compact title="Could not load reasons" onRetry={() => void reasons.refetch()} /> : null}
+            <div className="flex gap-2">
+              <Input aria-label="New reason" placeholder="Add a reason" value={newReason} onChange={(e) => setNewReason(e.target.value)} />
+              <Button type="button" variant="outline" loading={addReason.loading} disabled={!newReason.trim()} onClick={() => void addReason.mutate(undefined)}>Add reason</Button>
+            </div>
+            {addReason.error ? <ApiError error={addReason.error} title="Could not add the reason" /> : null}
+          </div>
+          {moved && close.error ? <p role="status" className="text-sm text-muted-foreground">The deal is closed, but the reason was not saved. Try again to save only the reason.</p> : null}
+          {close.error ? <ApiError error={marker ? new Error(`The API needs more before this deal can close (${marker.replace(/_/g, " ")}).`) : close.error} title={moved ? "Could not save the reason" : "Could not close the deal"} /> : null}
+          <div className="flex justify-end gap-2">
+            <Button type="button" variant="outline" disabled={close.loading} onClick={onClose}>Cancel</Button>
+            <Button type="submit" loading={close.loading} disabled={!valid}>{moved ? "Save reason" : `Close as ${outcome}`}</Button>
+          </div>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export interface DealActionsProps {
+  deal: Deal;
+  pipelines: Pipeline[];
+  onChanged?: () => void;
+}
+
+export function DealActions({ deal, pipelines, onChanged }: DealActionsProps) {
+  const [closing, setClosing] = useState(false);
+  const [moving, setMoving] = useState(false);
+  const [target, setTarget] = useState("");
+  const current = pipelines.find((p) => p.id === deal.pipeline_id);
+  const stages = current?.stages ?? [];
+  const isOpen = stageKind(stages.find((s) => s.id === deal.stage_id)) === "open";
+  const others = pipelines.filter((p) => p.id !== deal.pipeline_id);
+  const move = useG8Mutation(() => g8Put(`/deals/${encodeURIComponent(deal.id)}/pipeline`, { target_pipeline_id: target }), {
+    invalidates: [["deals"]],
+    onSuccess: () => { setMoving(false); setTarget(""); onChanged?.(); },
+  });
+  return (
+    <>
+      {isOpen && stages.length > 0 ? <Button size="sm" onClick={() => setClosing(true)}>Close deal</Button> : null}
+      {others.length > 0 ? <Button size="sm" variant="outline" onClick={() => setMoving(true)}>Move to pipeline</Button> : null}
+      {closing ? <CloseDealDialog key={deal.id} deal={deal} stages={stages} open onClose={() => setClosing(false)} onClosed={onChanged} /> : null}
+      <Dialog open={moving} onOpenChange={(o) => { if (!o && !move.loading) setMoving(false); }}>
+        <DialogContent>
+          <DialogTitle>Move "{deal.name ?? "this deal"}" to another pipeline</DialogTitle>
+          <DialogDescription>The API places it in a stage of the pipeline you pick; check the board afterwards.</DialogDescription>
+          <div className="space-y-1">
+            <Label htmlFor="move-pipeline">Pipeline</Label>
+            <select id="move-pipeline" className="h-9 w-full rounded-md border bg-background px-2 text-sm" value={target} onChange={(e) => setTarget(e.target.value)}>
+              <option value="">Choose a pipeline</option>
+              {others.map((p) => <option key={p.id} value={p.id}>{p.name}</option>)}
+            </select>
+          </div>
+          {move.error ? <ApiError error={move.error} title="Could not move the deal" /> : null}
+          <div className="flex justify-end gap-2">
+            <Button type="button" variant="outline" disabled={move.loading} onClick={() => setMoving(false)}>Cancel</Button>
+            <Button type="button" loading={move.loading} disabled={!target} onClick={() => void move.mutate(undefined)}>Move deal</Button>
+          </div>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

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

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