@graph8/sdk 0.308.1 → 0.357.0

package/blocks/campaigns/components/persona-editor.tsx

@@ -0,0 +1,210 @@
+"use client";
+
+/**
+ * PersonaEditor: the buyer personas campaigns speak to. Add and edit them by hand for free, or have AI
+ * recommend a set from your company profile (confirmed first, it spends credits).
+ *
+ * SDK operations, in order:
+ *   1. getCompanyProfile            GET  /company-profile                     (read; via useCompanyProfile, supplies website_url)
+ *   2. listPersonas                 GET  /personas                            (read)
+ *   3. createPersona / updatePersona POST /personas, PATCH /personas/{persona_id}  (write)
+ *   4. recommendCampaignPersonas    POST /campaigns/recommend-personas        (billable, ConfirmSpendDialog; returns suggestions and SAVES NOTHING)
+ *      accept a suggestion          POST /personas                            (write; free, no extra confirmation)
+ *   5. archivePersona               POST /personas/{persona_id}/archive       (destructive, ConfirmSpendDialog)
+ *
+ * Tiers: 4 spends credits, then you choose which suggestions to keep (each Accept is a free create); 5 removes a persona from the default list, so both are confirmed. Personas are
+ * keyed by the workspace website; with none saved, creating is disabled (save it in IcpEditor first).
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle, Input, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Textarea } 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 { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useCompanyProfile } from "../hooks/use-company-profile";
+import { CREDIT_ESTIMATES, lines, listOf, statusClass, text } from "../lib/campaigns-utils";
+import { FormField } from "./form-field";
+
+export interface PersonaEditorProps {
+  /** Overrides the website from the saved profile. */
+  websiteUrl?: string;
+  /** Called after any change, so a wizard can refresh its persona choices. */
+  onChange?: () => void;
+  className?: string;
+}
+
+interface PersonaRow {
+  id: string;
+  title?: string | null;
+  why_target?: string | null;
+  key_signals?: unknown[] | null;
+  campaign_approach?: string | null;
+  recommended_goal?: string | null;
+  priority?: number | null;
+  confidence?: string | null;
+  status?: string | null;
+}
+
+interface Suggestion {
+  title: string;
+  why_target?: string;
+  key_signals?: unknown[];
+  campaign_approach?: string;
+  expected_receptivity?: string;
+  priority?: number;
+  confidence?: string;
+}
+
+interface PersonaForm { title: string; why: string; signals: string; approach: string; goal: string; priority: string; confidence: string }
+const emptyForm: PersonaForm = { title: "", why: "", signals: "", approach: "", goal: "", priority: "1", confidence: "medium" };
+
+function formOf(p: PersonaRow): PersonaForm {
+  return {
+    title: p.title ?? "", why: p.why_target ?? "", approach: p.campaign_approach ?? "", goal: p.recommended_goal ?? "",
+    priority: String(p.priority ?? 1), confidence: p.confidence ?? "medium", signals: (p.key_signals ?? []).map((s) => text(s)).filter(Boolean).join("\n"),
+  };
+}
+
+export function PersonaEditor({ websiteUrl, onChange, className }: PersonaEditorProps) {
+  const profile = useCompanyProfile(websiteUrl);
+  const personas = useG8Query((signal) => g8Get("/personas", { limit: 100 }, { signal }), []);
+  const [editing, setEditing] = useState<PersonaRow | "new" | null>(null);
+  const [form, setForm] = useState<PersonaForm>(emptyForm);
+  const [archiving, setArchiving] = useState<PersonaRow | null>(null);
+  const [confirmRecommend, setConfirmRecommend] = useState(false);
+  const [suggestions, setSuggestions] = useState<Suggestion[]>([]);
+  const [accepting, setAccepting] = useState<string | null>(null);
+  const [busyId, setBusyId] = useState<string | null>(null);
+
+  const done = () => { void personas.refetch(); onChange?.(); };
+  const save = useG8Mutation(async () => {
+    const body = {
+      title: form.title.trim(), why_target: form.why, key_signals: lines(form.signals), campaign_approach: form.approach,
+      recommended_goal: form.goal, priority: Number(form.priority) || 1, confidence: form.confidence,
+    };
+    return editing && editing !== "new" ? g8Patch(`/personas/${editing.id}`, body) : g8Post("/personas", { ...body, website_url: profile.websiteUrl });
+  }, { onSuccess: () => { setEditing(null); done(); } });
+  const archive = useG8Mutation(async (p: PersonaRow) => {
+    setBusyId(p.id);
+    try { await g8Post(`/personas/${p.id}/archive`, {}); } finally { setBusyId(null); setArchiving(null); }
+  }, { onSuccess: done });
+  const recommend = useG8Mutation(() => g8Post("/campaigns/recommend-personas", { website_url: profile.websiteUrl }), {
+    onSuccess: (res) => { setConfirmRecommend(false); setSuggestions(listOf<Suggestion>(res)); },
+    onError: () => setConfirmRecommend(false),
+  });
+
+  const accept = useG8Mutation(async (s: Suggestion) => {
+    setAccepting(s.title);
+    try {
+      await g8Post("/personas", {
+        title: s.title, why_target: s.why_target, key_signals: s.key_signals ?? [], campaign_approach: s.campaign_approach,
+        expected_receptivity: s.expected_receptivity, priority: s.priority ?? 1, confidence: s.confidence ?? "medium", source: "recommended", website_url: profile.websiteUrl,
+      });
+    } finally { setAccepting(null); }
+    setSuggestions((all) => all.filter((x) => x.title !== s.title));
+  }, { onSuccess: done });
+
+  const rows = listOf<PersonaRow>(personas.data);
+  const open = (p: PersonaRow | "new") => { setForm(p === "new" ? emptyForm : formOf(p)); setEditing(p); save.reset(); };
+  const set = (k: keyof PersonaForm) => (e: { target: { value: string } }) => setForm({ ...form, [k]: e.target.value });
+
+  return (
+    <section aria-label="Personas" className={`space-y-3 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center justify-between gap-2">
+        <h3 className="font-medium">Buyer personas</h3>
+        <div className="flex gap-2">
+          <Button size="sm" variant="outline" disabled={!profile.websiteUrl} onClick={() => setConfirmRecommend(true)}>Recommend with AI</Button>
+          <Button size="sm" disabled={!profile.websiteUrl} onClick={() => open("new")}>Add persona</Button>
+        </div>
+      </div>
+      {!profile.loading && !profile.websiteUrl ? <p className="text-sm text-muted-foreground">Save the company website (IcpEditor) before adding personas.</p> : null}
+      {suggestions.length > 0 ? (
+        <section aria-label="Recommended personas" className="space-y-2 rounded-md border border-dashed p-3">
+          <p className="text-sm font-medium">AI recommendations. Nothing is saved until you accept.</p>
+          {suggestions.map((s) => (
+            <div key={s.title} className="flex items-start justify-between gap-3 text-sm">
+              <div><p className="font-medium">{s.title}</p><p className="text-muted-foreground">{s.why_target}</p></div>
+              <div className="flex shrink-0 gap-2">
+                <Button size="sm" aria-label={`Accept ${s.title}`} loading={accepting === s.title} onClick={() => void accept.mutate(s)}>Accept</Button>
+                <Button size="sm" variant="outline" aria-label={`Dismiss ${s.title}`} onClick={() => setSuggestions((all) => all.filter((x) => x.title !== s.title))}>Dismiss</Button>
+              </div>
+            </div>
+          ))}
+        </section>
+      ) : null}
+      {recommend.data && suggestions.length === 0 && !recommend.error ? <p role="status" className="text-sm text-muted-foreground">No recommendations left to review.</p> : null}
+      {[personas.error, archive.error, recommend.error, accept.error].map((e, i) => (e ? <ApiError key={i} error={e} onRetry={i === 0 ? () => void personas.refetch() : undefined} /> : null))}
+      <Table>
+        <TableHeader><TableRow><TableHead>Title</TableHead><TableHead>Why target</TableHead><TableHead>Confidence</TableHead><TableHead>Status</TableHead><TableHead className="w-40" /></TableRow></TableHeader>
+        <TableBody>
+          {personas.loading && !personas.data ? <TableRow><TableCell colSpan={5}><Skeleton className="h-6 w-full" /></TableCell></TableRow> : null}
+          {rows.map((p) => (
+            <TableRow key={p.id}>
+              <TableCell className="font-medium">{p.title}</TableCell>
+              <TableCell className="max-w-md truncate text-muted-foreground">{p.why_target}</TableCell>
+              <TableCell>{p.confidence}</TableCell>
+              <TableCell><span className={`rounded px-2 py-0.5 text-xs ${statusClass(p.status)}`}>{p.status ?? "active"}</span></TableCell>
+              <TableCell className="space-x-2 text-right">
+                <Button size="sm" variant="outline" aria-label={`Edit ${p.title}`} onClick={() => open(p)}>Edit</Button>
+                <Button size="sm" variant="outline" aria-label={`Archive ${p.title}`} loading={busyId === p.id} onClick={() => setArchiving(p)}>Archive</Button>
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      {!personas.loading && !personas.error && rows.length === 0 ? <EmptyState title="No personas yet" description="Add the roles you sell to, or let AI recommend them." /> : null}
+
+      <Dialog open={editing !== null} onOpenChange={(o) => { if (!o) setEditing(null); }}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>{editing === "new" ? "Add persona" : "Edit persona"}</DialogTitle></DialogHeader>
+          <div className="space-y-3">
+            <FormField label="Title" htmlFor="persona-title"><Input id="persona-title" value={form.title} placeholder="Director of Marketing Operations" onChange={set("title")} /></FormField>
+            <FormField label="Why target" htmlFor="persona-why"><Textarea id="persona-why" value={form.why} onChange={set("why")} /></FormField>
+            <FormField label="Key signals" htmlFor="persona-signals" hint="One per line."><Textarea id="persona-signals" value={form.signals} onChange={set("signals")} /></FormField>
+            <FormField label="Campaign approach" htmlFor="persona-approach"><Textarea id="persona-approach" value={form.approach} onChange={set("approach")} /></FormField>
+            <FormField label="Recommended goal" htmlFor="persona-goal"><Input id="persona-goal" value={form.goal} onChange={set("goal")} /></FormField>
+            <div className="grid grid-cols-2 gap-3">
+              <FormField label="Priority" htmlFor="persona-priority"><Input id="persona-priority" type="number" min={1} value={form.priority} onChange={set("priority")} /></FormField>
+              <FormField label="Confidence" htmlFor="persona-confidence">
+                <select id="persona-confidence" className="h-9 rounded-md border bg-background px-2" value={form.confidence} onChange={set("confidence")}>
+                  {["low", "medium", "high"].map((c) => <option key={c} value={c}>{c}</option>)}
+                </select>
+              </FormField>
+            </div>
+            {save.error ? <ApiError error={save.error} title="Could not save the persona" /> : null}
+          </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setEditing(null)}>Cancel</Button>
+            <Button loading={save.loading} disabled={!form.title.trim()} onClick={() => void save.mutate(undefined)}>Save persona</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      <ConfirmSpendDialog
+        open={confirmRecommend}
+        tier="billable"
+        title="Recommend personas with AI"
+        description="Reads your company profile and suggests personas. Nothing is saved until you accept each one. Estimate only."
+        estimatedCredits={CREDIT_ESTIMATES.personaRecommend}
+        confirmLabel="Recommend personas"
+        confirming={recommend.loading}
+        onConfirm={() => void recommend.mutate(undefined)}
+        onCancel={() => setConfirmRecommend(false)}
+      />
+      <ConfirmSpendDialog
+        open={archiving !== null}
+        tier="destructive"
+        title={`Archive ${archiving?.title ?? "this persona"}`}
+        description="It drops out of the default list. Existing campaigns keep the persona text."
+        affected={1}
+        confirmLabel="Archive persona"
+        confirming={archive.loading}
+        onConfirm={() => archiving && void archive.mutate(archiving)}
+        onCancel={() => setArchiving(null)}
+      />
+    </section>
+  );
+}

package/blocks/campaigns/hooks/use-company-profile.ts

@@ -0,0 +1,34 @@
+"use client";
+
+/**
+ * useCompanyProfile: the workspace's company profile and its website, which every ICP, persona and campaign
+ * generation call needs.
+ *
+ * SDK operations:
+ *   1. getCompanyProfile  GET /company-profile  (read; `data.profile` is null until one is saved)
+ *
+ * Tiers: read only.
+ */
+
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { objectOf } from "../lib/campaigns-utils";
+
+export interface CompanyProfile {
+  website_url?: string;
+  fields?: Record<string, unknown> | null;
+  approved?: boolean;
+  first_run_completed_at?: string | null;
+}
+
+export function useCompanyProfile(websiteOverride?: string) {
+  const query = useG8Query((signal) => g8Get("/company-profile", undefined, { signal }), []);
+  const profile = (objectOf(query.data).profile ?? null) as CompanyProfile | null;
+  return {
+    profile,
+    websiteUrl: websiteOverride || profile?.website_url || "",
+    loading: query.loading,
+    error: query.error,
+    refetch: query.refetch,
+  };
+}

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

@@ -0,0 +1,155 @@
+"use client";
+
+/** Types and helpers shared by the campaign components. Payloads are open-shaped: every field is optional. */
+
+/** Where the person manages mailboxes. Google and Microsoft OAuth consent can only run in the graph8 app. */
+export const GRAPH8_APP_MAILBOXES_URL = "https://app.graph8.com/studio/settings?tab=purchase&view=mailboxes";
+
+/**
+ * Rough credit estimates shown in ConfirmSpendDialog. The API has no price read and no balance read, so these
+ * are placeholders: tune them to your plan. A 402 from the call means the workspace is out of credits.
+ */
+export const CREDIT_ESTIMATES = {
+  profileGenerate: 50,
+  personaRecommend: 25,
+  perIdea: 10,
+  documentSet: 100,
+  stepContent: 5,
+  documentRegenerate: 10,
+} as const;
+
+/** The proxy refuses request bodies over 5 MiB (413). Check before sending. */
+export const MAX_BODY_BYTES = 5 * 1024 * 1024;
+
+export interface CampaignRow {
+  id: string;
+  name?: string | null;
+  slug?: string | null;
+  status?: string | null;
+  category?: string | null;
+  goal?: string | null;
+  brief?: string | null;
+  core_concept?: string | null;
+  primary_hook?: string | null;
+  target_persona?: string | null;
+  audience_list_id?: string | number | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+
+export interface CampaignDocRow {
+  id: string;
+  display_name?: string | null;
+  file_type?: string | null;
+  folder_path?: string | null;
+  status?: string | null;
+  content?: string | null;
+  updated_at?: string | null;
+}
+
+export interface SequenceStep {
+  step_id: string;
+  name?: string | null;
+  channel?: string | null;
+  mode?: string | null;
+  day?: number | null;
+  stop_on_reply?: boolean | null;
+  status?: string | null;
+}
+
+/** The channel -> mode matrix the step API enforces (docs/developer-api-reference.md, GTM Campaigns). */
+export const CHANNEL_MODES: Record<string, string[]> = {
+  email: ["email"],
+  phone: ["call", "voicemail"],
+  sms: ["sms"],
+  social: ["connect_note", "dm", "comment", "reply"],
+  voice_ai: ["call"],
+};
+
+export function listOf<T>(envelope: unknown): T[] {
+  const data = (envelope as { data?: unknown } | null)?.data;
+  if (Array.isArray(data)) return data as T[];
+  const named = data as { items?: unknown; documents?: unknown; personas?: unknown } | null;
+  for (const rows of [named?.items, named?.documents, named?.personas]) if (Array.isArray(rows)) return rows as T[];
+  return [];
+}
+
+export function objectOf(envelope: unknown): Record<string, unknown> {
+  const data = (envelope as { data?: unknown } | null)?.data;
+  return data && typeof data === "object" && !Array.isArray(data) ? (data as Record<string, unknown>) : {};
+}
+
+export function text(v: unknown): string {
+  return typeof v === "string" ? v : typeof v === "number" ? String(v) : "";
+}
+
+export function lines(value: string): string[] {
+  return value.split("\n").map((s) => s.trim()).filter(Boolean);
+}
+
+export function commaList(value: string): string[] {
+  return value.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+export function statusClass(status: string | null | undefined): string {
+  const s = (status ?? "").toLowerCase();
+  if (["active", "live", "completed", "approved", "complete", "done"].includes(s)) return "bg-green-100 text-green-800";
+  if (["draft", "pending", "running", "generating", "in_progress", "copy_in_progress", "scheduling"].includes(s)) return "bg-amber-100 text-amber-800";
+  if (s) return "bg-red-100 text-red-800";
+  return "bg-gray-100 text-gray-700";
+}
+
+/** Timestamps are shown in UTC so the same value reads the same everywhere. */
+export function formatDate(value: string | null | undefined): string {
+  if (!value) return "";
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return value;
+  return d.toLocaleDateString("en-US", { year: "numeric", month: "short", day: "numeric", timeZone: "UTC" });
+}
+
+/** Scalar fields of an open-shaped object, for a summary grid. */
+export function scalars(obj: Record<string, unknown>): Array<[string, string]> {
+  return Object.entries(obj)
+    .filter(([, v]) => ["string", "number", "boolean"].includes(typeof v))
+    .map(([k, v]) => [k.replace(/_/g, " "), typeof v === "number" && !Number.isInteger(v) ? v.toFixed(2) : String(v)]);
+}
+
+const RUNNING = new Set(["pending", "running", "in_progress", "processing", "started", "generating", "queued", "copy_in_progress"]);
+
+/** True when no string under a `status` or `state` key (at any depth) is still in progress. */
+export function settled(value: unknown): boolean {
+  if (Array.isArray(value)) return value.every(settled);
+  if (!value || typeof value !== "object") return true;
+  return Object.entries(value as Record<string, unknown>).every(([k, v]) => {
+    if (typeof v === "string" && /status|state/i.test(k)) return !RUNNING.has(v.toLowerCase());
+    return settled(v);
+  });
+}
+
+/**
+ * Steps from a GET /campaigns/{id}/sequence (or /full) payload. The ORDER lives in `sequence.steps`
+ * ({ step_id, day, condition, stop_on_reply }); the name, channel and mode live in `step_catalog.steps`,
+ * keyed by step_id. This joins the two.
+ */
+export function stepsOf(envelope: unknown): SequenceStep[] {
+  const data = objectOf(envelope);
+  const order = (data.sequence as { steps?: unknown } | null)?.steps;
+  const catalog = ((data.step_catalog as { steps?: unknown } | null)?.steps ?? {}) as Record<string, Partial<SequenceStep>>;
+  if (!Array.isArray(order)) return [];
+  return order
+    .filter((s): s is SequenceStep => !!s && typeof s === "object" && typeof (s as SequenceStep).step_id === "string")
+    .map((s) => ({ ...catalog[s.step_id], ...s }));
+}
+
+/** Contacts on the attached list from a /full payload (`audience.item_count`, also read as `total`). */
+export function audienceOf(envelope: unknown): { listId: string | null; name: string; size: number | undefined } {
+  const d = objectOf(envelope);
+  const a = (d.audience ?? {}) as Record<string, unknown>;
+  const id = d.audience_list_id;
+  const size = typeof a.item_count === "number" ? a.item_count : typeof a.total === "number" ? a.total : undefined;
+  return { listId: id == null || id === "" ? null : String(id), name: text(a.name) || text(a.title), size };
+}
+
+export function byteLength(s: string): number {
+  return typeof Blob !== "undefined" ? new Blob([s]).size : s.length;
+}

package/blocks/campaigns/recipes/attach-audience-and-launch.ts

@@ -0,0 +1,33 @@
+/**
+ * @title Attach an audience, check readiness, and launch
+ * @when The campaign has steps and copy and a human has approved reaching the list. `launchCampaign` is tier
+ * `external`: it BEGINS REAL OUTREACH and cannot be recalled, so show the recipient count and get approval
+ * first. Readiness needs a non-empty audience, completed copy, at least one complete step and an ACTIVE
+ * email mailbox (Google and Microsoft mailboxes are connected by the person in the graph8 app). An empty body
+ * auto-picks the first active mailbox; pass `sender_mailbox_ids` to choose. Read the state with
+ * `getCampaignFull` (plain `getCampaign` omits the audience): `is_launched` means do not launch again. If
+ * launch fails with 502 `draft_created_activation_failed` or `activation_state_uncertain`, a sequence may
+ * exist: check it before retrying, never repeat blindly.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function attachAndLaunch(campaignId: string, listId: number, senderMailboxIds?: number[]) {
+  await g8.api.gtmCampaigns.attachAudienceToCampaign({ path: { campaign_id: campaignId }, body: { list_id: String(listId) } });
+
+  const verdict = await g8.api.deliverability.getSafeToSend();
+  const safe = ((verdict.data ?? {}) as { safe_to_send?: boolean }).safe_to_send;
+  if (safe === false) return { launched: false as const, reason: "deliverability says do not send" };
+
+  const full = await g8.api.gtmCampaigns.getCampaignFull({ path: { campaign_id: campaignId } });
+  const state = (full.data ?? {}) as { is_launched?: boolean; audience?: { item_count?: number }; sequence?: { steps?: unknown[] } };
+  if (state.is_launched) return { launched: false as const, reason: "already launched" };
+  if (!state.sequence?.steps?.length) return { launched: false as const, reason: "the campaign has no steps" };
+
+  const launched = await g8.api.gtmCampaigns.launchCampaign({
+    path: { campaign_id: campaignId },
+    body: senderMailboxIds ? { sender_mailbox_ids: senderMailboxIds } : {},
+  });
+  return { launched: true as const, recipients: state.audience?.item_count, result: launched.data };
+}

package/blocks/campaigns/recipes/campaign-report.ts

@@ -0,0 +1,22 @@
+/**
+ * @title Report on every campaign
+ * @when A daily or weekly summary. Reads only (no spend). `listCampaigns` is page-numbered and returns a bare array; metrics take a
+ * window in days (1 to 365). The metrics payload is open-shaped, so this returns it as is.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function campaignReport(days = 30) {
+  const report: Array<{ id: string; name: string; status: string; metrics: unknown }> = [];
+  for (let page = 1; ; page++) {
+    const res = await g8.api.gtmCampaigns.listCampaigns({ query: { page, limit: 50 } });
+    const rows = (res.data ?? []) as Array<{ id: string; name: string; status: string }>;
+    for (const c of rows) {
+      const metrics = await g8.api.gtmCampaigns.getCampaignMetrics({ path: { campaign_id: c.id }, query: { days } });
+      report.push({ id: c.id, name: c.name, status: c.status, metrics: metrics.data });
+    }
+    if (rows.length < 50) break; // a bare array with no pagination block: a short page is the last
+  }
+  return report;
+}

package/blocks/campaigns/recipes/generate-ideas-and-create-campaign.ts

@@ -0,0 +1,51 @@
+/**
+ * @title Generate campaign ideas, then create the campaign from one
+ * @when Starting a campaign from the company profile. `generateCampaignIdeasAsync` is BILLABLE (it scales with
+ * `num_ideas`): a human approves the spend first. It returns a `task_id`; there are no streams, so poll
+ * `getCampaignIdeasTaskStatus` every 2 to 3 seconds until `completed` or `failed`. `createCampaign` is tier
+ * `external` in the contract but contacts nobody; with `auto_generate_documents: true` it also spends credits
+ * writing the documents. Store the returned campaign id at once: a retry after a later failure must reuse it.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+interface Idea {
+  campaign_name?: string;
+  campaign_category?: string;
+  core_concept?: string;
+  primary_hook?: string;
+  why_this_works?: string;
+  target_channels?: string[];
+}
+
+export async function generateIdeas(websiteUrl: string, goal: "awareness" | "consideration" | "decision", numIdeas = 5) {
+  const started = await g8.api.campaigns.generateCampaignIdeasAsync({
+    body: { organization_id: "current", website_url: websiteUrl, campaign_goal: goal, num_ideas: numIdeas },
+  });
+  const taskId = String(started.data?.task_id ?? "");
+  for (let attempt = 0; attempt < 60; attempt++) {
+    const task = await g8.api.campaigns.getCampaignIdeasTaskStatus({ path: { task_id: taskId } });
+    const data = (task.data ?? {}) as { status?: string; ideas?: Idea[]; error?: string };
+    if (data.status === "completed") return data.ideas ?? [];
+    if (data.status === "failed") throw new Error(data.error ?? "idea generation failed");
+    await new Promise((r) => setTimeout(r, 2500));
+  }
+  throw new Error(`idea task ${taskId} did not finish in time`);
+}
+
+export async function createCampaignFromIdea(idea: Idea, listId?: number) {
+  const created = await g8.api.gtmCampaigns.createCampaign({
+    body: {
+      name: idea.campaign_name ?? "New campaign",
+      category: idea.campaign_category ?? "Outbound",
+      core_concept: idea.core_concept,
+      primary_hook: idea.primary_hook,
+      brief: idea.why_this_works,
+      target_channels: ["email"],
+      audience_list_id: listId == null ? undefined : String(listId),
+      auto_generate_documents: false,
+    },
+  });
+  return String(created.data?.id);
+}

package/blocks/campaigns/recipes/set-up-icp-and-personas.ts

@@ -0,0 +1,37 @@
+/**
+ * @title Set the company profile, then create an ICP and personas
+ * @when Before any campaign work. Every idea, persona and campaign is generated from the company profile, so
+ * a wrong website here makes everything downstream describe the wrong company. `updateCompanyProfile` replaces
+ * the stored field set (send all of it) and refuses an APPROVED profile with 409 unless you pass
+ * `unapprove_if_approved: true`, which a human should decide. Creating ICPs and personas by hand is free;
+ * `recommendCampaignPersonas` and `generateCompanyProfile` spend credits and need approval first.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function setUpProfile(websiteUrl: string, fields: Record<string, string>) {
+  await g8.api.gtmContext.updateCompanyProfile({ body: { website_url: websiteUrl, fields } });
+
+  const icp = await g8.api.gtmContext.createIcp({
+    body: {
+      name: "Mid-market B2B SaaS",
+      website_url: websiteUrl,
+      description: "Software companies with 50 to 500 employees and a sales team.",
+      firmographics: { industries: ["Software"], company_size: "50-500", regions: ["US"] },
+      buying_signals: ["Hiring SDRs", "New VP of Sales"],
+    },
+  });
+
+  const persona = await g8.api.gtmContext.createPersona({
+    body: {
+      title: "VP of Sales",
+      website_url: websiteUrl,
+      why_target: "Owns pipeline targets and the outbound budget.",
+      key_signals: ["Missed quota", "New sales tooling"],
+      campaign_approach: "Lead with the time saved on prospecting.",
+      recommended_goal: "consideration",
+    },
+  });
+  return { icpId: icp.data?.id, personaId: persona.data?.id };
+}

package/blocks/coach/README.md

@@ -0,0 +1,93 @@
+# coach: sales coach scorecards and a coaching feed
+
+Show reps how their practice calls went and what to work on next, and give managers a leaderboard. Builds on
+the `dialer` block (the optional "Real calls" tab reuses its `CallLog`).
+
+Install: `npx @graph8/sdk add coach` (installs `foundation`, `lists`, `crm` and `dialer` first).
+
+## What you get
+
+| Component | Use it for | Embed props |
+|---|---|---|
+| `CallScorecard` | One graded call: overall score, stages with checklist verdicts, strengths, improvements, recording, transcript | `callId`, `allowDelete`, `onDeleted` |
+| `CoachingFeed` | Practice calls newest first with the first tip, a leaderboard tab, optional real-calls tab | `userEmail`, `onOpenCall`, `allowCreate`, `showDialerCalls`, `allowDelete`, `pageSize` |
+
+## The flow, with the ids that pass between steps
+
+1. **Feed**: `GET /sales-coach/calls?email=` returns the calls (newest first) with `scores` and transcript
+   segments inline. Without `email` it is the key owner's own; another rep's calls need a manager key (403
+   otherwise). Each call's `id` is the `call_id` for everything below.
+2. **Score**: `scores[0].evaluation_data` holds `stages[].criteria[].verdict` (met / partial / missed; a stage
+   is the share of judged lines, met = 1, partial = 0.5) or, on older calls, `evaluatorResult` categories
+   out of 10. `scorecardOf()` reads both. `evaluatorResult.areas_of_improvement[0]` is the tip the feed shows.
+3. **Scorecard**: `GET /sales-coach/calls/{call_id}`, `.../transcript` (segments with `in_call_timestamp` in
+   ms), and on demand `.../audio-url` (a short-lived signed URL; the card fetches it only on "Load recording").
+4. **Leaderboard**: `GET /sales-coach/leaderboard` ranks completed calls per rep (`score` total, `calls`,
+   `avgScore`).
+5. **Create** (optional): `POST /sales-coach/calls { call_mode: "assisted" | "compete", prospect_name, ... }`
+   creates only the call row. The live practice conversation runs in the graph8 app.
+6. **Delete**: `DELETE /sales-coach/calls/{call_id}` removes the call, its transcript and its scores.
+
+```tsx
+"use client";
+import { CoachingFeed } from "@/components/g8/coach/components/coaching-feed";
+
+export function MyCoaching() {
+  return <CoachingFeed userEmail={me.email} showDialerCalls allowDelete={false} />;
+}
+```
+
+(`add` installs under `components/g8/coach/`, or `src/components/g8/coach/`; adjust the alias.)
+
+## Tiers and confirmations
+
+- Everything read is free. Creating a call row is a write and runs directly.
+- Deleting a call is `destructive` and goes through `ConfirmSpendDialog`; it also drops the score from the
+  leaderboard. Turn it off for reps with `allowDelete={false}`.
+
+## Prerequisites
+
+- `dialer-installed` (app): the CLI installs it as a dependency.
+- `manager-key` (api): reading other reps' calls needs an org admin or sales manager's key.
+- `practice-in-app` (app): practice calls are run in the graph8 app; this block shows the results.
+- Proxy `allowedPrefixes` include `sales-coach` (and `voice` for the Real calls tab). Scopes: `team:read`,
+  `team:write`, `team:delete`, `voice:read`.
+
+## Defaults the agent can use without asking
+
+| Decision | Default |
+|---|---|
+| Whose calls the feed shows | the key owner's own |
+| Delete / create form | delete on, create form off |
+
+Ask the person: who may read other reps' calls (graph8 enforces managers-only; decide who gets a manager key).
+
+## Known limits
+
+- The create form is hidden when `userEmail` is set (it would create a call for the key owner, not that rep). The Real calls tab needs `userEmail` too: the dialer API will not list calls without a rep.
+- Legacy calls store `final_score` out of 30; `scorecardOf()` turns it into a percent. Checklist calls store a percent.
+- Delete is allowed for the call owner or a manager.
+
+- The live practice audio session (LiveKit token) is deliberately not in the public API.
+- Dates on a call are datetimes shown in the viewer's locale.
+- Another rep's calls: 403 for a rep's key; the error is shown, not hidden.
+
+## Recipes
+
+| File | Does |
+|---|---|
+| `recipes/read-a-scorecard.ts` | Latest graded call, its transcript and a signed recording URL |
+| `recipes/weekly-coaching-digest.ts` | Per-rep weakest stage and first tip from the leaderboard and their calls |
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| listCalls | GET /sales-coach/calls | read | CoachingFeed |
+| createCall | POST /sales-coach/calls | write | CoachingFeed |
+| getCall | GET /sales-coach/calls/{call_id} | read | CallScorecard |
+| deleteCall | DELETE /sales-coach/calls/{call_id} | destructive | CallScorecard |
+| getCallAudioUrl | GET /sales-coach/calls/{call_id}/audio-url | read | CallScorecard |
+| getCallTranscript | GET /sales-coach/calls/{call_id}/transcript | read | CallScorecard |
+| getSalesCoachLeaderboard | GET /sales-coach/leaderboard | read | CoachingFeed |
+| listCallsForContact | GET /voice/dialer/calls | read | CoachingFeed |