@graph8/sdk 0.303.0 → 0.357.0

package/blocks/deals/README.md

@@ -0,0 +1,78 @@
+# deals: pipelines and revenue
+
+A kanban of deals by stage with drag and drop, a deal detail with history, a stage editor, and a forecast.
+Install with `npx @graph8/sdk add deals` (depends on `crm`, whose notes, tasks and activity timeline you can
+compose under `DealDetail`'s `children`). Drag and drop needs `npm i @dnd-kit/core`.
+
+## The flow, in order
+
+1. **Pipelines** `GET /deals/pipelines` (`usePipelines`): `[{ id, name, is_default, stages: [{ id, name,
+   position, probability, stage_type, color }] }]`. **Stage ids only ever come from here.** `stage_type` is
+   free text: `"won"` and `"lost"` close a deal, anything else is open.
+2. **Deals** `GET /deals?pipeline_id=&page=&limit=` (`usePipelineDeals`): each deal has `id` (a UUID string),
+   `stage_id`, `amount`, `close_date`, `owner_*`, and `revision`.
+3. **Move** `PATCH /deals/{id}` with `{ stage_id, expected_revision }` (`PipelineBoard`). It is a plain write:
+   no confirm dialog. The board updates optimistically and rolls back if the API refuses.
+4. **Closing**: a move into a won/lost stage needs a close date (past dates are allowed), an amount for
+   won, and an owner. The board prompts for the date and amount first; if the API still answers 422 with
+   `close_date_required_for_won_stage`, `amount_required_for_won_stage` or `owner_required_for_closed_stage`,
+   the board shows what is missing and rolls back.
+5. **Create / edit** (`DealDetail`): `POST /deals` needs `name`, `owner_id` and `contact_ids` (a list, may be
+   empty); `stage_id` defaults to the first stage of the default pipeline. Edits send `expected_revision`;
+   a stale revision is refused, so reload and retry. `DELETE /deals/{id}` is destructive and confirmed.
+6. **Configure** (`StageEditor`): `GET /pipelines/{id}`, `POST .../stages`, `PUT .../stages/{stage_id}`,
+   `PUT .../stages/reorder` (send every stage id in the new order), `DELETE .../stages/{stage_id}` (destructive,
+   confirmed; refused while deals remain in it). These live under the `campaigns:*` scopes.
+7. **Forecast** (`ForecastView`): `GET /deals/analytics`, `GET /deals/stage-velocity`, and open deals for the
+   weighted estimate.
+
+IDs passed between steps: `pipeline.id` (list -> deals filter -> stage editor), `stage.id` (columns -> move,
+create), `deal.id` + `deal.revision` (card -> detail -> update/delete).
+
+## Prerequisites a human must do
+
+- None in the graph8 app for the basic board: a default pipeline exists.
+- Give the key `deals:read` / `deals:write` (and `deals:delete` to delete). StageEditor needs `campaigns:read`,
+  `campaigns:write` and `campaigns:delete`.
+- `npm i @dnd-kit/core`.
+
+## Defaults (the agent does not need to ask)
+
+- The board shows the default pipeline. Moves save immediately; no confirm dialog (nobody is contacted).
+- Every card has a "Move to" select, the keyboard and screen-reader path, doing the same PATCH as dragging.
+- Ask the human only who should **own deals created in the UI** (the API requires an owner).
+
+## Gotchas
+
+- The analytics endpoint returns **no weighted pipeline** on purpose. `ForecastView` computes one from open deals
+  and stage probabilities, labels it an estimate and counts deals whose stage has no probability (an unset
+  probability is 0). Set probabilities in `StageEditor`.
+- Mixed currencies: when `currency.is_mixed` is true the analytics withhold sums; the view shows counts only.
+- `GET /deals/pipelines` (stage ids used by deals) and `GET /pipelines` (pipeline management) are different
+  routes returning the same pipeline objects; the board uses the first, the editor the second.
+- `POST /deals/bulk` has PUT semantics: `""` clears a field, `null` leaves it alone (see recipe 03).
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| `deals.listPipelines` | GET /deals/pipelines | read | usePipelines |
+| `deals.listDeals` | GET /deals | read | usePipelineDeals, ForecastView |
+| `deals.updateDeal` | PATCH /deals/{id} | write | PipelineBoard, DealDetail |
+| `deals.getDeal` | GET /deals/{id} | read | DealDetail |
+| `deals.listDealHistory` | GET /deals/{id}/history | read | DealDetail |
+| `deals.createDeal` | POST /deals | write | DealDetail |
+| `deals.deleteDeal` | DELETE /deals/{id} | destructive | DealDetail |
+| `cliPipelines.getPipeline` | GET /pipelines/{id} | read | StageEditor |
+| `cliPipelines.createStage` | POST /pipelines/{id}/stages | write | StageEditor |
+| `cliPipelines.updateStage` | PUT /pipelines/{id}/stages/{stage_id} | write | StageEditor |
+| `cliPipelines.reorderStages` | PUT /pipelines/{id}/stages/reorder | write | StageEditor |
+| `cliPipelines.deleteStage` | DELETE /pipelines/{id}/stages/{stage_id} | destructive | StageEditor |
+| `deals.getDealAnalytics` | GET /deals/analytics | read | ForecastView |
+| `deals.getDealStageVelocity` | GET /deals/stage-velocity | read | ForecastView |
+
+## Recipes (server side)
+
+- `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.

package/blocks/deals/block.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "deals",
+  "title": "Deals & pipelines",
+  "summary": "Revenue pipeline: drag-and-drop kanban, deal detail and history, stage configuration and a forecast with stage velocity.",
+  "features": [
+    "kanban board with drag and drop plus a keyboard Move to control",
+    "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"
+  ],
+  "dependsOn": [
+    "crm"
+  ],
+  "operations": [
+    "create_deal_deals_post",
+    "create_stage_pipelines__pipeline_id__stages_post",
+    "delete_deal_deals__deal_id__delete",
+    "delete_stage_pipelines__pipeline_id__stages__stage_id__delete",
+    "get_deal_analytics_deals_analytics_get",
+    "get_deal_deals__deal_id__get",
+    "get_deal_stage_velocity_deals_stage_velocity_get",
+    "get_pipeline_pipelines__pipeline_id__get",
+    "list_deal_history_deals__deal_id__history_get",
+    "list_deals_deals_get",
+    "list_pipelines_deals_pipelines_get",
+    "reorder_stages_pipelines__pipeline_id__stages_reorder_put",
+    "update_deal_deals__deal_id__patch",
+    "update_stage_pipelines__pipeline_id__stages__stage_id__put"
+  ],
+  "components": [
+    {
+      "name": "PipelineBoard",
+      "file": "components/pipeline-board.tsx",
+      "purpose": "Kanban of deals by stage; drag a card (or use Move to) to change its stage, with a close-date/amount prompt for won and lost.",
+      "operations": [
+        "list_deals_deals_get",
+        "list_pipelines_deals_pipelines_get",
+        "update_deal_deals__deal_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "DealDetail",
+      "file": "components/deal-detail.tsx",
+      "purpose": "Create or edit a deal with stage, amount and close date; contacts, stage history and a confirmed delete.",
+      "operations": [
+        "create_deal_deals_post",
+        "delete_deal_deals__deal_id__delete",
+        "get_deal_deals__deal_id__get",
+        "list_deal_history_deals__deal_id__history_get",
+        "list_pipelines_deals_pipelines_get",
+        "update_deal_deals__deal_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "StageEditor",
+      "file": "components/stage-editor.tsx",
+      "purpose": "Rename, reorder, add and delete stages and set win probability and won/lost type.",
+      "operations": [
+        "create_stage_pipelines__pipeline_id__stages_post",
+        "delete_stage_pipelines__pipeline_id__stages__stage_id__delete",
+        "get_pipeline_pipelines__pipeline_id__get",
+        "reorder_stages_pipelines__pipeline_id__stages_reorder_put",
+        "update_stage_pipelines__pipeline_id__stages__stage_id__put"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "ForecastView",
+      "file": "components/forecast-view.tsx",
+      "purpose": "Pipeline totals, win rate, deals by stage, stage velocity, stuck deals and a labelled weighted-pipeline estimate.",
+      "operations": [
+        "get_deal_analytics_deals_analytics_get",
+        "get_deal_stage_velocity_deals_stage_velocity_get",
+        "list_deals_deals_get",
+        "list_pipelines_deals_pipelines_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "usePipelines",
+      "file": "hooks/use-pipelines.ts",
+      "purpose": "Every pipeline with ordered stages; the only source of stage ids.",
+      "operations": [
+        "list_pipelines_deals_pipelines_get"
+      ]
+    },
+    {
+      "name": "usePipelineDeals",
+      "file": "hooks/use-pipeline-deals.ts",
+      "purpose": "Deals of one pipeline (all pages, capped) with an optimistic stage move that rolls back on refusal.",
+      "operations": [
+        "list_deals_deals_get",
+        "update_deal_deals__deal_id__patch"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/deals-types.ts",
+      "purpose": "Deal, pipeline and stage types, stage kind, money formatting, weighted-pipeline estimate and closed-stage error markers."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/01-create-deal-and-advance.ts",
+      "title": "Create a deal and move it through the pipeline",
+      "when": "Tracking revenue from an agent or webhook; includes closing as won with the required fields."
+    },
+    {
+      "file": "recipes/02-pipeline-report.ts",
+      "title": "Pipeline report with an estimated weighted forecast",
+      "when": "A weekly summary; read-only."
+    },
+    {
+      "file": "recipes/03-stale-deals-sweep.ts",
+      "title": "Find open deals with no recent activity and flag them",
+      "when": "A nightly job; list is read-only, the flag is one bulk write."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "pipeline-exists",
+      "description": "At least one pipeline with stages. New orgs have a default pipeline; custom stages are set up with StageEditor.",
+      "where": "api",
+      "verify": "GET /deals/pipelines returns a pipeline with stages and one with is_default true."
+    },
+    {
+      "id": "deals-scopes",
+      "description": "Key scopes deals:read and deals:write for the board, detail and forecast (deals:delete to delete a deal); campaigns:read, campaigns:write and campaigns:delete for StageEditor (pipelines are managed under the campaigns scopes).",
+      "where": "api",
+      "verify": "`g8.api.me.describeCurrentKey()` lists deals:read and deals:write (and campaigns:* if you use StageEditor)."
+    },
+    {
+      "id": "dnd-kit",
+      "description": "The drag-and-drop packages: `npm i @dnd-kit/core`. The Move to select works without dragging.",
+      "where": "app",
+      "verify": "`import \"@dnd-kit/core\"` resolves."
+    }
+  ],
+  "scopes": [
+    "campaigns:delete",
+    "campaigns:read",
+    "campaigns:write",
+    "deals:delete",
+    "deals:read",
+    "deals:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Which pipeline the board shows",
+      "default": "The org's default pipeline (is_default), or the pipelineId prop",
+      "askHuman": false
+    },
+    {
+      "decision": "How a stage move is saved",
+      "default": "Immediately and optimistically; rolled back with the API's message if refused. No confirm dialog: it contacts nobody and is easy to undo",
+      "askHuman": false
+    },
+    {
+      "decision": "What a card shows",
+      "default": "Name, amount, owner, close date and a Move to control",
+      "askHuman": false
+    },
+    {
+      "decision": "Who owns deals created in the UI",
+      "default": "The signed-in user of your app: pass their graph8 user id as ownerId (the API requires an owner)",
+      "askHuman": true
+    },
+    {
+      "decision": "Weighted forecast",
+      "default": "Computed client-side from stage probabilities and labelled an estimate; the API gives no weighted total",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "@dnd-kit/core": "^6.3.1"
+  }
+}

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

