@graph8/sdk 0.308.1 → 0.357.0

package/blocks/quotes/lib/quotes.ts

@@ -0,0 +1,142 @@
+"use client";
+
+/**
+ * Types and pure helpers for quotes: line-item math, money in cents, statuses, and the request bodies.
+ *
+ * All amounts are CENTS (`unit_amount`, `total`, `tax_amount`); `discount_pct` is a percentage (10 = 10%).
+ * The same arithmetic runs in the builder preview and in the tests, so the numbers shown while editing match what the
+ * server stores. The server is still the authority: after saving, the screens show the saved totals.
+ */
+
+export type Rec = Record<string, unknown>;
+
+export function asRec(value: unknown): Rec {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Rec) : {};
+}
+
+export function text(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : value == null ? fallback : String(value);
+}
+
+/** The body of a response: unwrap `{ data }`. */
+export function body(res: unknown): Rec {
+  const r = asRec(res);
+  return asRec("data" in r ? r.data : r);
+}
+
+export function money(cents: unknown, currency = "USD"): string {
+  if (typeof cents !== "number" || !Number.isFinite(cents)) return "";
+  return (cents / 100).toLocaleString(undefined, { style: "currency", currency: currency || "USD" });
+}
+
+export type BillingFrequency = "one_time" | "month" | "quarter" | "year";
+
+export interface LineItem {
+  /** Local key for React lists only; never sent. */
+  key: string;
+  product_name: string;
+  description?: string;
+  unit_amount: number;
+  quantity: number;
+  discount_pct: number;
+  billing_frequency: BillingFrequency;
+  stripe_product_id?: string | null;
+  stripe_price_id?: string | null;
+  manual_product_id?: string | null;
+}
+
+export const PAYMENT_TERMS = ["due_on_receipt", "net_15", "net_30", "net_45", "net_60", "net_90"] as const;
+export type PaymentTerms = (typeof PAYMENT_TERMS)[number];
+
+export function lineTotal(l: Pick<LineItem, "unit_amount" | "quantity" | "discount_pct">): number {
+  return Math.round(l.unit_amount * l.quantity * (1 - Math.min(100, Math.max(0, l.discount_pct)) / 100));
+}
+
+export function subtotal(lines: LineItem[]): number {
+  return lines.reduce((sum, l) => sum + lineTotal(l), 0);
+}
+
+/** A quotable-products price row (one per Stripe price, or the single price of a manual product). */
+export interface ProductPrice {
+  stripe_price_id: string | null;
+  unit_amount: number | null;
+  currency: string | null;
+  recurring_interval: string | null;
+  type: string | null;
+}
+
+export interface QuotableProduct {
+  stripe_product_id: string | null;
+  manual_product_id: string | null;
+  name: string;
+  description?: string | null;
+  category?: string | null;
+  source: "stripe" | "manual";
+  prices: ProductPrice[];
+}
+
+export function frequencyOf(interval: string | null | undefined): BillingFrequency {
+  return interval === "month" || interval === "year" || interval === "quarter" ? interval : "one_time";
+}
+
+let counter = 0;
+export const nextKey = (): string => `li-${Date.now().toString(36)}-${counter++}`;
+
+export function lineFromProduct(p: QuotableProduct, price: ProductPrice | undefined): LineItem {
+  return {
+    key: nextKey(),
+    product_name: p.name,
+    description: p.description ?? undefined,
+    unit_amount: price?.unit_amount ?? 0,
+    quantity: 1,
+    discount_pct: 0,
+    billing_frequency: frequencyOf(price?.recurring_interval),
+    stripe_product_id: p.stripe_product_id,
+    stripe_price_id: price?.stripe_price_id ?? null,
+    manual_product_id: p.manual_product_id,
+  };
+}
+
+/** The `line_items` of a create/update request (the local key is dropped, empty links are omitted). */
+export function toRequestLines(lines: LineItem[]): Rec[] {
+  return lines.map((l, i) => {
+    const out: Rec = { product_name: l.product_name, unit_amount: l.unit_amount, quantity: l.quantity, discount_pct: l.discount_pct, billing_frequency: l.billing_frequency, sort_order: i };
+    if (l.description) out.description = l.description;
+    if (l.stripe_product_id) out.stripe_product_id = l.stripe_product_id;
+    if (l.stripe_price_id) out.stripe_price_id = l.stripe_price_id;
+    if (l.manual_product_id) out.manual_product_id = l.manual_product_id;
+    return out;
+  });
+}
+
+export function linesFromQuote(items: unknown): LineItem[] {
+  if (!Array.isArray(items)) return [];
+  return items.map((raw) => {
+    const r = asRec(raw);
+    const freq = text(r.billing_frequency);
+    return {
+      key: nextKey(),
+      product_name: text(r.product_name),
+      description: text(r.description) || undefined,
+      unit_amount: Number(r.unit_amount ?? 0),
+      quantity: Number(r.quantity ?? 1),
+      discount_pct: Number(r.discount_pct ?? 0),
+      billing_frequency: (["one_time", "month", "quarter", "year"].includes(freq) ? freq : "one_time") as BillingFrequency,
+      stripe_product_id: (r.stripe_product_id as string | null) ?? null,
+      stripe_price_id: (r.stripe_price_id as string | null) ?? null,
+      manual_product_id: (r.manual_product_id as string | null) ?? null,
+    };
+  });
+}
+
+export const STATUS_LABEL: Record<string, string> = {
+  draft: "Draft",
+  sent: "Sent",
+  viewed: "Viewed",
+  accepted: "Accepted",
+  declined: "Declined",
+  voided: "Voided",
+  expired: "Expired",
+  archived: "Archived",
+};
+export const statusLabel = (s: unknown): string => STATUS_LABEL[text(s)] ?? text(s, "Unknown");

