@graph8/sdk 0.303.0 → 0.357.0

package/blocks/deals/components/pipeline-board.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+/**
+ * PipelineBoard: the deals kanban. One column per stage, drag a card to move the deal, column counts and totals.
+ *
+ * SDK operations, in order:
+ *   1. GET   /deals/pipelines                    (deals.listPipelines)  read  - columns and stage ids
+ *   2. GET   /deals?pipeline_id=&page=&limit=    (deals.listDeals)      read  - the cards (all pages, capped)
+ *   3. PATCH /deals/{id}  { stage_id, expected_revision, close_date?, amount? }   (deals.updateDeal)   write
+ * A stage move is an ordinary write (no confirm dialog): it contacts nobody and is easy to move back.
+ * Moving into a won/lost stage has server rules: a close date (and an amount for won) must exist. The board asks
+ * for them in a small dialog first; if the API still answers with a closed-stage marker it explains and rolls back.
+ *
+ * Drag and drop uses @dnd-kit/core (an optional peer of @graph8/sdk, declared by this block). Every card also has a
+ * "Move to" select, which is the keyboard and screen-reader path and does the exact same PATCH.
+ */
+import { useMemo, useState } from "react";
+import { DndContext, KeyboardSensor, PointerSensor, useDraggable, useDroppable, useSensor, useSensors, type DragEndEvent } from "@dnd-kit/core";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { usePipelineDeals } from "../hooks/use-pipeline-deals";
+import { usePipelines } from "../hooks/use-pipelines";
+import { closedStageMarker, formatDate, formatMoney, stageKind, sumAmounts, type Deal, type Stage } from "../lib/deals-types";
+
+export interface PipelineBoardProps {
+  /** Show this pipeline; defaults to the org's default one. */
+  pipelineId?: string;
+  search?: string;
+  ownerId?: string;
+  onSelectDeal?: (deal: Deal) => void;
+  className?: string;
+}
+
+function Card({ deal, stages, busy, onMove, onSelect }: { deal: Deal; stages: Stage[]; busy: boolean; onMove: (stage: Stage) => void; onSelect?: (deal: Deal) => void }) {
+  const { attributes, listeners, setNodeRef, transform, isDragging } = useDraggable({ id: deal.id, disabled: busy });
+  const style = transform ? { transform: `translate3d(${transform.x}px, ${transform.y}px, 0)` } : undefined;
+  return (
+    <div ref={setNodeRef} style={style} className={`rounded-md border bg-background p-3 text-sm shadow-xs ${isDragging ? "opacity-60" : ""}`} data-deal-id={deal.id}>
+      <div className="flex items-start justify-between gap-2">
+        <button type="button" className="text-left font-medium hover:underline" onClick={() => onSelect?.(deal)}>{deal.name || "Untitled deal"}</button>
+        <button type="button" aria-label={`Drag ${deal.name ?? "deal"}`} className="cursor-grab px-1 text-muted-foreground" {...listeners} {...attributes}>::</button>
+      </div>
+      <div className="mt-1 text-muted-foreground">{formatMoney(deal.amount, deal.currency)}</div>
+      <div className="mt-1 flex justify-between text-xs text-muted-foreground">
+        <span>{deal.owner_name ?? deal.owner_email ?? "No owner"}</span>
+        <span>{formatDate(deal.close_date)}</span>
+      </div>
+      <select aria-label={`Move ${deal.name ?? "deal"} to`} aria-busy={busy} disabled={busy} className="mt-2 h-7 w-full rounded border bg-background px-1 text-xs" value={deal.stage_id ?? ""} onChange={(e) => { const s = stages.find((x) => x.id === e.target.value); if (s) onMove(s); }}>
+        {stages.map((s) => <option key={s.id} value={s.id}>{s.name}</option>)}
+      </select>
+    </div>
+  );
+}
+
+function Column({ stage, stages, deals, moving, onMove, onSelect }: { stage: Stage; stages: Stage[]; deals: Deal[]; moving: ReadonlySet<string>; onMove: (deal: Deal, stage: Stage) => void; onSelect?: (deal: Deal) => void }) {
+  const { setNodeRef, isOver } = useDroppable({ id: stage.id });
+  const kind = stageKind(stage);
+  return (
+    <section ref={setNodeRef} aria-label={stage.name} className={`flex w-72 shrink-0 flex-col gap-2 rounded-lg border bg-muted/40 p-2 ${isOver ? "ring-2 ring-primary" : ""}`}>
+      <header className="flex items-center justify-between px-1">
+        <h3 className="text-sm font-semibold">{stage.name}{kind !== "open" ? ` (${kind})` : ""}</h3>
+        <span className="text-xs text-muted-foreground">{deals.length} · {formatMoney(sumAmounts(deals), deals[0]?.currency)}</span>
+      </header>
+      <div className="flex min-h-16 flex-col gap-2">
+        {deals.map((d) => <Card key={d.id} deal={d} stages={stages} busy={moving.has(d.id)} onMove={(s) => onMove(d, s)} onSelect={onSelect} />)}
+      </div>
+    </section>
+  );
+}
+
+/** Today's date in the USER's time zone as YYYY-MM-DD (toISOString would give tomorrow's date in the evening west of UTC). */
+export function localToday(now = new Date()): string {
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())}`;
+}
+
+function CloseDialog({ stage, deal, onConfirm, onCancel }: { stage: Stage; deal: Deal; onConfirm: (extra: { close_date: string; amount?: number }) => void; onCancel: () => void }) {
+  const won = stageKind(stage) === "won";
+  const [date, setDate] = useState(deal.close_date?.slice(0, 10) ?? localToday());
+  const [amount, setAmount] = useState(deal.amount != null ? String(deal.amount) : "");
+  const valid = Boolean(date) && (!won || amount !== "");
+  return (
+    <div role="dialog" aria-modal="true" aria-label={`Close deal as ${stageKind(stage)}`} className="fixed inset-0 z-50 flex items-center justify-center bg-black/40 p-4">
+      <form className="w-full max-w-sm space-y-3 rounded-lg bg-background p-5 shadow-xl" onSubmit={(e) => { e.preventDefault(); if (valid) onConfirm({ close_date: date, amount: amount === "" ? undefined : Number(amount) }); }}>
+        <h2 className="text-base font-semibold">Move "{deal.name}" to {stage.name}</h2>
+        <div className="space-y-1"><Label htmlFor="cd-date">Close date</Label><Input id="cd-date" type="date" value={date} onChange={(e) => setDate(e.target.value)} /></div>
+        {won ? <div className="space-y-1"><Label htmlFor="cd-amount">Amount</Label><Input id="cd-amount" type="number" min={0} value={amount} onChange={(e) => setAmount(e.target.value)} /></div> : null}
+        <div className="flex justify-end gap-2"><Button type="button" variant="outline" onClick={onCancel}>Cancel</Button><Button type="submit" disabled={!valid}>Move deal</Button></div>
+      </form>
+    </div>
+  );
+}
+
+export function PipelineBoard({ pipelineId, search, ownerId, onSelectDeal, className }: PipelineBoardProps) {
+  const pipelines = usePipelines();
+  const pipeline = pipelines.pipelines.find((p) => p.id === pipelineId) ?? pipelines.defaultPipeline;
+  const { deals, loading, error, reload, moveDeal, movingIds } = usePipelineDeals(pipeline?.id, { search, ownerId });
+  const [closing, setClosing] = useState<{ deal: Deal; stage: Stage } | null>(null);
+  const [moveError, setMoveError] = useState<unknown>(null);
+  const sensors = useSensors(useSensor(PointerSensor, { activationConstraint: { distance: 6 } }), useSensor(KeyboardSensor));
+  const stages = pipeline?.stages ?? [];
+  const byStage = useMemo(() => {
+    const map = new Map<string, Deal[]>(stages.map((s) => [s.id, []]));
+    for (const d of deals) map.get(d.stage_id ?? "")?.push(d);
+    return map;
+  }, [deals, stages]);
+
+  const request = async (deal: Deal, stage: Stage, extra?: { close_date?: string; amount?: number }) => {
+    if (deal.stage_id === stage.id || movingIds.has(deal.id)) return;
+    setMoveError(null);
+    if (stageKind(stage) !== "open" && !extra) { setClosing({ deal, stage }); return; }
+    try { await moveDeal(deal, stage.id, extra); } catch (err) {
+      const marker = closedStageMarker(err);
+      setMoveError(marker ? new Error(`The API needs more before this deal can close (${marker.replace(/_/g, " ")}).`) : err);
+    }
+  };
+  const onDragEnd = (e: DragEndEvent) => {
+    const deal = deals.find((d) => d.id === e.active.id);
+    const stage = stages.find((s) => s.id === e.over?.id);
+    if (deal && stage) void request(deal, stage);
+  };
+
+  if (pipelines.error) return <ApiError error={pipelines.error} title="Could not load pipelines" onRetry={() => void pipelines.refetch()} />;
+  if (pipelines.loading || !pipeline) return pipelines.loading ? <Skeleton className="h-64 w-full" aria-label="Loading pipeline" /> : <EmptyState title="No pipeline yet" description="Create a pipeline with stages, then your deals appear here." />;
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      <h2 className="text-base font-semibold">{pipeline.name}</h2>
+      {error ? <ApiError error={error} title="Could not load deals" onRetry={() => void reload()} /> : null}
+      {moveError ? <ApiError error={moveError} title="That move was not saved" /> : null}
+      {loading && deals.length === 0 ? <Skeleton className="h-48 w-full" aria-label="Loading deals" /> : (
+        <DndContext sensors={sensors} onDragEnd={onDragEnd}>
+          <div className="flex gap-3 overflow-x-auto pb-2">
+            {stages.map((s) => <Column key={s.id} stage={s} stages={stages} deals={byStage.get(s.id) ?? []} moving={movingIds} onMove={(d, st) => void request(d, st)} onSelect={onSelectDeal} />)}
+          </div>
+        </DndContext>
+      )}
+      {!loading && !error && deals.length === 0 ? <EmptyState title="No deals in this pipeline" description="Create a deal and it lands in the first stage." /> : null}
+      {closing ? <CloseDialog stage={closing.stage} deal={closing.deal} onCancel={() => setClosing(null)} onConfirm={(extra) => { const c = closing; setClosing(null); void request(c.deal, c.stage, extra); }} /> : null}
+    </div>
+  );
+}

package/blocks/deals/components/stage-editor.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+/**
+ * StageEditor: configure a pipeline's stages: names, win probability, won/lost type, colour and order.
+ *
+ * SDK operations, in order:
+ *   1. GET    /pipelines/{id}                        (cliPipelines.getPipeline)    read
+ *   2. POST   /pipelines/{id}/stages                 (cliPipelines.createStage)    write
+ *      PUT    /pipelines/{id}/stages/{stage_id}      (cliPipelines.updateStage)    write
+ *      PUT    /pipelines/{id}/stages/reorder         (cliPipelines.reorderStages)  write - send ALL stage ids in the new order
+ *   3. DELETE /pipelines/{id}/stages/{stage_id}      (cliPipelines.deleteStage)    DESTRUCTIVE -> ConfirmSpendDialog first
+ * Set probabilities: the forecast's weighted pipeline treats an unset (0) probability as "not configured".
+ * A stage with `stage_type` "won" or "lost" closes the deal and enforces a close date (and amount for won).
+ */
+import { useEffect, useState } from "react";
+import { Button, Input, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+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 { dataOf, sortedStages, type Pipeline, type Stage } from "../lib/deals-types";
+
+export interface StageEditorProps {
+  pipelineId: string;
+  onChanged?: (stages: Stage[]) => void;
+  className?: string;
+}
+
+const TYPES = [["open", "Open"], ["won", "Closed won"], ["lost", "Closed lost"]] as const;
+
+export function StageEditor({ pipelineId, onChanged, className }: StageEditorProps) {
+  const base = `/pipelines/${encodeURIComponent(pipelineId)}`;
+  const pipeline = useG8Query(async (signal) => dataOf<Pipeline>(await g8Get(base, undefined, { signal })), [pipelineId]);
+  const [stages, setStages] = useState<Stage[]>([]);
+  const [newName, setNewName] = useState("");
+  const [removing, setRemoving] = useState<Stage | null>(null);
+  const [savingId, setSavingId] = useState<string | null>(null);
+  useEffect(() => { if (pipeline.data) setStages(sortedStages(pipeline.data)); }, [pipeline.data]);
+
+  const done = (next: Stage[]) => { setStages(next); onChanged?.(next); };
+  const save = useG8Mutation(async (s: Stage) => {
+    setSavingId(s.id);
+    try {
+    const saved = dataOf<Stage>(await g8Put(`${base}/stages/${encodeURIComponent(s.id)}`, { name: s.name, probability: s.probability ?? 0, stage_type: s.stage_type ?? "open", color: s.color ?? undefined }));
+    done(stages.map((x) => (x.id === saved.id ? { ...x, ...saved } : x)));
+    } finally { setSavingId(null); }
+  });
+  const add = useG8Mutation(async (name: string) => {
+    const created = dataOf<Stage>(await g8Post(`${base}/stages`, { name, probability: 0, stage_type: "open" }));
+    done([...stages, created]);
+    setNewName("");
+  });
+  const reorder = useG8Mutation(async (next: Stage[]) => {
+    await g8Put(`${base}/stages/reorder`, { stage_ids: next.map((s) => s.id) });
+    done(next);
+  });
+  const remove = useG8Mutation(async (s: Stage) => {
+    await g8Delete(`${base}/stages/${encodeURIComponent(s.id)}`);
+    done(stages.filter((x) => x.id !== s.id));
+    setRemoving(null);
+  }, { onError: () => setRemoving(null) });
+
+  const patch = (id: string, change: Partial<Stage>) => setStages((all) => all.map((s) => (s.id === id ? { ...s, ...change } : s)));
+  const swap = (i: number, j: number) => { const next = [...stages]; [next[i], next[j]] = [next[j], next[i]]; void reorder.mutate(next); };
+  const failure = save.error ?? add.error ?? reorder.error ?? remove.error;
+
+  if (pipeline.error) return <ApiError error={pipeline.error} title="Could not load the pipeline" onRetry={() => void pipeline.refetch()} />;
+  if (pipeline.loading && !pipeline.data) return <Skeleton className="h-48 w-full" aria-label="Loading stages" />;
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      <h2 className="text-base font-semibold">{pipeline.data?.name} stages</h2>
+      {failure ? <ApiError error={failure} title="That stage change failed" /> : null}
+      <ol className="space-y-2">
+        {stages.map((s, i) => (
+          <li key={s.id} className="flex flex-wrap items-center gap-2 rounded-md border p-2">
+            <Input aria-label={`Name of ${s.name}`} className="w-48" value={s.name} onChange={(e) => patch(s.id, { name: e.target.value })} />
+            <Input aria-label={`Probability of ${s.name}`} type="number" min={0} max={100} className="w-24" value={s.probability ?? 0} onChange={(e) => patch(s.id, { probability: Math.min(100, Math.max(0, Number(e.target.value))) })} />
+            <select aria-label={`Type of ${s.name}`} className="h-9 rounded-md border bg-background px-2 text-sm" value={(s.stage_type ?? "open").toLowerCase()} onChange={(e) => patch(s.id, { stage_type: e.target.value })}>
+              {TYPES.map(([v, label]) => <option key={v} value={v}>{label}</option>)}
+            </select>
+            <Button size="sm" variant="outline" loading={savingId === s.id} disabled={savingId === s.id} onClick={() => void save.mutate(s)}>Save</Button>
+            <Button size="sm" variant="ghost" aria-label={`Move ${s.name} up`} disabled={i === 0 || reorder.loading} onClick={() => swap(i, i - 1)}>Up</Button>
+            <Button size="sm" variant="ghost" aria-label={`Move ${s.name} down`} disabled={i === stages.length - 1 || reorder.loading} onClick={() => swap(i, i + 1)}>Down</Button>
+            <Button size="sm" variant="ghost" aria-label={`Delete ${s.name}`} onClick={() => setRemoving(s)}>Delete</Button>
+          </li>
+        ))}
+      </ol>
+      <div className="flex gap-2">
+        <Input aria-label="New stage name" placeholder="New stage name" value={newName} onChange={(e) => setNewName(e.target.value)} />
+        <Button disabled={!newName.trim() || add.loading} onClick={() => void add.mutate(newName.trim())}>Add stage</Button>
+      </div>
+      <ConfirmSpendDialog open={removing != null} tier="destructive" title={`Delete the "${removing?.name}" stage?`} description="Deals sitting in this stage must be moved first; the API refuses to delete a stage that still has deals." confirmLabel="Delete stage" affected={1} confirming={remove.loading} onConfirm={() => removing && void remove.mutate(removing)} onCancel={() => setRemoving(null)} />
+    </div>
+  );
+}

package/blocks/deals/hooks/use-pipeline-deals.ts

@@ -0,0 +1,67 @@
+"use client";
+
+/**
+ * usePipelineDeals: the deals in one pipeline, all pages up to `maxDeals`, with an optimistic stage move.
+ *
+ * SDK operations:
+ *   GET   /deals?pipeline_id=&search=&owner_id=&page=&limit=   (deals.listDeals)   read
+ *   PATCH /deals/{deal_id}                                      (deals.updateDeal)  write - the stage move
+ *
+ * `moveDeal` updates the board immediately and, if the API refuses, refetches the list (the server is the truth)
+ * and rethrows; `movingIds` holds the deals with a move in flight so a card can disable only its own control (a stale revision, or a closed-stage
+ * rule such as "a won deal needs a close date and an amount"). Pass those with `extra`.
+ * A deal in a closed stage is still returned by the list; filter on the stage kind to hide won/lost.
+ */
+import { useCallback, useEffect, useState } from "react";
+import { g8Get, g8Patch } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import type { Deal } from "../lib/deals-types";
+import { dataOf } from "../lib/deals-types";
+
+export interface PipelineDealFilters {
+  search?: string;
+  ownerId?: string;
+}
+
+export interface MoveExtra {
+  close_date?: string;
+  amount?: number;
+}
+
+export function usePipelineDeals(pipelineId: string | undefined, filters: PipelineDealFilters = {}, maxDeals = 500) {
+  const [deals, setDeals] = useState<Deal[]>([]);
+  const [movingIds, setMovingIds] = useState<ReadonlySet<string>>(new Set());
+  const query = useG8Query(
+    async (signal) => {
+      const all: Deal[] = [];
+      for (let page = 1; all.length < maxDeals; page++) {
+        const env = await g8Get<Deal[]>("/deals", { pipeline_id: pipelineId, search: filters.search || undefined, owner_id: filters.ownerId || undefined, page, limit: 100 }, { signal });
+        all.push(...(env.data ?? []));
+        if (!env.pagination?.has_next) break;
+      }
+      return all.slice(0, maxDeals);
+    },
+    [pipelineId, filters.search, filters.ownerId, maxDeals],
+    { enabled: Boolean(pipelineId) },
+  );
+  useEffect(() => { if (query.data) setDeals(query.data); }, [query.data]);
+
+  const moveDeal = useCallback(async (deal: Deal, stageId: string, extra: MoveExtra = {}): Promise<Deal> => {
+    const mark = (on: boolean) => setMovingIds((ids) => { const next = new Set(ids); if (on) next.add(deal.id); else next.delete(deal.id); return next; });
+    mark(true);
+    setDeals((all) => all.map((d) => (d.id === deal.id ? { ...d, stage_id: stageId } : d)));
+    try {
+      const saved = dataOf<Deal>(await g8Patch(`/deals/${encodeURIComponent(deal.id)}`, { stage_id: stageId, expected_revision: deal.revision ?? undefined, ...extra }));
+      setDeals((all) => all.map((d) => (d.id === deal.id ? { ...d, ...saved } : d)));
+      return saved;
+    } catch (err) {
+      // Roll back by re-reading the server's truth: a snapshot taken before the move could itself be stale.
+      await query.refetch();
+      throw err;
+    } finally {
+      mark(false);
+    }
+  }, [query]);
+
+  return { deals, loading: query.loading, error: query.error, reload: query.refetch, moveDeal, movingIds };
+}

package/blocks/deals/hooks/use-pipelines.ts

@@ -0,0 +1,19 @@
+"use client";
+
+/**
+ * usePipelines: every deal pipeline with its stages in order. The source of stage ids for everything else.
+ *
+ * SDK operations: GET /deals/pipelines (deals.listPipelines), read tier.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { sortedStages, type Pipeline } from "../lib/deals-types";
+
+export function usePipelines() {
+  const q = useG8Query(async (signal) => {
+    const env = await g8Get<Pipeline[]>("/deals/pipelines", undefined, { signal });
+    return (env.data ?? []).map((p) => ({ ...p, stages: sortedStages(p) }));
+  }, []);
+  const pipelines = q.data ?? [];
+  return { ...q, pipelines, defaultPipeline: pipelines.find((p) => p.is_default) ?? pipelines[0] };
+}

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

@@ -0,0 +1,128 @@
+"use client";
+
+/**
+ * Deal, pipeline and stage shapes plus the money/stage helpers the deals components share.
+ *
+ * Stage ids ALWAYS come from the API (`GET /deals/pipelines`); never type one in. A stage's `stage_type` is free
+ * text on the server ("won", "lost", or anything else for an open stage), so compare it through `stageKind()`.
+ */
+
+export interface DealContact {
+  id: number;
+  name?: string | null;
+  email?: string | null;
+  role?: string | null;
+  title?: string | null;
+}
+
+export interface Deal {
+  id: string;
+  name: string | null;
+  amount?: number | null;
+  currency?: string | null;
+  close_date?: string | null;
+  description?: string | null;
+  owner_id?: string | null;
+  owner_name?: string | null;
+  owner_email?: string | null;
+  pipeline_id?: string | null;
+  pipeline_name?: string | null;
+  stage_id?: string | null;
+  stage_name?: string | null;
+  contact_count?: number;
+  contacts?: DealContact[] | null;
+  primary_contact?: DealContact | null;
+  closed_lost_reason?: string | null;
+  last_activity_at?: string | null;
+  /** Send it back as `expected_revision` so a concurrent edit is rejected instead of overwritten. */
+  revision?: number | null;
+  updated_at?: string | null;
+}
+
+export interface Stage {
+  id: string;
+  name: string;
+  color?: string | null;
+  position?: number | null;
+  /** 0 to 100. */
+  probability?: number | null;
+  stage_type?: string | null;
+}
+
+export interface Pipeline {
+  id: string;
+  name: string;
+  is_default?: boolean;
+  stages: Stage[];
+}
+
+export type StageKind = "won" | "lost" | "open";
+
+export function stageKind(stage: Pick<Stage, "stage_type"> | null | undefined): StageKind {
+  const t = (stage?.stage_type ?? "").trim().toLowerCase();
+  return t === "won" || t === "lost" ? t : "open";
+}
+
+export function sortedStages(pipeline: Pipeline | undefined): Stage[] {
+  return [...(pipeline?.stages ?? [])].sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+}
+
+export function formatMoney(amount: number | null | undefined, currency?: string | null): string {
+  if (amount == null) return "No amount";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency: currency || "USD", maximumFractionDigits: 0 }).format(amount);
+  } catch {
+    return String(amount);
+  }
+}
+
+export function sumAmounts(deals: ReadonlyArray<Pick<Deal, "amount">>): number {
+  return deals.reduce((total, d) => total + (d.amount ?? 0), 0);
+}
+
+/**
+ * Probability-weighted value of open deals. This is an ESTIMATE computed here: the analytics endpoint refuses to
+ * return a weighted total because a stage's probability defaults to 0 when nobody configured it, which would
+ * silently drop those deals. `unweighted` counts the deals whose stage has no probability set.
+ */
+export function weightedPipeline(deals: ReadonlyArray<Deal>, stages: ReadonlyArray<Stage>): { value: number; unweighted: number } {
+  const byId = new Map(stages.map((s) => [s.id, s]));
+  let value = 0;
+  let unweighted = 0;
+  for (const deal of deals) {
+    const stage = deal.stage_id ? byId.get(deal.stage_id) : undefined;
+    if (!stage || stageKind(stage) !== "open") continue;
+    if (!stage.probability) unweighted++;
+    value += (deal.amount ?? 0) * ((stage.probability ?? 0) / 100);
+  }
+  return { value, unweighted };
+}
+
+/** Markers the API puts at the start of a 422 `detail` when a deal cannot move into a closed stage. */
+export const CLOSED_STAGE_MARKERS = [
+  "close_date_required_for_won_stage",
+  "close_date_required_for_lost_stage",
+  "amount_required_for_won_stage",
+  "owner_required_for_closed_stage",
+] as const;
+
+export function closedStageMarker(error: unknown): (typeof CLOSED_STAGE_MARKERS)[number] | null {
+  const detail = String((error as { detail?: unknown } | null)?.detail ?? (error as Error | null)?.message ?? "");
+  return CLOSED_STAGE_MARKERS.find((m) => detail.startsWith(m)) ?? null;
+}
+
+export function dataOf<T>(env: unknown): T {
+  const e = env as { data?: unknown } | null;
+  return (e && typeof e === "object" && "data" in e && e.data != null ? e.data : env) as T;
+}
+
+/**
+ * A date-only value (a close date) for display. Always UTC: `2026-10-01` must read as the 1st in every time zone,
+ * whereas local formatting shows the 30th west of UTC. Send date-only values to the API as `YYYY-MM-DD`, never
+ * through `new Date(x).toISOString()`.
+ */
+export function formatDate(value: string | null | undefined): 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" });
+}

package/blocks/deals/recipes/01-create-deal-and-advance.ts

@@ -0,0 +1,32 @@
+/**
+ * @title Create a deal and move it through the pipeline
+ * @when Tracking revenue from an agent or a webhook. Stage ids come from `deals.pipelines()`; never guess them.
+ * `owner_id` is a graph8 user id. Moving into a won/lost stage needs a close date (and an amount for won), or the
+ * API answers 422 with a marker such as `close_date_required_for_won_stage`. Pass `expected_revision` so a
+ * concurrent edit is refused instead of overwritten.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const { data: pipelines } = await g8.deals.pipelines();
+const pipeline = pipelines.find((p) => p.is_default) ?? pipelines[0];
+const stages = [...pipeline.stages].sort((a, b) => (a.position ?? 0) - (b.position ?? 0));
+const won = stages.find((s) => (s.stage_type ?? "").toLowerCase() === "won");
+
+const deal = await g8.deals.create({
+  name: "Acme - annual plan",
+  owner_id: "user_123",
+  contact_ids: [101],
+  amount: 24000,
+  currency: "USD",
+  pipeline_id: pipeline.id,
+  stage_id: stages[0].id,
+});
+if (!deal.id) throw new Error("graph8 returned a deal without an id");
+
+// An ordinary move between open stages.
+const next = await g8.deals.update(deal.id, { stage_id: stages[1].id });
+
+// Closing as won: the close date (past dates are allowed) and the amount must exist on the deal or in this call.
+if (won) await g8.deals.update(deal.id, { stage_id: won.id, close_date: new Date().toISOString(), amount: 24000, expected_revision: next.revision ?? undefined });

package/blocks/deals/recipes/02-pipeline-report.ts

@@ -0,0 +1,35 @@
+/**
+ * @title Pipeline report: totals, win rate, where deals stall, and an estimated weighted forecast
+ * @when A weekly summary for a manager or an agent answering "how is the pipeline?". Read-only. The analytics
+ * endpoint returns NO weighted number on purpose (an unset stage probability is 0 and would drop deals); compute
+ * the estimate yourself and say how many deals had no probability.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const { data: pipelines } = await g8.deals.pipelines();
+const pipeline = pipelines.find((p) => p.is_default) ?? pipelines[0];
+
+const analytics = (await g8.api.deals.getDealAnalytics({ query: { pipeline_id: pipeline.id } })) as {
+  data?: { totals?: { open_count: number; open_value?: number | null; win_rate?: number | null }; currency?: { code?: string | null; is_mixed?: boolean } };
+};
+const totals = analytics.data?.totals;
+console.log(`open: ${totals?.open_count} deals, ${totals?.open_value ?? "n/a"} ${analytics.data?.currency?.code ?? ""}`);
+console.log(`win rate (won / (won + lost)): ${totals?.win_rate != null ? Math.round(totals.win_rate * 100) + "%" : "n/a"}`);
+
+const velocity = await g8.api.deals.getDealStageVelocity({ query: { pipeline_id: pipeline.id, stuck_threshold_days: 14 } });
+for (const s of velocity.data.by_stage ?? []) console.log(s.stage_name, s.avg_days_in_stage, "days avg,", s.still_in_stage_count, "waiting");
+console.log("stuck deals:", velocity.data.stuck_deals.total_count);
+
+// Weighted estimate from open deals x stage probability (0-100).
+const probability = new Map(pipeline.stages.map((s) => [s.id, s.probability ?? 0]));
+const open = await g8.api.deals.listDeals({ query: { pipeline_id: pipeline.id, outcome: "open", limit: 100 } });
+let weighted = 0;
+let noProbability = 0;
+for (const d of open.data) {
+  const p = probability.get(d.stage_id ?? "") ?? 0;
+  if (p === 0) noProbability++;
+  weighted += (d.amount ?? 0) * (p / 100);
+}
+console.log(`weighted estimate: ${Math.round(weighted)} (${noProbability} deals in stages with no probability set)`);

package/blocks/deals/recipes/03-stale-deals-sweep.ts

@@ -0,0 +1,20 @@
+/**
+ * @title Find open deals with no recent activity and flag them
+ * @when A nightly job that surfaces neglected deals. The list is read-only; the flag is one bulk write
+ * (`POST /deals/bulk`, up to 100 deals, tier `write`). PUT semantics apply to `change`: null leaves a field alone,
+ * an EMPTY STRING clears it, so never send "" unless you mean to erase the value.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const cutoff = new Date(Date.now() - 21 * 86_400_000).toISOString();
+const stale = await g8.api.deals.listDeals({ query: { outcome: "open", stale_before: cutoff, limit: 100 } });
+console.log(`${stale.data.length} open deals untouched since ${cutoff.slice(0, 10)}`);
+for (const d of stale.data) console.log(d.id, d.name, d.stage_name, d.owner_name ?? "no owner");
+
+if (stale.data.length > 0 && process.env.FLAG_STALE === "1") {
+  const ids = stale.data.map((d) => d.id).filter((id): id is string => Boolean(id));
+  const result = await g8.api.deals.bulkUpdateDeals({ body: { deal_ids: ids, change: { next_step: "Stale: follow up or close out" } } });
+  console.log(JSON.stringify(result.data)); // read the per-deal result, not just the HTTP status
+}