@graph8/sdk 0.303.0 → 0.357.0

package/blocks/radar/components/competitor-tracker.tsx

@@ -0,0 +1,158 @@
+"use client";
+
+/**
+ * CompetitorTracker: the roster of competitors graph8 watches. Add one (or several detected ones), scan, pause,
+ * resume or remove. Shows threat score, traffic, posting and ads at a glance and follows a scan until it finishes.
+ *
+ * SDK operations, in order:
+ *   1. listCompetitors        GET    /radar/competitors                    (read)   { competitors, capacity }; polled while a scan runs
+ *   2. competitorSuggestions  GET    /radar/competitors/suggestions        (read)   detected, untracked competitors { suggestions }
+ *   3. createCompetitor       POST   /radar/competitors { domain, name, tier, scan_on_add }   (billable tier)
+ *   4. bulkAddCompetitors     POST   /radar/competitors/bulk { competitors, scan_on_add }     (billable tier)
+ *   5. scanCompetitor         POST   /radar/competitors/{id}/scan           (billable) 1 credit per page up to the budget + 1
+ *   6. scanAllCompetitors     POST   /radar/scan-all                        (billable) every active competitor not already scanning
+ *   7. updateCompetitor       PATCH  /radar/competitors/{id} { is_active }  (billable tier; free unless it triggers a scan) pause or resume
+ *   8. deleteCompetitor       DELETE /radar/competitors/{id}                (destructive) removes its history too
+ * Every one of these goes through ConfirmSpendDialog. Adding or pausing is free when `scan_on_add` is off, and the dialog
+ * then says 0 credits. The API has no quote or balance read: the scan figure is the most one scan can charge.
+ */
+
+import { useRef, useState } from "react";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import type { ConfirmTier } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useCompetitors } from "../hooks/use-competitors";
+import { formatCount, isScanning, normalizeDomain, radarBody, scanCostEstimate } from "../lib/radar-types";
+import type { Competitor, CompetitorList, CompetitorSuggestion } from "../lib/radar-types";
+
+export interface CompetitorTrackerProps {
+  /** Called when a person opens a competitor (for example to show its CompetitorBattleCard). */
+  onSelect?: (competitor: Competitor) => void;
+  className?: string;
+}
+
+type Pending =
+  | { type: "add"; domain: string; name: string; tier: string; scan: boolean }
+  | { type: "bulk"; domains: string[]; scan: boolean }
+  | { type: "scan"; competitor: Competitor }
+  | { type: "scanAll" }
+  | { type: "toggle"; competitor: Competitor }
+  | { type: "delete"; competitor: Competitor };
+
+export function CompetitorTracker({ onSelect, className }: CompetitorTrackerProps) {
+  const { competitors, capacity, scanning, loading, error, refetch } = useCompetitors();
+  const [domain, setDomain] = useState("");
+  const [name, setName] = useState("");
+  const [tier, setTier] = useState("tier2");
+  const [scanOnAdd, setScanOnAdd] = useState(false);
+  const [picked, setPicked] = useState<string[]>([]);
+  const [pending, setPending] = useState<Pending | null>(null);
+  const suggestions = useG8Query(async (signal) => radarBody<{ suggestions: CompetitorSuggestion[] }>(await g8Get("/radar/competitors/suggestions", undefined, { signal })).suggestions ?? [], []);
+  // `refetch` resolves undefined when it failed OR was superseded by another refetch (done() below). That must never read
+  // as "scans finished": fall back to the last known list so polling carries on while a scan is still running.
+  const latest = useRef<CompetitorList>({ competitors, capacity: capacity ?? { limit: 0, used: 0, remaining: 0 } });
+  latest.current = { competitors, capacity: capacity ?? latest.current.capacity };
+  useJobPoll(async () => (await refetch()) ?? latest.current, { enabled: scanning, intervalMs: 5000, maxAttempts: 120, isTerminal: (list) => !list.competitors.some(isScanning) });
+
+  const done = () => { setPending(null); void refetch(); void suggestions.refetch(); };
+  const run = useG8Mutation(async (p: Pending) => {
+    if (p.type === "add") return g8Post("/radar/competitors", { domain: p.domain, name: p.name || undefined, tier: p.tier, scan_on_add: p.scan });
+    if (p.type === "bulk") return g8Post("/radar/competitors/bulk", { competitors: p.domains.map((d) => ({ domain: d })), scan_on_add: p.scan });
+    if (p.type === "scan") return g8Post(`/radar/competitors/${p.competitor.id}/scan`, {});
+    if (p.type === "scanAll") return g8Post("/radar/scan-all", {});
+    if (p.type === "toggle") return g8Patch(`/radar/competitors/${p.competitor.id}`, { is_active: !p.competitor.is_active });
+    return g8Delete(`/radar/competitors/${p.competitor.id}`);
+  }, { onSuccess: (_r, p) => { if (p.type === "add") { setDomain(""); setName(""); } if (p.type === "bulk") setPicked([]); done(); } });
+
+  const active = competitors.filter((c) => c.is_active && !isScanning(c));
+  const detected = (suggestions.data ?? []).filter((s) => s.domain && !s.already_tracked);
+  // Ticked suggestions that are no longer on offer (tracked meanwhile, or the list reloaded) drop out of the selection.
+  const chosen = picked.filter((d) => detected.some((s) => s.domain === d));
+  const plan = describe(pending, active);
+  const normalized = normalizeDomain(domain);
+
+  if (error) return <ApiError error={error} title="Could not load competitors" onRetry={() => void refetch()} />;
+  return (
+    <div className={`flex flex-col gap-5 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <p className="text-sm text-muted-foreground">{capacity ? `${capacity.used} of ${capacity.limit} competitors tracked` : "Competitors"}</p>
+        <Button size="sm" variant="outline" disabled={active.length === 0} onClick={() => setPending({ type: "scanAll" })}>Scan all ({active.length})</Button>
+      </div>
+
+      <form className="flex flex-wrap items-end gap-2" onSubmit={(e) => { e.preventDefault(); if (normalized) setPending({ type: "add", domain: normalized, name: name.trim(), tier, scan: scanOnAdd }); }}>
+        <div className="flex flex-col gap-1"><Label htmlFor="rd-domain">Website</Label><Input id="rd-domain" value={domain} onChange={(e) => setDomain(e.target.value)} placeholder="competitor.com" /></div>
+        <div className="flex flex-col gap-1"><Label htmlFor="rd-name">Name (optional)</Label><Input id="rd-name" value={name} onChange={(e) => setName(e.target.value)} /></div>
+        <select aria-label="Tier" className="h-9 rounded-md border bg-background px-2" value={tier} onChange={(e) => setTier(e.target.value)}>
+          <option value="tier1">Tier 1 (25 pages per scan)</option><option value="tier2">Watchlist (8 pages per scan)</option>
+        </select>
+        <label className="flex items-center gap-1 text-sm"><input type="checkbox" checked={scanOnAdd} onChange={(e) => setScanOnAdd(e.target.checked)} /> Scan now</label>
+        <Button type="submit" disabled={!normalized}>Track</Button>
+      </form>
+      {run.error ? <ApiError error={run.error} title="That did not work" /> : null}
+
+      {detected.length > 0 ? (
+        <section aria-label="Detected competitors" className="rounded-md border p-3">
+          <h3 className="mb-2 text-sm font-medium">Detected from your market research</h3>
+          <ul className="flex flex-col gap-1">
+            {detected.map((s) => (
+              <li key={s.domain!} className="flex items-center gap-2 text-sm">
+                <input type="checkbox" aria-label={`Track ${s.domain}`} checked={picked.includes(s.domain!)} onChange={() => setPicked(picked.includes(s.domain!) ? picked.filter((d) => d !== s.domain) : [...picked, s.domain!])} />
+                <span className="font-medium">{s.name || s.domain}</span><span className="text-muted-foreground">{s.domain}</span>
+              </li>
+            ))}
+          </ul>
+          <div className="mt-2"><Button size="sm" variant="outline" disabled={chosen.length === 0} onClick={() => setPending({ type: "bulk", domains: chosen, scan: false })}>Track {chosen.length} selected</Button></div>
+        </section>
+      ) : null}
+
+      {loading && competitors.length === 0 ? <Skeleton className="h-24 w-full" /> : null}
+      {!loading && competitors.length === 0 ? <EmptyState title="No competitors tracked yet" description="Add a website above, or pick one graph8 detected from your market research." /> : null}
+      <ul className="flex flex-col gap-2">
+        {competitors.map((c) => (
+          <li key={c.id} className="flex flex-wrap items-center justify-between gap-2 rounded-md border p-3" data-testid="competitor">
+            <button type="button" className="flex flex-col text-left" onClick={() => onSelect?.(c)}>
+              <span className="text-sm font-medium">{c.name || c.domain}{!c.is_active ? <span className="ml-2 text-xs text-muted-foreground">paused</span> : null}</span>
+              <span className="text-xs text-muted-foreground">
+                {c.domain} · {c.tier === "tier1" ? "tier 1" : "watchlist"} · threat {c.threat_score ?? "-"} · traffic {formatCount(c.traffic_estimate)} · {formatCount(c.ads_live_count)} ads live · {isScanning(c) ? "scanning..." : c.last_scanned_at ? `scanned ${c.last_scanned_at.slice(0, 10)}` : "not scanned yet"}
+              </span>
+            </button>
+            <div className="flex gap-1">
+              <Button size="sm" variant="outline" disabled={isScanning(c) || !c.is_active} onClick={() => setPending({ type: "scan", competitor: c })}>Scan</Button>
+              <Button size="sm" variant="ghost" onClick={() => setPending({ type: "toggle", competitor: c })}>{c.is_active ? "Pause" : "Resume"}</Button>
+              <Button size="sm" variant="ghost" onClick={() => setPending({ type: "delete", competitor: c })}>Remove</Button>
+            </div>
+          </li>
+        ))}
+      </ul>
+
+      <ConfirmSpendDialog
+        open={pending != null}
+        tier={plan.tier}
+        title={plan.title}
+        description={plan.description}
+        estimatedCredits={plan.credits}
+        affected={plan.affected}
+        confirmLabel={plan.confirm}
+        confirming={run.loading}
+        onConfirm={() => pending && void run.mutate(pending)}
+        onCancel={() => setPending(null)}
+      />
+    </div>
+  );
+}
+
+function describe(p: Pending | null, active: Competitor[]): { tier: ConfirmTier; title: string; description: string; credits?: number; affected?: number; confirm: string } {
+  if (!p) return { tier: "billable", title: "", description: "", confirm: "Confirm" };
+  if (p.type === "add") return { tier: "billable", title: `Track ${p.domain}`, confirm: "Track", credits: p.scan ? scanCostEstimate({ tier: p.tier, page_budget: 0 }) : 0, description: p.scan ? "The first scan starts now: 1 credit per page captured plus 1 for the traffic lookup, at most this many (the maximum, not an average)." : "Adding is free. No scan runs until you start one." };
+  if (p.type === "bulk") return { tier: "billable", title: `Track ${p.domains.length} competitors`, confirm: "Track", credits: p.scan ? p.domains.length * scanCostEstimate({ tier: "tier2", page_budget: 0 }) : 0, description: "Adding is free. No scan runs until you start one." };
+  if (p.type === "scan") return { tier: "billable", title: `Scan ${p.competitor.name || p.competitor.domain}`, confirm: "Scan", credits: scanCostEstimate(p.competitor), description: `1 credit per page captured (up to ${p.competitor.page_budget}) plus 1 for the traffic lookup. This is the most it can charge; your balance is not checked here.` };
+  if (p.type === "scanAll") return { tier: "billable", title: `Scan ${active.length} competitors`, confirm: "Scan all", credits: active.reduce((sum, c) => sum + scanCostEstimate(c), 0), affected: active.length, description: "Every active competitor that is not already scanning. This is the most it can charge." };
+  if (p.type === "toggle") return { tier: "billable", title: `${p.competitor.is_active ? "Pause" : "Resume"} ${p.competitor.name || p.competitor.domain}`, confirm: p.competitor.is_active ? "Pause" : "Resume", credits: 0, description: p.competitor.is_active ? "A paused competitor is no longer scanned. Its history is kept." : "Scans resume on the normal schedule." };
+  return { tier: "destructive", title: `Remove ${p.competitor.name || p.competitor.domain}`, confirm: "Remove", description: "The competitor and its captured pages, ads and history are deleted." };
+}

package/blocks/radar/components/radar-overview.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+/**
+ * RadarOverview: the one-screen state of competitive intelligence: how many rivals are tracked, moves in the last
+ * 7 days, open gaps, the threat board, recent moves and alerts. Read-only.
+ *
+ * SDK operations, in order:
+ *   1. overview   GET /radar/overview   (read)   { summary, threat_board, moves, alerts, ... }
+ * Nothing here spends credits.
+ */
+
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { radarBody } from "../lib/radar-types";
+import type { RadarOverviewBody } from "../lib/radar-types";
+
+export interface RadarOverviewProps {
+  /** Called with a competitor id when a threat-board row is opened. */
+  onSelectCompetitor?: (competitorId: string) => void;
+  className?: string;
+}
+
+export function RadarOverview({ onSelectCompetitor, className }: RadarOverviewProps) {
+  const query = useG8Query(async (signal) => radarBody<RadarOverviewBody>(await g8Get("/radar/overview", undefined, { signal })), []);
+  const o = query.data;
+
+  if (query.error) return <ApiError error={query.error} title="Could not load the overview" onRetry={() => void query.refetch()} />;
+  if (query.loading && !o) return <Skeleton className="h-40 w-full" />;
+  if (!o || o.summary.tracked === 0) return <EmptyState title="Nothing is tracked yet" description="Add a competitor to start seeing moves, gaps and a threat board." />;
+
+  const s = o.summary;
+  const stats: Array<[string, number]> = [["Tracked", s.tracked], ["Tier 1", s.tier1], ["Moves (7 days)", s.moves_7d], ["Open gaps", s.open_gaps], ["Act now", s.act_now]];
+  return (
+    <div className={`flex flex-col gap-5 ${className ?? ""}`}>
+      <dl className="grid grid-cols-2 gap-3 sm:grid-cols-5">
+        {stats.map(([label, value]) => (
+          <div key={label} className="rounded-md border p-3"><dt className="text-xs text-muted-foreground">{label}</dt><dd className="text-xl font-semibold">{value}</dd></div>
+        ))}
+      </dl>
+      {s.scan_stale ? <p role="status" className="text-sm text-amber-700">The last scan{s.last_scan_at ? ` (${s.last_scan_at.slice(0, 10)})` : ""} is older than your cadence.</p> : null}
+      {s.credit_cap_reached ? <p role="status" className="text-sm text-amber-700">The monthly radar credit cap is reached: automatic scans are paused.</p> : null}
+
+      <section aria-label="Threat board"><h3 className="mb-2 text-sm font-medium">Threat board</h3>
+        <ul className="flex flex-col gap-1">
+          {o.threat_board.map((r) => (
+            <li key={r.id}><Button variant="ghost" className="w-full justify-between" onClick={() => onSelectCompetitor?.(r.id)}>
+              <span>{r.name || r.domain}</span><span className="text-xs text-muted-foreground">threat {r.threat_score ?? "-"} · {r.moves_7d} moves</span>
+            </Button></li>
+          ))}
+        </ul>
+      </section>
+      <section aria-label="Alerts"><h3 className="mb-2 text-sm font-medium">Alerts</h3>
+        {o.alerts.length === 0 ? <p className="text-sm text-muted-foreground">No alerts.</p> : (
+          <ul className="flex flex-col gap-1">{o.alerts.map((a) => <li key={a.id} className="text-sm"><span className="font-medium">{a.title}</span>{a.detail ? <span className="text-muted-foreground"> {a.detail}</span> : null}</li>)}</ul>
+        )}
+      </section>
+      <section aria-label="Recent moves"><h3 className="mb-2 text-sm font-medium">Recent moves</h3>
+        {o.moves.length === 0 ? <p className="text-sm text-muted-foreground">No moves yet.</p> : (
+          <ul className="flex flex-col gap-1">{o.moves.map((m) => <li key={m.id} className="text-sm">{m.competitor_domain ? <span className="font-medium">{m.competitor_domain}: </span> : null}{m.text || m.title}{m.became_gap ? <span className="ml-1 text-xs text-amber-700">became a gap</span> : null}</li>)}</ul>
+        )}
+      </section>
+    </div>
+  );
+}

package/blocks/radar/components/radar-report.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+/**
+ * RadarReport: deep-dive reports on one capability (a claim from your feature matrix) for an audience. Start one
+ * (runs a model, billable), watch it generate, then open the finished HTML or PDF.
+ *
+ * SDK operations, in order:
+ *   1. featureMatrix       GET  /radar/feature-matrix                          (read)   { capabilities: [{ id, name }] }: where capability_id comes from
+ *   2. listRadarReports    GET  /radar/reports                                  (read)   { data: { items } }; polled while any report is generating
+ *   3. createRadarReport   POST /radar/reports { audience, capability_id, edge } (billable) ConfirmSpendDialog first; 202-style { report_id, status: "generating" }
+ *   4. getRadarReportHtml / getRadarReportPdf  GET /radar/reports/{id}/html | /pdf (read) opened as links through your /api/g8 proxy once status is completed
+ * Regenerating the same capability, audience and edge overwrites the earlier report; one already generating answers 409.
+ * The API quotes no price: the dialog says the report uses credits and that your balance is not checked here.
+ */
+
+import { useRef, useState } from "react";
+import { Button, Skeleton } 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 { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { G8_PROXY_BASE, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { isReportFinal, radarBody } from "../lib/radar-types";
+import type { Capability, RadarReportRow } from "../lib/radar-types";
+
+export interface RadarReportProps {
+  /** Preselect a capability (a feature-matrix row id). */
+  capabilityId?: string;
+  className?: string;
+}
+
+export function RadarReport({ capabilityId, className }: RadarReportProps) {
+  const [capability, setCapability] = useState(capabilityId ?? "");
+  const [audience, setAudience] = useState<"executive" | "developer">("executive");
+  const [edge, setEdge] = useState<"us" | "them">("us");
+  const [confirm, setConfirm] = useState(false);
+
+  const matrix = useG8Query(async (signal) => radarBody<{ capabilities: Capability[] }>(await g8Get("/radar/feature-matrix", undefined, { signal })).capabilities ?? [], []);
+  const reports = useG8Query(async (signal) => radarBody<{ items?: RadarReportRow[]; reports?: RadarReportRow[] }>(await g8Get("/radar/reports", undefined, { signal })), []);
+  const rows = reports.data?.items ?? reports.data?.reports ?? [];
+  const generating = rows.some((r) => !isReportFinal(r.status));
+  // A failed or superseded refetch resolves undefined: keep the last known rows so polling continues while a report generates.
+  const latest = useRef(reports.data);
+  latest.current = reports.data ?? latest.current;
+  useJobPoll(async () => (await reports.refetch()) ?? latest.current ?? { items: [] }, { enabled: generating, intervalMs: 4000, maxAttempts: 150, isTerminal: (d) => !(d.items ?? d.reports ?? []).some((r) => !isReportFinal(r.status)) });
+
+  const create = useG8Mutation(() => g8Post("/radar/reports", { audience, capability_id: capability, edge }), { onSuccess: () => { setConfirm(false); void reports.refetch(); } });
+  const name = (matrix.data ?? []).find((c) => c.id === capability)?.name ?? "this capability";
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-end gap-2">
+        <label className="flex flex-col gap-1 text-sm">Capability
+          <select aria-label="Capability" className="h-9 max-w-xs rounded-md border bg-background px-2" value={capability} onChange={(e) => setCapability(e.target.value)}>
+            <option value="">Choose one</option>
+            {(matrix.data ?? []).map((c) => <option key={c.id} value={c.id}>{c.name.length > 80 ? `${c.name.slice(0, 80)}...` : c.name}</option>)}
+          </select>
+        </label>
+        <select aria-label="Audience" className="h-9 rounded-md border bg-background px-2" value={audience} onChange={(e) => setAudience(e.target.value as "executive" | "developer")}><option value="executive">Executive</option><option value="developer">Developer</option></select>
+        <select aria-label="Angle" className="h-9 rounded-md border bg-background px-2" value={edge} onChange={(e) => setEdge(e.target.value as "us" | "them")}><option value="us">Where we win</option><option value="them">Where they win</option></select>
+        <Button disabled={!capability} onClick={() => setConfirm(true)}>Generate report</Button>
+      </div>
+      {matrix.error ? <ApiError error={matrix.error} title="Could not load capabilities" onRetry={() => void matrix.refetch()} /> : null}
+      {create.error ? <ApiError error={create.error} title="Could not start the report" /> : null}
+      {reports.error ? <ApiError error={reports.error} title="Could not load reports" onRetry={() => void reports.refetch()} /> : null}
+      {reports.loading && !reports.data ? <Skeleton className="h-16 w-full" /> : null}
+      {!reports.loading && !reports.error && rows.length === 0 ? <EmptyState title="No reports yet" description="Pick a capability and generate a deep-dive." /> : null}
+      <ul className="flex flex-col gap-2">
+        {rows.map((r) => (
+          <li key={r.id} className="flex items-center justify-between gap-2 rounded-md border p-3" data-testid="report">
+            <div className="flex flex-col"><span className="text-sm font-medium">{r.title || r.capability_name}</span>
+              <span className="text-xs text-muted-foreground">{r.audience} · {r.status}{r.error_message ? ` · ${r.error_message}` : ""}</span></div>
+            {r.status === "completed" ? (
+              <div className="flex gap-2"><a className="text-sm underline" href={`${G8_PROXY_BASE}/radar/reports/${r.id}/html`} target="_blank" rel="noreferrer">Open</a><a className="text-sm underline" href={`${G8_PROXY_BASE}/radar/reports/${r.id}/pdf`} target="_blank" rel="noreferrer">PDF</a></div>
+            ) : null}
+          </li>
+        ))}
+      </ul>
+      <ConfirmSpendDialog open={confirm} tier="billable" title={`Generate a ${audience} report on ${name}`}
+        description="A model writes the report and it uses credits. The API gives no price in advance and your balance is not checked here. Regenerating overwrites the earlier report for this capability and audience."
+        confirmLabel="Generate" confirming={create.loading} onConfirm={() => void create.mutate(undefined)} onCancel={() => setConfirm(false)} />
+    </div>
+  );
+}

package/blocks/radar/hooks/use-competitors.ts

@@ -0,0 +1,23 @@
+"use client";
+
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { radarBody } from "../lib/radar-types";
+import type { CompetitorList } from "../lib/radar-types";
+
+/**
+ * Every tracked competitor (active and paused) with the plan's capacity (`GET /radar/competitors`).
+ * `scanning` is true while any scan is queued or running, which is when a caller should poll.
+ */
+export function useCompetitors() {
+  const query = useG8Query(async (signal) => radarBody<CompetitorList>(await g8Get("/radar/competitors", undefined, { signal })), []);
+  const competitors = query.data?.competitors ?? [];
+  return {
+    competitors,
+    capacity: query.data?.capacity,
+    scanning: competitors.some((c) => c.scan_status === "scanning" || c.scan_status === "queued"),
+    loading: query.loading,
+    error: query.error,
+    refetch: query.refetch,
+  };
+}

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

@@ -0,0 +1,124 @@
+"use client";
+
+/**
+ * Shapes and helpers for the radar components.
+ *
+ * Radar answers with the app's own bodies, UNWRAPPED (`{ competitors, capacity }`, `{ summary, moves, ... }`), while the
+ * report endpoints use the usual `{ data }` envelope. `radarBody` reads either, so a component never cares which.
+ *
+ * Money: a scan bills 1 credit per page captured plus 1 for the traffic lookup, up to the competitor's `page_budget`
+ * (25 pages for tier1, 8 for tier2). The API gives no quote and no balance read, so `scanCostEstimate` is the most
+ * one scan can charge. Adding or editing a competitor is free unless it also starts a scan.
+ */
+
+export type Tier = "tier1" | "tier2" | string;
+
+export interface Competitor {
+  id: string;
+  domain: string;
+  name?: string | null;
+  tier: Tier;
+  is_active: boolean;
+  threat_score?: number | null;
+  traffic_estimate?: number | null;
+  traffic_trend_pct?: number | null;
+  posts_per_week?: number | null;
+  ads_live_count?: number | null;
+  last_scanned_at?: string | null;
+  /** "idle" or "scanning" (queued and running scans), else the last outcome. */
+  scan_status: string;
+  page_budget: number;
+  enrichment_errors?: Record<string, string>;
+}
+
+export interface CompetitorList {
+  competitors: Competitor[];
+  capacity: { limit: number; used: number; remaining: number };
+}
+
+export interface CompetitorSuggestion {
+  /** Null when the detected competitor has no known website: it cannot be tracked until one is typed in. */
+  domain: string | null;
+  name?: string | null;
+  threat_level?: string | null;
+  description?: string | null;
+  already_tracked: boolean;
+  tracking_status?: "active" | "paused" | null;
+}
+
+export interface RadarMove {
+  id: string;
+  kind: string;
+  text?: string | null;
+  title?: string | null;
+  competitor_domain?: string | null;
+  captured_at?: string | null;
+  became_gap?: boolean;
+}
+
+export interface RadarAlert { id: string; kind: string; severity: string; title: string; detail?: string | null; competitor_domain?: string | null }
+
+export interface RadarOverviewBody {
+  summary: {
+    tracked: number; tier1: number; watchlist: number; moves_7d: number; open_gaps: number; act_now: number;
+    last_scan_at?: string | null; scan_stale?: boolean; credit_cap_reached?: boolean;
+  };
+  threat_board: Array<{ id: string; domain: string; name?: string | null; tier: Tier; threat_score?: number | null; moves_7d: number; scan_status: string }>;
+  moves: RadarMove[];
+  alerts: RadarAlert[];
+}
+
+export interface BattleCard {
+  competitor: Competitor;
+  summary: string;
+  our_advantages: Array<{ claim: string; verified: boolean; strength?: string | null; dimension?: string | null }>;
+  watch_outs: Array<{ id: string; title: string; detail?: string | null }>;
+  recent_moves: Array<{ id: string; kind: string; title?: string | null; url?: string | null; captured_at?: string | null }>;
+  talk_track: { lead_with: string[]; be_ready_for: string[] };
+  unverified_advantages_count?: number;
+  unverified_advantages_hidden?: number;
+}
+
+export interface RadarReportRow {
+  id: string;
+  audience: "executive" | "developer" | string;
+  status: "pending" | "generating" | "completed" | "failed" | string;
+  title?: string | null;
+  capability_id?: string | null;
+  capability_name?: string | null;
+  edge?: string | null;
+  created_at?: string | null;
+  completed_at?: string | null;
+  error_message?: string | null;
+}
+
+export interface Capability { id: string; name: string; dimension?: string | null }
+
+/** Read a body that may or may not be wrapped in `{ data }`. */
+export function radarBody<T>(env: unknown): T {
+  const e = env as { data?: unknown } | null;
+  return (e && typeof e === "object" && "data" in e && e.data != null && !Array.isArray(e.data) ? e.data : env) as T;
+}
+
+/** The most one scan of this competitor can charge: a credit per page up to the budget, plus the traffic lookup. */
+export function scanCostEstimate(competitor: Pick<Competitor, "page_budget" | "tier">): number {
+  return (competitor.page_budget || (competitor.tier === "tier1" ? 25 : 8)) + 1;
+}
+
+export function isScanning(c: Pick<Competitor, "scan_status">): boolean {
+  return c.scan_status === "scanning" || c.scan_status === "queued";
+}
+
+/** Reports are final once they stop generating. */
+export function isReportFinal(status: string | undefined | null): boolean {
+  return status != null && status !== "pending" && status !== "generating";
+}
+
+/** A domain as a person types it: strips the scheme, www. and any path. */
+export function normalizeDomain(input: string): string {
+  return input.trim().toLowerCase().replace(/^https?:\/\//, "").replace(/^www\./, "").split(/[/?#]/)[0];
+}
+
+export function formatCount(n: number | null | undefined): string {
+  return n == null ? "-" : n.toLocaleString();
+}

package/blocks/radar/recipes/battle-card.ts

@@ -0,0 +1,28 @@
+/**
+ * @title Read a competitor battle card and the market overview
+ * @when Preparing a sales call or a weekly digest. Free reads. The card only claims advantages that have evidence
+ * (`include_unverified` adds the rest, which you must label as unverified). The overview gives tracked counts, moves
+ * in the last 7 days, open gaps, the threat board and alerts. Radar bodies are unwrapped (no `data`).
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function battleCard(competitorId: string, includeUnverified = false) {
+  const card = (await g8.api.radar.competitorBattleCard({ path: { competitor_id: competitorId }, query: { include_unverified: includeUnverified } })) as unknown as {
+    summary: string;
+    talk_track: { lead_with: string[]; be_ready_for: string[] };
+    our_advantages: Array<{ claim: string; verified: boolean }>;
+    watch_outs: Array<{ title: string }>;
+  };
+  return { summary: card.summary, leadWith: card.talk_track.lead_with, beReadyFor: card.talk_track.be_ready_for };
+}
+
+export async function weeklyDigest() {
+  const o = (await g8.api.radar.overview()) as unknown as {
+    summary: { tracked: number; moves_7d: number; open_gaps: number; act_now: number };
+    threat_board: Array<{ domain: string; threat_score: number | null }>;
+    moves: Array<{ competitor_domain?: string; text?: string }>;
+  };
+  return { ...o.summary, topThreats: o.threat_board.slice(0, 3), moves: o.moves.slice(0, 5) };
+}

package/blocks/radar/recipes/deep-dive-report.ts

@@ -0,0 +1,32 @@
+/**
+ * @title Generate a deep-dive report on one capability and download it
+ * @when A leadership or enablement document on one claim from the feature matrix. Generating runs a model and is
+ * BILLABLE with no advance price: get a human to approve it. Order: feature matrix (capability ids) -> create the
+ * report (a duplicate already generating answers 409; regenerating overwrites) -> poll the list until its status is
+ * final -> fetch the HTML. Reports use the usual `{ data }` envelope; competitors and the matrix do not.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function capabilities() {
+  const res = (await g8.api.radar.featureMatrix()) as unknown as { capabilities: Array<{ id: string; name: string }> };
+  return res.capabilities;
+}
+
+export async function generate(capabilityId: string, audience: "executive" | "developer" = "executive", edge: "us" | "them" = "us") {
+  const res = await g8.api.radarReports.createRadarReport({ body: { capability_id: capabilityId, audience, edge } });
+  return (res.data as { report_id: string }).report_id;
+}
+
+export async function waitForReport(reportId: string) {
+  let delay = 4000;
+  for (let i = 0; i < 80; i++) {
+    const res = await g8.api.radarReports.listRadarReports();
+    const row = ((res.data as { items?: Array<{ id: string; status: string; error_message?: string }> }).items ?? []).find((r) => r.id === reportId);
+    if (row && row.status !== "pending" && row.status !== "generating") return row;
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(20000, Math.round(delay * 1.3));
+  }
+  throw new Error(`report ${reportId} did not finish in time`);
+}

package/blocks/radar/recipes/marketing-snapshot.ts

@@ -0,0 +1,18 @@
+/**
+ * @title Pair competitor moves with your own marketing numbers
+ * @when A "market vs us" summary. Free reads from marketing intelligence (your site, campaigns and outbound bridge)
+ * and radar (the rivals). `days` is the lookback; the response is `{ data, meta }` where `meta.cached` says whether it
+ * came from cache. Combine with the radar overview: moves by rivals next to what your own traffic did that week.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function snapshot(days = 7) {
+  const [mine, rivals] = await Promise.all([
+    g8.api.marketingIntelligence.getMarketingOverview({ query: { days } }),
+    g8.api.radar.overview(),
+  ]);
+  const summary = (rivals as unknown as { summary: { moves_7d: number; open_gaps: number } }).summary;
+  return { days, mine: mine.data, rivalMoves: summary.moves_7d, openGaps: summary.open_gaps };
+}

package/blocks/radar/recipes/track-and-scan.ts

@@ -0,0 +1,39 @@
+/**
+ * @title Track competitors, scan them and wait for the scan
+ * @when Setting up competitive monitoring. Adding a competitor is free unless `scan_on_add` is true; a scan is
+ * BILLABLE (1 credit per page captured up to the tier budget, plus 1 for the traffic lookup: at most 26 for tier 1,
+ * 9 for the watchlist) and the API gives no quote, so tell a human that figure first. Radar answers with the app's
+ * own unwrapped bodies, so read `res.competitors`, not `res.data`. Order: suggestions -> add -> scan -> poll the
+ * list until no competitor has scan_status "scanning".
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type CompetitorRow = { id: string; domain: string; tier: string; page_budget: number; scan_status: string; threat_score?: number | null };
+
+export async function suggestions() {
+  const res = (await g8.api.radar.competitorSuggestions()) as unknown as { suggestions: Array<{ name?: string; domain: string | null; already_tracked: boolean }> };
+  return res.suggestions.filter((s) => s.domain && !s.already_tracked);
+}
+
+/** Free. 409 means it is already tracked, 422 means the plan's competitor limit is reached. */
+export async function track(domain: string, tier: "tier1" | "tier2" = "tier2") {
+  return (await g8.api.radar.createCompetitor({ body: { domain, tier, scan_on_add: false } })) as unknown as CompetitorRow;
+}
+
+/** Billable. Only after a person approved up to `page_budget + 1` credits. */
+export async function scan(competitorId: string) {
+  return g8.api.radar.scanCompetitor({ path: { competitor_id: competitorId } });
+}
+
+export async function waitForScans() {
+  let delay = 5000;
+  for (let i = 0; i < 60; i++) {
+    const res = (await g8.api.radar.listCompetitors()) as unknown as { competitors: CompetitorRow[] };
+    if (!res.competitors.some((c) => c.scan_status === "scanning" || c.scan_status === "queued")) return res.competitors;
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(30000, Math.round(delay * 1.3));
+  }
+  throw new Error("scans did not finish in time; check the list again later");
+}