package/blocks/quotes/recipes/create-and-send-quote.ts

@@ -0,0 +1,44 @@
+/**
+ * @title Create a quote from quotable products and send it for signature
+ * @when A deal is ready for paper. Line items MUST reference a quotable product: read /quotable-products first and copy
+ * the ids and the price, never type a Stripe id. Amounts are CENTS. Creating stores a draft (nobody is emailed);
+ * SENDING emails the signer a signing link (external tier), so only send after the person confirmed the quote.
+ * The `dealId` comes from the deals block; the signer is an existing contact id or an email.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function createQuote(opts: { dealId: string; title: string; signerEmail: string; contractStart: string; productName: string; quantity?: number; send?: boolean }): Promise<string> {
+  // 1. Pick a real quotable product and its first flat price.
+  const catalog = await g8.api.quotes.listQuotableProducts({ query: { limit: 100 } });
+  const product = catalog.data.items.find((p) => String(p.name).toLowerCase() === opts.productName.toLowerCase());
+  const price = (product?.prices as Array<{ stripe_price_id: string | null; unit_amount: number; recurring_interval: string | null }> | undefined)?.[0];
+  if (!product || !price) throw new Error(`"${opts.productName}" is not a quotable product with a flat price`);
+
+  // 2. Create the draft. contract_start_date, a signer and at least one line item are required.
+  const created = await g8.api.quotes.createQuote({
+    body: {
+      deal_id: opts.dealId,
+      title: opts.title,
+      contract_start_date: opts.contractStart,
+      signer_email: opts.signerEmail,
+      line_items: [
+        {
+          product_name: String(product.name),
+          unit_amount: price.unit_amount,
+          quantity: opts.quantity ?? 1,
+          billing_frequency: price.recurring_interval === "month" || price.recurring_interval === "year" || price.recurring_interval === "quarter" ? price.recurring_interval : "one_time",
+          stripe_product_id: (product.stripe_product_id as string | null) ?? null,
+          stripe_price_id: price.stripe_price_id,
+          manual_product_id: (product.manual_product_id as string | null) ?? null,
+        },
+      ],
+    },
+  });
+  const quoteId = String(created.data.id);
+
+  // 3. Send only when asked: this emails the signer.
+  if (opts.send) await g8.api.quotes.sendQuote({ path: { quote_id: quoteId }, body: {} });
+  return quoteId;
+}

package/blocks/quotes/recipes/revise-sent-quote.ts

@@ -0,0 +1,18 @@
+/**
+ * @title Change a quote that was already sent
+ * @when The customer asked for different terms. A sent quote cannot be edited in place: "edit as draft" VOIDS the sent
+ * copy (the signing link stops working) and returns a new draft (its id is `new_quote_id`), which is edited and sent again. Both the void and the
+ * resend are external tier: confirm with the person before running this.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function reviseAndResend(sentQuoteId: string, changes: { title?: string; paymentTerms?: "due_on_receipt" | "net_15" | "net_30" | "net_45" | "net_60" | "net_90" }): Promise<string> {
+  const draft = await g8.api.quotes.editQuoteAsDraft({ path: { quote_id: sentQuoteId } });
+  const draftId = String((draft.data as Record<string, unknown>).new_quote_id);
+
+  await g8.api.quotes.updateQuotePatch({ path: { quote_id: draftId }, body: { title: changes.title, payment_terms: changes.paymentTerms } });
+  await g8.api.quotes.sendQuote({ path: { quote_id: draftId }, body: { message: "Updated as discussed." } });
+  return draftId;
+}

package/blocks/quotes/recipes/track-quote-signature.ts

@@ -0,0 +1,22 @@
+/**
+ * @title Wait for a quote to be signed (or declined)
+ * @when After sending, when the next step depends on the signature. The envelope inside the quote reports `sent`,
+ * `viewed`, `signed` or `declined`; there is no webhook to wait on from this recipe, so poll slowly. Reading is free.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function waitForSignature(quoteId: string, maxChecks = 20): Promise<{ status: string; signedAt?: string | null }> {
+  for (let i = 0; i < maxChecks; i++) {
+    const quote = (await g8.api.quotes.getQuote({ path: { quote_id: quoteId } })).data;
+    const envelope = (quote.envelope ?? {}) as { status?: string; signed_at?: string | null };
+    if (envelope.status === "signed" || envelope.status === "declined" || envelope.status === "voided" || envelope.status === "expired") {
+      return { status: envelope.status, signedAt: envelope.signed_at };
+    }
+    await sleep(Math.min(5 * 60_000, 30_000 * 1.5 ** i));
+  }
+  return { status: "still waiting" };
+}

package/blocks/radar/README.md

@@ -0,0 +1,106 @@
+# radar
+
+Know what competitors are doing: track them, scan them, read a threat board and a free battle card, and generate
+deep-dive reports. Depends only on `foundation`.
+
+Install: `npx @graph8/sdk add radar`.
+
+## What you get
+
+| Component | Use it for | Props |
+|---|---|---|
+| `CompetitorTracker` | Roster: add, bulk-add detected, scan one or all, pause, resume, remove | `onSelect(competitor)` |
+| `RadarOverview` | Counts, moves, open gaps, threat board, alerts | `onSelectCompetitor(id)` |
+| `CompetitorBattleCard` | Free battle card with a talk track | `competitorId` |
+| `RadarReport` | Generate and open deep-dive reports | `capabilityId` |
+
+Hook `useCompetitors()`; helpers in `lib/radar-types.ts` (`radarBody`, `scanCostEstimate`, `normalizeDomain`).
+
+## Cost, in plain numbers
+
+| Action | Cost | Confirmed with |
+|---|---|---|
+| Add a competitor | free, unless `scan_on_add` | `ConfirmSpendDialog` (0 credits shown; the operation's tier is billable) |
+| Pause / resume | free | `ConfirmSpendDialog` (0 credits) |
+| Scan one competitor | 1 credit per page captured (25 pages tier 1, 8 watchlist) + 1 for traffic: at most 26 / 9 | `ConfirmSpendDialog` (billable) |
+| Scan all | the sum of the above for every active competitor not already scanning | `ConfirmSpendDialog` (billable) |
+| Generate a report | uses credits; **no advance price** | `ConfirmSpendDialog` (billable) without a number |
+| Remove a competitor | free, irreversible | `ConfirmSpendDialog` (destructive) |
+| Overview, battle card, lists | free | none |
+
+There is no quote and no balance read; the figures are the most a scan can charge. A monthly radar credit cap pauses
+automatic scans (`summary.credit_cap_reached`); manual scans still run.
+
+## The flow, with the ids that pass between steps
+
+1. `GET /radar/competitors/suggestions` (detected, untracked) -> `POST /radar/competitors { domain, tier, scan_on_add }` -> competitor `id` (a UUID string).
+2. `POST /radar/competitors/{id}/scan` -> `{ task_id, status: "queued" }`. Poll `GET /radar/competitors` (`useJobPoll`; there is no stream) until no
+   competitor has `scan_status` `scanning`. A scan already queued or running answers 409.
+3. `GET /radar/competitors/{id}/battle-card` (free): `talk_track.lead_with`, `watch_outs`, `our_advantages`, `recent_moves`.
+4. Reports: `GET /radar/feature-matrix` -> `capabilities[].id` -> `POST /radar/reports { capability_id, audience, edge }` -> `{ report_id, status: "generating" }`
+   -> poll `GET /radar/reports` until the status is final -> open `/api/g8/radar/reports/{id}/html` or `/pdf` in a new tab (through your proxy, so the signed-in
+   session authorizes it).
+
+**Response shapes differ:** competitor, overview, battle card, matrix and scan bodies are the app's own and come **unwrapped** (`{ competitors, capacity }`);
+reports use the usual `{ data: { items } }`. `radarBody()` reads both.
+
+```tsx
+"use client";
+import { useState } from "react";
+import { CompetitorTracker } from "@/components/g8/radar/competitor-tracker";
+import { CompetitorBattleCard } from "@/components/g8/radar/competitor-battle-card";
+
+export function Competitors() {
+  const [id, setId] = useState<string | null>(null);
+  return (<div className="grid gap-6 md:grid-cols-2"><CompetitorTracker onSelect={(c) => setId(c.id)} />{id ? <CompetitorBattleCard competitorId={id} /> : null}</div>);
+}
+```
+
+(`add` flattens `components/` into `components/g8/radar/`; adjust the alias to your app.)
+
+## Prerequisites (a human must do these)
+
+- `proxy-allowlist` (app): `allowedPrefixes` includes `radar` (and `analytics` for the marketing snapshot recipe).
+- `credits` (api): credits for scans and reports.
+- `market-research` (api): detected competitors, the feature matrix and verified advantages come from the workspace's research and proof catalog in graph8.
+
+## Defaults the agent can use without asking
+
+| Decision | Default |
+|---|---|
+| Tier of a new competitor | watchlist (tier 2) |
+| Scan when adding | off |
+| Battle card advantages | evidence-backed only |
+| Report audience and angle | executive, where we win |
+
+Ask the person: who may scan or generate reports (the proxy's `authorize`).
+
+## Recipes
+
+| File | Does |
+|---|---|
+| `recipes/track-and-scan.ts` | Suggestions, add, scan, poll the roster |
+| `recipes/battle-card.ts` | Battle card and a weekly digest from the overview |
+| `recipes/deep-dive-report.ts` | Matrix -> create report -> poll -> done |
+| `recipes/marketing-snapshot.ts` | Your marketing overview next to rival moves |
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| bulkAddCompetitors | POST /radar/competitors/bulk | billable | CompetitorTracker |
+| competitorBattleCard | GET /radar/competitors/{competitor_id}/battle-card | read | CompetitorBattleCard |
+| competitorSuggestions | GET /radar/competitors/suggestions | read | CompetitorTracker |
+| createCompetitor | POST /radar/competitors | billable | CompetitorTracker |
+| createRadarReport | POST /radar/reports | billable | RadarReport |
+| deleteCompetitor | DELETE /radar/competitors/{competitor_id} | destructive | CompetitorTracker |
+| featureMatrix | GET /radar/feature-matrix | read | RadarReport |
+| getMarketingOverview | GET /analytics/marketing/overview | read | recipes |
+| getRadarReportHtml | GET /radar/reports/{report_id}/html | read | recipes |
+| getRadarReportPdf | GET /radar/reports/{report_id}/pdf | read | recipes |
+| listCompetitors | GET /radar/competitors | read | CompetitorTracker, useCompetitors |
+| listRadarReports | GET /radar/reports | read | RadarReport |
+| overview | GET /radar/overview | read | RadarOverview |
+| scanAllCompetitors | POST /radar/scan-all | billable | CompetitorTracker |
+| scanCompetitor | POST /radar/competitors/{competitor_id}/scan | billable | CompetitorTracker |
+| updateCompetitor | PATCH /radar/competitors/{competitor_id} | billable | CompetitorTracker |

package/blocks/radar/block.json

@@ -0,0 +1,189 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "radar",
+  "title": "Competitors & market",
+  "summary": "Track competitors, scan them, read the threat board and battle cards, and generate deep-dive reports.",
+  "features": [
+    "roster of tracked competitors with threat score, traffic, ads and scan status, polled while a scan runs",
+    "add, bulk-add detected competitors, pause, resume and remove, each confirmed with the credits it can use",
+    "overview with moves, alerts and the threat board",
+    "free battle card with a talk track; evidence-backed advantages by default",
+    "deep-dive reports per capability and audience, generated, polled and opened as HTML or PDF"
+  ],
+  "dependsOn": [
+    "foundation"
+  ],
+  "operations": [
+    "bulk_add_competitors_radar_competitors_bulk_post",
+    "competitor_battle_card_radar_competitors__competitor_id__battle_card_get",
+    "competitor_suggestions_radar_competitors_suggestions_get",
+    "create_competitor_radar_competitors_post",
+    "create_radar_report_radar_reports_post",
+    "delete_competitor_radar_competitors__competitor_id__delete",
+    "feature_matrix_radar_feature_matrix_get",
+    "get_marketing_overview_analytics_marketing_overview_get",
+    "get_radar_report_html_radar_reports__report_id__html_get",
+    "get_radar_report_pdf_radar_reports__report_id__pdf_get",
+    "list_competitors_radar_competitors_get",
+    "list_radar_reports_radar_reports_get",
+    "overview_radar_overview_get",
+    "scan_all_competitors_radar_scan_all_post",
+    "scan_competitor_radar_competitors__competitor_id__scan_post",
+    "update_competitor_radar_competitors__competitor_id__patch"
+  ],
+  "components": [
+    {
+      "name": "CompetitorTracker",
+      "file": "components/competitor-tracker.tsx",
+      "purpose": "The competitor roster: add, bulk-add detected ones, scan one or all (confirmed, 1 credit per page up to the tier budget plus 1), pause, resume and remove.",
+      "operations": [
+        "list_competitors_radar_competitors_get",
+        "competitor_suggestions_radar_competitors_suggestions_get",
+        "create_competitor_radar_competitors_post",
+        "bulk_add_competitors_radar_competitors_bulk_post",
+        "scan_competitor_radar_competitors__competitor_id__scan_post",
+        "scan_all_competitors_radar_scan_all_post",
+        "update_competitor_radar_competitors__competitor_id__patch",
+        "delete_competitor_radar_competitors__competitor_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "RadarOverview",
+      "file": "components/radar-overview.tsx",
+      "purpose": "Tracked counts, moves in 7 days, open gaps, the threat board, alerts and recent moves. Read-only.",
+      "operations": [
+        "overview_radar_overview_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "CompetitorBattleCard",
+      "file": "components/competitor-battle-card.tsx",
+      "purpose": "A free battle card for one competitor: what to lead with, what to be ready for, proven advantages and recent moves.",
+      "operations": [
+        "competitor_battle_card_radar_competitors__competitor_id__battle_card_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "RadarReport",
+      "file": "components/radar-report.tsx",
+      "purpose": "Pick a capability, audience and angle, confirm and generate a deep-dive report, watch it generate, open the HTML or PDF.",
+      "operations": [
+        "feature_matrix_radar_feature_matrix_get",
+        "list_radar_reports_radar_reports_get",
+        "create_radar_report_radar_reports_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useCompetitors",
+      "file": "hooks/use-competitors.ts",
+      "purpose": "Tracked competitors with plan capacity and a `scanning` flag for polling.",
+      "operations": [
+        "list_competitors_radar_competitors_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/radar-types.ts",
+      "purpose": "Competitor, overview, battle card and report shapes; radarBody (wrapped or not), scanCostEstimate, isScanning, normalizeDomain."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/track-and-scan.ts",
+      "title": "Track competitors, scan them and wait for the scan",
+      "when": "Setting up monitoring. Adding is free unless scan_on_add; a scan is billable (1 credit per page up to the tier budget, plus 1) with no quote, so tell a human the figure first. Radar bodies are unwrapped."
+    },
+    {
+      "file": "recipes/battle-card.ts",
+      "title": "Read a competitor battle card and the market overview",
+      "when": "Preparing a call or a weekly digest. Free reads; only evidence-backed advantages unless include_unverified, which you must label."
+    },
+    {
+      "file": "recipes/deep-dive-report.ts",
+      "title": "Generate a deep-dive report on one capability and download it",
+      "when": "An enablement document on one feature-matrix claim. Billable, no advance price: get approval. Duplicates in flight answer 409; regenerating overwrites."
+    },
+    {
+      "file": "recipes/marketing-snapshot.ts",
+      "title": "Pair competitor moves with your own marketing numbers",
+      "when": "A market-versus-us summary from free reads of marketing intelligence and the radar overview."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "proxy-allowlist",
+      "where": "app",
+      "description": "allowedPrefixes in the /api/g8 route includes `radar` (and `analytics` for the marketing snapshot recipe).",
+      "verify": "GET /api/g8/radar/competitors returns 200 when signed in."
+    },
+    {
+      "id": "credits",
+      "where": "api",
+      "description": "The workspace has credits for scans and reports. The API has no balance read and no scan quote, so the UI shows the most a scan can charge.",
+      "verify": "A scan of one competitor starts."
+    },
+    {
+      "id": "market-research",
+      "where": "api",
+      "description": "Detected competitors, the feature matrix and battle-card advantages come from the workspace's market research and proof catalog in graph8. Without them those lists are empty.",
+      "verify": "GET /radar/competitors/suggestions returns suggestions, or you add competitors by hand."
+    }
+  ],
+  "scopes": [
+    "analytics:read",
+    "intent:read",
+    "intent:run",
+    "radar:delete",
+    "radar:read",
+    "radar:run",
+    "radar:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Tier of a new competitor",
+      "default": "Watchlist (tier 2, 8 pages per scan)",
+      "askHuman": false
+    },
+    {
+      "decision": "Scan when adding",
+      "default": "Off",
+      "askHuman": false
+    },
+    {
+      "decision": "Battle card advantages",
+      "default": "Only evidence-backed ones; unverified are an explicit toggle and labelled",
+      "askHuman": false
+    },
+    {
+      "decision": "Report audience and angle",
+      "default": "Executive, where we win",
+      "askHuman": false
+    },
+    {
+      "decision": "Who may scan or generate reports (credits)",
+      "default": "Anyone the proxy's authorize lets through",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/radar/components/competitor-battle-card.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+/**
+ * CompetitorBattleCard: a sales-enablement card for one competitor, composed from what radar already knows (no
+ * AI call, free): our proven advantages, where they beat us (watch-outs), their recent moves and a talk track.
+ *
+ * SDK operations, in order:
+ *   1. competitorBattleCard   GET /radar/competitors/{competitor_id}/battle-card?include_unverified   (read, free)
+ * By default only advantages backed by evidence are shown; the toggle also shows unverified ones, labelled.
+ */
+
+import { useState } from "react";
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { radarBody } from "../lib/radar-types";
+import type { BattleCard } from "../lib/radar-types";
+
+export interface CompetitorBattleCardProps {
+  competitorId: string;
+  className?: string;
+}
+
+export function CompetitorBattleCard({ competitorId, className }: CompetitorBattleCardProps) {
+  const [unverified, setUnverified] = useState(false);
+  const query = useG8Query(
+    async (signal) => radarBody<BattleCard>(await g8Get(`/radar/competitors/${competitorId}/battle-card`, { include_unverified: unverified }, { signal })),
+    [competitorId, unverified],
+  );
+  const card = query.data;
+
+  if (query.error) return <ApiError error={query.error} title="Could not load the battle card" onRetry={() => void query.refetch()} />;
+  if (!card) return <Skeleton className="h-40 w-full" />;
+  return (
+    <article className={`flex flex-col gap-4 ${className ?? ""}`} aria-busy={query.loading}>
+      <header><h3 className="text-base font-semibold">{card.competitor.name || card.competitor.domain}</h3><p className="text-sm text-muted-foreground">{card.summary}</p></header>
+      <section aria-label="Lead with"><h4 className="text-sm font-medium">Lead with</h4>
+        {card.talk_track.lead_with.length ? <ul className="list-disc pl-5 text-sm">{card.talk_track.lead_with.map((t) => <li key={t}>{t}</li>)}</ul> : <p className="text-sm text-muted-foreground">No proven advantage yet. Add proof to your catalog or show unverified ones.</p>}
+      </section>
+      <section aria-label="Be ready for"><h4 className="text-sm font-medium">Be ready for</h4>
+        {card.watch_outs.length ? <ul className="list-disc pl-5 text-sm">{card.watch_outs.map((w) => <li key={w.id}>{w.title}</li>)}</ul> : <p className="text-sm text-muted-foreground">No open gaps against this competitor.</p>}
+      </section>
+      <section aria-label="Our advantages"><h4 className="text-sm font-medium">Our advantages</h4>
+        <ul className="flex flex-col gap-1 text-sm">{card.our_advantages.map((a) => <li key={a.claim}>{a.claim}{!a.verified ? <span className="ml-1 rounded bg-muted px-1 text-xs">unverified</span> : null}</li>)}</ul>
+        <label className="mt-1 flex items-center gap-2 text-xs text-muted-foreground"><input type="checkbox" checked={unverified} onChange={(e) => setUnverified(e.target.checked)} /> Also show unverified advantages{card.unverified_advantages_hidden ? ` (${card.unverified_advantages_hidden} hidden)` : ""}</label>
+      </section>
+      <section aria-label="Recent moves"><h4 className="text-sm font-medium">Recent moves</h4>
+        {card.recent_moves.length ? <ul className="text-sm">{card.recent_moves.map((m) => <li key={m.id}>{m.title || m.url}{m.captured_at ? <span className="text-muted-foreground"> · {m.captured_at.slice(0, 10)}</span> : null}</li>)}</ul> : <p className="text-sm text-muted-foreground">No recent moves.</p>}
+      </section>
+    </article>
+  );
+}