@graph8/sdk 0.308.1 → 0.357.0

package/blocks/campaigns/block.json

@@ -0,0 +1,361 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "campaigns",
+  "title": "AI campaign builder",
+  "summary": "Build a company profile, ICPs and personas, generate campaign ideas, then create, staff with steps, attach an audience to and launch a campaign.",
+  "features": [
+    "company profile, ICP and persona editors with AI build/recommend behind a credit confirmation",
+    "campaign wizard: AI ideas (polled) -> create -> attach audience list -> steps and copy -> launch",
+    "launch readiness checklist, sender choice and deliverability warning before real outreach",
+    "campaign documents: read, edit, rewrite with AI, add and delete",
+    "campaign list with delete, and per-campaign metrics"
+  ],
+  "dependsOn": [
+    "lists",
+    "mailboxes"
+  ],
+  "operations": [
+    "get_company_profile_company_profile_get",
+    "update_company_profile_company_profile_put",
+    "generate_company_profile_company_profile_generate_post",
+    "get_company_profile_workflow_status_company_profile_workflow_status_get",
+    "approve_company_profile_company_profile_approve_post",
+    "list_icps_icps_get",
+    "create_icp_icps_post",
+    "update_icp_icps__icp_id__patch",
+    "archive_icp_icps__icp_id__archive_post",
+    "list_personas_personas_get",
+    "create_persona_personas_post",
+    "update_persona_personas__persona_id__patch",
+    "archive_persona_personas__persona_id__archive_post",
+    "recommend_campaign_personas_campaigns_recommend_personas_post",
+    "generate_campaign_ideas_async_campaigns_generate_ideas_async_post",
+    "get_campaign_ideas_task_status_campaigns_ideas_status__task_id__get",
+    "create_campaign_campaigns_post",
+    "update_campaign_campaigns__campaign_id__patch",
+    "get_campaign_generation_status_campaigns__campaign_id__status_get",
+    "get_campaign_full_campaigns__campaign_id__full_get",
+    "attach_audience_to_campaign_campaigns__campaign_id__audience_put",
+    "get_campaign_sequence_campaigns__campaign_id__sequence_get",
+    "create_campaign_step_campaigns__campaign_id__sequence_steps_post",
+    "update_campaign_step_campaigns__campaign_id__sequence_steps__step_id__put",
+    "delete_campaign_step_campaigns__campaign_id__sequence_steps__step_id__delete",
+    "generate_campaign_step_content_campaigns__campaign_id__sequence_steps__step_id__generate_post",
+    "list_mailboxes_mailboxes_get",
+    "get_safe_to_send_deliverability_safe_to_send_get",
+    "launch_campaign_campaigns__campaign_id__launch_post",
+    "list_campaigns_campaigns_get",
+    "delete_campaign_campaigns__campaign_id__delete",
+    "list_campaigns_for_picker_campaigns_picker_get",
+    "get_campaign_metrics_campaigns__campaign_id__metrics_get",
+    "list_campaign_documents_campaigns__campaign_id__documents_get",
+    "get_campaign_document_campaigns__campaign_id__documents__document_id__get",
+    "create_campaign_document_campaigns__campaign_id__documents_post",
+    "update_campaign_document_campaigns__campaign_id__documents__document_id__put",
+    "delete_campaign_document_campaigns__campaign_id__documents__document_id__delete",
+    "regenerate_campaign_document_campaigns__campaign_id__documents__document_id__regenerate_post"
+  ],
+  "components": [
+    {
+      "name": "IcpEditor",
+      "file": "components/icp-editor.tsx",
+      "purpose": "Company profile (edit, build with AI, approve) and ideal customer profiles: add, edit, archive (confirmed).",
+      "operations": [
+        "get_company_profile_company_profile_get",
+        "update_company_profile_company_profile_put",
+        "generate_company_profile_company_profile_generate_post",
+        "get_company_profile_workflow_status_company_profile_workflow_status_get",
+        "approve_company_profile_company_profile_approve_post",
+        "list_icps_icps_get",
+        "create_icp_icps_post",
+        "update_icp_icps__icp_id__patch",
+        "archive_icp_icps__icp_id__archive_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "PersonaEditor",
+      "file": "components/persona-editor.tsx",
+      "purpose": "Buyer personas: add, edit, archive (confirmed), or have AI suggest a set (confirmed with a credit estimate) and accept the ones you want.",
+      "operations": [
+        "get_company_profile_company_profile_get",
+        "list_personas_personas_get",
+        "create_persona_personas_post",
+        "update_persona_personas__persona_id__patch",
+        "archive_persona_personas__persona_id__archive_post",
+        "recommend_campaign_personas_campaigns_recommend_personas_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CampaignWizard",
+      "file": "components/campaign-wizard.tsx",
+      "purpose": "Idea -> create campaign -> attach audience -> steps and copy -> launch. Every billable or external step is confirmed; ideas are polled.",
+      "operations": [
+        "get_company_profile_company_profile_get",
+        "list_personas_personas_get",
+        "generate_campaign_ideas_async_campaigns_generate_ideas_async_post",
+        "get_campaign_ideas_task_status_campaigns_ideas_status__task_id__get",
+        "create_campaign_campaigns_post",
+        "update_campaign_campaigns__campaign_id__patch",
+        "get_campaign_generation_status_campaigns__campaign_id__status_get",
+        "get_campaign_full_campaigns__campaign_id__full_get",
+        "attach_audience_to_campaign_campaigns__campaign_id__audience_put",
+        "get_campaign_sequence_campaigns__campaign_id__sequence_get",
+        "create_campaign_step_campaigns__campaign_id__sequence_steps_post",
+        "update_campaign_step_campaigns__campaign_id__sequence_steps__step_id__put",
+        "delete_campaign_step_campaigns__campaign_id__sequence_steps__step_id__delete",
+        "generate_campaign_step_content_campaigns__campaign_id__sequence_steps__step_id__generate_post",
+        "list_mailboxes_mailboxes_get",
+        "get_safe_to_send_deliverability_safe_to_send_get",
+        "launch_campaign_campaigns__campaign_id__launch_post"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CampaignAudienceStep",
+      "file": "components/campaign-audience-step.tsx",
+      "purpose": "Attach (or detach) a contact list as the campaign audience, confirmed with the contact count.",
+      "operations": [
+        "get_campaign_full_campaigns__campaign_id__full_get",
+        "attach_audience_to_campaign_campaigns__campaign_id__audience_put"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "CampaignSequenceStep",
+      "file": "components/campaign-sequence-step.tsx",
+      "purpose": "Add, edit, remove and AI-write the steps of a campaign sequence; each change is confirmed.",
+      "operations": [
+        "get_campaign_sequence_campaigns__campaign_id__sequence_get",
+        "create_campaign_step_campaigns__campaign_id__sequence_steps_post",
+        "update_campaign_step_campaigns__campaign_id__sequence_steps__step_id__put",
+        "delete_campaign_step_campaigns__campaign_id__sequence_steps__step_id__delete",
+        "generate_campaign_step_content_campaigns__campaign_id__sequence_steps__step_id__generate_post"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CampaignLaunchStep",
+      "file": "components/campaign-launch-step.tsx",
+      "purpose": "Readiness checklist, sender choice and deliverability warning, then a confirmed launch.",
+      "operations": [
+        "get_campaign_full_campaigns__campaign_id__full_get",
+        "list_mailboxes_mailboxes_get",
+        "get_safe_to_send_deliverability_safe_to_send_get",
+        "launch_campaign_campaigns__campaign_id__launch_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "CampaignList",
+      "file": "components/campaign-list.tsx",
+      "purpose": "All campaigns with status; open one for metrics and documents, or delete it (confirmed). No required props.",
+      "operations": [
+        "list_campaigns_campaigns_get",
+        "delete_campaign_campaigns__campaign_id__delete",
+        "list_campaigns_for_picker_campaigns_picker_get",
+        "get_campaign_metrics_campaigns__campaign_id__metrics_get",
+        "list_campaign_documents_campaigns__campaign_id__documents_get",
+        "get_campaign_document_campaigns__campaign_id__documents__document_id__get",
+        "create_campaign_document_campaigns__campaign_id__documents_post",
+        "update_campaign_document_campaigns__campaign_id__documents__document_id__put",
+        "delete_campaign_document_campaigns__campaign_id__documents__document_id__delete",
+        "regenerate_campaign_document_campaigns__campaign_id__documents__document_id__regenerate_post"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CampaignAssets",
+      "file": "components/campaign-assets.tsx",
+      "purpose": "Campaign documents: read, edit, rewrite with AI, add and delete, each confirmed.",
+      "operations": [
+        "list_campaigns_for_picker_campaigns_picker_get",
+        "list_campaign_documents_campaigns__campaign_id__documents_get",
+        "get_campaign_document_campaigns__campaign_id__documents__document_id__get",
+        "create_campaign_document_campaigns__campaign_id__documents_post",
+        "update_campaign_document_campaigns__campaign_id__documents__document_id__put",
+        "delete_campaign_document_campaigns__campaign_id__documents__document_id__delete",
+        "regenerate_campaign_document_campaigns__campaign_id__documents__document_id__regenerate_post"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CampaignMetrics",
+      "file": "components/campaign-metrics.tsx",
+      "purpose": "Performance tiles for a campaign over 7, 30, 90 or 365 days. No required props.",
+      "operations": [
+        "list_campaigns_for_picker_campaigns_picker_get",
+        "get_campaign_metrics_campaigns__campaign_id__metrics_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "CampaignSelect",
+      "file": "components/campaign-select.tsx",
+      "purpose": "Pick a campaign (id and name only); used by the page components when no campaignId is given.",
+      "operations": [
+        "list_campaigns_for_picker_campaigns_picker_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "FormField",
+      "file": "components/form-field.tsx",
+      "purpose": "A label around a control; the layout piece the editors share.",
+      "operations": [],
+      "tiers": []
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useCompanyProfile",
+      "file": "hooks/use-company-profile.ts",
+      "purpose": "The saved company profile and its website, which every generation call needs.",
+      "operations": [
+        "get_company_profile_company_profile_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/campaigns-utils.ts",
+      "purpose": "Row types, credit estimate constants, channel-to-mode matrix, UTC date format and response helpers."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/set-up-icp-and-personas.ts",
+      "title": "Set the company profile, then create an ICP and personas",
+      "when": "Before any campaign work; a wrong website makes everything downstream describe the wrong company."
+    },
+    {
+      "file": "recipes/generate-ideas-and-create-campaign.ts",
+      "title": "Generate campaign ideas, then create the campaign from one",
+      "when": "Starting a campaign; idea generation spends credits and is polled."
+    },
+    {
+      "file": "recipes/attach-audience-and-launch.ts",
+      "title": "Attach an audience, check readiness, and launch",
+      "when": "The campaign has steps and copy and a human approved reaching the list; launch is real outreach."
+    },
+    {
+      "file": "recipes/campaign-report.ts",
+      "title": "Report on every campaign",
+      "when": "A daily or weekly summary; reads only."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "company-website",
+      "description": "The workspace has a company profile with the real website. Ideas, personas and campaigns are generated from it.",
+      "where": "api",
+      "verify": "GET /company-profile returns data.profile with website_url."
+    },
+    {
+      "id": "active-mailbox",
+      "description": "At least one ACTIVE email mailbox. Google and Microsoft mailboxes are connected by the person in the graph8 app; the API cannot run the OAuth consent screen.",
+      "where": "app",
+      "verify": "GET /mailboxes lists one with connection_status active."
+    },
+    {
+      "id": "audience-list",
+      "description": "A contact list to message, created in the lists block. Search results are masked until saved to a list.",
+      "where": "api",
+      "verify": "GET /lists returns the list with a non-zero total."
+    },
+    {
+      "id": "credits-for-generation",
+      "description": "Credits for AI generation (profile, personas, ideas, step copy, documents). There is no balance read, so the UI shows estimates.",
+      "where": "api",
+      "verify": "A generation call returns 200 or 202; a 402 means insufficient credits."
+    }
+  ],
+  "scopes": [
+    "campaigns:delete",
+    "campaigns:launch",
+    "campaigns:read",
+    "campaigns:run",
+    "campaigns:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Number of campaign ideas to generate",
+      "default": "5",
+      "askHuman": false
+    },
+    {
+      "decision": "Campaign goal for idea generation",
+      "default": "awareness",
+      "askHuman": false
+    },
+    {
+      "decision": "Channels for a new campaign",
+      "default": "email (the one-step API launch executes email only)",
+      "askHuman": false
+    },
+    {
+      "decision": "Generate campaign documents with AI at creation",
+      "default": "No: generate per step and per document so each spend is confirmed",
+      "askHuman": false
+    },
+    {
+      "decision": "Sender mailbox for launch",
+      "default": "The first active email mailbox",
+      "askHuman": false
+    },
+    {
+      "decision": "Whether to launch, and to which list",
+      "default": "None: never launch without approval of the recipient count",
+      "askHuman": true
+    },
+    {
+      "decision": "Approving the company profile (locks it)",
+      "default": "Leave unapproved",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/campaigns/components/campaign-assets.tsx

@@ -0,0 +1,180 @@
+"use client";
+
+/**
+ * CampaignAssets: the documents behind a campaign (brief, targeting, copy). Read one, edit it, rewrite it with
+ * AI, add a new one or delete it. Without `campaignId` it shows a campaign picker first.
+ *
+ * SDK operations, in order:
+ *   1. listCampaignsForPicker       GET    /campaigns/picker                               (read; only when no `campaignId`)
+ *   2. listCampaignDocuments        GET    /campaigns/{campaign_id}/documents              (read)
+ *   3. getCampaignDocument          GET    /campaigns/{campaign_id}/documents/{document_id} (read; full content)
+ *   4. updateCampaignDocument       PUT    /campaigns/{campaign_id}/documents/{document_id} (external, ConfirmSpendDialog)
+ *   5. regenerateCampaignDocument   POST   .../documents/{document_id}/regenerate          (billable, ConfirmSpendDialog; 202, POLLED via 3)
+ *   6. createCampaignDocument       POST   /campaigns/{campaign_id}/documents              (external, ConfirmSpendDialog)
+ *   7. deleteCampaignDocument       DELETE .../documents/{document_id}                     (destructive, ConfirmSpendDialog)
+ *
+ * Tiers: 4-7 are all confirmed. Regenerating REPLACES the current content, so unsaved edits are discarded;
+ * the editor resets whenever the open document or the campaign changes. Content over 5 MiB is refused client
+ * side (the proxy would answer 413).
+ */
+
+import { useState } from "react";
+import { Button, Dialog, DialogContent, DialogFooter, DialogHeader, DialogTitle, Input, Skeleton, 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 { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { CREDIT_ESTIMATES, MAX_BODY_BYTES, byteLength, listOf, objectOf, statusClass, text } from "../lib/campaigns-utils";
+import type { CampaignDocRow } from "../lib/campaigns-utils";
+import { CampaignSelect } from "./campaign-select";
+import { FormField } from "./form-field";
+
+export interface CampaignAssetsProps {
+  campaignId?: string;
+  className?: string;
+}
+
+type Pending = { kind: "save" | "regenerate" | "delete" };
+const FILE_TYPES = ["campaign_brief", "targeting", "sequence", "email_copy", "landing_page", "other"];
+
+function Editor({ campaignId, doc, onChanged, onClosed }: { campaignId: string; doc: CampaignDocRow; onChanged: () => void; onClosed: () => void }) {
+  const base = `/campaigns/${campaignId}/documents/${doc.id}`;
+  const [content, setContent] = useState<string | null>(null);
+  const [pending, setPending] = useState<Pending | null>(null);
+  const full = useG8Query((signal) => g8Get(base, undefined, { signal }), [base]);
+  const poll = useJobPoll(async (signal) => objectOf(await g8Get(base, undefined, { signal })), {
+    enabled: false,
+    isTerminal: (d) => text(d.status) !== "generating",
+    onDone: () => { setContent(null); void full.refetch(); onChanged(); },
+  });
+  const run = useG8Mutation(async (p: Pending) => {
+    try {
+      if (p.kind === "save") return await g8Put(base, { content: content ?? "" });
+      if (p.kind === "regenerate") return await g8Post(`${base}/regenerate`, {});
+      if (p.kind !== "delete") return undefined;
+      try { return await g8Delete(base); } catch (err) { if ((err as { status?: number }).status === 404) return undefined; throw err; }
+    } finally { setPending(null); }
+  }, {
+    onSuccess: (_r, p) => {
+      if (p.kind === "regenerate") poll.start();
+      else if (p.kind === "delete") { onChanged(); onClosed(); }
+      else { setContent(null); void full.refetch(); onChanged(); }
+    },
+  });
+
+  const d = objectOf(full.data);
+  const body = content ?? text(d.content);
+  const tooBig = byteLength(body) > MAX_BODY_BYTES;
+  return (
+    <section aria-label={`Document ${doc.display_name ?? doc.id}`} className="space-y-2 rounded-md border p-3">
+      <div className="flex items-center justify-between">
+        <h4 className="font-medium">{doc.display_name}</h4>
+        <Button size="sm" variant="outline" onClick={onClosed}>Close</Button>
+      </div>
+      {full.error ? <ApiError error={full.error} title="Could not load the document" onRetry={() => void full.refetch()} /> : null}
+      {full.loading && !full.data ? <Skeleton className="h-32 w-full" /> : null}
+      {run.error ? <ApiError error={run.error} /> : null}
+      {poll.polling ? <p role="status" className="text-sm text-muted-foreground">Rewriting the document with AI.</p> : null}
+      {full.data ? (
+        <>
+          <Textarea aria-label="Document content" className="min-h-48 font-mono text-sm" value={body} onChange={(e) => setContent(e.target.value)} />
+          {tooBig ? <p role="alert" className="text-sm text-red-700">This document is over 5 MiB and cannot be saved through the proxy.</p> : null}
+          <div className="flex gap-2">
+            <Button disabled={content === null || tooBig || poll.polling} onClick={() => setPending({ kind: "save" })}>Save changes</Button>
+            <Button variant="outline" disabled={poll.polling} onClick={() => setPending({ kind: "regenerate" })}>Rewrite with AI</Button>
+            <Button variant="outline" disabled={poll.polling} onClick={() => setPending({ kind: "delete" })}>Delete</Button>
+          </div>
+        </>
+      ) : null}
+      <ConfirmSpendDialog
+        open={pending !== null}
+        tier={pending?.kind === "regenerate" ? "billable" : pending?.kind === "delete" ? "destructive" : "external"}
+        title={pending?.kind === "save" ? `Save "${doc.display_name}"` : pending?.kind === "regenerate" ? `Rewrite "${doc.display_name}" with AI` : `Delete "${doc.display_name}"`}
+        description={pending?.kind === "regenerate" ? "Replaces the current content, including unsaved edits. Estimate only." : pending?.kind === "delete" ? "The document is removed from the campaign." : "Nothing is sent to contacts."}
+        estimatedCredits={pending?.kind === "regenerate" ? CREDIT_ESTIMATES.documentRegenerate : undefined}
+        affected={pending?.kind === "delete" ? 1 : undefined}
+        confirmLabel={pending?.kind === "save" ? "Save document" : pending?.kind === "regenerate" ? "Rewrite document" : "Delete document"}
+        confirming={run.loading}
+        onConfirm={() => pending && void run.mutate(pending)}
+        onCancel={() => setPending(null)}
+      />
+    </section>
+  );
+}
+
+function Documents({ campaignId, className }: { campaignId: string; className?: string }) {
+  const docs = useG8Query((signal) => g8Get(`/campaigns/${campaignId}/documents`, undefined, { signal }), [campaignId]);
+  const [openId, setOpenId] = useState<string | null>(null);
+  const [creating, setCreating] = useState(false);
+  const [form, setForm] = useState({ display_name: "", file_type: FILE_TYPES[0], content: "" });
+  const [confirmCreate, setConfirmCreate] = useState(false);
+  const create = useG8Mutation(() => g8Post(`/campaigns/${campaignId}/documents`, { ...form, status: "draft" }), {
+    onSuccess: (res) => { setConfirmCreate(false); setCreating(false); setForm({ display_name: "", file_type: FILE_TYPES[0], content: "" }); void docs.refetch(); setOpenId(text(objectOf(res).id) || null); },
+    onError: () => setConfirmCreate(false),
+  });
+  const rows = listOf<CampaignDocRow>(docs.data);
+  const open = rows.find((r) => r.id === openId);
+  return (
+    <section aria-label="Campaign documents" className={`space-y-3 ${className ?? ""}`}>
+      <div className="flex items-center justify-between">
+        <h3 className="font-medium">Documents</h3>
+        <Button size="sm" onClick={() => { create.reset(); setCreating(true); }}>Add document</Button>
+      </div>
+      {docs.error ? <ApiError error={docs.error} title="Could not load documents" onRetry={() => void docs.refetch()} /> : null}
+      {create.error && !creating ? <ApiError error={create.error} title="Could not add the document" /> : null}
+      {docs.loading && !docs.data ? <Skeleton className="h-20 w-full" /> : null}
+      {!docs.loading && !docs.error && rows.length === 0 ? <EmptyState title="No documents yet" description="Documents appear once the campaign finishes generating, or add one yourself." /> : null}
+      <ul className="divide-y rounded-md border">
+        {rows.map((d) => (
+          <li key={d.id} className="flex items-center justify-between px-3 py-2 text-sm">
+            <button type="button" className="text-left font-medium underline-offset-2 hover:underline" aria-label={`Open ${d.display_name}`} onClick={() => setOpenId(d.id === openId ? null : d.id)}>{d.display_name ?? d.id}</button>
+            <span className="flex items-center gap-2 text-xs text-muted-foreground">{d.file_type}<span className={`rounded px-2 py-0.5 ${statusClass(d.status)}`}>{d.status}</span></span>
+          </li>
+        ))}
+      </ul>
+      {open ? <Editor key={open.id} campaignId={campaignId} doc={open} onChanged={() => void docs.refetch()} onClosed={() => setOpenId(null)} /> : null}
+
+      <Dialog open={creating} onOpenChange={setCreating}>
+        <DialogContent>
+          <DialogHeader><DialogTitle>Add document</DialogTitle></DialogHeader>
+          <div className="space-y-3">
+            <FormField label="Name" htmlFor="doc-name"><Input id="doc-name" value={form.display_name} onChange={(e) => setForm({ ...form, display_name: e.target.value })} /></FormField>
+            <FormField label="Type" htmlFor="doc-type">
+              <select id="doc-type" className="h-9 rounded-md border bg-background px-2" value={form.file_type} onChange={(e) => setForm({ ...form, file_type: e.target.value })}>{FILE_TYPES.map((t) => <option key={t}>{t}</option>)}</select>
+            </FormField>
+            <FormField label="Content" htmlFor="doc-content"><Textarea id="doc-content" value={form.content} onChange={(e) => setForm({ ...form, content: e.target.value })} /></FormField>
+            {create.error ? <ApiError error={create.error} title="Could not add the document" /> : null}
+          </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setCreating(false)}>Cancel</Button>
+            <Button disabled={!form.display_name.trim() || byteLength(form.content) > MAX_BODY_BYTES} onClick={() => { setCreating(false); setConfirmCreate(true); }}>Review</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <ConfirmSpendDialog
+        open={confirmCreate}
+        tier="external"
+        title={`Add document "${form.display_name}"`}
+        description="Nothing is sent to contacts."
+        confirmLabel="Add document"
+        confirming={create.loading}
+        onConfirm={() => void create.mutate(undefined)}
+        onCancel={() => setConfirmCreate(false)}
+      />
+    </section>
+  );
+}
+
+export function CampaignAssets({ campaignId, className }: CampaignAssetsProps) {
+  const [picked, setPicked] = useState<string | null>(null);
+  const id = campaignId ?? picked;
+  return (
+    <div className={`space-y-3 ${className ?? ""}`}>
+      {campaignId ? null : <CampaignSelect value={picked} onChange={setPicked} />}
+      {id ? <Documents key={id} campaignId={id} /> : null}
+    </div>
+  );
+}

package/blocks/campaigns/components/campaign-audience-step.tsx

@@ -0,0 +1,91 @@
+"use client";
+
+/**
+ * CampaignAudienceStep: attach a contact list to a campaign (or detach it). The list is the audience the
+ * campaign will message at launch, so attaching is confirmed with the contact count.
+ *
+ * SDK operations, in order:
+ *   1. getCampaignFull              GET /campaigns/{campaign_id}/full      (read; audience_list_id and the audience summary; plain GET /campaigns/{id} omits them)
+ *   2. listLists / createList       GET/POST /lists  via the lists block's ListPicker  (read / write; pick or create the list)
+ *   3. attachAudienceToCampaign     PUT /campaigns/{campaign_id}/audience  (external, ConfirmSpendDialog; { list_id } or null to detach)
+ *
+ * Tiers: 3 is `external` in the contract. Nothing is sent by attaching, but it fixes who a later launch will
+ * reach, so the confirmation states the count. `list_id` is sent as a string. Search results are masked until
+ * saved to a list (see the search block), so build the list there first.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Put } from "@/g8/lib/g8-client";
+import { ListPicker } from "@/g8/lists/components/list-picker";
+import type { ListSummary } from "@/g8/lists/components/list-picker";
+import { audienceOf } from "../lib/campaigns-utils";
+
+export interface CampaignAudienceStepProps {
+  campaignId: string;
+  /** Called after a successful attach (list) or detach (null). */
+  onAttached?: (list: ListSummary | null) => void;
+  className?: string;
+}
+
+type Pending = { list: ListSummary | null };
+
+export function CampaignAudienceStep({ campaignId, onAttached, className }: CampaignAudienceStepProps) {
+  const campaign = useG8Query((signal) => g8Get(`/campaigns/${campaignId}/full`, undefined, { signal }), [campaignId]);
+  const [picked, setPicked] = useState<ListSummary | null>(null);
+  const [pending, setPending] = useState<Pending | null>(null);
+
+  const attach = useG8Mutation(
+    (p: Pending) => g8Put(`/campaigns/${campaignId}/audience`, { list_id: p.list ? String(p.list.id) : null }),
+    {
+      onSuccess: (_res, p) => {
+        setPending(null);
+        setPicked(null);
+        void campaign.refetch();
+        onAttached?.(p.list);
+      },
+      onError: () => setPending(null),
+    },
+  );
+
+  const { listId: attachedId, name: attachedName, size: attachedSize } = audienceOf(campaign.data);
+  return (
+    <section aria-label="Audience" className={`space-y-3 ${className ?? ""}`}>
+      <h3 className="font-medium">Audience</h3>
+      {campaign.error ? <ApiError error={campaign.error} title="Could not load the campaign" onRetry={() => void campaign.refetch()} /> : null}
+      {campaign.loading && !campaign.data ? <Skeleton className="h-6 w-64" /> : null}
+      {!campaign.loading && !campaign.error ? (
+        <p className="text-sm" data-testid="attached-audience">
+          {attachedId ? <>Attached list: <strong>{attachedName || `#${attachedId}`}</strong>{attachedSize != null ? ` (${attachedSize.toLocaleString()} contacts)` : ""}</> : "No list attached yet."}
+        </p>
+      ) : null}
+      <ListPicker value={picked?.id ?? (attachedId ? Number(attachedId) : null)} onChange={setPicked} allowCreate />
+      {attach.error ? <ApiError error={attach.error} title="Could not change the audience" /> : null}
+      <div className="flex gap-2">
+        <Button disabled={!picked || String(picked.id) === attachedId} onClick={() => picked && setPending({ list: picked })}>
+          Attach {picked ? `"${picked.title}"` : "list"}
+        </Button>
+        <Button variant="outline" disabled={!attachedId} onClick={() => setPending({ list: null })}>Detach list</Button>
+      </div>
+      <ConfirmSpendDialog
+        open={pending !== null}
+        tier="external"
+        title={pending?.list ? `Attach "${pending.list.title}" to this campaign` : "Detach the audience from this campaign"}
+        description={
+          pending?.list
+            ? "The campaign will message this list when you launch it. Nothing is sent by attaching."
+            : "The campaign will have no audience and cannot launch until you attach one."
+        }
+        recipients={pending?.list ? (pending.list.total ?? pending.list.contact_count ?? undefined) : undefined}
+        confirmLabel={pending?.list ? "Attach list" : "Detach list"}
+        confirming={attach.loading}
+        onConfirm={() => pending && void attach.mutate(pending)}
+        onCancel={() => setPending(null)}
+      />
+    </section>
+  );
+}