@graph8/sdk 0.362.0 → 0.370.0

package/blocks/intent/components/intent-screen.tsx

@@ -0,0 +1,265 @@
+"use client";
+
+/**
+ * IntentScreen: the finished buyer-intent product page (Apollo / 6sense "intent"). Two tabs:
+ *   Accounts  accounts showing intent, strongest first (IntentFeed), a look-back window filter, a keyword scope chip,
+ *             and the selected account's detail panel (signals, trend, top keywords, buying-committee coverage).
+ *   Keywords  track keywords and competitor domains (IntentKeywordManager). Each keyword opens its complete detail screen
+ *             (KeywordDetail: fields, accounts showing intent for it, companies behind it, stop tracking; `?id=`).
+ * Every detail also opens as a full page with `?view=full`.
+ *
+ * User flows: see who is showing intent, filter to high intent, change the window, open an account (deep link
+ * `?id=<company id>`), read its buying committee, look up who visited a URL, track keywords, preview and track a
+ * competitor domain, list the companies behind a keyword, stop tracking (destructive, confirmed).
+ *
+ * SDK operations: none of its own. Composes IntentFeed (read), AccountIntentScore / useAccountIntent (read),
+ * IntentKeywordManager (billable + destructive, every call confirmed) and one read of listAbmCompanies for the stat strip.
+ * Prerequisite: ABM intent enabled for the workspace (a 403 is explained inline), and something to measure.
+ */
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { Radar, Tags, X } from "lucide-react";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import type { StatItem } from "@/g8/components/screen/stat-strip";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { BarList } from "@/g8/components/screen/bar-list";
+import { useAccountIntent } from "../hooks/use-account-intent";
+import { formatDate, rowsOf, totalOf } from "../lib/intent-utils";
+import type { AbmAccount, IntentKeywordRow } from "../lib/intent-utils";
+import { AccountIntentScore } from "./account-intent-score";
+import { IntentFeed } from "./intent-feed";
+import { IntentKeywordManager } from "./intent-keyword-manager";
+import { KeywordDetail } from "./keyword-detail";
+
+export interface IntentScreenProps {
+  /** Extra buttons for the toolbar (for example "Add to list" glue from another block). */
+  toolbarActions?: ReactNode;
+  /** Buttons shown in the account detail header. */
+  renderDetailActions?: (account: AbmAccount) => ReactNode;
+  /** Extra tabs in the account detail panel. */
+  extraDetailTabs?: { id: string; label: string; render: (account: AbmAccount) => ReactNode }[];
+  className?: string;
+}
+
+const WINDOWS = [7, 30, 90] as const;
+type Tab = "accounts" | "keywords";
+
+export function strengthTone(strength: string | null | undefined): "positive" | "warning" | "neutral" {
+  const s = (strength ?? "").toLowerCase();
+  if (s.includes("strong") || s === "high") return "positive";
+  if (s.includes("moderate") || s === "medium") return "warning";
+  return "neutral";
+}
+
+interface PanelProps {
+  onClose: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+}
+
+function AccountDetail({ account, panel, props }: { account: AbmAccount; panel: PanelProps; props: IntentScreenProps }) {
+  const name = account.company_name ?? account.company_domain ?? "Unknown company";
+  const keywords = (account.top_keywords ?? []).map((k) => ({ label: k.keyword ?? "keyword", value: k.signal_count ?? 0 }));
+  const trend = typeof account.trend_pct === "number" ? `${account.trend_pct > 0 ? "+" : ""}${Math.round(account.trend_pct)}%` : "No trend yet";
+  const tabs = [
+    {
+      id: "signals",
+      label: "Signals",
+      content: (
+        <div className="space-y-4">
+          <KeyValueList
+            columns={2}
+            items={[
+              { label: "Domain", value: account.company_domain ?? "-" },
+              { label: "Industry", value: account.industry ?? "-" },
+              { label: "Employees", value: account.employee_count ?? "-" },
+              { label: "Signals", value: account.total_signal_count ?? 0 },
+              { label: "Trend", value: trend },
+              { label: "Last signal", value: formatDate(account.latest_signal_date) },
+            ]}
+          />
+          <SectionCard title="Top keywords" description="Where this account's interest comes from.">
+            {keywords.length ? <BarList items={keywords} /> : <p className="text-sm text-muted-foreground">No keyword breakdown for this account.</p>}
+          </SectionCard>
+        </div>
+      ),
+    },
+    {
+      id: "committee",
+      label: "Buying committee",
+      content:
+        account.company_id != null ? (
+          <AccountIntentScore companyIds={[account.company_id]} />
+        ) : (
+          <p className="text-sm text-muted-foreground">This account has no company id to score.</p>
+        ),
+    },
+    ...(props.extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(account) })),
+  ];
+  return (
+    <DetailPanel
+      title={name}
+      subtitle={account.company_domain ?? undefined}
+      avatar={<EntityAvatar name={name} imageUrl={account.logo_url ?? undefined} kind="company" size="lg" />}
+      badges={
+        <>
+          <StatusPill tone={strengthTone(account.account_strength)}>{account.account_strength ?? "unscored"}</StatusPill>
+          {account.is_high_intent ? <StatusPill tone="negative" dot>High intent</StatusPill> : null}
+        </>
+      }
+      actions={props.renderDetailActions?.(account)}
+      tabs={tabs}
+      onClose={panel.onClose}
+      onExpand={panel.onExpand}
+      onCollapse={panel.onCollapse}
+    />
+  );
+}
+
+function useStats(days: number): { items: StatItem[] | undefined; loading: boolean } {
+  const q = useG8Query((signal) => g8Get("/intent/abm/companies", { days, page: 1, limit: 100 }, { signal }), [days]);
+  if (q.error || !q.data) return { items: undefined, loading: q.loading };
+  // The ABM payload is open-shaped in the contract: only report what the rows actually carry.
+  const rows = rowsOf<AbmAccount>(q.data);
+  const total = totalOf(q.data) ?? rows.length;
+  const items: StatItem[] = [{ label: "Accounts with intent", value: total.toLocaleString(), hint: `last ${days} days` }];
+  if (rows.some((r) => typeof r.is_high_intent === "boolean")) {
+    const high = rows.filter((r) => r.is_high_intent).length;
+    items.push({ label: "High intent", value: high, tone: high ? "negative" : "neutral", hint: "in the first 100" });
+  }
+  if (rows.some((r) => typeof r.account_strength === "string")) {
+    const strong = rows.filter((r) => strengthTone(r.account_strength) === "positive").length;
+    items.push({ label: "Strong accounts", value: strong, tone: strong ? "positive" : "neutral", hint: "in the first 100" });
+  }
+  return { loading: q.loading, items };
+}
+
+export function IntentScreen(props: IntentScreenProps) {
+  const [tab, setTab] = useUrlState("tab", "accounts");
+  const [id, setId] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const [days, setDays] = useState<number>(30);
+  const [selected, setSelected] = useState<AbmAccount | null>(null);
+  const [keyword, setKeyword] = useState<IntentKeywordRow | null>(null);
+  // `?kw=<keyword id>` scopes the account feed to one tracked keyword (chip in the toolbar).
+  const [scopeId, setScopeId] = useUrlState("kw", "");
+  const [scopeLabel, setScopeLabel] = useState<string | null>(null);
+  const [removed, setRemoved] = useState<string[]>([]);
+  const stats = useStats(days);
+  const active: Tab = tab === "keywords" ? "keywords" : "accounts";
+  const expanded = view === "full" && Boolean(id);
+  // A non-numeric `?id=` opens nothing instead of asking for account NaN.
+  const idNumber = id && Number.isFinite(Number(id)) ? Number(id) : null;
+  const deepLinked = useAccountIntent(active === "accounts" && idNumber != null && !selected ? [idNumber] : [], days);
+  const account = selected ?? (active === "accounts" && idNumber != null && deepLinked.rollups[id] ? { ...deepLinked.rollups[id], company_id: idNumber } : null);
+  // A deep-linked account with no signal in this window (or a bad id) gets a not-found state instead of a silent no-op.
+  const accountMissing = active === "accounts" && Boolean(id) && !account && (idNumber == null || (!deepLinked.loading && !deepLinked.error));
+  const accountFailed = active === "accounts" && Boolean(id) && !account && idNumber != null && Boolean(deepLinked.error);
+
+  const close = () => {
+    setSelected(null);
+    setKeyword(null);
+    setId("");
+    setView("");
+  };
+  const panel: PanelProps = {
+    onClose: close,
+    onExpand: expanded ? undefined : () => setView("full"),
+    onCollapse: expanded ? () => setView("") : undefined,
+  };
+  const showAccounts = (k: IntentKeywordRow) => {
+    close();
+    setScopeId(k.id);
+    setScopeLabel(k.keyword);
+    setTab("accounts");
+  };
+  const openAccount = (a: AbmAccount) => {
+    setTab("accounts");
+    setKeyword(null);
+    setSelected(a);
+    setId(String(a.company_id ?? ""));
+  };
+
+  return (
+    <ScreenLayout
+      title="Intent"
+      description="Accounts researching what you sell, and the keywords and competitors you track to find them."
+      icon={<Radar className="size-5" />}
+      actions={
+        <Button onClick={() => { setTab("keywords"); close(); }}>
+          <Tags className="mr-1.5 size-4" /> Track keywords
+        </Button>
+      }
+      tabs={[
+        { id: "accounts", label: "Accounts" },
+        { id: "keywords", label: "Keywords" },
+      ]}
+      activeTab={active}
+      onTabChange={(next) => {
+        setTab(next);
+        close();
+      }}
+      stats={active === "accounts" ? stats.items : undefined}
+      className={props.className}
+    >
+      {active === "accounts" ? (
+        <div className="space-y-3">
+          <Toolbar actions={props.toolbarActions}>
+            {scopeId ? (
+              <Button size="sm" variant="outline" aria-label={`Remove keyword scope ${scopeLabel ?? scopeId}`} onClick={() => { setScopeId(null); setScopeLabel(null); }}>
+                Keyword: {scopeLabel ?? scopeId} <X className="ml-1 size-3.5" aria-hidden />
+              </Button>
+            ) : null}
+            <div className="inline-flex gap-1" role="group" aria-label="Look-back window">
+              {WINDOWS.map((w) => (
+                <Button key={w} size="sm" variant={days === w ? "default" : "outline"} aria-pressed={days === w} onClick={() => setDays(w)}>
+                  {w} days
+                </Button>
+              ))}
+            </div>
+          </Toolbar>
+          <SplitView
+            detailOpen={Boolean(account) || accountMissing || accountFailed}
+            onCloseDetail={close}
+            expanded={expanded && Boolean(account)}
+            onExpandedChange={(next) => setView(next ? "full" : "")}
+            detailWidth="lg"
+            list={<IntentFeed key={scopeId || "all"} days={days} keywordIds={scopeId ? [scopeId] : undefined} onSelectAccount={openAccount} />}
+            detail={account ? (
+              <AccountDetail key={account.company_id ?? account.company_domain} account={account} panel={panel} props={props} />
+            ) : accountFailed ? (
+              <div className="space-y-3 p-4"><ApiError error={deepLinked.error} title="Could not load this account's intent" onRetry={() => void deepLinked.refetch()} /><Button size="sm" variant="outline" onClick={close}>Close</Button></div>
+            ) : accountMissing ? (
+              <div className="space-y-3 p-4"><EmptyState title="No intent for this account" description={`No buying-intent signal for this account in the last ${days} days. Try a longer window.`} /><Button size="sm" variant="outline" onClick={close}>Close</Button></div>
+            ) : null}
+          />
+        </div>
+      ) : (
+        <SplitView
+          detailOpen={Boolean(id)}
+          onCloseDetail={close}
+          expanded={expanded}
+          onExpandedChange={(next) => setView(next ? "full" : "")}
+          detailWidth="lg"
+          list={<IntentKeywordManager hiddenIds={removed} onSelectKeyword={(k) => { setKeyword(k); setId(k.id); }} />}
+          detail={id ? (
+            <KeywordDetail key={id} keywordId={id} keyword={keyword?.id === id ? keyword : null} onLoaded={setKeyword}
+              onSelectAccount={openAccount} onShowAccounts={showAccounts} onRemoved={(kid) => setRemoved((r) => [...r, kid])} {...panel} />
+          ) : null}
+        />
+      )}
+    </ScreenLayout>
+  );
+}