@@ -0,0 +1,134 @@
+"use client";
+
+/**
+ * DealDetail: view, edit, create and delete one deal, with its contacts and stage history.
+ *
+ * SDK operations, in order:
+ *   1. GET    /deals/pipelines                 (deals.listPipelines)    read   - the stage picker
+ *   2. GET    /deals/{id}                      (deals.getDeal)          read   - edit mode
+ *   3. GET    /deals/{id}/history              (deals.listDealHistory)  read
+ *   4. POST   /deals                           (deals.createDeal)       write  - create mode (needs owner_id and contact_ids)
+ *      PATCH  /deals/{id} { expected_revision } (deals.updateDeal)      write  - a stale revision is refused (409), reload and retry
+ *   5. DELETE /deals/{id}                      (deals.deleteDeal)       DESTRUCTIVE -> ConfirmSpendDialog first
+ * Compose notes, tasks and the activity timeline from the crm block under `children`.
+ */
+import { useEffect, useState, type ReactNode } from "react";
+import { Button, Input, Label, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { usePipelines } from "../hooks/use-pipelines";
+import { dataOf, formatMoney, type Deal } from "../lib/deals-types";
+
+export interface DealDetailProps {
+  /** Edit this deal; omit to create one. */
+  dealId?: string;
+  /** Create mode: the graph8 user id who owns the new deal (required by the API). */
+  ownerId?: string;
+  /** Create mode: contact ids to link (the API requires the list; it may be empty). */
+  contactIds?: number[];
+  pipelineId?: string;
+  onSaved?: (deal: Deal) => void;
+  onDeleted?: (dealId: string) => void;
+  children?: ReactNode;
+  className?: string;
+}
+
+interface HistoryItem {
+  from_stage_name?: string | null;
+  to_stage_name?: string | null;
+  changed_at?: string | null;
+  created_at?: string | null;
+}
+
+interface Form { name: string; amount: string; closeDate: string; stageId: string; description: string }
+const EMPTY: Form = { name: "", amount: "", closeDate: "", stageId: "", description: "" };
+
+function fromDeal(d: Deal): Form {
+  return { name: d.name ?? "", amount: d.amount != null ? String(d.amount) : "", closeDate: d.close_date?.slice(0, 10) ?? "", stageId: d.stage_id ?? "", description: d.description ?? "" };
+}
+
+export function DealDetail({ dealId, ownerId, contactIds = [], pipelineId, onSaved, onDeleted, children, className }: DealDetailProps) {
+  const { pipelines, defaultPipeline } = usePipelines();
+  const [form, setForm] = useState<Form>(EMPTY);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+  // Retry-safe create: once POST /deals succeeded, further saves edit that deal instead of creating another.
+  const [createdId, setCreatedId] = useState<string | null>(null);
+  const [createdRevision, setCreatedRevision] = useState<number | null>(null);
+  const effectiveId = dealId ?? createdId ?? undefined;
+  const deal = useG8Query(async (signal) => dataOf<Deal>(await g8Get(`/deals/${encodeURIComponent(dealId as string)}`, undefined, { signal })), [dealId], { enabled: Boolean(dealId) });
+  const history = useG8Query(async (signal) => dataOf<{ items?: HistoryItem[] }>(await g8Get(`/deals/${encodeURIComponent(dealId as string)}/history`, { limit: 20 }, { signal })).items ?? [], [dealId], { enabled: Boolean(dealId) });
+  useEffect(() => { if (deal.data) setForm(fromDeal(deal.data)); }, [deal.data]);
+  // A different deal (or create mode again) must not show the previous one's fields.
+  useEffect(() => { setForm(EMPTY); setCreatedId(null); setCreatedRevision(null); setConfirmDelete(false); }, [dealId]);
+
+  const pipeline = pipelines.find((p) => p.id === (deal.data?.pipeline_id ?? pipelineId)) ?? defaultPipeline;
+  const set = <K extends keyof Form>(k: K, v: Form[K]) => setForm((f) => ({ ...f, [k]: v }));
+
+  const save = useG8Mutation(async () => {
+    const body = {
+      name: form.name.trim(),
+      amount: form.amount === "" ? null : Number(form.amount),
+      close_date: form.closeDate || null, // date-only: YYYY-MM-DD, never toISOString()
+      description: form.description || null,
+      stage_id: form.stageId || undefined,
+    };
+    const env = effectiveId
+      ? await g8Patch(`/deals/${encodeURIComponent(effectiveId)}`, { ...body, expected_revision: (dealId ? deal.data?.revision : createdRevision) ?? undefined })
+      : await g8Post("/deals", { ...body, owner_id: ownerId, contact_ids: contactIds, pipeline_id: pipeline?.id, amount: body.amount ?? undefined, close_date: body.close_date ?? undefined });
+    return dataOf<Deal>(env);
+  }, { onSuccess: (saved) => { if (!dealId && saved.id) { setCreatedId(saved.id); setCreatedRevision(saved.revision ?? null); } if (dealId) { void deal.refetch(); void history.refetch(); } onSaved?.(saved); } });
+  const remove = useG8Mutation(async () => { await g8Delete(`/deals/${encodeURIComponent(dealId as string)}`); }, { onSuccess: () => { setConfirmDelete(false); onDeleted?.(dealId as string); }, onError: () => setConfirmDelete(false) });
+
+  if (deal.error) return <ApiError error={deal.error} title="Could not load the deal" onRetry={() => void deal.refetch()} />;
+  if (dealId && deal.loading && !deal.data) return <Skeleton className="h-56 w-full" aria-label="Loading deal" />;
+  const d = deal.data;
+  const canCreate = Boolean(ownerId);
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`}>
+      <form className="space-y-3" onSubmit={(e) => { e.preventDefault(); if (form.name.trim() && (dealId || canCreate)) void save.mutate(undefined); }}>
+        <div className="grid gap-3 sm:grid-cols-2">
+          <div className="space-y-1"><Label htmlFor="deal-name">Name</Label><Input id="deal-name" value={form.name} onChange={(e) => set("name", e.target.value)} /></div>
+          <div className="space-y-1"><Label htmlFor="deal-amount">Amount{d?.currency ? ` (${d.currency})` : ""}</Label><Input id="deal-amount" type="number" min={0} value={form.amount} onChange={(e) => set("amount", e.target.value)} /></div>
+          <div className="space-y-1"><Label htmlFor="deal-close">Close date</Label><Input id="deal-close" type="date" value={form.closeDate} onChange={(e) => set("closeDate", e.target.value)} /></div>
+          <div className="space-y-1">
+            <Label htmlFor="deal-stage">Stage</Label>
+            <select id="deal-stage" className="h-9 w-full rounded-md border bg-background px-2 text-sm" value={form.stageId} onChange={(e) => set("stageId", e.target.value)}>
+              <option value="">{dealId ? "Keep current stage" : "First stage"}</option>
+              {(pipeline?.stages ?? []).map((s) => <option key={s.id} value={s.id}>{s.name}</option>)}
+            </select>
+          </div>
+        </div>
+        <div className="space-y-1"><Label htmlFor="deal-desc">Description</Label><Textarea id="deal-desc" rows={3} value={form.description} onChange={(e) => set("description", e.target.value)} /></div>
+        {!dealId && !canCreate ? <p className="text-sm text-muted-foreground">Pass ownerId (a graph8 user id) to create deals: the API requires an owner.</p> : null}
+        {save.error ? <ApiError error={save.error} title="Could not save the deal" /> : null}
+        {remove.error ? <ApiError error={remove.error} title="Could not delete the deal" /> : null}
+        <div className="flex justify-between">
+          {dealId ? <Button type="button" variant="ghost" onClick={() => setConfirmDelete(true)}>Delete deal</Button> : <span />}
+          <Button type="submit" loading={save.loading} disabled={!form.name.trim() || (!effectiveId && !canCreate)}>{effectiveId ? "Save changes" : "Create deal"}</Button>
+        </div>
+      </form>
+
+      {d ? (
+        <section aria-label="Contacts" className="space-y-1 text-sm">
+          <h3 className="font-semibold">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>
+          {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>)}
+        </section>
+      ) : null}
+      {children}
+      <ConfirmSpendDialog open={confirmDelete} tier="destructive" title={`Delete "${d?.name ?? "this deal"}"?`} description="The deal and its stage history are removed. Linked contacts and companies are kept." confirmLabel="Delete deal" affected={1} confirming={remove.loading} onConfirm={() => void remove.mutate(undefined)} onCancel={() => setConfirmDelete(false)} />
+    </div>
+  );
+}

package/blocks/deals/components/forecast-view.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+/**
+ * ForecastView: pipeline totals, win rate, deals per stage, monthly won/lost trend, stuck deals and an ESTIMATED
+ * weighted forecast.
+ *
+ * SDK operations, in order:
+ *   1. GET /deals/pipelines                          (deals.listPipelines)         read - stage probabilities
+ *   2. GET /deals/analytics?pipeline_id=             (deals.getDealAnalytics)      read - totals, by_stage, trend
+ *   3. GET /deals/stage-velocity?pipeline_id=        (deals.getDealStageVelocity)  read - time in stage, stuck deals
+ *   4. GET /deals?pipeline_id=&outcome=open          (deals.listDeals)             read - to weight open deals
+ * The API deliberately returns NO weighted-pipeline number (a stage's probability defaults to 0, which would drop
+ * deals silently). The weighted figure here is computed from the open deals and each stage's probability and is
+ * labelled an estimate, with a count of deals whose stage has no probability set (see StageEditor).
+ */
+import { useMemo } from "react";
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { usePipelines } from "../hooks/use-pipelines";
+import { dataOf, formatMoney, weightedPipeline, type Deal } from "../lib/deals-types";
+
+export interface ForecastViewProps {
+  pipelineId?: string;
+  /** Days without movement before a deal counts as stuck. */
+  stuckAfterDays?: number;
+  className?: string;
+}
+
+interface Analytics {
+  totals?: { deal_count: number; won_count: number; lost_count: number; open_count: number; won_value?: number | null; open_value?: number | null; win_rate?: number | null; avg_deal_size?: number | null };
+  currency?: { code?: string | null; is_mixed?: boolean };
+  by_stage?: Array<{ stage_id?: string | null; stage_name: string; deal_count: number; value?: number | null; outcome: string }>;
+  trend?: Array<{ period: string; won_count: number; won_value?: number | null; lost_count: number }>;
+  disclosures?: string[];
+}
+interface Velocity {
+  by_stage?: Array<{ stage_id: string; stage_name: string; avg_days_in_stage?: number | null; conversion_rate?: number | null; still_in_stage_count: number }>;
+  stuck_deals?: { total_count: number; threshold_days: number; deals?: Array<{ deal_id?: string; id?: string; name?: string; stage_name?: string; days_in_stage?: number }> };
+}
+
+function Tile({ label, value, hint }: { label: string; value: string; hint?: string }) {
+  return <div className="rounded-lg border p-3"><div className="text-xs uppercase text-muted-foreground">{label}</div><div className="text-lg font-semibold">{value}</div>{hint ? <div className="text-xs text-muted-foreground">{hint}</div> : null}</div>;
+}
+
+const MAX_OPEN_DEALS = 2000;
+
+export function ForecastView({ pipelineId, stuckAfterDays = 14, className }: ForecastViewProps) {
+  const { pipelines, defaultPipeline, loading: loadingPipelines, error: pipelinesError } = usePipelines();
+  const pipeline = pipelines.find((p) => p.id === pipelineId) ?? defaultPipeline;
+  const id = pipeline?.id;
+  const analytics = useG8Query(async (s) => dataOf<Analytics>(await g8Get("/deals/analytics", { pipeline_id: id }, { signal: s })), [id], { enabled: Boolean(id) });
+  const velocity = useG8Query(async (s) => dataOf<Velocity>(await g8Get("/deals/stage-velocity", { pipeline_id: id, stuck_threshold_days: stuckAfterDays }, { signal: s })), [id, stuckAfterDays], { enabled: Boolean(id) });
+  const open = useG8Query(async (s) => {
+    const all: Deal[] = [];
+    // Every page, so the weighted figure is not silently low for pipelines with more than 100 open deals.
+    for (let page = 1; all.length < MAX_OPEN_DEALS; page++) {
+      const env = await g8Get<Deal[]>("/deals", { pipeline_id: id, outcome: "open", page, limit: 100 }, { signal: s });
+      all.push(...(env.data ?? []));
+      if (!env.pagination?.has_next) break;
+    }
+    return all;
+  }, [id], { enabled: Boolean(id) });
+  const weighted = useMemo(() => weightedPipeline(open.data ?? [], pipeline?.stages ?? []), [open.data, pipeline]);
+
+  const error = pipelinesError ?? analytics.error ?? velocity.error ?? open.error;
+  if (error) return <ApiError error={error} title="Could not load the forecast" onRetry={() => { void analytics.refetch(); void velocity.refetch(); void open.refetch(); }} />;
+  if (loadingPipelines || analytics.loading || open.loading) return <Skeleton className="h-64 w-full" aria-label="Loading forecast" />;
+  const t = analytics.data?.totals;
+  if (!pipeline || !t || t.deal_count === 0) return <EmptyState className={className} title="No deals to forecast" description="Create deals in this pipeline and the forecast fills in." />;
+  const code = analytics.data?.currency?.code ?? undefined;
+  const mixed = analytics.data?.currency?.is_mixed;
+  const maxCount = Math.max(1, ...(analytics.data?.by_stage ?? []).map((s) => s.deal_count));
+
+  return (
+    <div className={`space-y-5 ${className ?? ""}`}>
+      <div className="grid grid-cols-2 gap-3 lg:grid-cols-4">
+        <Tile label="Open pipeline" value={mixed ? "Mixed currencies" : formatMoney(t.open_value, code)} hint={`${t.open_count} open deals`} />
+        <Tile label="Weighted (estimate)" value={mixed ? "n/a" : formatMoney(Math.round(weighted.value), code)} hint={weighted.unweighted > 0 ? `${weighted.unweighted} open deals sit in stages with no probability` : "From stage probabilities"} />
+        <Tile label="Won" value={mixed ? `${t.won_count} deals` : formatMoney(t.won_value, code)} hint={`${t.won_count} won, ${t.lost_count} lost`} />
+        <Tile label="Win rate" value={t.win_rate != null ? `${Math.round(t.win_rate * 100)}%` : "n/a"} hint={t.avg_deal_size != null && !mixed ? `Avg deal ${formatMoney(t.avg_deal_size, code)}` : undefined} />
+      </div>
+
+      <section aria-label="Deals by stage" className="space-y-1">
+        <h3 className="text-sm font-semibold">Deals by stage</h3>
+        {(analytics.data?.by_stage ?? []).map((s) => (
+          <div key={`${s.stage_id}-${s.stage_name}`} className="flex items-center gap-2 text-sm">
+            <span className="w-40 truncate">{s.stage_name}</span>
+            <div className="h-3 flex-1 rounded bg-muted"><div className="h-3 rounded bg-primary" style={{ width: `${(s.deal_count / maxCount) * 100}%` }} /></div>
+            <span className="w-24 text-right">{s.deal_count} · {mixed ? "" : formatMoney(s.value, code)}</span>
+          </div>
+        ))}
+      </section>
+
+      <section aria-label="Stage velocity" className="space-y-1 text-sm">
+        <h3 className="font-semibold">Where deals stall</h3>
+        {(velocity.data?.by_stage ?? []).map((s) => <p key={s.stage_id}>{s.stage_name}: {s.avg_days_in_stage != null ? `${s.avg_days_in_stage.toFixed(1)} days average` : "no data"}{s.conversion_rate != null ? `, ${Math.round(s.conversion_rate * 100)}% advance` : ""}, {s.still_in_stage_count} waiting</p>)}
+        <p className="text-muted-foreground">{velocity.data?.stuck_deals?.total_count ?? 0} deals have not moved in {velocity.data?.stuck_deals?.threshold_days ?? stuckAfterDays}+ days.</p>
+      </section>
+
+      {(analytics.data?.trend ?? []).length > 0 ? (
+        <section aria-label="Won and lost by month" className="space-y-1 text-sm">
+          <h3 className="font-semibold">Won and lost by month</h3>
+          {(analytics.data?.trend ?? []).slice(-6).map((p) => <p key={p.period}>{p.period}: {p.won_count} won{p.won_value != null && !mixed ? ` (${formatMoney(p.won_value, code)})` : ""}, {p.lost_count} lost</p>)}
+        </section>
+      ) : null}
+      {(analytics.data?.disclosures ?? []).map((d) => <p key={d} className="text-xs text-muted-foreground">{d}</p>)}
+    </div>
+  );
+}