@graph8/sdk 0.303.0 → 0.357.0

package/blocks/lifecycle/components/customer-table.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+/**
+ * CustomerTable: the Customers stage as a book of business: headline counts, MRR per account, and an
+ * account brief (what the team knows about the customer) that can be rewritten with AI.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. getRevenueSummary           GET  /accounts/revenue-summary                          (read; bucket counts)
+ *   2. listLifecycleStages         GET  /lifecycle-stages                                  (read; resolves "customers")
+ *   3. listLifecycleStageRecords   GET  /lifecycle-stages/customers/records?page&limit     (read; name, MRR, subscription)
+ *   4. getBrief                    GET  /customer-success/companies/{company_id}/brief     (read; free)
+ *   5. synthesizeBrief             POST /customer-success/companies/{company_id}/brief/synthesize  (billable: runs a model)
+ *
+ * MRR on this screen is the sum of `mrr_cents` over the rows on the current page, not the whole book; the API
+ * has no total MRR field on this route, so the figure is labelled "this page".
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { g8Get, 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 { EmptyState } from "@/g8/components/empty-state";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { asRec, body, money, text } from "../lib/lifecycle";
+import type { CompanyRecord } from "../lib/lifecycle";
+
+export interface CustomerTableProps {
+  /** Stage slug to list. Defaults to "customers". */
+  stageSlug?: string;
+  onOpenCompany?: (companyId: number) => void;
+  pageSize?: number;
+  className?: string;
+}
+
+function Summary() {
+  const q = useG8Query((signal) => g8Get("/accounts/revenue-summary", undefined, { signal }), []);
+  const tiles = Object.entries(asRec(body(q.data))).filter(([, v]) => typeof v === "number") as Array<[string, number]>;
+  if (q.error || tiles.length === 0) return null;
+  return (
+    <div className="mb-4 grid grid-cols-2 gap-3 sm:grid-cols-4" data-testid="revenue-summary">
+      {tiles.map(([key, value]) => (
+        <Card key={key}><CardContent className="p-4"><div className="text-2xl font-semibold">{value.toLocaleString()}</div><div className="text-muted-foreground text-xs capitalize">{key.replace(/_count$/, "").replace(/_/g, " ")}</div></CardContent></Card>
+      ))}
+    </div>
+  );
+}
+
+function BriefSheet({ company, onClose }: { company: CompanyRecord; onClose: () => void }) {
+  const base = `/customer-success/companies/${company.company_id}/brief`;
+  const brief = useG8Query((signal) => g8Get(base, undefined, { signal }), [company.company_id]);
+  const [confirm, setConfirm] = useState(false);
+  const write = useG8Mutation(() => g8Post(`${base}/synthesize`), { onSuccess: () => { setConfirm(false); void brief.refetch(); } });
+  const b = asRec(body(brief.data));
+  return (
+    <Sheet open onOpenChange={(open) => { if (!open) onClose(); }}>
+      <SheetContent className="w-full overflow-y-auto sm:max-w-lg">
+        <SheetHeader>
+          <SheetTitle>{company.name ?? `Company ${company.company_id}`}</SheetTitle>
+          <SheetDescription>{[company.domain, money(company.mrr_cents) && `${money(company.mrr_cents)} MRR`].filter(Boolean).join(" · ")}</SheetDescription>
+        </SheetHeader>
+        <div className="space-y-3 px-4 pb-4 text-sm">
+          {brief.error ? <ApiError error={brief.error} onRetry={() => void brief.refetch()} /> : null}
+          {brief.loading && !brief.data ? <Skeleton className="h-24 w-full" /> : b.summary ? <p className="whitespace-pre-wrap" data-testid="brief-summary">{text(b.summary)}</p> : <p className="text-muted-foreground">No brief written yet.</p>}
+          {b.synthesized_at ? <p className="text-muted-foreground text-xs">Written {new Date(text(b.synthesized_at)).toLocaleDateString()}</p> : null}
+          {write.error ? <ApiError error={write.error} title="Could not write the brief" /> : null}
+          <Button variant="outline" onClick={() => setConfirm(true)}>{b.summary ? "Rewrite brief" : "Write brief"}</Button>
+        </div>
+        {confirm ? (
+          <ConfirmSpendDialog open tier="billable" title={`Write a brief for ${company.name ?? "this customer"}`} confirmLabel="Write brief" confirming={write.loading}
+            description="Reads everything known about the customer and writes a new brief with an AI model. This spends credits." onConfirm={() => void write.mutate(undefined)} onCancel={() => setConfirm(false)} />
+        ) : null}
+      </SheetContent>
+    </Sheet>
+  );
+}
+
+export function CustomerTable({ stageSlug = "customers", onOpenCompany, pageSize = 25, className }: CustomerTableProps) {
+  const [page, setPage] = useState(1);
+  const [open, setOpen] = useState<CompanyRecord | null>(null);
+  const list = useG8Query((signal) => g8Get(`/lifecycle-stages/${encodeURIComponent(stageSlug)}/records`, { page, limit: pageSize }, { signal }), [stageSlug, page, pageSize]);
+  const rows = (Array.isArray(body(list.data)) ? body(list.data) : []) as CompanyRecord[];
+  const pagination = asRec(asRec(list.data).pagination);
+  const total = typeof pagination.total === "number" ? pagination.total : rows.length;
+  const pageMrr = rows.reduce((sum, r) => sum + (r.mrr_cents ?? 0), 0);
+
+  return (
+    <div className={className}>
+      <Summary />
+      {list.error ? <ApiError error={list.error} onRetry={() => void list.refetch()} /> : null}
+      {list.loading && !list.data ? <div className="space-y-2" aria-busy="true">{[0, 1, 2].map((i) => <Skeleton key={i} className="h-10 w-full" />)}</div> : !list.error && rows.length === 0 ? (
+        <EmptyState title="No customers yet" description="Companies with an active subscription appear here." />
+      ) : (
+        <Table>
+          <TableHeader><TableRow><TableHead>Customer</TableHead><TableHead>Subscription</TableHead><TableHead className="text-right">MRR</TableHead><TableHead className="text-right">Actions</TableHead></TableRow></TableHeader>
+          <TableBody>
+            {rows.map((r) => (
+              <TableRow key={r.company_id}>
+                <TableCell><button type="button" className="font-medium hover:underline" onClick={() => onOpenCompany?.(r.company_id)}>{r.name || r.domain || `Company ${r.company_id}`}</button><div className="text-muted-foreground text-xs">{r.domain}</div></TableCell>
+                <TableCell className="capitalize">{text(r.subscription_status).replace(/_/g, " ")}</TableCell>
+                <TableCell className="text-right">{money(r.mrr_cents)}</TableCell>
+                <TableCell className="text-right"><Button size="sm" variant="outline" aria-label={`Brief for ${r.name ?? r.company_id}`} onClick={() => setOpen(r)}>Brief</Button></TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
+      <div className="mt-3 flex items-center justify-between text-sm">
+        <span className="text-muted-foreground">{total.toLocaleString()} customers · {money(pageMrr)} MRR this page</span>
+        <div className="flex gap-2">
+          <Button size="sm" variant="outline" disabled={page === 1} onClick={() => setPage(page - 1)}>Previous</Button>
+          <Button size="sm" variant="outline" disabled={page * pageSize >= total} onClick={() => setPage(page + 1)}>Next</Button>
+        </div>
+      </div>
+      {open ? <BriefSheet company={open} onClose={() => setOpen(null)} /> : null}
+    </div>
+  );
+}

package/blocks/lifecycle/components/lead-queue.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+/**
+ * LeadQueue: the contacts in one lifecycle stage (Leads by default) as a work queue, with search, unlock and move.
+ *
+ * Emails and phones of contacts you have not unlocked arrive masked as "***". Unlocking charges credits per
+ * NEWLY unlocked contact (already unlocked ones are free), so it goes through ConfirmSpendDialog; the credits
+ * actually charged are reported after the call because the API has no price quote or balance read.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. listLifecycleStages        GET  /lifecycle-stages                       (read; resolves the stage's entry id)
+ *   2. listLifecycleContacts      GET  /lifecycle-contacts?lifecycle_id&search&skip&limit  (read; masked PII)
+ *   3. unlockLifecycleContacts    POST /lifecycle-contacts/unlock { lifecycle_id, contact_ids }  (billable)
+ *   4. moveContactLifecycleStage  POST /contacts/{id}/lifecycle-stage          (write; via StageMoveDialog)
+ *
+ * `lifecycle_id` is the stage's ENTRY id (`id` in step 1), not its slug.
+ */
+
+import { useState } from "react";
+import { Button, Input, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { g8Get, 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 { EmptyState } from "@/g8/components/empty-state";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useDebounced } from "../hooks/use-debounced";
+import { useLifecycleStages } from "../hooks/use-lifecycle-stages";
+import { asRec, body, contactName, findStage, isMasked, text } from "../lib/lifecycle";
+import type { ContactRecord } from "../lib/lifecycle";
+import { StageMoveDialog } from "./stage-move-dialog";
+
+export interface LeadQueueProps {
+  /** Stage slug to list. Defaults to "leads". */
+  stageSlug?: string;
+  onOpenContact?: (contactId: number) => void;
+  pageSize?: number;
+  className?: string;
+}
+
+const show = (value: unknown, masked = "Locked") => (isMasked(value) ? masked : text(value, ""));
+
+export function LeadQueue({ stageSlug = "leads", onOpenContact, pageSize = 25, className }: LeadQueueProps) {
+  const { stages, loading: stagesLoading, error: stagesError } = useLifecycleStages();
+  const stage = findStage(stages, stageSlug);
+  const [search, setSearch] = useState("");
+  const debounced = useDebounced(search);
+  const [skip, setSkip] = useState(0);
+  const [picked, setPicked] = useState<number[]>([]);
+  const [confirm, setConfirm] = useState(false);
+  const [moving, setMoving] = useState<ContactRecord | null>(null);
+  const [charged, setCharged] = useState<string | null>(null);
+
+  const list = useG8Query(
+    (signal) => g8Get("/lifecycle-contacts", { lifecycle_id: stage?.id, search: debounced || undefined, skip, limit: pageSize }, { signal }),
+    [stage?.id, debounced, skip, pageSize],
+    { enabled: Boolean(stage) },
+  );
+  const unlock = useG8Mutation(
+    async (ids: number[]) => asRec(body(await g8Post("/lifecycle-contacts/unlock", { lifecycle_id: stage?.id, contact_ids: ids }))),
+    {
+      onSuccess: (r) => {
+        setConfirm(false);
+        setPicked([]);
+        setCharged(`Unlocked ${text(r.contact_count, "0")} contacts and charged ${text(r.credits_charged, "0")} credits.`);
+        void list.refetch();
+      },
+    },
+  );
+
+  const data = asRec(body(list.data));
+  const rows = (Array.isArray(data.contacts) ? data.contacts : []) as ContactRecord[];
+  const total = typeof data.total === "number" ? data.total : rows.length;
+  // Selection only ever holds contacts that are on screen: it is pruned when the page, search or stage changes.
+  const selected = picked.filter((id) => rows.some((r) => r.id === id));
+  const toggle = (id: number) => setPicked(picked.includes(id) ? picked.filter((p) => p !== id) : [...picked, id]);
+
+  if (stagesLoading) return <div className={className} aria-busy="true"><Skeleton className="h-32 w-full" /></div>;
+  if (stagesError) return <ApiError error={stagesError} />;
+  if (!stage) return <EmptyState title={`No "${stageSlug}" stage`} description="Check the stage slug against GET /lifecycle-stages." />;
+
+  return (
+    <div className={className}>
+      <div className="mb-3 flex flex-wrap items-center gap-2">
+        <Input aria-label="Search contacts" placeholder={`Search ${stage.name.toLowerCase()}`} value={search} onChange={(e) => { setSearch(e.target.value); setSkip(0); setPicked([]); setCharged(null); }} className="w-64" />
+        <Button className="ml-auto" disabled={selected.length === 0} onClick={() => setConfirm(true)}>Unlock selected ({selected.length})</Button>
+      </div>
+      {charged ? <p className="mb-2 text-sm" role="status">{charged}</p> : null}
+      {list.error ? <ApiError error={list.error} onRetry={() => void list.refetch()} /> : null}
+      {unlock.error ? <ApiError error={unlock.error} title="Could not unlock those contacts" /> : null}
+      {list.loading && !list.data ? <div className="space-y-2" aria-busy="true">{[0, 1, 2].map((i) => <Skeleton key={i} className="h-10 w-full" />)}</div> : !list.error && rows.length === 0 ? (
+        <EmptyState title={`No contacts in ${stage.name}`} description="Contacts appear here as they enter this stage." />
+      ) : (
+        <Table>
+          <TableHeader><TableRow><TableHead /><TableHead>Name</TableHead><TableHead>Title</TableHead><TableHead>Email</TableHead><TableHead className="text-right">Actions</TableHead></TableRow></TableHeader>
+          <TableBody>
+            {rows.map((c) => (
+              <TableRow key={c.id}>
+                <TableCell><input type="checkbox" aria-label={`Select ${contactName(c)}`} checked={picked.includes(c.id)} onChange={() => toggle(c.id)} /></TableCell>
+                <TableCell><button type="button" className="font-medium hover:underline" onClick={() => onOpenContact?.(c.id)}>{contactName(c)}</button><div className="text-muted-foreground text-xs">{text(c.company_name)}</div></TableCell>
+                <TableCell>{text(c.title)}</TableCell>
+                <TableCell>{show(c.email) || "No email"}</TableCell>
+                <TableCell className="text-right"><Button size="sm" variant="ghost" aria-label={`Move ${contactName(c)}`} onClick={() => setMoving(c)}>Move</Button></TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
+      <div className="mt-3 flex items-center justify-between text-sm">
+        <span className="text-muted-foreground">{total.toLocaleString()}{data.total_is_estimate ? "+" : ""} contacts</span>
+        <div className="flex gap-2">
+          <Button size="sm" variant="outline" disabled={skip === 0} onClick={() => { setSkip(Math.max(0, skip - pageSize)); setPicked([]); setCharged(null); }}>Previous</Button>
+          <Button size="sm" variant="outline" disabled={skip + pageSize >= total && !data.total_is_estimate} onClick={() => { setSkip(skip + pageSize); setPicked([]); setCharged(null); }}>Next</Button>
+        </div>
+      </div>
+      {confirm ? (
+        <ConfirmSpendDialog open tier="billable" title={`Unlock ${selected.length} contacts`} confirmLabel="Unlock" confirming={unlock.loading}
+          description="Charges credits for each contact that is not unlocked yet. Contacts you already unlocked cost nothing."
+          onConfirm={() => void unlock.mutate(selected)} onCancel={() => setConfirm(false)} />
+      ) : null}
+      {moving ? (
+        <StageMoveDialog kind="contact" recordId={moving.id} recordName={contactName(moving)} currentSlug={stage.slug} stages={stages}
+          onClose={() => setMoving(null)} onMoved={() => { setPicked(picked.filter((id) => id !== moving.id)); setMoving(null); void list.refetch(); }} />
+      ) : null}
+    </div>
+  );
+}

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

@@ -0,0 +1,102 @@
+"use client";
+
+/**
+ * LifecycleBoard: one column per lifecycle stage (Suspects, Leads, Trial, Customers, Churned, plus custom ones)
+ * with the companies in each, counts in the headers, and a Move action on every card.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. listLifecycleStages        GET /lifecycle-stages                      (read; columns, in display order)
+ *   2. getLifecycleStageCounts    GET /lifecycle-stages/counts               (read; keyed by stage ENTRY ID)
+ *   3. listLifecycleStageRecords  GET /lifecycle-stages/{slug}/records?page&limit  (read; one call per column)
+ *   4. moveCompanyLifecycleStage  POST /companies/{company_id}/lifecycle-stage (write; via StageMoveDialog, dry run first)
+ *
+ * Nothing here is billable, external or destructive. The `company_id` on each record is the id to pass to your
+ * company detail route (`onOpenCompany`) and to the move call; it is `mashup_companies.id`, the same id
+ * `GET /companies/{id}` takes.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Skeleton } from "@graph8/sdk/ui";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+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";
+
+export interface LifecycleBoardProps {
+  /** Open a company in your detail route (CompanyDetail from the crm block, for example). */
+  onOpenCompany?: (companyId: number) => void;
+  /** Cards loaded per column; "Show more" adds this many (API maximum 200 per column). */
+  pageSize?: number;
+  className?: string;
+}
+
+interface ColumnProps {
+  stage: LifecycleStage;
+  count?: number;
+  pageSize: number;
+  version: number;
+  onOpenCompany?: (id: number) => void;
+  onMove: (record: CompanyRecord, stage: LifecycleStage) => void;
+}
+
+function Column({ stage, count, pageSize, version, onOpenCompany, onMove }: ColumnProps) {
+  const [limit, setLimit] = useState(pageSize);
+  const q = useG8Query(
+    (signal) => g8Get(`/lifecycle-stages/${encodeURIComponent(stage.slug)}/records`, { page: 1, limit }, { signal }),
+    [stage.slug, limit, version],
+  );
+  const rows = (Array.isArray(body(q.data)) ? body(q.data) : []) as CompanyRecord[];
+  const total = (asRec(asRec(q.data).pagination).total as number | undefined) ?? count ?? rows.length;
+  return (
+    <Card className="w-72 shrink-0" data-testid={`column-${stage.slug}`}>
+      <CardHeader>
+        <CardTitle className="text-sm">{stage.name} <span className="text-muted-foreground font-normal">{count ?? total}</span></CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-2">
+        {q.error ? <ApiError error={q.error} onRetry={() => void q.refetch()} /> : null}
+        {q.loading && !q.data ? <><Skeleton className="h-14 w-full" /><Skeleton className="h-14 w-full" /></> : null}
+        {!q.loading && !q.error && rows.length === 0 ? <EmptyState title="Nobody here" description={stage.description ?? undefined} className="py-4" /> : null}
+        {rows.map((r) => (
+          <div key={r.company_id} className="rounded-md border p-2 text-sm">
+            <button type="button" className="text-left font-medium hover:underline" onClick={() => onOpenCompany?.(r.company_id)}>{r.name || r.domain || `Company ${r.company_id}`}</button>
+            <div className="text-muted-foreground text-xs">{[r.domain, r.industry].filter(Boolean).join(" · ")}</div>
+            <div className="mt-1 flex items-center justify-between">
+              <span className="text-xs">{money(r.mrr_cents)}</span>
+              <Button size="sm" variant="ghost" aria-label={`Move ${r.name ?? r.company_id}`} onClick={() => onMove(r, stage)}>Move</Button>
+            </div>
+          </div>
+        ))}
+        {rows.length < total && limit < 200 ? <Button size="sm" variant="outline" className="w-full" loading={q.loading} onClick={() => setLimit(Math.min(200, limit + pageSize))}>Show more</Button> : null}
+      </CardContent>
+    </Card>
+  );
+}
+
+export function LifecycleBoard({ onOpenCompany, pageSize = 25, className }: LifecycleBoardProps) {
+  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." />;
+
+  return (
+    <div className={className}>
+      <div className="flex gap-3 overflow-x-auto pb-2">
+        {stages.map((s) => (
+          <Column key={s.id} stage={s} count={countOf(s)} pageSize={pageSize} version={version} onOpenCompany={onOpenCompany} onMove={(record, stage) => setMoving({ record, stage })} />
+        ))}
+      </div>
+      {moving ? (
+        <StageMoveDialog kind="company" recordId={moving.record.company_id} recordName={moving.record.name ?? `company ${moving.record.company_id}`}
+          currentSlug={moving.stage.slug} stages={stages} onClose={() => setMoving(null)}
+          onMoved={() => { setMoving(null); setVersion((v) => v + 1); void refetch(); }} />
+      ) : null}
+    </div>
+  );
+}

package/blocks/lifecycle/components/stage-move-dialog.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+/**
+ * StageMoveDialog: move one company or contact to another lifecycle stage.
+ *
+ * SDK operations, in the order the dialog uses them:
+ *   1. moveCompanyLifecycleStage  POST /companies/{id}/lifecycle-stage  { target_slug, dry_run: true }  (write; the check)
+ *   2. moveCompanyLifecycleStage  POST /companies/{id}/lifecycle-stage  { target_slug }                  (write; the move)
+ *   or moveContactLifecycleStage  POST /contacts/{id}/lifecycle-stage   { target_slug }                  (write; no dry run)
+ *
+ * Moves are plain writes (reversible by moving back), so there is no spend confirmation. Companies get a dry run
+ * first because the API refuses some moves: to Customers without an active subscription, and to Churned for a
+ * company that never was a customer. The refusal is shown as-is instead of failing after the person clicked Move.
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from "@graph8/sdk/ui";
+import { g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ApiError } from "@/g8/components/api-error";
+import { body, describeMove } from "../lib/lifecycle";
+import type { LifecycleStage, MoveResult } from "../lib/lifecycle";
+
+export interface StageMoveDialogProps {
+  kind: "company" | "contact";
+  /** `company_id` of a stage record, or the contact id. */
+  recordId: number;
+  recordName: string;
+  /** Slug the record is in now; hidden from the choices. */
+  currentSlug?: string;
+  stages: LifecycleStage[];
+  /** Pre-select a destination (for example "leads" for a win-back). */
+  defaultTargetSlug?: string;
+  onMoved: (result: MoveResult) => void;
+  onClose: () => void;
+}
+
+export function StageMoveDialog(props: StageMoveDialogProps) {
+  const { kind, recordId, recordName, currentSlug, stages, onMoved, onClose } = props;
+  const choices = stages.filter((s) => s.slug !== currentSlug);
+  const [target, setTarget] = useState(props.defaultTargetSlug ?? choices[0]?.slug ?? "");
+  const [checked, setChecked] = useState<{ slug: string; result: MoveResult } | null>(null);
+  const path = `/${kind === "company" ? "companies" : "contacts"}/${recordId}/lifecycle-stage`;
+
+  const check = useG8Mutation(async (slug: string) => body(await g8Post(path, { target_slug: slug, dry_run: true })) as MoveResult, { onSuccess: (r, slug) => setChecked({ slug, result: r }) });
+  const move = useG8Mutation(async (slug: string) => body(await g8Post(path, { target_slug: slug })) as MoveResult, { onSuccess: (r, slug) => onMoved({ ...r, target_slug: r.target_slug ?? slug }) });
+  const error = check.error ?? move.error;
+  const needsCheck = kind === "company" && checked?.slug !== target;
+
+  return (
+    <Dialog open onOpenChange={(open) => { if (!open) onClose(); }}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Move {recordName}</DialogTitle>
+          <DialogDescription>Choose the stage this {kind} belongs in now.</DialogDescription>
+        </DialogHeader>
+        <label htmlFor="move-target" className="text-sm font-medium">New stage</label>
+        <select id="move-target" value={target} onChange={(e) => { setTarget(e.target.value); setChecked(null); check.reset(); move.reset(); }}
+          className="border-input bg-background h-9 w-full rounded-md border px-2 text-sm">
+          {choices.map((s) => <option key={s.id} value={s.slug}>{s.name}</option>)}
+        </select>
+        {checked && !needsCheck ? <p className="text-sm" data-testid="move-preview">This will change: {describeMove(checked.result)}</p> : null}
+        {error ? <ApiError error={error} title="That move is not allowed" /> : null}
+        <DialogFooter>
+          <Button variant="outline" onClick={onClose}>Cancel</Button>
+          {needsCheck ? (
+            <Button disabled={!target} loading={check.loading} onClick={() => void check.mutate(target)}>Check move</Button>
+          ) : (
+            <Button disabled={!target} loading={move.loading} onClick={() => void move.mutate(target)}>Move</Button>
+          )}
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/blocks/lifecycle/hooks/use-debounced.ts

@@ -0,0 +1,13 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/** The value, `ms` after it stopped changing. Search boxes use it so each keystroke is not a request. */
+export function useDebounced<T>(value: T, ms = 300): T {
+  const [settled, setSettled] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setSettled(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return settled;
+}

package/blocks/lifecycle/hooks/use-lifecycle-stages.ts

@@ -0,0 +1,27 @@
+"use client";
+
+/**
+ * useLifecycleStages: the configured stages and their company counts.
+ *
+ * SDK operations, in order: listLifecycleStages (GET /lifecycle-stages, read), getLifecycleStageCounts
+ * (GET /lifecycle-stages/counts, read; keyed by stage id). Both are free; counts are company-only.
+ */
+
+import { useMemo } from "react";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { countFor, stagesOf } from "../lib/lifecycle";
+import type { LifecycleStage } from "../lib/lifecycle";
+
+export function useLifecycleStages() {
+  const stagesQ = useG8Query((signal) => g8Get("/lifecycle-stages", undefined, { signal }), []);
+  const countsQ = useG8Query((signal) => g8Get("/lifecycle-stages/counts", undefined, { signal }), []);
+  const stages = useMemo<LifecycleStage[]>(() => stagesOf(stagesQ.data), [stagesQ.data]);
+  return {
+    stages,
+    countOf: (stage: LifecycleStage) => countFor(countsQ.data, stage),
+    loading: stagesQ.loading && !stagesQ.data,
+    error: stagesQ.error,
+    refetch: () => Promise.all([stagesQ.refetch(), countsQ.refetch()]),
+  };
+}

package/blocks/lifecycle/lib/lifecycle.ts

@@ -0,0 +1,99 @@
+"use client";
+
+/**
+ * Types and helpers for the revenue lifecycle (Suspects, Leads, Trial, Customers, Churned, plus any custom stage).
+ *
+ * Two things are easy to get wrong and are handled here:
+ *  - `GET /lifecycle-stages/counts` is keyed by stage ENTRY ID, not slug; `countFor` resolves it.
+ *  - Money is in cents (`mrr_cents`); `money` formats it and never shows a fake zero for an unknown value.
+ */
+
+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 }` when present (most routes), otherwise the object itself. */
+export function body(res: unknown): unknown {
+  const r = asRec(res);
+  return "data" in r ? r.data : res;
+}
+
+export interface LifecycleStage {
+  id: string;
+  slug: string;
+  name: string;
+  sort_order: number;
+  hidden: boolean;
+  description?: string | null;
+}
+
+export interface CompanyRecord {
+  company_id: number;
+  name?: string | null;
+  domain?: string | null;
+  industry?: string | null;
+  status?: string | null;
+  custom_status?: string | null;
+  subscription_status?: string | null;
+  owner_id?: string | null;
+  mrr_cents?: number | null;
+}
+
+export interface ContactRecord {
+  id: number;
+  first_name?: string | null;
+  last_name?: string | null;
+  email?: string | null;
+  title?: string | null;
+  company_name?: string | null;
+}
+
+export interface MoveResult {
+  target_slug: string;
+  previous_status?: string | null;
+  new_status?: string | null;
+  previous_custom_status?: string | null;
+  new_custom_status?: string | null;
+  dry_run?: boolean;
+}
+
+export function stagesOf(res: unknown): LifecycleStage[] {
+  const rows = body(res);
+  return (Array.isArray(rows) ? (rows as LifecycleStage[]) : []).filter((s) => !s.hidden).sort((a, b) => a.sort_order - b.sort_order);
+}
+
+export function countFor(counts: unknown, stage: LifecycleStage): number | undefined {
+  const value = asRec(body(counts))[stage.id];
+  return typeof value === "number" ? value : undefined;
+}
+
+/** A stage by slug, falling back to a case-insensitive name match ("Trial" is slug `trials`). */
+export function findStage(stages: LifecycleStage[], slugOrName: string): LifecycleStage | undefined {
+  const needle = slugOrName.trim().toLowerCase();
+  return stages.find((s) => s.slug.toLowerCase() === needle) ?? stages.find((s) => s.name.toLowerCase() === needle);
+}
+
+export function money(cents: number | null | undefined, currency = "USD"): string {
+  if (typeof cents !== "number") return "";
+  return (cents / 100).toLocaleString(undefined, { style: "currency", currency, maximumFractionDigits: 0 });
+}
+
+export function contactName(c: ContactRecord): string {
+  return [c.first_name, c.last_name].filter(Boolean).join(" ") || "Unnamed contact";
+}
+
+/** A masked field arrives as `"***"`; the real value needs an unlock (billable) or an enrichment. */
+export const isMasked = (value: unknown): boolean => value === "***";
+
+/** Describe a stage move for a confirmation line: "customers: status trial -> active". */
+export function describeMove(m: MoveResult): string {
+  const from = m.previous_status ?? m.previous_custom_status;
+  const to = m.new_status ?? m.new_custom_status;
+  return from || to ? `${m.target_slug}: ${from ?? "none"} -> ${to ?? "none"}` : m.target_slug;
+}

package/blocks/lifecycle/recipes/customer-brief.ts

@@ -0,0 +1,23 @@
+/**
+ * @title Read a customer's brief, and rewrite it when it is stale
+ * @when Before a renewal or a check-in call. Reading is free. Rewriting runs an AI model over everything known about
+ * the customer and spends credits (billable tier), so only rewrite when the brief is missing or old and the person
+ * agreed. `company_id` is the id from a lifecycle stage record.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Brief = { summary?: string | null; synthesized_at?: string | null };
+
+export async function customerBrief(companyId: number, rewriteIfOlderThanDays?: number): Promise<string> {
+  const read = async () => ((await g8.api.customerSuccess.getBrief({ path: { company_id: String(companyId) } })).data ?? {}) as Brief;
+  let brief = await read();
+
+  const ageDays = brief.synthesized_at ? (Date.now() - Date.parse(brief.synthesized_at)) / 86_400_000 : Infinity;
+  if (rewriteIfOlderThanDays !== undefined && ageDays > rewriteIfOlderThanDays) {
+    await g8.api.customerSuccess.synthesizeBrief({ path: { company_id: String(companyId) } });
+    brief = await read();
+  }
+  return brief.summary ?? "No brief yet";
+}

package/blocks/lifecycle/recipes/move-company-stage.ts

@@ -0,0 +1,17 @@
+/**
+ * @title Move a company to another lifecycle stage, checking first
+ * @when A company should change stage (qualified lead, customer, churned, win-back). Always run the dry run first:
+ * the API refuses a move to Customers without an active subscription and a move to Churned for a company that never
+ * was a customer, and the dry run reports that without writing anything. The id is `company_id` from a stage record.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function moveCompany(companyId: number, targetSlug: string): Promise<string> {
+  const check = await g8.api.revenueLifecycle.moveCompanyLifecycleStage({ path: { company_id: companyId }, body: { target_slug: targetSlug, dry_run: true } });
+  console.log(`would change: ${check.data.previous_status ?? "none"} -> ${check.data.new_status ?? "none"}`);
+
+  const done = await g8.api.revenueLifecycle.moveCompanyLifecycleStage({ path: { company_id: companyId }, body: { target_slug: targetSlug } });
+  return `${done.data.target_slug}: ${done.data.previous_status ?? "none"} -> ${done.data.new_status ?? "none"}`;
+}

package/blocks/lifecycle/recipes/read-lifecycle-board.ts

@@ -0,0 +1,21 @@
+/**
+ * @title Read the lifecycle board: stages, counts and who is in each
+ * @when The customer wants to see (or report on) Suspects / Leads / Trial / Customers / Churned. All three calls are
+ * free. Counts are keyed by stage ENTRY ID, not slug, so join them to the stage list before showing a name.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function readBoard(perStage = 25): Promise<Array<{ stage: string; count: number | undefined; companies: string[] }>> {
+  const stages = (await g8.api.revenueLifecycle.listLifecycleStages({})).data.filter((s) => !s.hidden);
+  const counts = (await g8.api.revenueLifecycle.getLifecycleStageCounts({})).data;
+
+  const board = [];
+  for (const stage of stages.sort((a, b) => a.sort_order - b.sort_order)) {
+    // The path takes the slug (or the entry id); `limit` is capped at 200 and pages are 1-indexed.
+    const records = await g8.api.revenueLifecycle.listLifecycleStageRecords({ path: { stage: stage.slug }, query: { page: 1, limit: perStage } });
+    board.push({ stage: stage.name, count: counts[stage.id], companies: records.data.map((r) => r.name ?? r.domain ?? String(r.company_id)) });
+  }
+  return board;
+}