package/blocks/intent/components/keyword-detail.tsx

@@ -0,0 +1,124 @@
+"use client";
+
+/**
+ * KeywordDetail: the complete screen for one tracked keyword or competitor domain. Shows every field the list returns, the
+ * accounts currently showing intent for it (the intent feed scoped to this keyword), the companies resolved behind it, and the
+ * action to stop tracking. Pass the row from IntentKeywordManager; with only an id (a deep link) it offers to load the row.
+ *
+ * SDK operations, in order:
+ *   1. listAbmCompanies  GET    /intent/abm/companies?keyword_ids   (read; inside IntentFeed)
+ *   2. keywordsList      POST   /intent/keywords/list               (billable tier, confirmed; only to restore a row from an id)
+ *   3. keywordCompanies  POST   /intent/keywords/{id}/companies     (billable, confirmed)
+ *   4. keywordsDelete    DELETE /intent/keywords/{id}               (destructive, confirmed; 404 counts as done)
+ */
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Delete, g8Post } from "@/g8/lib/g8-client";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { rowsOf } from "../lib/intent-utils";
+import type { AbmAccount, IntentKeywordRow } from "../lib/intent-utils";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { AskButton, useConfirmAction } from "@/g8/components/confirmed-action";
+import { IntentFeed } from "./intent-feed";
+
+export interface KeywordDetailProps {
+  keywordId: string;
+  /** The row from the keyword list. Without it the screen can restore it after a confirmed list call. */
+  keyword?: IntentKeywordRow | null;
+  /** Called with the restored row. */
+  onLoaded?: (keyword: IntentKeywordRow) => void;
+  onSelectAccount?: (account: AbmAccount) => void;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  /** Called after the keyword was removed. */
+  onRemoved?: (keywordId: string) => void;
+  /** Shows a "Show accounts" button that scopes the account feed to this keyword. */
+  onShowAccounts?: (keyword: IntentKeywordRow) => void;
+}
+
+interface CompanyRow {
+  name?: string | null;
+  company_name?: string | null;
+  COMPANY_NAME?: string | null;
+  domain?: string | null;
+  company_domain?: string | null;
+  COMPANY_DOMAIN?: string | null;
+}
+const companyName = (c: CompanyRow) => c.name ?? c.company_name ?? c.COMPANY_NAME ?? c.domain ?? c.company_domain ?? c.COMPANY_DOMAIN ?? "Unknown";
+
+export function KeywordDetail({ keywordId, keyword, onLoaded, onSelectAccount, onClose, onExpand, onCollapse, onRemoved, onShowAccounts }: KeywordDetailProps) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const [companies, setCompanies] = useState<CompanyRow[] | null>(null);
+  const restore = useG8Mutation(async () => {
+    const found = rowsOf<IntentKeywordRow>(await g8Post("/intent/keywords/list", { page: 1, limit: 200 })).find((k) => k.id === keywordId);
+    if (found) onLoaded?.(found);
+    return found ?? null;
+  });
+
+  if (!keyword) {
+    return (
+      <div className="space-y-3 p-4">
+        {restore.data === null ? (
+          <EmptyState title="Keyword not found" description="It is no longer among your tracked keywords. It may have been removed." />
+        ) : (
+          <EmptyState title="Keyword details are not loaded" description="Listing tracked keywords is a billable read, so it asks first." />
+        )}
+        <div className="flex justify-center">
+          <AskButton ask={ask} label="Load keyword" tier="billable" title="Load tracked keywords" confirmLabel="Load keywords" description="Listing tracked keywords is classified billable by the API."
+            run={async () => { await restore.mutateAsync(undefined); }} />
+        </div>
+        {/* A failed load surfaces once, through the confirm hook's `failure`. */}
+        {failure ? <ApiError error={failure} title="That did not work" /> : null}
+        <ConfirmSpendDialog {...dialog} />
+      </div>
+    );
+  }
+
+  const actions = (
+    <div className="flex flex-wrap gap-1">
+      {onShowAccounts ? <Button size="sm" variant="outline" onClick={() => onShowAccounts(keyword)}>Show accounts</Button> : null}
+      <AskButton ask={ask} label="Load companies" tier="billable" title={`Load companies for "${keyword.keyword}"`} confirmLabel="Load companies" description="Resolves the companies behind this keyword's traffic."
+        run={async () => setCompanies(rowsOf<CompanyRow>(await g8Post(`/intent/keywords/${keyword.id}/companies`, { limit: 50, page: 1 })))} />
+      <AskButton ask={ask} label="Stop tracking" variant="ghost" tier="destructive" title={`Stop tracking "${keyword.keyword}"`} confirmLabel="Stop tracking" tolerateStatus={[404]}
+        description="The keyword is removed. Companies already saved to lists stay." run={() => g8Delete(`/intent/keywords/${keyword.id}`)} onDone={() => { onRemoved?.(keyword.id); onClose?.(); }} />
+    </div>
+  );
+  const tabs = [
+    {
+      id: "overview",
+      label: "Overview",
+      content: (
+        <div className="space-y-4">
+          <KeyValueList columns={2} items={[
+            { label: "Keyword", value: keyword.keyword },
+            { label: "Type", value: keyword.signal_type ?? "-" },
+            { label: "Companies resolved", value: keyword.total_resolved_companies ?? 0 },
+            { label: "People resolved", value: keyword.total_resolved_contacts ?? 0 },
+            { label: "Pages tracked", value: keyword.total_urls ?? "-" },
+            { label: "Auto sync", value: keyword.auto_sync_enabled == null ? "-" : keyword.auto_sync_enabled ? "on" : "off" },
+          ]} />
+          <SectionCard title="Companies behind this keyword" description="Loading them is billable, so it asks first (Load companies above).">
+            {companies == null ? <p className="text-sm text-muted-foreground">Not loaded yet.</p> : companies.length === 0 ? <p className="text-sm text-muted-foreground">No resolved companies yet.</p> : (
+              <ul className="grid gap-1 text-sm md:grid-cols-2">{companies.map((c, i) => <li key={i}>{companyName(c)}</li>)}</ul>
+            )}
+          </SectionCard>
+        </div>
+      ),
+    },
+    { id: "accounts", label: "Accounts showing intent", content: <IntentFeed keywordIds={[keyword.id]} onSelectAccount={onSelectAccount} /> },
+  ];
+  return (
+    <>
+      <DetailPanel title={keyword.keyword} subtitle="Tracked keyword" badges={<StatusPill tone={keyword.is_active === false ? "neutral" : "positive"}>{keyword.is_active === false ? "inactive" : "tracking"}</StatusPill>} actions={actions} tabs={tabs} onClose={onClose} onExpand={onExpand} onCollapse={onCollapse} />
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </>
+  );
+}

