@graph8/sdk 0.362.0 → 0.373.0

package/blocks/crm/hooks/use-page-query.ts

@@ -3,6 +3,7 @@
 import { useState } from "react";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import type { G8Envelope } from "@/g8/lib/g8-client";
+import type { G8QueryKey } from "@/g8/lib/g8-cache";
 import type { PageInfo } from "../lib/crm-types";
 
 export interface UsePageQueryResult<T> {
@@ -24,16 +25,23 @@ export interface UsePageQueryResult<T> {
  * have one, so the table keeps a page number instead.
  *
  * Changing `deps` (a filter, a search box) goes back to page 1 without a second request.
+ *
+ * Optional `cacheKey` joins the shared query cache (each page cached as `[...cacheKey, { page, deps }]`),
+ * so the list shows instantly when you come back and refreshes when a write invalidates its prefix.
  */
 export function usePageQuery<T>(
   fetchPage: (page: number, signal: AbortSignal) => Promise<G8Envelope<T[]>>,
   deps: readonly unknown[],
   pageSize = 25,
+  cacheKey?: readonly unknown[],
+  /** Hold the read (for example until URL filters are known). Default true. */
+  enabled = true,
 ): UsePageQueryResult<T> {
   const key = JSON.stringify(deps);
   const [state, setState] = useState({ key, page: 1 });
   const page = state.key === key ? state.page : 1;
-  const query = useG8Query((signal) => fetchPage(page, signal), [key, page]);
+  const queryKey: G8QueryKey | undefined = cacheKey ? [...cacheKey, { page, pageSize, deps: key }] : undefined;
+  const query = useG8Query((signal) => fetchPage(page, signal), [key, page], { key: queryKey, enabled });
 
   const info = query.data?.pagination as Partial<PageInfo> | undefined;
   const rows = (query.data?.data ?? []) as T[];

package/blocks/crm/lib/crm-types.ts

@@ -31,6 +31,8 @@ export interface ContactRecord {
   last_name?: string | null;
   full_name?: string | null;
   work_email?: string | null;
+  /** Personal addresses, comma separated. */
+  personal_emails?: string | null;
   direct_phone?: string | null;
   mobile_phone?: string | null;
   job_title?: string | null;
@@ -102,9 +104,26 @@ export function isMasked(value: unknown): boolean {
   return typeof value === "string" && value.trim() === "***";
 }
 
-export function contactName(c: Pick<ContactRecord, "first_name" | "last_name" | "full_name" | "work_email">): string {
+export function contactName(c: Pick<ContactRecord, "first_name" | "last_name" | "full_name" | "work_email"> & { id?: number | string }): string {
   const joined = [c.first_name, c.last_name].filter(Boolean).join(" ").trim();
-  return joined || c.full_name || (c.work_email && !isMasked(c.work_email) ? c.work_email : "") || "Unnamed contact";
+  return joined || c.full_name || (c.work_email && !isMasked(c.work_email) ? c.work_email : "") || (c.id != null ? `#${c.id}` : "-");
+}
+
+/**
+ * The line under a contact's name: "VP of Sales at Acme". The company is the company's own name (`company.name`, else the
+ * list row's `company_name`); it never falls back to anything about the person. "at ..." is left out when there is no
+ * title or no company. A company that happens to share the person's name (a freelancer) is shown as the API sent it.
+ */
+export function contactSubtitle(c: Pick<ContactRecord, "job_title" | "company_name" | "company">): string {
+  const company = [c.company?.name, c.company_name].map((n) => (n ?? "").trim()).find((n) => n !== "");
+  const title = (c.job_title ?? "").trim();
+  if (title && company) return `${title} at ${company}`;
+  return title || company || "No title or company";
+}
+
+/** A company's display name: name, then domain, then `#id`, then a dash. Never "Unnamed". */
+export function companyName(c: { name?: string | null; domain?: string | null; id?: number | string }): string {
+  return c.name || c.domain || (c.id != null ? `#${c.id}` : "-");
 }
 
 export function initials(name: string): string {
@@ -134,3 +153,8 @@ export function errorDetail(error: unknown): Record<string, unknown> | undefined
   const detail = (error as { detail?: unknown } | null)?.detail;
   return detail && typeof detail === "object" && !Array.isArray(detail) ? (detail as Record<string, unknown>) : undefined;
 }
+
+/** Passed as the second argument to a screen's `renderRowActions` / `renderDetailActions`: reload what the screen shows (filters, page, sort and selection are kept). */
+export interface ScreenActionContext {
+  reload: () => void;
+}

package/blocks/crm/lib/read-lists.ts

@@ -0,0 +1,16 @@
+"use client";
+
+/**
+ * readLists: one page of audience lists, for ListSelect and useAllLists.
+ *
+ * SDK operations: GET /lists?search&page&limit   (lists.listLists)   read
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { hasNextOf } from "@/g8/lib/paging";
+import type { ListSelectOption, ListsReader } from "@/g8/components/list-select";
+
+export const readLists: ListsReader = async (q, page, pageSize, signal) => {
+  const env = await g8Get<ListSelectOption[]>("/lists", { search: q || undefined, page, limit: pageSize }, { signal });
+  const rows = (env.data ?? []) as ListSelectOption[];
+  return { rows, hasNext: hasNextOf(env, pageSize, rows.length) };
+};

package/blocks/crm/lib/screen-parts.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+/**
+ * Small pieces shared by ContactsScreen, CompaniesScreen and TasksScreen: client-side sorting of the loaded
+ * page, a sortable table header, row selection that resets with the data source, the retry-safe bulk delete
+ * (Promise.allSettled, 404 = already gone, always refetch) and a pager. No operations of its own except the
+ * DELETE the caller names.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Button, TableHead } from "@graph8/sdk/ui";
+import { ArrowDown, ArrowUp, ChevronsUpDown } from "lucide-react";
+import { g8Delete } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { errorStatus, isMasked } from "./crm-types";
+
+export type SortDir = "asc" | "desc";
+export interface SortState { key: string; dir: SortDir }
+
+/** Sort rows by a text accessor. Empty and locked values always go last. Sorts only what is loaded (the API has no sort). */
+export function sortRows<T>(rows: T[], sort: SortState | null, get: (row: T, key: string) => string | null | undefined): T[] {
+  if (!sort) return rows;
+  const sign = sort.dir === "asc" ? 1 : -1;
+  const norm = (r: T) => { const v = get(r, sort.key); return v == null || v === "" || isMasked(v) ? null : v.toLowerCase(); };
+  return [...rows].sort((a, b) => {
+    const x = norm(a), y = norm(b);
+    if (x === y) return 0;
+    if (x == null) return 1;
+    if (y == null) return -1;
+    return x < y ? -sign : sign;
+  });
+}
+
+export function useSort(initial: SortState | null = null) {
+  const [sort, setSort] = useState<SortState | null>(initial);
+  const toggle = useCallback((key: string) => setSort((s) => (s?.key !== key ? { key, dir: "asc" } : s.dir === "asc" ? { key, dir: "desc" } : null)), []);
+  return { sort, toggle };
+}
+
+export function SortHead({ label, sortKey, sort, onSort, className }: { label: string; sortKey: string; sort: SortState | null; onSort: (key: string) => void; className?: string }) {
+  const active = sort?.key === sortKey;
+  const Icon = !active ? ChevronsUpDown : sort.dir === "asc" ? ArrowUp : ArrowDown;
+  return (
+    <TableHead className={className} aria-sort={active ? (sort.dir === "asc" ? "ascending" : "descending") : "none"}>
+      <button type="button" className="inline-flex items-center gap-1 font-medium hover:text-foreground" onClick={() => onSort(sortKey)}>
+        {label}<Icon className={`size-3.5 ${active ? "text-foreground" : "text-muted-foreground"}`} aria-hidden />
+      </button>
+    </TableHead>
+  );
+}
+
+/** Selected rows keyed by id. Clears itself when `scope` changes (another filter, list or reload). */
+export function useRowSelection<T extends { id: number | string }>(scope: string) {
+  const [selected, setSelected] = useState<Map<T["id"], T>>(new Map());
+  const last = useRef(scope);
+  useEffect(() => {
+    if (last.current === scope) return;
+    last.current = scope;
+    setSelected(new Map());
+  }, [scope]);
+  const toggle = (row: T) => setSelected((m) => { const n = new Map(m); if (!n.delete(row.id)) n.set(row.id, row); return n; });
+  const togglePage = (rows: T[]) => setSelected((m) => {
+    const n = new Map(m);
+    const all = rows.length > 0 && rows.every((r) => n.has(r.id));
+    for (const r of rows) all ? n.delete(r.id) : n.set(r.id, r);
+    return n;
+  });
+  const drop = (ids: Array<T["id"]>) => setSelected((m) => { const n = new Map(m); ids.forEach((id) => n.delete(id)); return n; });
+  const clear = () => setSelected(new Map());
+  const ids = useMemo(() => [...selected.keys()], [selected]);
+  return { selected, ids, rows: [...selected.values()], toggle, togglePage, drop, clear };
+}
+
+/** Deletes every id under `basePath` (`/contacts`). A 404 counts as done; never throws; `onSettled` gets who is gone. */
+export function useBulkDelete<Id extends number | string = number>(basePath: string, onSettled: (gone: Id[], total: number) => void) {
+  return useG8Mutation(async (ids: Id[]) => {
+    const results = await Promise.allSettled(ids.map((id) => g8Delete(`${basePath}/${id}`)));
+    const gone = ids.filter((_, i) => results[i].status === "fulfilled" || errorStatus((results[i] as PromiseRejectedResult).reason) === 404);
+    return { gone, total: ids.length };
+  }, {
+    // `/contacts` -> every cached contacts list and count refreshes (a deleted record's detail is left alone).
+    invalidates: [[basePath.split("/")[1], "list"], [basePath.split("/")[1], "count"], [basePath.split("/")[1], "record"]],
+    onSuccess: ({ gone, total }) => onSettled(gone, total),
+  });
+}
+
+export function Pager({ page, pageCount, total, noun, hasNext, loading, onPage }: { page: number; pageCount: number; total: number; noun: string; hasNext: boolean; loading: boolean; onPage: (p: number) => void }) {
+  return (
+    <div className="flex items-center justify-between border-t px-3 py-2 text-sm text-muted-foreground">
+      <span className="tabular-nums">{total.toLocaleString()} {noun}</span>
+      <div className="flex items-center gap-2">
+        <Button variant="outline" size="sm" disabled={page <= 1 || loading} onClick={() => onPage(page - 1)}>Previous</Button>
+        <span className="tabular-nums">Page {page} of {pageCount}</span>
+        <Button variant="outline" size="sm" disabled={!hasNext || loading} onClick={() => onPage(page + 1)}>Next</Button>
+      </div>
+    </div>
+  );
+}
+
+/** Date-only or timestamp to a short UTC date, so a `2026-10-15` due date never shifts a day. */
+export function formatDay(value?: string | null): string {
+  if (!value) return "";
+  const d = new Date(value.length === 10 ? `${value}T00:00:00Z` : value);
+  return Number.isNaN(d.getTime()) ? "" : d.toLocaleDateString(undefined, { timeZone: "UTC", month: "short", day: "numeric", year: "numeric" });
+}

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": [
     {
@@ -101,15 +127,136 @@
       "name": "DealsScreen",
       "file": "components/deals-screen.tsx",
       "purpose": "Finished deals product: board and list, new deal with the owner defaulted to the API key user, deal detail with activity, forecast and pipeline settings.",
-      "operations": [],
-      "tiers": []
+      "operations": [
+        "get_deal_deals__deal_id__get",
+        "list_contacts_contacts_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     },
     {
       "name": "DealContactsTab",
       "file": "components/deal-related.tsx",
       "purpose": "A deal's contacts with roles; open one for the full CRM record. Also exports DealQuotesTab, a read-only list of the deal's quotes.",
       "operations": [
-        "get_deal_deals__deal_id__get"
+        "get_deal_deals__deal_id__get",
+        "list_quotes_quotes_get"
+      ],
+      "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"
@@ -148,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": [
@@ -195,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>
+    </>
+  );
+}