@graph8/sdk 0.308.1 → 0.357.0

package/blocks/analytics/block.json

@@ -0,0 +1,178 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "analytics",
+  "title": "Analytics & reports",
+  "summary": "Outbound KPI tiles, rep leaderboard, funnel charts and a builder for saved custom-object reports.",
+  "features": [
+    "top-line outbound KPIs with a time range",
+    "rep leaderboard ranked by reply rate",
+    "meeting and revenue funnels without a chart library",
+    "build, preview, save, run and delete custom-object reports",
+    "stale-cache notices instead of silent old numbers"
+  ],
+  "dependsOn": [
+    "foundation"
+  ],
+  "operations": [
+    "archive_object_report_api_reports__report_id__delete",
+    "create_object_report_api_reports_post",
+    "execute_object_report_api_reports__report_id__execute_post",
+    "get_meeting_funnel_analytics_outbound_meeting_funnel_get",
+    "get_outbound_summary_analytics_outbound_summary_get",
+    "get_sdr_leaderboard_analytics_outbound_sdr_activity_leaderboard_get",
+    "get_team_conversion_funnel_analytics_team_conversion_funnel_get",
+    "list_object_reports_api_reports_get",
+    "preview_object_report_api_reports_preview_post",
+    "update_object_report_api_reports__report_id__patch"
+  ],
+  "components": [
+    {
+      "name": "KpiTiles",
+      "file": "components/kpi-tiles.tsx",
+      "purpose": "Emails, reply rate, calls and meetings for a 7, 30 or 90 day window.",
+      "operations": [
+        "get_outbound_summary_analytics_outbound_summary_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "Leaderboard",
+      "file": "components/leaderboard.tsx",
+      "purpose": "Reps ranked by reply rate with emails, replies and meetings, sortable.",
+      "operations": [
+        "get_sdr_leaderboard_analytics_outbound_sdr_activity_leaderboard_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "FunnelChart",
+      "file": "components/funnel-chart.tsx",
+      "purpose": "Meeting funnel or revenue conversion funnel as bars with step conversion.",
+      "operations": [
+        "get_meeting_funnel_analytics_outbound_meeting_funnel_get",
+        "get_team_conversion_funnel_analytics_team_conversion_funnel_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ReportBuilder",
+      "file": "components/report-builder.tsx",
+      "purpose": "Define, preview, save, re-run and delete (confirmed) custom-object reports.",
+      "operations": [
+        "archive_object_report_api_reports__report_id__delete",
+        "create_object_report_api_reports_post",
+        "execute_object_report_api_reports__report_id__execute_post",
+        "list_object_reports_api_reports_get",
+        "preview_object_report_api_reports_preview_post",
+        "update_object_report_api_reports__report_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useReport",
+      "file": "hooks/use-report.ts",
+      "purpose": "Load an analytics report and unwrap the app's success/data/meta wrapper, exposing stale.",
+      "operations": [
+        "get_meeting_funnel_analytics_outbound_meeting_funnel_get",
+        "get_outbound_summary_analytics_outbound_summary_get",
+        "get_sdr_leaderboard_analytics_outbound_sdr_activity_leaderboard_get",
+        "get_team_conversion_funnel_analytics_team_conversion_funnel_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/analytics-types.ts",
+      "purpose": "Report shapes, reportBody/reportMeta unwrapping and number/percent formatting."
+    },
+    {
+      "file": "lib/use-debounced.ts",
+      "purpose": "useDebounced: a value that settles after the user stops typing, so inputs do not fire a request per keystroke."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/01-weekly-outbound-report.ts",
+      "title": "Weekly outbound report",
+      "when": "A Monday summary: KPIs, rep leaderboard, meeting funnel; read-only."
+    },
+    {
+      "file": "recipes/02-revenue-snapshot.ts",
+      "title": "Revenue snapshot",
+      "when": "Team dashboard, conversion funnel and forecast for a board-pack summary."
+    },
+    {
+      "file": "recipes/03-saved-report.ts",
+      "title": "Define, preview, save and run a custom-object report",
+      "when": "Reporting on a custom object; the feature is per-org."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "analytics-scope",
+      "description": "Key scope analytics:read for the KPI tiles, leaderboard and funnels; objects:read, objects:write and objects:delete for ReportBuilder.",
+      "where": "api",
+      "verify": "`g8.api.me.describeCurrentKey()` lists analytics:read (and objects:* if you use ReportBuilder)."
+    },
+    {
+      "id": "reports-switch",
+      "description": "Custom-object reports are switched on per organisation in graph8; while off every /reports call is a 404 and ReportBuilder says so. Ask graph8 support or enable it in the app.",
+      "where": "app",
+      "verify": "GET /reports returns 200 (not 404)."
+    },
+    {
+      "id": "data-flowing",
+      "description": "Charts are empty until the org has sent email, placed calls or booked meetings. There is nothing to configure; do not fake data.",
+      "where": "api",
+      "verify": "GET /analytics/outbound/summary shows non-zero emails_sent for the window."
+    }
+  ],
+  "scopes": [
+    "analytics:read",
+    "objects:delete",
+    "objects:read",
+    "objects:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Default time window",
+      "default": "30 days with 7 and 90 as the alternatives",
+      "askHuman": false
+    },
+    {
+      "decision": "Which leaderboard",
+      "default": "Outbound reply-rate ranking (reps with at least 10 emails); the dialer's call leaderboard is a separate report",
+      "askHuman": false
+    },
+    {
+      "decision": "Which funnel",
+      "default": "Meetings (booked, still on calendar, attended); pass source revenue for account-to-deal conversion",
+      "askHuman": false
+    },
+    {
+      "decision": "Chart library",
+      "default": "None: bars are plain divs; use @graph8/sdk/ui's chart primitives if you want line charts",
+      "askHuman": false
+    },
+    {
+      "decision": "Who may see saved reports",
+      "default": "Private (visibility private); sharing with the org needs an admin key",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/analytics/components/funnel-chart.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+/**
+ * FunnelChart: horizontal funnel bars with the count and the step-to-step conversion.
+ *
+ * SDK operations (pick the source):
+ *   source "meetings": GET /analytics/outbound/meeting-funnel?days=   (analytics.getMeetingFunnel)        read
+ *        booked -> still on the calendar -> attended (from the bookings table)
+ *   source "revenue":  GET /analytics/team/conversion-funnel?period_days=  (revenueAnalytics.getTeamConversionFunnel)   read
+ *        accounts -> contacted -> ... -> won, with the overall conversion rate
+ * Or pass your own `steps` and no request is made. Drawn with plain divs: no chart library is needed.
+ */
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useReport } from "../hooks/use-report";
+import { formatNumber, formatPercent, type FunnelStep } from "../lib/analytics-types";
+
+export interface FunnelChartProps {
+  source?: "meetings" | "revenue";
+  /** Window in days. */
+  days?: number;
+  /** Bring your own steps instead of fetching. */
+  steps?: FunnelStep[];
+  className?: string;
+}
+
+interface MeetingFunnel {
+  summary?: { meetings_booked?: number; meetings_active?: number; meetings_attended?: number };
+}
+interface RevenueFunnel {
+  funnel_stages?: Array<{ stage_name: string; stage_label: string; count: number; conversion_rate?: number | null }>;
+  overall_conversion_rate?: number;
+}
+
+function stepsFrom(source: "meetings" | "revenue", data: unknown): FunnelStep[] {
+  if (source === "revenue") {
+    return ((data as RevenueFunnel)?.funnel_stages ?? []).map((s) => ({ key: s.stage_name, label: s.stage_label, count: s.count, conversion: s.conversion_rate }));
+  }
+  const s = (data as MeetingFunnel)?.summary;
+  if (!s) return [];
+  const booked = s.meetings_booked ?? 0;
+  const pct = (n?: number, of?: number) => (of ? ((n ?? 0) / of) * 100 : null);
+  return [
+    { key: "booked", label: "Booked", count: booked },
+    { key: "active", label: "Still on calendar", count: s.meetings_active ?? 0, conversion: pct(s.meetings_active, booked) },
+    { key: "attended", label: "Attended", count: s.meetings_attended ?? 0, conversion: pct(s.meetings_attended, s.meetings_active) },
+  ];
+}
+
+export function FunnelChart({ source = "meetings", days = 30, steps: given, className }: FunnelChartProps) {
+  const path = source === "revenue" ? "/analytics/team/conversion-funnel" : "/analytics/outbound/meeting-funnel";
+  const { data, loading, error, refetch } = useReport<unknown>(path, source === "revenue" ? { period_days: days } : { days }, { enabled: !given });
+  const steps = given ?? stepsFrom(source, data);
+  const max = Math.max(1, ...steps.map((s) => s.count));
+
+  if (!given && error) return <ApiError error={error} title="Could not load the funnel" onRetry={() => void refetch()} />;
+  if (!given && loading && !data) return <Skeleton className="h-40 w-full" aria-label="Loading funnel" />;
+  if (steps.length === 0 || steps[0].count === 0) return <EmptyState className={className} title="Nothing to chart yet" description="The funnel fills in as activity is recorded in this window." />;
+
+  return (
+    <ol className={`space-y-2 ${className ?? ""}`} aria-label="Funnel">
+      {steps.map((s) => (
+        <li key={s.key} className="space-y-1">
+          <div className="flex justify-between text-sm">
+            <span className="font-medium">{s.label}</span>
+            <span>{formatNumber(s.count)}{s.conversion != null ? <span className="ml-2 text-muted-foreground">{formatPercent(s.conversion)} of previous</span> : null}</span>
+          </div>
+          <div className="h-6 rounded bg-muted" role="img" aria-label={`${s.label}: ${s.count}`}>
+            <div className="h-6 rounded bg-primary" style={{ width: `${Math.max(2, (s.count / max) * 100)}%` }} />
+          </div>
+        </li>
+      ))}
+      {!given && source === "revenue" && (data as RevenueFunnel | undefined)?.overall_conversion_rate != null ? (
+        <li className="text-sm text-muted-foreground">Overall conversion {formatPercent((data as RevenueFunnel).overall_conversion_rate)}</li>
+      ) : null}
+    </ol>
+  );
+}

package/blocks/analytics/components/kpi-tiles.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+/**
+ * KpiTiles: the top-line outbound numbers (emails, replies, calls, meetings) for a chosen window.
+ *
+ * SDK operations: GET /analytics/outbound/summary?days=   (analytics.getOutboundSummary)   read
+ * Rates in the response are percentages. Meetings come from the bookings table (the canonical count), so
+ * `meetings_active` is meetings still on the calendar. If the API answers from a stale cache a notice is shown.
+ * Pass `tiles` to choose different fields from the summary.
+ */
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { useReport } from "../hooks/use-report";
+import { DAY_RANGES, formatNumber, formatPercent, type OutboundSummary } from "../lib/analytics-types";
+
+export interface KpiTile {
+  key: keyof OutboundSummary & string;
+  label: string;
+  kind?: "number" | "percent";
+  hint?: (s: OutboundSummary) => string | undefined;
+}
+
+export const DEFAULT_TILES: KpiTile[] = [
+  { key: "emails_sent", label: "Emails sent", hint: (s) => `${formatPercent(s.delivery_rate as number | undefined)} delivered` },
+  { key: "reply_rate", label: "Reply rate", kind: "percent", hint: (s) => `${formatNumber(s.emails_replied as number | undefined)} replies` },
+  { key: "calls_dispatched", label: "Calls placed", hint: (s) => `${formatPercent(s.connect_rate as number | undefined)} connected` },
+  { key: "meetings_booked", label: "Meetings booked", hint: (s) => `${formatNumber(s.meetings_active as number | undefined)} still on the calendar` },
+];
+
+export interface KpiTilesProps {
+  /** Initial window in days. */
+  days?: number;
+  tiles?: KpiTile[];
+  className?: string;
+}
+
+export function KpiTiles({ days: initialDays = 30, tiles = DEFAULT_TILES, className }: KpiTilesProps) {
+  const [days, setDays] = useState(initialDays);
+  const { data, stale, loading, error, refetch } = useReport<OutboundSummary>("/analytics/outbound/summary", { days });
+
+  return (
+    <section className={`space-y-3 ${className ?? ""}`} aria-label="Key metrics">
+      <div role="group" aria-label="Time range" className="flex gap-1">
+        {DAY_RANGES.map((d) => (
+          <Button key={d} size="sm" variant={days === d ? "default" : "outline"} onClick={() => setDays(d)}>
+            Last {d} days
+          </Button>
+        ))}
+      </div>
+      {error ? (
+        <ApiError error={error} title="Could not load metrics" onRetry={() => void refetch()} />
+      ) : loading && !data ? (
+        <div className="grid grid-cols-2 gap-3 lg:grid-cols-4" aria-busy="true" aria-label="Loading metrics">
+          {tiles.map((t) => <Skeleton key={t.key} className="h-24" />)}
+        </div>
+      ) : (
+        <div className="grid grid-cols-2 gap-3 lg:grid-cols-4">
+          {tiles.map((t) => {
+            const raw = data?.[t.key] as number | undefined;
+            return (
+              <div key={t.key} className="rounded-lg border p-4">
+                <div className="text-xs uppercase text-muted-foreground">{t.label}</div>
+                <div className="mt-1 text-2xl font-semibold">{t.kind === "percent" ? formatPercent(raw) : formatNumber(raw)}</div>
+                {data && t.hint ? <div className="mt-1 text-xs text-muted-foreground">{t.hint(data)}</div> : null}
+              </div>
+            );
+          })}
+        </div>
+      )}
+      {stale ? <p role="status" className="text-xs text-muted-foreground">These numbers are from a recent cache because a refresh failed.</p> : null}
+    </section>
+  );
+}

package/blocks/analytics/components/leaderboard.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+/**
+ * Leaderboard: reps ranked by reply rate, with emails, replies and meetings booked.
+ *
+ * SDK operations: GET /analytics/outbound/sdr-activity/leaderboard?days=&limit=   (analytics.getSdrLeaderboard)   read
+ * A rep only appears after sending at least 10 emails (the app's floor), so a rep with three sends and one reply is
+ * not ranked at 33%. Warming mailboxes are collapsed to the person who owns them. This is the OUTBOUND ranking; the
+ * dialer's call leaderboard is a different report (`GET /analytics/dialer/leaderboard`).
+ * Rows are sorted client-side by the column you click; `rep` shows the email unless you pass `nameFor`.
+ */
+import { useMemo, useState } from "react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useReport } from "../hooks/use-report";
+import { DAY_RANGES, formatNumber, formatPercent, type LeaderRow } from "../lib/analytics-types";
+
+type SortKey = "reply_rate" | "emails_sent" | "replies" | "meetings_booked";
+
+export interface LeaderboardProps {
+  days?: number;
+  limit?: number;
+  /** Map an email to a display name. */
+  nameFor?: (email: string) => string;
+  onSelectRep?: (email: string) => void;
+  className?: string;
+}
+
+const COLUMNS: ReadonlyArray<{ key: SortKey; label: string; percent?: boolean }> = [
+  { key: "reply_rate", label: "Reply rate", percent: true },
+  { key: "emails_sent", label: "Emails sent" },
+  { key: "replies", label: "Replies" },
+  { key: "meetings_booked", label: "Meetings" },
+];
+
+export function Leaderboard({ days: initialDays = 30, limit = 20, nameFor, onSelectRep, className }: LeaderboardProps) {
+  const [days, setDays] = useState(initialDays);
+  const [sortKey, setSortKey] = useState<SortKey>("reply_rate");
+  const { data, stale, loading, error, refetch } = useReport<LeaderRow[]>("/analytics/outbound/sdr-activity/leaderboard", { days, limit });
+  const rows = useMemo(() => [...(Array.isArray(data) ? data : [])].sort((a, b) => Number(b[sortKey] ?? 0) - Number(a[sortKey] ?? 0)), [data, sortKey]);
+
+  return (
+    <section className={`space-y-3 ${className ?? ""}`} aria-label="Rep leaderboard">
+      <div role="group" aria-label="Time range" className="flex gap-1">
+        {DAY_RANGES.map((d) => <Button key={d} size="sm" variant={days === d ? "default" : "outline"} onClick={() => setDays(d)}>Last {d} days</Button>)}
+      </div>
+      {error ? (
+        <ApiError error={error} title="Could not load the leaderboard" onRetry={() => void refetch()} />
+      ) : loading && !data ? (
+        <Skeleton className="h-40 w-full" aria-label="Loading leaderboard" />
+      ) : rows.length === 0 ? (
+        <EmptyState title="No ranked reps yet" description="A rep appears here after sending at least 10 emails in the window." />
+      ) : (
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead className="w-10">#</TableHead>
+              <TableHead>Rep</TableHead>
+              {COLUMNS.map((c) => (
+                <TableHead key={c.key} className="text-right" aria-sort={sortKey === c.key ? "descending" : "none"}>
+                  <button type="button" className="font-medium hover:underline" onClick={() => setSortKey(c.key)}>{c.label}</button>
+                </TableHead>
+              ))}
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {rows.map((r, i) => {
+              const email = r.sdr_email ?? "unknown";
+              return (
+                <TableRow key={email} className={onSelectRep ? "cursor-pointer" : undefined} onClick={() => onSelectRep?.(email)}>
+                  <TableCell>{i + 1}</TableCell>
+                  <TableCell className="font-medium">{nameFor ? nameFor(email) : email}</TableCell>
+                  {COLUMNS.map((c) => (
+                    <TableCell key={c.key} className="text-right">{c.percent ? formatPercent(r[c.key] as number | undefined) : formatNumber(r[c.key] as number | undefined)}</TableCell>
+                  ))}
+                </TableRow>
+              );
+            })}
+          </TableBody>
+        </Table>
+      )}
+      {stale ? <p role="status" className="text-xs text-muted-foreground">Showing cached numbers because a refresh failed.</p> : null}
+    </section>
+  );
+}

package/blocks/analytics/components/report-builder.tsx

@@ -0,0 +1,200 @@
+"use client";
+
+/**
+ * ReportBuilder: build a custom-object report (count, sum, average by a field or by time), preview it, save it,
+ * and open, re-run or delete saved reports.
+ *
+ * SDK operations, in order:
+ *   1. GET    /reports?object_slug=            (reports.listObjectReportsApi)     read   - saved reports
+ *   2. POST   /reports/preview                 (reports.previewObjectReportApi)   write  - runs an UNSAVED definition
+ *   3. POST   /reports                         (reports.createObjectReportApi)    write  - save
+ *      PATCH  /reports/{id} { expected_revision } (reports.updateObjectReportApi) write  - used when re-saving a loaded report
+ *   4. POST   /reports/{id}/execute            (reports.executeObjectReportApi)   write  - run a saved report
+ *   5. DELETE /reports/{id}                    (reports.archiveObjectReportApi)   DESTRUCTIVE -> ConfirmSpendDialog first
+ * These reports run over CUSTOM OBJECTS and process lists (the `objects` block): `object_slug` is the object's slug.
+ * The feature is switched on per organisation; while it is off every call is a 404 and the component says so.
+ * Preview and run share the org's report-run slots (429 `too_many_report_runs` when all are busy: retry shortly).
+ * "write" tier on preview/execute is the contract's classification (they create run records); nothing is sent.
+ */
+import { useState } from "react";
+import { Button, Input, Label, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useDebounced } from "../lib/use-debounced";
+import { reportBody, type ReportResultData, type ResultRow, type SavedReport } from "../lib/analytics-types";
+
+export interface ReportBuilderProps {
+  /** Pre-select the object (its slug), for example from the objects block. */
+  objectSlug?: string;
+  onSaved?: (report: SavedReport) => void;
+  className?: string;
+}
+
+const MEASURES = ["count", "sum", "avg", "min", "max"] as const;
+const GRAINS = ["day", "week", "month", "quarter"] as const;
+const CHARTS = ["table", "bar", "line"] as const;
+
+interface Draft {
+  title: string;
+  chart: (typeof CHARTS)[number];
+  measure: (typeof MEASURES)[number];
+  measureField: string;
+  groupBy: string;
+  grain: (typeof GRAINS)[number];
+}
+
+type Cfg = { measures?: Array<Record<string, unknown>>; group_by?: Array<Record<string, unknown>>; [k: string]: unknown };
+
+/** The config to send. A loaded report keeps everything the form cannot edit (filters, extra measures and groups). */
+function configOf(d: Draft, base: Cfg = {}): Record<string, unknown> {
+  const measure = { kind: d.measure, ...(d.measure === "count" ? {} : { attribute_slug: d.measureField }) };
+  const g = d.groupBy.trim();
+  const group = g === "created_at" ? { kind: "created_at", grain: d.grain } : g ? { kind: "attribute", attribute_slug: g } : null;
+  return { filters: [], ...base, measures: [measure, ...(base.measures ?? []).slice(1)], group_by: [...(group ? [group] : []), ...(base.group_by ?? []).slice(1)] };
+}
+
+/** Fill the form from a saved report so Preview and Save changes act on ITS definition, not on form defaults. */
+function draftFromReport(r: SavedReport, current: Draft): Draft {
+  const cfg = r.config as Cfg;
+  const m = cfg.measures?.[0];
+  const g = cfg.group_by?.[0];
+  const measureKinds = MEASURES as readonly string[];
+  return {
+    ...current,
+    title: r.title,
+    chart: (r.chart_type as Draft["chart"]) ?? "table",
+    measure: m && measureKinds.includes(String(m.kind)) ? (m.kind as Draft["measure"]) : "count",
+    measureField: String(m?.attribute_slug ?? ""),
+    groupBy: g ? (g.kind === "created_at" ? "created_at" : String(g.attribute_slug ?? "")) : "",
+    grain: g && GRAINS.includes(g.grain as Draft["grain"]) ? (g.grain as Draft["grain"]) : "month",
+  };
+}
+
+function groupLabel(g: ResultRow["group"][number]): string {
+  if (g == null) return "(none)";
+  if (typeof g === "object") return String(g.label ?? g.value ?? "(none)");
+  return String(g);
+}
+
+function ResultTable({ result }: { result: ReportResultData }) {
+  const rows = result.rows ?? [];
+  if (result.status === "restricted") return <p role="alert" className="text-sm">You do not have access to every field in this report.</p>;
+  if (rows.length === 0) return <EmptyState title="No records match" description="Change the object, field or grouping and preview again." />;
+  const measureKeys = Object.keys(rows[0].measures ?? {});
+  return (
+    <div className="space-y-1">
+      <Table aria-label="Report result">
+        <TableHeader>
+          <TableRow><TableHead>Group</TableHead>{measureKeys.map((k) => <TableHead key={k} className="text-right">{k}</TableHead>)}<TableHead className="text-right">Records</TableHead></TableRow>
+        </TableHeader>
+        <TableBody>
+          {rows.map((r) => (
+            <TableRow key={r.key}>
+              <TableCell>{r.group.length ? r.group.map(groupLabel).join(" / ") : "All records"}</TableCell>
+              {measureKeys.map((k) => <TableCell key={k} className="text-right">{String(r.measures[k] ?? "")}</TableCell>)}
+              <TableCell className="text-right">{r.record_count ?? ""}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      {result.truncated ? <p className="text-xs text-muted-foreground">Showing the first rows only; narrow the report to see the rest.</p> : null}
+      {(result.disclosures ?? []).map((d) => <p key={d} className="text-xs text-muted-foreground">{d}</p>)}
+    </div>
+  );
+}
+
+export function ReportBuilder({ objectSlug: initialSlug = "", onSaved, className }: ReportBuilderProps) {
+  const [slug, setSlug] = useState(initialSlug);
+  const [draft, setDraft] = useState<Draft>({ title: "", chart: "table", measure: "count", measureField: "", groupBy: "", grain: "month" });
+  const [loaded, setLoaded] = useState<SavedReport | null>(null);
+  const [result, setResult] = useState<ReportResultData | null>(null);
+  const [deleting, setDeleting] = useState<SavedReport | null>(null);
+  const set = <K extends keyof Draft>(k: K, v: Draft[K]) => setDraft((d) => ({ ...d, [k]: v }));
+
+  const listSlug = useDebounced(slug.trim());
+  const saved = useG8Query(async (signal) => reportBody<{ reports?: SavedReport[] }>(await g8Get("/reports", { object_slug: listSlug || undefined, limit: 50 }, { signal })).reports ?? [], [listSlug]);
+  const body = () => ({ object_slug: slug, chart_type: draft.chart, config: configOf(draft, loaded?.config as Cfg) });
+  const preview = useG8Mutation(async () => { const r = reportBody<ReportResultData>(await g8Post("/reports/preview", body())); setResult(r); return r; });
+  const run = useG8Mutation(async (r: SavedReport) => { const out = reportBody<ReportResultData>(await g8Post(`/reports/${encodeURIComponent(r.id)}/execute`, {})); setResult(out); return out; });
+  const save = useG8Mutation(async () => {
+    const env = loaded
+      ? await g8Patch(`/reports/${encodeURIComponent(loaded.id)}`, { title: draft.title, chart_type: draft.chart, config: configOf(draft, loaded.config as Cfg), expected_revision: loaded.revision })
+      : await g8Post("/reports", { ...body(), title: draft.title, visibility: "private" });
+    return reportBody<SavedReport>(env);
+  }, { onSuccess: (r) => { setLoaded(r); void saved.refetch(); onSaved?.(r); } });
+  const remove = useG8Mutation(async (r: SavedReport) => { await g8Delete(`/reports/${encodeURIComponent(r.id)}`); }, {
+    onSuccess: () => { if (deleting?.id === loaded?.id) startOver(); setDeleting(null); void saved.refetch(); },
+    onError: () => setDeleting(null),
+  });
+
+  // Start over: clears the loaded report, the definition, the preview and any errors.
+  const startOver = () => {
+    setLoaded(null);
+    setResult(null);
+    setSlug(initialSlug);
+    setDraft({ title: "", chart: "table", measure: "count", measureField: "", groupBy: "", grain: "month" });
+    preview.reset();
+    run.reset();
+    save.reset();
+    remove.reset();
+  };
+
+  const open = (r: SavedReport) => {
+    setLoaded(r);
+    setSlug(r.source.slug);
+    setDraft((d) => draftFromReport(r, d));
+    void run.mutate(r);
+  };
+  const failure = preview.error ?? run.error ?? save.error ?? remove.error;
+  const switchedOff = (saved.error as { status?: number } | undefined)?.status === 404;
+
+  return (
+    <div className={`grid gap-4 lg:grid-cols-[minmax(0,2fr)_minmax(0,3fr)] ${className ?? ""}`}>
+      <section aria-label="Saved reports" className="space-y-2">
+        <h3 className="text-sm font-semibold">Saved reports</h3>
+        {switchedOff ? <EmptyState title="Reports are not enabled" description="Custom-object reports are switched on per organisation in graph8." /> : saved.error ? <ApiError error={saved.error} title="Could not load saved reports" onRetry={() => void saved.refetch()} /> : null}
+        {(saved.data ?? []).map((r) => (
+          <div key={r.id} className="flex items-center justify-between rounded border p-2 text-sm">
+            <button type="button" className="text-left hover:underline" onClick={() => open(r)}>{r.title} <span className="text-muted-foreground">({r.source.plural_noun})</span></button>
+            {r.can_delete ? <Button size="sm" variant="ghost" aria-label={`Delete ${r.title}`} onClick={() => setDeleting(r)}>Delete</Button> : null}
+          </div>
+        ))}
+        {!saved.loading && !saved.error && (saved.data ?? []).length === 0 ? <p className="text-sm text-muted-foreground">Nothing saved yet.</p> : null}
+      </section>
+
+      <section aria-label="Report definition" className="space-y-3">
+        <div className="grid gap-3 sm:grid-cols-2">
+          <div className="space-y-1"><Label htmlFor="rb-slug">Object slug</Label><Input id="rb-slug" value={slug} onChange={(e) => setSlug(e.target.value)} placeholder="for example projects" /></div>
+          <div className="space-y-1"><Label htmlFor="rb-title">Title</Label><Input id="rb-title" value={draft.title} onChange={(e) => set("title", e.target.value)} /></div>
+          <div className="space-y-1">
+            <Label htmlFor="rb-measure">Measure</Label>
+            <div className="flex gap-2">
+              <select id="rb-measure" className="h-9 rounded-md border bg-background px-2 text-sm" value={draft.measure} onChange={(e) => set("measure", e.target.value as Draft["measure"])}>{MEASURES.map((m) => <option key={m}>{m}</option>)}</select>
+              {draft.measure !== "count" ? <Input aria-label="Measure field" placeholder="numeric field slug" value={draft.measureField} onChange={(e) => set("measureField", e.target.value)} /> : null}
+            </div>
+          </div>
+          <div className="space-y-1">
+            <Label htmlFor="rb-group">Group by</Label>
+            <div className="flex gap-2">
+              <Input id="rb-group" value={draft.groupBy} onChange={(e) => set("groupBy", e.target.value)} placeholder="field slug, or created_at" />
+              {draft.groupBy.trim() === "created_at" ? <select aria-label="Grain" className="h-9 rounded-md border bg-background px-2 text-sm" value={draft.grain} onChange={(e) => set("grain", e.target.value as Draft["grain"])}>{GRAINS.map((g) => <option key={g}>{g}</option>)}</select> : null}
+            </div>
+          </div>
+          <div className="space-y-1"><Label htmlFor="rb-chart">Chart</Label><select id="rb-chart" className="h-9 w-full rounded-md border bg-background px-2 text-sm" value={draft.chart} onChange={(e) => set("chart", e.target.value as Draft["chart"])}>{CHARTS.map((c) => <option key={c}>{c}</option>)}</select></div>
+        </div>
+        {failure ? <ApiError error={failure} title="That report action failed" /> : null}
+        <div className="flex gap-2">
+          <Button variant="ghost" onClick={startOver}>New report</Button>
+          <Button variant="outline" disabled={!slug || preview.loading} loading={preview.loading} onClick={() => void preview.mutate(undefined)}>Preview</Button>
+          <Button disabled={!slug || !draft.title.trim() || save.loading} loading={save.loading} onClick={() => void save.mutate(undefined)}>{loaded ? "Save changes" : "Save report"}</Button>
+        </div>
+        {result ? <ResultTable result={result} /> : null}
+      </section>
+      <ConfirmSpendDialog open={deleting != null} tier="destructive" title={`Delete "${deleting?.title}"?`} description="The saved report is removed for everyone who can see it. The underlying records are not touched." confirmLabel="Delete report" affected={1} confirming={remove.loading} onConfirm={() => deleting && void remove.mutate(deleting)} onCancel={() => setDeleting(null)} />
+    </div>
+  );
+}

package/blocks/analytics/hooks/use-report.ts

@@ -0,0 +1,26 @@
+"use client";
+
+/**
+ * useReport: load one analytics report and unwrap the app's `{ success, data, meta }` wrapper.
+ *
+ * Pass the path relative to /api/v1 and its query. Re-fetches when the path or query change. `stale` is true when
+ * the numbers came from a cache after a failed refresh.
+ *
+ * SDK operations: any GET report under /analytics (read tier). Components pass the exact path they use.
+ */
+import { g8Get, type G8QueryValue } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { reportBody, reportMeta, type ReportMeta } from "../lib/analytics-types";
+
+export function useReport<T>(path: string, query: Record<string, G8QueryValue>, options: { enabled?: boolean } = {}) {
+  const key = JSON.stringify(query);
+  const q = useG8Query(
+    async (signal) => {
+      const env = await g8Get(path, query, { signal });
+      return { body: reportBody<T>(env), meta: reportMeta(env) as ReportMeta };
+    },
+    [path, key],
+    options,
+  );
+  return { data: q.data?.body, stale: Boolean(q.data?.meta.stale), loading: q.loading, error: q.error, refetch: q.refetch };
+}