package/blocks/lifecycle/block.json

@@ -13,17 +13,18 @@
     "crm"
   ],
   "operations": [
-    "list_lifecycle_stages_lifecycle_stages_get",
+    "get_account_intent_signals_accounts__account_id__intent_signals_get",
+    "get_brief_customer_success_companies__company_id__brief_get",
+    "get_company_companies__company_id__get",
     "get_lifecycle_stage_counts_lifecycle_stages_counts_get",
+    "get_revenue_summary_accounts_revenue_summary_get",
+    "list_lifecycle_contacts_lifecycle_contacts_get",
     "list_lifecycle_stage_records_lifecycle_stages__stage__records_get",
+    "list_lifecycle_stages_lifecycle_stages_get",
     "move_company_lifecycle_stage_companies__company_id__lifecycle_stage_post",
     "move_contact_lifecycle_stage_contacts__contact_id__lifecycle_stage_post",
-    "list_lifecycle_contacts_lifecycle_contacts_get",
-    "unlock_lifecycle_contacts_lifecycle_contacts_unlock_post",
-    "get_revenue_summary_accounts_revenue_summary_get",
-    "get_brief_customer_success_companies__company_id__brief_get",
     "synthesize_brief_customer_success_companies__company_id__brief_synthesize_post",
-    "get_account_intent_signals_accounts__account_id__intent_signals_get"
+    "unlock_lifecycle_contacts_lifecycle_contacts_unlock_post"
   ],
   "components": [
     {
@@ -103,8 +104,12 @@
       "name": "LifecycleScreen",
       "file": "components/lifecycle-screen.tsx",
       "purpose": "Finished lifecycle product: board, one tab per stage (contact queue, customers, churned) and a CRM record panel with Move stage.",
-      "operations": [],
-      "tiers": []
+      "operations": [
+        "get_company_companies__company_id__get"
+      ],
+      "tiers": [
+        "read"
+      ]
     },
     {
       "name": "AccountBriefTab",

package/blocks/lifecycle/components/lifecycle-board.tsx

@@ -25,6 +25,7 @@ import { useLifecycleStages } from "../hooks/use-lifecycle-stages";
 import { asRec, body, money } from "../lib/lifecycle";
 import type { CompanyRecord, LifecycleStage } from "../lib/lifecycle";
 import { StageMoveDialog } from "./stage-move-dialog";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface LifecycleBoardProps {
   /** Open a company in your detail route (CompanyDetail from the crm block, for example). */
@@ -77,13 +78,14 @@ function Column({ stage, count, pageSize, version, onOpenCompany, onMove }: Colu
 }
 
 export function LifecycleBoard({ onOpenCompany, pageSize = 25, className }: LifecycleBoardProps) {
+  const brand = useBrand();
   const { stages, countOf, loading, error, refetch } = useLifecycleStages();
   const [moving, setMoving] = useState<{ record: CompanyRecord; stage: LifecycleStage } | null>(null);
   const [version, setVersion] = useState(0);
 
   if (loading) return <div className={className} aria-busy="true"><Skeleton className="h-48 w-full" /></div>;
   if (error) return <ApiError error={error} onRetry={() => void refetch()} />;
-  if (stages.length === 0) return <EmptyState title="No lifecycle stages" description="Stages are configured in graph8 under Revenue settings." />;
+  if (stages.length === 0) return <EmptyState title="No lifecycle stages" description={`Stages are configured in ${brand.linkLabel} under Revenue settings.`} />;
 
   return (
     <div className={className}>

package/blocks/lifecycle/components/lifecycle-screen.tsx

@@ -47,6 +47,7 @@ import { CustomerTable } from "./customer-table";
 import { LeadQueue } from "./lead-queue";
 import { LifecycleBoard } from "./lifecycle-board";
 import { StageMoveDialog } from "./stage-move-dialog";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface LifecycleScreenProps {
   /** Buttons next to "Move stage" in the record panel. */
@@ -78,6 +79,7 @@ function StageTab({ stage, version, onOpenCompany, onOpenContact }: { stage: Lif
 }
 
 export function LifecycleScreen({ renderDetailActions, extraDetailTabs, toolbarActions }: LifecycleScreenProps) {
+  const brand = useBrand();
   const { stages, countOf, loading, error, refetch } = useLifecycleStages();
   const [tabParam, setTab] = useUrlState("tab", "board");
   const [raw, setRaw] = useUrlState("rec");
@@ -123,7 +125,7 @@ export function LifecycleScreen({ renderDetailActions, extraDetailTabs, toolbarA
 
   let body: ReactNode;
   if (error) body = <ApiError error={error} title="Could not load lifecycle stages" onRetry={() => void refetch()} />;
-  else if (!loading && stages.length === 0) body = <EmptyState title="No lifecycle stages" description="Stages are configured in graph8 under Revenue settings." />;
+  else if (!loading && stages.length === 0) body = <EmptyState title="No lifecycle stages" description={`Stages are configured in ${brand.linkLabel} under Revenue settings.`} />;
   else if (activeStage) body = <StageTab stage={activeStage} version={version} onOpenCompany={openCompany} onOpenContact={openContact} />;
   else body = <LifecycleBoard key={version} onOpenCompany={openCompany} />;
 

package/blocks/lifecycle/lib/lifecycle.ts

@@ -85,7 +85,7 @@ export function money(cents: number | null | undefined, currency = "USD"): strin
 }
 
 export function contactName(c: ContactRecord): string {
-  return [c.first_name, c.last_name].filter(Boolean).join(" ") || "Unnamed contact";
+  return [c.first_name, c.last_name].filter(Boolean).join(" ") || (c.id != null ? `#${c.id}` : "-");
 }
 
 /** A masked field arrives as `"***"`; the real value needs an unlock (billable) or an enrichment. */

package/blocks/lists/README.md

@@ -6,6 +6,19 @@ It builds on the `crm` block (the members panel is a `ContactTable`).
 
 Install: `npx @graph8/sdk add lists` (installs `foundation` and `crm` first).
 
+## Screens
+
+Two finished pages. Mount one as a route with no props (`<ListsScreen />`); both take optional `toolbarActions`,
+`renderRowActions` and `renderDetailActions` slots for cross-block glue.
+
+| Screen | What it does |
+|---|---|
+| `ListsScreen` | Searchable, paged table of lists with member counts and build status; **New list** / Edit / Delete (confirmed) in a side sheet; open a list (`?id=`) for its Members tab (contacts, remove from list with confirmation), **Add contacts** from the CRM (conflicts shown, never auto-picked), **Refresh** for dynamic lists, **Check health**, and a Details tab. **Export** downloads a list as CSV or XLSX. `?view=full` opens a list or a suppressed contact full-page. Company lists show counts; the API has no read operation for company-list members, so they link out to the graph8 app. |
+| `SuppressionsScreen` | Do-not-contact ledger filtered by channel and reason; **Suppress contacts** by id or by ticking people from the CRM (default channel: all); check any contact id; open a row for the contact's record and live status; **Reinstate** (confirmed, lifts every suppression on the contact). |
+
+Prerequisites: `crm` installed (the CLI does it), proxy allowlist `lists` and `contacts`, key scopes `lists:read/write/delete`
+and `contacts:read/write`. The screens use the foundation screen kit (`components/screen/*`, `hooks/use-url-state`).
+
 ## What you get
 
 | Component | Use it for | Embed props |

package/blocks/lists/block.json

@@ -8,7 +8,8 @@
     "members panel built on the CRM ContactTable with remove-from-list",
     "ListPicker (search or create) and AddToListButton for any contact selection",
     "conflict review when contacts belong to other reps",
-    "suppression ledger by channel and reason, bulk suppress, check, reinstate"
+    "suppression ledger by channel and reason, bulk suppress, check, reinstate",
+    "finished ListsScreen and SuppressionsScreen pages"
   ],
   "dependsOn": [
     "crm"
@@ -20,6 +21,7 @@
     "check_list_integrity_lists__list_id__integrity_check_post",
     "create_list_lists_post",
     "delete_list_lists__list_id__delete",
+    "download_list_lists__audience_id__download_get",
     "list_contact_fields_fields_get",
     "list_contacts_contacts_get",
     "list_lists_lists_get",
@@ -90,6 +92,41 @@
         "read",
         "write"
       ]
+    },
+    {
+      "name": "ListsScreen",
+      "file": "components/lists-screen.tsx",
+      "purpose": "Finished Lists page: searchable table, create/edit/delete, member panel with add and remove, refresh and health check.",
+      "operations": [
+        "check_list_integrity_lists__list_id__integrity_check_post",
+        "create_list_lists_post",
+        "delete_list_lists__list_id__delete",
+        "download_list_lists__audience_id__download_get",
+        "list_lists_lists_get",
+        "refresh_dynamic_list_lists__audience_id__refresh_post",
+        "remove_contacts_from_list_lists__list_id__contacts_delete",
+        "update_list_lists__list_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "SuppressionsScreen",
+      "file": "components/suppressions-screen.tsx",
+      "purpose": "Finished do-not-contact page: filtered ledger, suppress by id or from the CRM, contact detail, confirmed reinstate.",
+      "operations": [
+        "bulk_add_suppressions_contacts_suppressions_bulk_add_post",
+        "check_contact_suppression_contacts__contact_id__suppression_get",
+        "list_suppressions_contacts_suppressions_get",
+        "reinstate_suppressions_contacts_suppressions_reinstate_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
     }
   ],
   "hooks": [],
@@ -161,6 +198,7 @@
     }
   ],
   "peerDependencies": {
+    "lucide-react": ">=0.400.0",
     "react": ">=18"
   }
 }

package/blocks/lists/components/add-to-list-button.tsx

@@ -21,6 +21,7 @@ import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogH
 import { ApiError } from "@/g8/components/api-error";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
 import { ListPicker } from "./list-picker";
 import type { ListSummary } from "./list-picker";
 
@@ -63,7 +64,7 @@ export function AddToListButton({ contactIds, listId, label = "Add to list", var
       ...(resolution ? { conflict_resolution: resolution } : {}),
     });
     return { listId: destination as number, added: res.data.added, already_member: res.data.already_member ?? [], not_found: res.data.not_found ?? [] };
-  }, { onSuccess: (r) => { setResult(r); onAdded?.(r); } });
+  }, { invalidates: [["lists"], ["contacts", "list"]], onSuccess: (r) => { setResult(r); onAdded?.(r); } });
 
   const conflict = conflictOf(add.error);
   const close = () => { setOpen(false); setResult(null); setTarget(null); add.reset(); };
@@ -74,7 +75,7 @@ export function AddToListButton({ contactIds, listId, label = "Add to list", var
       <Dialog open={open} onOpenChange={(o) => (o ? setOpen(true) : close())}>
         <DialogContent>
           <DialogHeader>
-            <DialogTitle>Add {contactIds.length.toLocaleString()} contact{contactIds.length === 1 ? "" : "s"} to a list</DialogTitle>
+            <DialogTitle>Add {plural(contactIds.length, "contact")} to a list</DialogTitle>
             <DialogDescription>Contacts already in the list are skipped.</DialogDescription>
           </DialogHeader>
 

package/blocks/lists/components/list-picker.tsx

@@ -31,6 +31,9 @@ export interface ListSummary {
   contact_count?: number | null;
   company_count?: number | null;
   is_dynamic?: boolean;
+  source?: string | null;
+  created_by?: string | null;
+  tags?: string[];
   created_at?: string | null;
   updated_at?: string | null;
 }
@@ -60,8 +63,9 @@ export function ListPicker({ value, onChange, type = "contacts", allowCreate = t
   const [search, setSearch] = useState("");
   const [newName, setNewName] = useState(suggestedName ?? "");
   const q = useDebounced(search.trim());
-  const lists = useG8Query((signal) => g8Get<ListSummary[]>("/lists", { search: q || undefined, limit: 50 }, { signal }), [q]);
+  const lists = useG8Query((signal) => g8Get<ListSummary[]>("/lists", { search: q || undefined, limit: 50 }, { signal }), [q], { key: ["lists", "picker", { q }] });
   const create = useG8Mutation((title: string) => g8Post<ListSummary>("/lists", { title, type }), {
+    invalidates: [["lists"]],
     onSuccess: (res) => { setNewName(""); void lists.refetch(); onChange({ type, ...res.data, title: res.data.title ?? newName }); },
   });