@graph8/sdk 0.358.0 → 0.362.0

package/blocks/lifecycle/components/account-related.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+/**
+ * Account views for the lifecycle record panel: the customer-success brief and recent intent signals.
+ *
+ * SDK operations, in order:
+ *   AccountBriefTab:   GET  /customer-success/companies/{id}/brief              (lifecycle.getBrief)         read, free
+ *                      POST /customer-success/companies/{id}/brief/synthesize   (lifecycle.synthesizeBrief)  BILLABLE -> ConfirmSpendDialog
+ *   AccountSignalsTab: GET  /accounts/{id}/intent-signals?limit                  (lifecycle.getAccountIntentSignals) read
+ * The company id is the account id on these revenue routes.
+ */
+import { useState } from "react";
+import { Radar } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { asRec, body, text } from "../lib/lifecycle";
+
+export function AccountBriefTab({ companyId, name }: { companyId: number; name?: string | null }) {
+  const base = `/customer-success/companies/${companyId}/brief`;
+  const brief = useG8Query((signal) => g8Get(base, undefined, { signal }), [companyId]);
+  const [confirm, setConfirm] = useState(false);
+  const write = useG8Mutation(() => g8Post(`${base}/synthesize`), { onSuccess: () => { setConfirm(false); void brief.refetch(); } });
+  const b = asRec(body(brief.data));
+  if (brief.error) return <ApiError error={brief.error} title="Could not load the brief" onRetry={() => void brief.refetch()} />;
+  if (brief.loading && !brief.data) return <Skeleton className="h-24 w-full" aria-label="Loading brief" />;
+  return (
+    <SectionCard title="Account brief" description="What the team knows about this customer, in one place." actions={<Button size="sm" variant="outline" onClick={() => setConfirm(true)}>{b.summary ? "Rewrite brief" : "Write brief"}</Button>}>
+      {b.summary ? <p className="whitespace-pre-wrap text-sm" data-testid="brief-summary">{text(b.summary)}</p> : <p className="text-sm text-muted-foreground">No brief written yet.</p>}
+      {b.synthesized_at ? <p className="mt-2 text-xs text-muted-foreground">Written <time dateTime={text(b.synthesized_at)}>{new Date(text(b.synthesized_at)).toLocaleDateString()}</time></p> : null}
+      {write.error ? <ApiError error={write.error} title="Could not write the brief" /> : null}
+      {confirm ? (
+        <ConfirmSpendDialog open tier="billable" title={`Write a brief for ${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}
+    </SectionCard>
+  );
+}
+
+export function AccountSignalsTab({ companyId }: { companyId: number }) {
+  const q = useG8Query((signal) => g8Get(`/accounts/${companyId}/intent-signals`, { limit: 20 }, { signal }), [companyId]);
+  if (q.error) return <ApiError error={q.error} title="Could not load signals" onRetry={() => void q.refetch()} />;
+  if (q.loading && !q.data) return <Skeleton className="h-24 w-full" aria-label="Loading signals" />;
+  const payload = body(q.data);
+  const raw = Array.isArray(payload) ? payload : Array.isArray(asRec(payload).signals) ? (asRec(payload).signals as unknown[]) : [];
+  const signals = raw.map(asRec);
+  if (signals.length === 0) return <EmptyState icon={<Radar className="size-8" />} title="Quiet" description="No recent buying or activity signals for this account." />;
+  return (
+    <ul className="divide-y rounded-md border" aria-label="Signals">
+      {signals.map((s, i) => {
+        const when = text(s.detected_at ?? s.created_at ?? s.occurred_at);
+        return (
+          <li key={text(s.id, String(i))} className="flex items-center justify-between gap-3 p-3 text-sm">
+            <span className="min-w-0 truncate">{text(s.title ?? s.signal ?? s.signal_type ?? s.type ?? s.name, "Signal")}</span>
+            {when ? <time className="shrink-0 text-xs text-muted-foreground" dateTime={when} title={new Date(when).toLocaleString()}>{new Date(when).toLocaleDateString()}</time> : null}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}

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

@@ -0,0 +1,147 @@
+"use client";
+
+/**
+ * LifecycleScreen: the finished revenue-lifecycle product. One screen for Suspects, Leads, Trial, Customers and
+ * Churned (and any custom stage): the board, each stage's working list, and a record panel. No props are required.
+ *
+ * It composes: LifecycleBoard (columns with counts and Move), LeadQueue (contacts of a stage: search, billable
+ * unlock, move), CustomerTable (MRR, headline counts, AI account brief), ChurnList (last MRR, activity check,
+ * win-back), StageMoveDialog, and the crm block's CompanyDetail and ContactDetail for the open record.
+ *
+ * Flows:
+ *   - Headline numbers: how many companies sit in every stage.
+ *   - Board tab: move a company between stages (a dry run shows refusals first, for example Customers without an
+ *     active subscription). One tab per stage after it: Customers shows the book of business with an account brief
+ *     (rewriting it uses credits, confirmed); Churned shows lost revenue and a win-back to Leads; every other stage
+ *     is a contact queue where locked emails can be unlocked (credits, confirmed).
+ *   - Open a company or contact (deep link ?rec=company:<id> or ?rec=contact:<id>, full page with &view=full) -> the
+ *     full CRM record (activity, notes, tasks, edit) with a Move stage action; a company also gets Brief (rewrite
+ *     uses credits, confirmed) and Signals tabs. Leads are the contacts of a stage, customers and churned are companies.
+ *
+ * SDK operations (through the composed parts): listLifecycleStages, getLifecycleStageCounts,
+ * listLifecycleStageRecords, moveCompanyLifecycleStage (dry run first), moveContactLifecycleStage,
+ * listLifecycleContacts, unlockLifecycleContacts (billable), getRevenueSummary, getBrief, synthesizeBrief
+ * (billable), getAccountIntentSignals, plus the crm block's getCompany / getContact.
+ *
+ * Slots (all optional): renderDetailActions, extraDetailTabs, toolbarActions.
+ */
+import { useState, type ReactNode } from "react";
+import { GitBranch } from "lucide-react";
+import { Button } from "@graph8/sdk/ui";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { CompanyDetail } from "@/g8/crm/components/company-detail";
+import { ContactDetail } from "@/g8/crm/components/contact-detail";
+import type { CompanyRecord as CrmCompany, ContactRecord as CrmContact } from "@/g8/crm/lib/crm-types";
+import { useLifecycleStages } from "../hooks/use-lifecycle-stages";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import type { LifecycleStage } from "../lib/lifecycle";
+import { AccountBriefTab, AccountSignalsTab } from "./account-related";
+import { ChurnList } from "./churn-list";
+import { CustomerTable } from "./customer-table";
+import { LeadQueue } from "./lead-queue";
+import { LifecycleBoard } from "./lifecycle-board";
+import { StageMoveDialog } from "./stage-move-dialog";
+
+export interface LifecycleScreenProps {
+  /** Buttons next to "Move stage" in the record panel. */
+  renderDetailActions?: (record: { kind: "company" | "contact"; id: number }) => ReactNode;
+  /** Extra tabs in the record panel (for example Deals or Quotes for a company). */
+  extraDetailTabs?: Array<{ id: string; label: string; render: (record: { kind: "company" | "contact"; id: number }) => ReactNode }>;
+  toolbarActions?: ReactNode;
+}
+
+type OpenRecord = { kind: "company" | "contact"; id: number };
+
+function parseRecord(raw: string | null | undefined): OpenRecord | null {
+  const [kind, id] = (raw ?? "").split(":");
+  const n = Number(id);
+  return (kind === "company" || kind === "contact") && Number.isInteger(n) && n > 0 ? { kind, id: n } : null;
+}
+
+/** The brief tab, named after the company so the billable confirm says which customer it writes for. */
+function CompanyBrief({ companyId }: { companyId: number }) {
+  const company = useG8Query((signal) => g8Get<CrmCompany>(`/companies/${companyId}`, undefined, { signal }), [companyId]);
+  const name = company.data?.data?.name ?? null;
+  return <AccountBriefTab companyId={companyId} name={name} />;
+}
+
+function StageTab({ stage, version, onOpenCompany, onOpenContact }: { stage: LifecycleStage; version: number; onOpenCompany: (id: number) => void; onOpenContact: (id: number) => void }) {
+  if (stage.slug === "customers") return <CustomerTable key={version} stageSlug={stage.slug} onOpenCompany={onOpenCompany} />;
+  if (stage.slug === "churned") return <ChurnList key={version} stageSlug={stage.slug} onOpenCompany={onOpenCompany} />;
+  return <LeadQueue key={`${stage.slug}-${version}`} stageSlug={stage.slug} onOpenContact={onOpenContact} />;
+}
+
+export function LifecycleScreen({ renderDetailActions, extraDetailTabs, toolbarActions }: LifecycleScreenProps) {
+  const { stages, countOf, loading, error, refetch } = useLifecycleStages();
+  const [tabParam, setTab] = useUrlState("tab", "board");
+  const [raw, setRaw] = useUrlState("rec");
+  const [mode, setMode] = useUrlState("view");
+  const [version, setVersion] = useState(0);
+  const [moving, setMoving] = useState<{ record: OpenRecord; name: string } | null>(null);
+  const record = parseRecord(raw);
+  const tab = tabParam === "board" || stages.some((s) => s.slug === tabParam) ? (tabParam as string) : "board";
+  const activeStage = stages.find((s) => s.slug === tab);
+  const close = () => { setRaw(null); setMode(null); };
+  const openCompany = (id: number) => setRaw(`company:${id}`);
+  const openContact = (id: number) => setRaw(`contact:${id}`);
+  const refresh = () => { setVersion((v) => v + 1); void refetch(); };
+
+  const moveButton = (name: string | null | undefined) => record ? (
+    <>
+      <Button variant="outline" size="sm" onClick={() => setMoving({ record, name: name || `${record.kind} ${record.id}` })}>Move stage</Button>
+      {renderDetailActions?.(record)}
+    </>
+  ) : null;
+
+  const detail = record ? (
+    <DetailPanel
+      title={record.kind === "company" ? "Company" : "Contact"}
+      onClose={close}
+      onExpand={mode === "full" ? undefined : () => setMode("full")}
+      onCollapse={mode === "full" ? () => setMode(null) : undefined}
+      tabs={[
+        {
+          id: "record",
+          label: "Record",
+          content: record.kind === "company"
+            ? <CompanyDetail key={record.id} companyId={record.id} onOpenContact={(c: CrmContact) => openContact(c.id)} renderActions={(c: CrmCompany) => moveButton(c.name)} extraTabs={(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, render: () => t.render(record) }))} />
+            : <ContactDetail key={record.id} contactId={record.id} onOpenCompany={openCompany} renderActions={(c: CrmContact) => moveButton(c.full_name || [c.first_name, c.last_name].filter(Boolean).join(" "))} extraTabs={(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, render: () => t.render(record) }))} />,
+        },
+        ...(record.kind === "company" ? [
+          { id: "brief", label: "Brief", content: <CompanyBrief key={record.id} companyId={record.id} /> },
+          { id: "signals", label: "Signals", content: <AccountSignalsTab key={record.id} companyId={record.id} /> },
+        ] : []),
+      ]}
+    />
+  ) : null;
+
+  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 (activeStage) body = <StageTab stage={activeStage} version={version} onOpenCompany={openCompany} onOpenContact={openContact} />;
+  else body = <LifecycleBoard key={version} onOpenCompany={openCompany} />;
+
+  return (
+    <ScreenLayout
+      title="Lifecycle"
+      description="Follow every company from suspect to customer, and win back the ones that left."
+      icon={<GitBranch className="size-5" />}
+      actions={toolbarActions}
+      tabs={[{ id: "board", label: "Board" }, ...stages.map((s) => ({ id: s.slug, label: s.name }))]}
+      activeTab={tab}
+      onTabChange={(id) => { setTab(id); close(); }}
+      stats={stages.map((s) => ({ label: s.name, value: countOf(s) == null ? "-" : (countOf(s) as number).toLocaleString() }))}
+    >
+      <SplitView detailOpen={Boolean(record)} onCloseDetail={close} expanded={mode === "full" && Boolean(record)} onExpandedChange={(full) => setMode(full ? "full" : null)} detailWidth="xl" detail={detail} list={body} />
+      {moving ? (
+        <StageMoveDialog kind={moving.record.kind} recordId={moving.record.id} recordName={moving.name} stages={stages} onClose={() => setMoving(null)} onMoved={() => { setMoving(null); refresh(); }} />
+      ) : null}
+    </ScreenLayout>
+  );
+}

package/blocks/newsletter/README.md

@@ -4,6 +4,18 @@ Write, test, schedule and send newsletter issues, manage subscribers, and read o
 **Sending reaches real inboxes and cannot be recalled**, so every call that can mail a person is tier `external`
 and goes through `ConfirmSpendDialog` with the recipient count.
 
+## Screens
+
+`NewsletterScreen` (`components/newsletter-screen.tsx`) is the finished page: mount it and a person can run a newsletter end to end, no extra code.
+
+```tsx
+import { NewsletterScreen } from "@/g8/newsletter/components/newsletter-screen";
+export default function Page() { return <NewsletterScreen />; }
+```
+
+Flows: pick or create a newsletter (deep link `?newsletter=`), activate or pause it, read subscribers and open and click rates, search and filter issues, write an issue (deep link `?id=`), generate it with AI, send a test, send now or schedule, follow the send and pause, resume or cancel it, read per-issue results, manage subscribers (add, import a list, verify, unsubscribe, erase), compare sent issues. Every send, import, verify, unsubscribe and erase is confirmed.
+Prerequisites are the ones below (verified sending domain, consent, `campaigns:launch`). Optional props: `renderRowActions`, `renderDetailActions`, `extraDetailTabs`, `toolbarActions`.
+
 ## Install
 
 ```
@@ -82,6 +94,7 @@ export default function Page() {
 
 | Component | File | What it is |
 |---|---|---|
+| `NewsletterScreen` | `components/newsletter-screen.tsx` | The finished page: issues with write, send and results, subscribers and performance. |
 | `NewsletterEditor` | `components/newsletter-editor.tsx` | Pick or create a newsletter, list its issues, write issues and activate or pause the newsletter. |
 | `IssueForm` | `components/issue-form.tsx` | Draft one issue: subject, preview text, HTML, AI generation, test send and delete of drafts. |
 | `IssueScheduler` | `components/issue-scheduler.tsx` | Send an issue now or schedule it, confirmed with the subscriber count, then follow, pause, resume or cancel the send. |

package/blocks/newsletter/block.json

@@ -43,6 +43,13 @@
     "get_issue_analytics_kpis_newsletters__newsletter_id__issues__issue_id__analytics_kpis_get"
   ],
   "components": [
+    {
+      "name": "NewsletterScreen",
+      "file": "components/newsletter-screen.tsx",
+      "purpose": "Finished newsletter workspace: pick or create a newsletter, issues list with detail (write, send, results), subscribers and performance tabs.",
+      "operations": [],
+      "tiers": []
+    },
     {
       "name": "NewsletterEditor",
       "file": "components/newsletter-editor.tsx",
@@ -219,6 +226,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
   }
 }