@graph8/sdk 0.308.1 → 0.357.0

package/blocks/integrations/components/webhook-manager.tsx

@@ -0,0 +1,300 @@
+"use client";
+
+/**
+ * WebhookManager: subscribe your server to graph8 events, see delivery attempts, rotate the signing secret.
+ *
+ * SDK operations, in order:
+ *   1. listWebhooks           GET    /webhooks                       (read)
+ *   2. listWebhookEvents      GET    /webhooks/events                (read; the event names, grouped by category)
+ *   3. createWebhook          POST   /webhooks                       (external: confirmed; the secret is shown ONCE)
+ *   4. updateWebhook          PATCH  /webhooks/{webhook_id}          (external: confirmed; pause or resume)
+ *   5. rotateWebhookSecret    POST   /webhooks/{webhook_id}/rotate-secret (external: confirmed; new secret shown once)
+ *   6. listWebhookDeliveries  GET    /webhooks/{webhook_id}/deliveries    (read; attempts, status, response code)
+ *   7. deleteWebhook          DELETE /webhooks/{webhook_id}          (destructive: confirmed)
+ *
+ * Tiers: 3-5 change where graph8 sends your data, 7 removes the subscription: each opens ConfirmSpendDialog.
+ * VERIFY on the server, never in the browser: deliveries are signed with the secret. See the "Verify
+ * deliveries" note in the UI and recipes/verify-webhook-route.ts (`g8.webhooks.constructEvent`).
+ */
+
+import { useState } from "react";
+import { Button, Input, Skeleton } from "@graph8/sdk/ui";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+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 { arrayOf, formatWhen } from "../lib/integrations-utils";
+
+export interface WebhookManagerProps {
+  /** Pre-fill the endpoint URL of the create form (your /api/webhooks/graph8 route). */
+  defaultUrl?: string;
+  className?: string;
+}
+
+interface Webhook {
+  id: string;
+  url: string;
+  name?: string | null;
+  events?: string[];
+  is_active?: boolean;
+  secret?: string | null;
+}
+
+interface EventType {
+  event: string;
+  category?: string | null;
+  description?: string | null;
+}
+
+interface Delivery {
+  id: string;
+  event: string;
+  status: string;
+  attempts?: number;
+  response_code?: number | null;
+  error_message?: string | null;
+  created_at?: string | null;
+}
+
+type Pending =
+  | { kind: "create"; url: string; name: string; events: string[] }
+  | { kind: "toggle"; hook: Webhook }
+  | { kind: "rotate"; hook: Webhook }
+  | { kind: "delete"; hook: Webhook };
+
+function copyFor(p: Pending): { tier: ConfirmTier; title: string; description: string; label: string } {
+  switch (p.kind) {
+    case "create":
+      return {
+        tier: "external",
+        title: `Send ${p.events.length} event type${p.events.length === 1 ? "" : "s"} to ${p.url}`,
+        description: "graph8 will POST signed events to this URL as they happen.",
+        label: "Create webhook",
+      };
+    case "toggle":
+      return {
+        tier: "external",
+        title: `${p.hook.is_active === false ? "Resume" : "Pause"} deliveries to ${p.hook.url}`,
+        description:
+          p.hook.is_active === false
+            ? "graph8 starts sending events to this URL again."
+            : "Events stop being sent to this URL until you resume.",
+        label: p.hook.is_active === false ? "Resume" : "Pause",
+      };
+    case "rotate":
+      return {
+        tier: "external",
+        title: `Rotate the signing secret for ${p.hook.url}`,
+        description: "The old secret stops working immediately. Update your server before the next delivery.",
+        label: "Rotate secret",
+      };
+    case "delete":
+      return {
+        tier: "destructive",
+        title: `Delete the webhook for ${p.hook.url}`,
+        description: "Deliveries stop and the subscription cannot be restored.",
+        label: "Delete webhook",
+      };
+  }
+}
+
+function Deliveries({ hook }: { hook: Webhook }) {
+  const list = useG8Query((signal) => g8Get(`/webhooks/${hook.id}/deliveries`, { page: 1, limit: 20 }, { signal }), [hook.id]);
+  if (list.loading) return <Skeleton className="h-16 w-full" />;
+  if (list.error) return <ApiError error={list.error} onRetry={() => void list.refetch()} />;
+  const rows = arrayOf<Delivery>(list.data);
+  if (rows.length === 0) return <p className="text-sm text-gray-500">No deliveries yet.</p>;
+  return (
+    <table className="w-full text-sm" aria-label="Deliveries">
+      <thead>
+        <tr className="text-left text-gray-500">
+          <th>Event</th>
+          <th>Status</th>
+          <th>Code</th>
+          <th>Attempts</th>
+          <th>When</th>
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map((d) => (
+          <tr key={d.id} className="border-t">
+            <td>{d.event}</td>
+            <td>{d.status}</td>
+            <td>{d.response_code ?? "-"}</td>
+            <td>{d.attempts ?? 1}</td>
+            <td title={d.error_message ?? undefined}>{formatWhen(d.created_at)}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+export function WebhookManager({ defaultUrl = "", className }: WebhookManagerProps) {
+  const hooks = useG8Query((signal) => g8Get("/webhooks", undefined, { signal }), []);
+  const events = useG8Query((signal) => g8Get("/webhooks/events", undefined, { signal }), []);
+  const [url, setUrl] = useState(defaultUrl);
+  const [name, setName] = useState("");
+  const [chosen, setChosen] = useState<string[]>([]);
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [secret, setSecret] = useState<{ url: string; value: string } | null>(null);
+  const [openDeliveries, setOpenDeliveries] = useState<string | null>(null);
+
+  const run = useG8Mutation(async (p: Pending) => {
+    if (p.kind === "create") {
+      const res = await g8Post<Webhook>("/webhooks", { url: p.url, name: p.name || undefined, events: p.events });
+      if (res.data?.secret) setSecret({ url: p.url, value: res.data.secret });
+      setUrl("");
+      setName("");
+      setChosen([]);
+    } else if (p.kind === "toggle") {
+      await g8Patch(`/webhooks/${p.hook.id}`, { is_active: p.hook.is_active === false });
+    } else if (p.kind === "rotate") {
+      const res = await g8Post<Webhook>(`/webhooks/${p.hook.id}/rotate-secret`);
+      if (res.data?.secret) setSecret({ url: p.hook.url, value: res.data.secret });
+    } else {
+      await g8Delete(`/webhooks/${p.hook.id}`);
+      setOpenDeliveries((open) => (open === p.hook.id ? null : open));
+    }
+    await hooks.refetch();
+  });
+
+  const list = arrayOf<Webhook>(hooks.data);
+  const byCategory = arrayOf<EventType>(events.data).reduce<Record<string, EventType[]>>(
+    (acc, e) => ({ ...acc, [e.category ?? "other"]: [...(acc[e.category ?? "other"] ?? []), e] }),
+    {},
+  );
+  const urlOk = /^https:\/\/\S+$/.test(url.trim());
+  const toggle = (event: string) => setChosen((c) => (c.includes(event) ? c.filter((x) => x !== event) : [...c, event]));
+  const confirm = pending ? copyFor(pending) : null;
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`}>
+      <section className="space-y-3 rounded border border-gray-200 p-3" aria-label="New webhook">
+        <h3 className="text-sm font-semibold">New webhook</h3>
+        <div className="grid gap-2 md:grid-cols-2">
+          <Input
+            aria-label="Endpoint URL"
+            placeholder="https://yourapp.com/api/webhooks/graph8"
+            value={url}
+            onChange={(e) => setUrl(e.target.value)}
+          />
+          <Input aria-label="Name" placeholder="Name (optional)" value={name} onChange={(e) => setName(e.target.value)} />
+        </div>
+        {url && !urlOk ? <p className="text-xs text-red-700">The endpoint must be an https:// URL.</p> : null}
+        {events.loading ? (
+          <Skeleton className="h-12 w-full" />
+        ) : (
+          <div className="space-y-2">
+            {Object.entries(byCategory).map(([category, items]) => (
+              <fieldset key={category}>
+                <legend className="text-xs font-medium uppercase text-gray-500">{category}</legend>
+                <div className="flex flex-wrap gap-x-4 gap-y-1">
+                  {items.map((e) => (
+                    <label key={e.event} className="flex items-center gap-1 text-sm" title={e.description ?? undefined}>
+                      <input type="checkbox" checked={chosen.includes(e.event)} onChange={() => toggle(e.event)} />
+                      {e.event}
+                    </label>
+                  ))}
+                </div>
+              </fieldset>
+            ))}
+          </div>
+        )}
+        <Button
+          disabled={!urlOk || chosen.length === 0}
+          onClick={() => setPending({ kind: "create", url: url.trim(), name: name.trim(), events: chosen })}
+        >
+          Create webhook
+        </Button>
+      </section>
+
+      {secret ? (
+        <div role="alert" className="rounded border border-amber-300 bg-amber-50 p-3 text-sm">
+          <p className="font-medium">Signing secret for {secret.url}. It is shown once.</p>
+          <code className="mt-1 block break-all rounded bg-white p-2">{secret.value}</code>
+          <p className="mt-1 text-xs text-gray-600">
+            Store it in your server environment as G8_WEBHOOK_SECRET. Never put it in browser code.
+          </p>
+          <Button size="sm" variant="outline" className="mt-2" onClick={() => setSecret(null)}>
+            I saved it
+          </Button>
+        </div>
+      ) : null}
+      {run.error ? <ApiError error={run.error} onRetry={run.reset} /> : null}
+
+      {hooks.error ? (
+        <ApiError error={hooks.error} onRetry={() => void hooks.refetch()} />
+      ) : hooks.loading && !hooks.data ? (
+        <Skeleton className="h-24 w-full" />
+      ) : list.length === 0 ? (
+        <EmptyState title="No webhooks yet" description="Create one above to receive events like replies and meetings on your server." />
+      ) : (
+        <ul className="divide-y rounded border border-gray-200">
+          {list.map((h) => (
+            <li key={h.id} className="space-y-2 px-3 py-3">
+              <div className="flex flex-wrap items-center justify-between gap-2">
+                <div>
+                  <div className="font-medium">{h.name || h.url}</div>
+                  <div className="text-xs text-gray-500">
+                    {h.name ? `${h.url} - ` : ""}
+                    {(h.events ?? []).length} events - {h.is_active === false ? "paused" : "active"}
+                  </div>
+                </div>
+                <div className="flex gap-1">
+                  <Button size="sm" variant="outline" onClick={() => setOpenDeliveries(openDeliveries === h.id ? null : h.id)}>
+                    Deliveries
+                  </Button>
+                  <Button size="sm" variant="outline" onClick={() => setPending({ kind: "toggle", hook: h })}>
+                    {h.is_active === false ? "Resume" : "Pause"}
+                  </Button>
+                  <Button size="sm" variant="outline" onClick={() => setPending({ kind: "rotate", hook: h })}>
+                    Rotate secret
+                  </Button>
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    aria-label={`Delete webhook ${h.url}`}
+                    onClick={() => setPending({ kind: "delete", hook: h })}
+                  >
+                    Delete
+                  </Button>
+                </div>
+              </div>
+              {openDeliveries === h.id ? <Deliveries hook={h} /> : null}
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <details className="rounded border border-gray-200 p-3 text-sm">
+        <summary className="cursor-pointer font-medium">Verify deliveries (server side)</summary>
+        <p className="mt-2 text-gray-600">
+          Check the signature on the raw body before trusting an event. Deliveries repeat, so deduplicate on the event id.
+        </p>
+        <pre className="mt-2 overflow-x-auto rounded bg-gray-950 p-3 text-xs text-gray-100">
+          <code>{`const event = g8.webhooks.constructEvent(rawBody,
+  req.headers.get("x-studio-signature") ?? "",
+  req.headers.get("x-studio-timestamp") ?? "",
+  process.env.G8_WEBHOOK_SECRET!, { toleranceSeconds: 300 });`}</code>
+        </pre>
+      </details>
+
+      {pending && confirm ? (
+        <ConfirmSpendDialog
+          open
+          tier={confirm.tier}
+          title={confirm.title}
+          description={confirm.description}
+          confirmLabel={confirm.label}
+          confirming={run.loading}
+          onCancel={() => setPending(null)}
+          onConfirm={() => void run.mutate(pending).then(() => setPending(null))}
+        />
+      ) : null}
+    </div>
+  );
+}

package/blocks/integrations/lib/integrations-utils.ts

@@ -0,0 +1,62 @@
+"use client";
+
+/** Types and helpers shared by the integrations components. */
+
+export const CRM_PROVIDERS = ["hubspot", "salesforce", "pipedrive", "zoho", "sugarcrm"] as const;
+export type CrmProvider = (typeof CRM_PROVIDERS)[number];
+
+export const PROVIDER_LABELS: Record<CrmProvider, string> = {
+  hubspot: "HubSpot",
+  salesforce: "Salesforce",
+  pipedrive: "Pipedrive",
+  zoho: "Zoho CRM",
+  sugarcrm: "SugarCRM",
+};
+
+/** Where the person completes an OAuth connection. The API has no way to run the consent screen for you. */
+export const GRAPH8_APP_INTEGRATIONS_URL = "https://app.graph8.com/studio/settings?tab=integrations";
+
+export interface CrmSyncRow {
+  provider: string;
+  status: string;
+  connection_id?: string | null;
+  connected_at?: string | null;
+  last_sync_at?: string | null;
+}
+
+export interface CrmStatus {
+  connected: boolean;
+  connection_id?: string | null;
+  crm_type?: string | null;
+  last_sync_at?: string | null;
+  message?: string | null;
+  provider: string;
+}
+
+export interface ConnectionRow {
+  connection_id?: string;
+  provider?: string;
+  provider_config_key?: string;
+}
+
+export function arrayOf<T>(envelope: unknown): T[] {
+  const data = (envelope as { data?: unknown } | null)?.data;
+  if (Array.isArray(data)) return data as T[];
+  const items = (data as { items?: unknown } | null)?.items;
+  return Array.isArray(items) ? (items as T[]) : [];
+}
+
+export function formatWhen(value: string | null | undefined): string {
+  if (!value) return "never";
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? value : d.toLocaleString();
+}
+
+/** Open-shaped status objects: true when any of the usual "connected" flags is set. */
+export function looksConnected(status: unknown): boolean {
+  const data = (status as { data?: Record<string, unknown> } | null)?.data;
+  if (!data) return false;
+  return Boolean(data.connected ?? data.is_connected ?? data.installed ?? data.workspace ?? data.team ?? false);
+}
+
+export const TERMINAL_JOB_STATES = ["completed", "complete", "success", "succeeded", "failed", "error", "cancelled", "canceled"];

package/blocks/integrations/recipes/crm-sync-health.ts

@@ -0,0 +1,19 @@
+/**
+ * @title Check every CRM connection is healthy
+ * @when A scheduled health check or a status page. Reads only (no CRM writes). `connected: false` means the
+ * OAuth grant is gone: the human must reconnect it in the graph8 app, the API cannot do that.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function crmSyncHealth() {
+  const syncs = await g8.api.crmSyncs.listCrmSyncs();
+  const out: Array<{ provider: string; connected: boolean; lastSyncAt?: string | null }> = [];
+  for (const row of syncs.data ?? []) {
+    const provider = row.provider as "hubspot" | "salesforce" | "pipedrive" | "zoho" | "sugarcrm";
+    const status = await g8.api.crmSyncs.getCrmStatus({ path: { provider } });
+    out.push({ provider, connected: Boolean(status.data?.connected), lastSyncAt: status.data?.last_sync_at });
+  }
+  return out;
+}

package/blocks/integrations/recipes/push-contacts-to-crm.ts

@@ -0,0 +1,20 @@
+/**
+ * @title Push contacts to a connected CRM
+ * @when Sending graph8 contacts into HubSpot, Salesforce, Pipedrive, Zoho or SugarCRM. Tier `external`: it
+ * writes to the customer's CRM, so confirm the count with a human first. Discover valid field names with
+ * `getCrmFields` before building `records`; the result lists per-record `errors`.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Provider = "hubspot" | "salesforce" | "pipedrive" | "zoho" | "sugarcrm";
+
+export async function pushContacts(provider: Provider, records: Array<Record<string, unknown>>, humanApproved: boolean) {
+  if (!humanApproved) throw new Error(`Refusing to push ${records.length} contacts to ${provider} without approval`);
+  const status = await g8.api.crmSyncs.getCrmStatus({ path: { provider } });
+  if (!status.data?.connected) throw new Error(`${provider} is not connected: connect it in the graph8 app`);
+
+  const result = await g8.api.crmSyncs.pushContactsToCrm({ path: { provider }, body: { records } });
+  return { pushed: result.data?.pushed_count ?? 0, failed: result.data?.failed_count ?? 0, errors: result.data?.errors ?? [] };
+}

package/blocks/integrations/recipes/register-webhook.ts

@@ -0,0 +1,18 @@
+/**
+ * @title Subscribe a URL to graph8 events
+ * @when Wiring a server to graph8. Tier `external` (it changes where your data is sent): get a human OK for
+ * the URL and the event list first. The signing secret is returned ONCE: store it as G8_WEBHOOK_SECRET.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function registerWebhook(url: string, events: string[]) {
+  const available = await g8.api.webhooks.listWebhookEvents();
+  const known = new Set((available.data ?? []).map((e) => e.event));
+  const unknown = events.filter((e) => !known.has(e));
+  if (unknown.length) throw new Error(`Unknown events: ${unknown.join(", ")}`);
+
+  const created = await g8.api.webhooks.createWebhook({ body: { url, events, name: "app" } });
+  return { id: created.data?.id, secret: created.data?.secret };
+}

package/blocks/integrations/recipes/verify-webhook-route.ts

@@ -0,0 +1,33 @@
+/**
+ * @title Receive graph8 webhooks in a Next.js route and verify the signature
+ * @when After WebhookManager created a subscription. Copy the body of `POST` into
+ * `app/api/webhooks/graph8/route.ts`. Verify the RAW body BEFORE parsing; reject stale timestamps; the
+ * secret lives only in `G8_WEBHOOK_SECRET` on the server. Delivery is at least once: deduplicate on the id.
+ */
+import { g8, WebhookSignatureError } from "@graph8/sdk";
+
+const seen = new Set<string>();
+
+export async function POST(request: Request): Promise<Response> {
+  const raw = await request.text();
+  try {
+    const event = g8.webhooks.constructEvent(
+      raw,
+      request.headers.get("x-studio-signature") ?? "",
+      request.headers.get("x-studio-timestamp") ?? "",
+      process.env.G8_WEBHOOK_SECRET!,
+      { toleranceSeconds: 300 },
+    );
+    const id = String((event as { id?: unknown }).id ?? "");
+    if (id && seen.has(id)) return new Response(null, { status: 200 });
+    if (id) seen.add(id); // use a durable store in production
+    console.log("graph8 event", event.event);
+    return new Response(null, { status: 200 });
+  } catch (err) {
+    // Only a bad signature or stale timestamp is the sender's fault (400). Anything else is OUR failure:
+    // answer 5xx so graph8 retries the delivery instead of dropping it.
+    if (err instanceof WebhookSignatureError) return new Response("invalid signature", { status: 400 });
+    console.error("graph8 webhook handler failed", err);
+    return new Response("handler error", { status: 500 });
+  }
+}

package/blocks/intent/README.md

@@ -0,0 +1,57 @@
+# intent
+
+Track the keywords and competitor sites your market researches, see which accounts show buying intent,
+and score any account by strength and buying-committee coverage. The Apollo / 6sense "buyer intent" screen.
+
+Depends on: `crm` (account rows link to your company records). Install: `npx @graph8/sdk add intent`.
+
+## Components
+
+| Component | What it does | Tiers |
+|---|---|---|
+| `IntentKeywordManager` | Track keywords, preview and track a competitor domain, load the companies behind a keyword, stop tracking. | billable, destructive (all confirmed) |
+| `IntentFeed` | Accounts showing intent, strongest first. High-intent filter, keyword scope, paging, optional timed reload, "who visited this URL". | read |
+| `AccountIntentScore` | Intent badge + committee coverage for one or many accounts. | read |
+| `useAccountIntent` (hook) | The rollup for up to 500 company ids, for a table column. | read |
+
+## The flow, in order
+
+1. **Track something.** `IntentKeywordManager` -> `keywordsAdd` (plain keywords) or `keywordsCreateFromDomain`
+   with `dry_run: true` (preview), a human confirms, then `dry_run: false`. The response `keyword_id` is the
+   tracked keyword's id.
+2. **Wait for traffic.** There is no push: new accounts appear in the feed as visitors resolve. Reload with
+   the Refresh button or `refreshSeconds`.
+3. **Read the feed.** `IntentFeed` -> `listAbmCompanies` (`days`, `keyword_ids` from step 1, `page`, `limit`).
+   Each row's `company_id` is graph8's GLOBAL company id.
+4. **Score a company you already hold.** `AccountIntentScore` / `useAccountIntent` -> `rollupAbmCompanies`
+   with those global `company_id`s (not your CRM row ids). Companies with no signal are absent from the result.
+5. **Drill down.** `keywordCompanies` (billable, confirmed) lists the companies behind one keyword;
+   `urlCompanies` (free) lists who visited one page.
+
+## Prerequisites (the human or workspace must do these)
+
+- ABM intent enabled for the workspace (`where: "api"`): the feed and rollup answer 403 otherwise; the
+  components show a clear message instead of an empty table.
+- Something to measure: a tracked keyword/domain, or the tracking snippet (see the `visitors` block).
+
+## Defaults (do not ask the human)
+
+- Window: 30 days. Page size 25 (feed) / 50 (keywords).
+- Listing keywords is billable in the contract, so `IntentKeywordManager` asks first. Pass
+  `confirmListing={false}` only after you have confirmed your plan does not charge for it.
+- **Ask the human** which competitor domains to track. Never invent competitors.
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| `keywords_list_intent_keywords_list_post` | POST /intent/keywords/list | billable | IntentKeywordManager |
+| `keywords_add_intent_keywords_add_post` | POST /intent/keywords/add | billable | IntentKeywordManager |
+| `keywords_create_from_domain_intent_keywords_create_from_domain_post` | POST /intent/keywords/create-from-domain | billable | IntentKeywordManager |
+| `keyword_companies_intent_keywords__keyword_id__companies_post` | POST /intent/keywords/{keyword_id}/companies | billable | IntentKeywordManager |
+| `keywords_delete_intent_keywords__keyword_id__delete` | DELETE /intent/keywords/{keyword_id} | destructive | IntentKeywordManager |
+| `list_abm_companies_intent_abm_companies_get` | GET /intent/abm/companies | read | IntentFeed |
+| `url_companies_intent_url_companies_post` | POST /intent/url-companies | read | IntentFeed |
+| `rollup_abm_companies_intent_abm_rollup_post` | POST /intent/abm/rollup | read | AccountIntentScore, useAccountIntent |
+
+Recipes (`recipes/`): `track-competitor-domain.ts`, `rank-intent-accounts.ts`, `who-visited-url.ts`.

package/blocks/intent/block.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "intent",
+  "title": "Intent",
+  "summary": "Track keywords and competitor sites, see which accounts show buying intent, and score accounts by strength.",
+  "features": [
+    "tracked keywords and competitor domains",
+    "account intent feed with high-intent flag",
+    "account strength and buying-committee coverage",
+    "who visited this URL lookup"
+  ],
+  "dependsOn": [
+    "crm"
+  ],
+  "operations": [
+    "keywords_list_intent_keywords_list_post",
+    "keywords_add_intent_keywords_add_post",
+    "keywords_create_from_domain_intent_keywords_create_from_domain_post",
+    "keyword_companies_intent_keywords__keyword_id__companies_post",
+    "keywords_delete_intent_keywords__keyword_id__delete",
+    "list_abm_companies_intent_abm_companies_get",
+    "url_companies_intent_url_companies_post",
+    "rollup_abm_companies_intent_abm_rollup_post"
+  ],
+  "components": [
+    {
+      "name": "IntentKeywordManager",
+      "file": "components/intent-keyword-manager.tsx",
+      "purpose": "Add, preview, list and remove tracked keywords and competitor domains; load the companies behind a keyword. Every call is confirmed.",
+      "operations": [
+        "keywords_list_intent_keywords_list_post",
+        "keywords_add_intent_keywords_add_post",
+        "keywords_create_from_domain_intent_keywords_create_from_domain_post",
+        "keyword_companies_intent_keywords__keyword_id__companies_post",
+        "keywords_delete_intent_keywords__keyword_id__delete"
+      ],
+      "tiers": [
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "IntentFeed",
+      "file": "components/intent-feed.tsx",
+      "purpose": "Accounts showing intent, strongest first, with a high-intent filter, keyword scoping, paging and a who-visited-this-URL lookup.",
+      "operations": [
+        "list_abm_companies_intent_abm_companies_get",
+        "url_companies_intent_url_companies_post"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "AccountIntentScore",
+      "file": "components/account-intent-score.tsx",
+      "purpose": "Compact intent badge and buying-committee coverage for one or more accounts; drop into a company table or header.",
+      "operations": [
+        "rollup_abm_companies_intent_abm_rollup_post"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useAccountIntent",
+      "file": "hooks/use-account-intent.ts",
+      "purpose": "Fetch the ABM intent rollup for up to 500 company ids, for table columns.",
+      "operations": [
+        "rollup_abm_companies_intent_abm_rollup_post"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/intent-utils.ts",
+      "purpose": "Row types and envelope helpers shared by the intent components."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/track-competitor-domain.ts",
+      "title": "Track a competitor's website and read who visits it",
+      "when": "Starting competitor intent: preview, human approval, save, then list the interested companies."
+    },
+    {
+      "file": "recipes/rank-intent-accounts.ts",
+      "title": "Rank accounts by buying intent",
+      "when": "Building a who-to-call-today list from the ABM feed and rollup."
+    },
+    {
+      "file": "recipes/who-visited-url.ts",
+      "title": "List the companies whose people visited one URL",
+      "when": "Checking interest in a single page."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "abm-intent-enabled",
+      "description": "The ABM intent feature is enabled for the graph8 workspace (the feed and rollup return 403 otherwise).",
+      "where": "api",
+      "verify": "GET /intent/abm/companies?limit=1 returns 200, not 403."
+    },
+    {
+      "id": "tracking-live",
+      "description": "Intent needs data: at least one tracked keyword or domain, or the graph8 tracking snippet on your site.",
+      "where": "api",
+      "verify": "GET /intent/stats returns non-zero total_keywords or documents."
+    }
+  ],
+  "scopes": [
+    "intent:delete",
+    "intent:read",
+    "intent:run"
+  ],
+  "defaults": [
+    {
+      "decision": "Look-back window for the feed and rollups",
+      "default": "30 days",
+      "askHuman": false
+    },
+    {
+      "decision": "Confirm before listing tracked keywords",
+      "default": "Yes: the list call is billable in the contract (confirmListing)",
+      "askHuman": false
+    },
+    {
+      "decision": "Which competitor domains to track",
+      "default": "None: do not guess competitors",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}