@graph8/sdk 0.370.0 → 0.373.0

package/blocks/social-ads/block.json

@@ -14,39 +14,64 @@
     "lists"
   ],
   "operations": [
+    "apply_ad_creative_review_findings_ad_creatives__creative_id__ai_review_apply_post",
+    "archive_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__delete",
     "cancel_social_post_social_posts__post_id__cancel_post",
+    "chat_edit_ad_creative_ad_creatives__creative_id__chat_edit_post",
     "create_ad_creative_ad_creatives_post",
+    "create_ad_creative_size_set_ad_creatives__creative_id__size_set_post",
     "create_audience_sync_audience_syncs_post",
+    "create_campaign_ad_ad_campaigns__campaign_id__ads_post",
     "create_social_post_social_posts_post",
     "delete_ad_campaign_ad_campaigns__campaign_id__delete",
     "delete_ad_creative_ad_creatives__creative_id__delete",
     "delete_audience_sync_audience_syncs__config_id__delete",
     "delete_social_post_social_posts__post_id__delete",
+    "disconnect_social_account_social_accounts__account_id__delete",
+    "generate_ad_concepts_ad_creatives_concepts_post",
     "generate_social_post_social_posts_generate_post",
+    "get_ad_campaign_ad_campaigns__campaign_id__get",
+    "get_ad_creative_ad_creatives__creative_id__get",
     "get_ad_creative_specs_ad_creatives_specs_get",
     "get_ad_creative_status_ad_creatives__creative_id__status_get",
+    "get_campaign_editable_fields_ad_campaigns__campaign_id__editable_get",
     "get_per_campaign_metrics_ad_campaigns_metrics_get",
+    "get_social_analytics_social_analytics_get",
+    "get_social_post_metrics_social_posts__post_id__metrics_get",
     "get_social_post_social_posts__post_id__get",
     "launch_ad_campaign_audience_syncs__config_id__launch_post",
     "list_ad_campaigns_ad_campaigns_get",
+    "list_ad_creative_revisions_ad_creatives__creative_id__revisions_get",
     "list_ad_creatives_ad_creatives_get",
     "list_audience_syncs_audience_syncs_get",
+    "list_campaign_ads_ad_campaigns__campaign_id__ads_get",
     "list_social_accounts_social_accounts_get",
+    "list_social_ideas_social_ideas_get",
     "list_social_posts_social_posts_get",
     "list_sync_errors_audience_syncs__config_id__errors_get",
     "list_sync_runs_audience_syncs__config_id__runs_get",
+    "move_ad_creative_to_draft_ad_creatives__creative_id__move_to_draft_post",
     "move_ad_creative_to_gallery_ad_creatives__creative_id__move_to_gallery_post",
+    "preview_ad_campaign_edit_ad_campaigns__campaign_id__edit_preview_post",
     "publish_social_post_social_posts__post_id__publish_post",
     "refresh_all_campaign_statuses_ad_campaigns_status_refresh_post",
     "refresh_campaign_status_ad_campaigns__campaign_id__status_refresh_post",
+    "regenerate_ad_creative_copy_ad_creatives__creative_id__regenerate_copy_post",
     "regenerate_ad_creative_image_ad_creatives__creative_id__regenerate_image_post",
+    "restore_ad_creative_revision_ad_creatives__creative_id__restore_revision_post",
+    "retry_ad_creative_generation_ad_creatives__creative_id__retry_post",
     "retry_campaign_launch_ad_campaigns__campaign_id__retry_post",
+    "review_ad_creative_ad_creatives__creative_id__ai_review_post",
+    "rewrite_ad_creative_field_ad_creatives__creative_id__rewrite_field_post",
+    "save_ad_creative_as_template_ad_creatives__creative_id__save_as_template_post",
     "schedule_social_post_social_posts__post_id__schedule_post",
+    "set_campaign_ad_status_ad_campaigns__campaign_id__ads__ad_id__status_post",
     "trigger_audience_sync_audience_syncs__config_id__trigger_post",
+    "update_ad_campaign_ad_campaigns__campaign_id__put",
     "update_ad_creative_ad_creatives__creative_id__patch",
     "update_audience_sync_audience_syncs__config_id__patch",
-    "update_social_post_social_posts__post_id__patch",
-    "get_ad_creative_ad_creatives__creative_id__get"
+    "update_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__patch",
+    "update_social_post_social_posts__post_id__patch"
   ],
   "components": [
     {
@@ -146,10 +171,12 @@
       "file": "components/social-screen.tsx",
       "purpose": "Finished social page: posts by status with a New post composer sheet, and connected accounts.",
       "operations": [
-        "list_social_posts_social_posts_get"
+        "list_social_posts_social_posts_get",
+        "disconnect_social_account_social_accounts__account_id__delete"
       ],
       "tiers": [
-        "read"
+        "read",
+        "destructive"
       ]
     },
     {
@@ -237,6 +264,108 @@
         "external",
         "destructive"
       ]
+    },
+    {
+      "name": "CampaignAds",
+      "file": "components/campaign-ads.tsx",
+      "purpose": "The ads inside a campaign: list, edit, pause or activate, archive and add (each confirmed).",
+      "operations": [
+        "update_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__patch",
+        "list_campaign_ads_ad_campaigns__campaign_id__ads_get",
+        "set_campaign_ad_status_ad_campaigns__campaign_id__ads__ad_id__status_post",
+        "archive_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__delete",
+        "create_campaign_ad_ad_campaigns__campaign_id__ads_post"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CampaignEditor",
+      "file": "components/campaign-editor.tsx",
+      "purpose": "Edit a live ad campaign: name, budget, end date, spend cap, pause or resume; previewed, then confirmed.",
+      "operations": [
+        "preview_ad_campaign_edit_ad_campaigns__campaign_id__edit_preview_post",
+        "update_ad_campaign_ad_campaigns__campaign_id__put",
+        "get_ad_campaign_ad_campaigns__campaign_id__get",
+        "get_campaign_editable_fields_ad_campaigns__campaign_id__editable_get"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "CreativeConcepts",
+      "file": "components/creative-concepts.tsx",
+      "purpose": "Concept board: creative directions to react to before generating (confirmed AI spend).",
+      "operations": [
+        "generate_ad_concepts_ad_creatives_concepts_post"
+      ],
+      "tiers": [
+        "billable"
+      ]
+    },
+    {
+      "name": "CreativeRevisions",
+      "file": "components/creative-revisions.tsx",
+      "purpose": "Saved versions of an ad creative with restore.",
+      "operations": [
+        "list_ad_creative_revisions_ad_creatives__creative_id__revisions_get",
+        "restore_ad_creative_revision_ad_creatives__creative_id__restore_revision_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "CreativeTools",
+      "file": "components/creative-tools.tsx",
+      "purpose": "AI tools for a creative: edit by instruction, rewrite a field, review, other sizes, retry, template.",
+      "operations": [
+        "get_ad_creative_specs_ad_creatives_specs_get",
+        "update_ad_creative_ad_creatives__creative_id__patch",
+        "apply_ad_creative_review_findings_ad_creatives__creative_id__ai_review_apply_post",
+        "move_ad_creative_to_draft_ad_creatives__creative_id__move_to_draft_post",
+        "save_ad_creative_as_template_ad_creatives__creative_id__save_as_template_post",
+        "chat_edit_ad_creative_ad_creatives__creative_id__chat_edit_post",
+        "regenerate_ad_creative_copy_ad_creatives__creative_id__regenerate_copy_post",
+        "rewrite_ad_creative_field_ad_creatives__creative_id__rewrite_field_post",
+        "review_ad_creative_ad_creatives__creative_id__ai_review_post",
+        "create_ad_creative_size_set_ad_creatives__creative_id__size_set_post",
+        "retry_ad_creative_generation_ad_creatives__creative_id__retry_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable"
+      ]
+    },
+    {
+      "name": "SocialIdeas",
+      "file": "components/social-ideas.tsx",
+      "purpose": "Post ideas mined from signals and content, with a Draft a post action.",
+      "operations": [
+        "list_social_ideas_social_ideas_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SocialPerformance",
+      "file": "components/social-performance.tsx",
+      "purpose": "Social post performance: totals and per-day numbers, and the numbers of one post.",
+      "operations": [
+        "get_social_analytics_social_analytics_get",
+        "get_social_post_metrics_social_posts__post_id__metrics_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [
@@ -253,6 +382,10 @@
     {
       "file": "lib/social-ads-types.ts",
       "purpose": "Post, account, campaign, creative and sync shapes; time helpers (localInputToIso, formatInstant, formatDateOnly), metricsFor and listOf."
+    },
+    {
+      "file": "lib/ads-extra.ts",
+      "purpose": "Helpers for the ads and social management components: open-dict readers, editable-field map, campaign edit diff."
     }
   ],
   "recipes": [

package/blocks/social-ads/components/audience-sync-detail.tsx

@@ -17,6 +17,7 @@
 import { useState } from "react";
 import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
@@ -55,10 +56,14 @@ interface SyncError { id: number; error_message?: string; started_at?: string }
 
 const EMPTY_LAUNCH = { name: "", objective: "", daily_budget: "", currency: "USD", destination_url: "", creative_image_url: "", headline: "", primary_text: "", start_date: "", end_date: "" };
 
+/** The runs and errors APIs have no paging: a full read is announced under the list. */
+const RUN_LIMIT = 20;
+const ERROR_LIMIT = 10;
+
 function Runs({ syncId }: { syncId: number }) {
   const [confirm, setConfirm] = useState(false);
   const [runs, setRuns] = useState<SyncRun[] | null>(null);
-  const load = useG8Mutation(async () => { setRuns(listOf<SyncRun>((await g8Get(`/audience-syncs/${syncId}/runs`, { limit: 20 })).data, "runs")); });
+  const load = useG8Mutation(async () => { setRuns(listOf<SyncRun>((await g8Get(`/audience-syncs/${syncId}/runs`, { limit: RUN_LIMIT })).data, "runs")); });
   return (
     <SectionCard title="Runs" description="Loading past runs is a billable read, so it asks first.">
       {runs == null ? <Button size="sm" variant="outline" onClick={() => setConfirm(true)}>Load runs</Button> : runs.length === 0 ? <p className="text-sm text-muted-foreground">No runs yet.</p> : (
@@ -73,6 +78,7 @@ function Runs({ syncId }: { syncId: number }) {
           ))}
         </ul>
       )}
+      {runs ? <FirstNotice shown={runs.length} limit={RUN_LIMIT} noun="runs" /> : null}
       {load.error ? <ApiError error={load.error} onRetry={load.reset} /> : null}
       <ConfirmSpendDialog open={confirm} tier="billable" title="Load sync runs" description="Listing the runs of a sync is classified billable by the API." confirmLabel="Load runs" confirming={load.loading}
         onCancel={() => setConfirm(false)} onConfirm={() => void load.mutate(undefined).then(() => setConfirm(false))} />
@@ -84,7 +90,7 @@ export function AudienceSyncDetail({ syncId, onClose, onExpand, onCollapse, onCh
   const brand = useBrand();
   const { ask, dialog, failure } = useConfirmAction();
   const list = useG8Query(async (signal) => listOf<AudienceSyncConfig>((await g8Get("/audience-syncs", undefined, { signal })).data), []);
-  const errors = useG8Query(async (signal) => listOf<SyncError>((await g8Get(`/audience-syncs/${syncId}/errors`, { limit: 10 }, { signal })).data), [syncId]);
+  const errors = useG8Query(async (signal) => listOf<SyncError>((await g8Get(`/audience-syncs/${syncId}/errors`, { limit: ERROR_LIMIT }, { signal })).data), [syncId]);
   const [launch, setLaunch] = useState(EMPTY_LAUNCH);
   const [confirmLaunch, setConfirmLaunch] = useState(false);
   const [notice, setNotice] = useState<string | null>(null);
@@ -154,7 +160,7 @@ export function AudienceSyncDetail({ syncId, onClose, onExpand, onCollapse, onCh
       id: "errors",
       label: "Errors",
       content: errors.loading ? <Skeleton className="h-8 w-full" /> : errors.error ? <ApiError error={errors.error} onRetry={() => void errors.refetch()} /> : (errors.data ?? []).length === 0 ? <p className="text-sm text-muted-foreground">No recent errors.</p> : (
-        <ul className="space-y-1 text-sm">{(errors.data ?? []).map((e) => <li key={e.id}>{e.started_at ? `${formatInstant(e.started_at)}: ` : ""}{e.error_message}</li>)}</ul>
+        <><ul className="space-y-1 text-sm">{(errors.data ?? []).map((e) => <li key={e.id}>{e.started_at ? `${formatInstant(e.started_at)}: ` : ""}{e.error_message}</li>)}</ul><FirstNotice shown={(errors.data ?? []).length} limit={ERROR_LIMIT} noun="errors" /></>
       ),
     },
     {

package/blocks/social-ads/components/audience-sync.tsx

@@ -23,6 +23,7 @@
 import { useState } from "react";
 import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import type { ConfirmTier } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
@@ -49,6 +50,9 @@ type Pending =
 
 const listSize = (l: ListSummary) => l.total ?? l.contact_count ?? l.company_count ?? undefined;
 
+/** The errors API has no paging: a full read is announced under the list. */
+const ERROR_LIMIT = 5;
+
 export function AudienceSync({ onLaunched, onSelectSync, className }: AudienceSyncProps) {
   const brand = useBrand();
   const [list, setList] = useState<ListSummary | null>(null);
@@ -63,7 +67,7 @@ export function AudienceSync({ onLaunched, onSelectSync, className }: AudienceSy
   const [notice, setNotice] = useState<string | null>(null);
 
   const syncs = useG8Query(async (signal) => listOf<AudienceSyncConfig>((await g8Get("/audience-syncs", undefined, { signal })).data), []);
-  const errors = useG8Query(async (signal) => listOf<{ id: number; error_message?: string; started_at?: string }>((await g8Get(`/audience-syncs/${errorsFor}/errors`, { limit: 5 }, { signal })).data), [errorsFor], { enabled: errorsFor != null });
+  const errors = useG8Query(async (signal) => listOf<{ id: number; error_message?: string; started_at?: string }>((await g8Get(`/audience-syncs/${errorsFor}/errors`, { limit: ERROR_LIMIT }, { signal })).data), [errorsFor], { enabled: errorsFor != null });
 
   const work = async (id: number | "new", fn: () => Promise<unknown>, tolerate404 = false) => {
     setBusy(id);
@@ -123,7 +127,7 @@ export function AudienceSync({ onLaunched, onSelectSync, className }: AudienceSy
                 <Button size="sm" variant="ghost" disabled={busy != null} onClick={() => setPending({ kind: "delete", sync: s })}>Delete</Button>
               </div>
             </div>
-            {errorsFor === s.id ? <div className="text-xs">{errors.loading ? "Loading..." : (errors.data ?? []).length === 0 ? "No recent errors." : <ul>{(errors.data ?? []).map((e) => <li key={e.id}>{formatInstant(e.started_at)}: {e.error_message}</li>)}</ul>}</div> : null}
+            {errorsFor === s.id ? <div className="text-xs">{errors.loading ? "Loading..." : (errors.data ?? []).length === 0 ? "No recent errors." : <><ul>{(errors.data ?? []).map((e) => <li key={e.id}>{formatInstant(e.started_at)}: {e.error_message}</li>)}</ul><FirstNotice shown={(errors.data ?? []).length} limit={ERROR_LIMIT} noun="errors" /></>}</div> : null}
             {launch.syncId === s.id ? (
               <form className="grid gap-2 sm:grid-cols-2" onSubmit={(e) => { e.preventDefault(); if (readyToLaunch) setPending({ kind: "launch", sync: s }); }}>
                 {([["name", "Campaign name"], ["objective", "Objective"], ["daily_budget", "Daily budget"], ["destination_url", "Landing page URL"], ["creative_image_url", "Image URL (required on Google)"], ["headline", "Headline"], ["primary_text", "Primary text"]] as const).map(([key, label]) => (

package/blocks/social-ads/components/campaign-ads.tsx

@@ -0,0 +1,166 @@
+"use client";
+
+/**
+ * CampaignAds: the individual ads inside one campaign. See each ad's copy and state, edit an ad, pause or activate it,
+ * archive it, and add a new one.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. listCampaignAds    GET    /ad-campaigns/{id}/ads?include_archived              (read)
+ *   2. updateCampaignAd   PATCH  /ad-campaigns/{id}/ads/{ad}                          (EXTERNAL, confirmed: changes the live ad; only changed fields are sent)
+ *   3. setCampaignAdStatus POST  /ad-campaigns/{id}/ads/{ad}/status { status }        (EXTERNAL, confirmed: starts or stops delivery and spend)
+ *   4. archiveCampaignAd  DELETE /ad-campaigns/{id}/ads/{ad}                          (destructive, confirmed: takes the ad down)
+ *   5. createCampaignAd   POST   /ad-campaigns/{id}/ads                               (EXTERNAL, confirmed: adds an ad to the live campaign)
+ *
+ * Editing a live ad can make the platform replace it and send it to review again; the dialog says so, and the
+ * `consequences` the API returns after an edit are shown. The edit form starts from the loaded ad and sends only what
+ * changed.
+ */
+import { useState } from "react";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useConfirmAction } from "@/g8/components/confirmed-action";
+import { EmptyState } from "@/g8/components/empty-state";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { asRec, num, rowsOf, str } from "../lib/ads-extra";
+import type { Rec } from "../lib/ads-extra";
+
+export interface CampaignAdsProps {
+  campaignId: number;
+  /** The platform the campaign runs on, for the confirm text. */
+  platform?: string;
+  onChanged?: () => void;
+  className?: string;
+}
+
+const FIELDS = [
+  { key: "name", label: "Ad name" },
+  { key: "headline", label: "Headline" },
+  { key: "primary_text", label: "Primary text" },
+  { key: "description", label: "Description" },
+  { key: "cta", label: "Call to action" },
+  { key: "destination_url", label: "Destination URL" },
+] as const;
+type Key = (typeof FIELDS)[number]["key"];
+
+const tone = (s: string) => (["active", "approved", "running"].includes(s) ? "positive" : ["failed", "rejected", "disapproved"].includes(s) ? "negative" : s === "paused" || s === "archived" ? "neutral" : "info") as "positive" | "negative" | "neutral" | "info";
+
+/** The edit body: only fields whose text differs from the saved ad. A URL must be http(s) when changed. */
+export function adChanges(saved: Rec, draft: Record<Key, string>): Partial<Record<Key, string>> {
+  const out: Partial<Record<Key, string>> = {};
+  for (const { key } of FIELDS) if (draft[key].trim() !== str(saved[key]).trim()) out[key] = draft[key].trim();
+  return out;
+}
+
+export const isHttpUrl = (raw: string): boolean => /^https?:\/\/\S+\.\S+$/i.test(raw.trim());
+
+function AdEditor({ ad, base, onClose, onSaved }: { ad: Rec; base: string; onClose: () => void; onSaved: () => void }) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const saved: Record<Key, string> = { name: str(ad.name), headline: str(ad.headline), primary_text: str(ad.primary_text), description: str(ad.description), cta: str(ad.cta), destination_url: str(ad.destination_url) };
+  const [edits, setEdits] = useState<Partial<Record<Key, string>>>({});
+  const draft = { ...saved, ...edits };
+  const changes = adChanges(ad, draft);
+  const urlBad = "destination_url" in changes && changes.destination_url !== "" && !isHttpUrl(changes.destination_url ?? "");
+  const [note, setNote] = useState("");
+  const save = (): void => ask({
+    tier: "external", title: `Save changes to "${str(ad.name) || "this ad"}"`, confirmLabel: "Save to the platform",
+    description: "This changes the ad on the platform. The platform may replace the ad and review it again, so delivery can pause for a while.",
+    run: async () => {
+      const d = asRec((await g8Patch(`${base}/ads/${encodeURIComponent(str(ad.id))}`, changes)).data);
+      const lines = rowsOf<string>(d.consequences).map(String);
+      setNote(`Saved.${d.replaced_platform_ad === true ? " The platform ad was replaced." : ""}${lines.length ? ` ${lines.join(" ")}` : ""}`);
+      setEdits({});
+    },
+    onDone: onSaved,
+  });
+  return (
+    <div className="grid gap-3">
+      {FIELDS.map(({ key, label }) => (
+        <div key={key}><Label htmlFor={`ca-${key}`} className="mb-1">{label}</Label><Input id={`ca-${key}`} value={draft[key]} aria-invalid={key === "destination_url" && urlBad} onChange={(e) => setEdits({ ...edits, [key]: e.target.value })} /></div>
+      ))}
+      {urlBad ? <p role="alert" className="text-error-foreground text-xs">Enter a full address starting with https://.</p> : null}
+      {str(ad.approval_nuance) ? <p className="text-muted-foreground text-xs">{str(ad.approval_nuance)}</p> : null}
+      {note ? <p role="status" className="text-sm">{note}</p> : null}
+      {failure ? <ApiError error={failure} title="The platform did not accept the change" /> : null}
+      <div className="flex justify-end gap-2"><Button variant="outline" onClick={onClose}>Close</Button><Button disabled={Object.keys(changes).length === 0 || urlBad} onClick={save}>Save changes</Button></div>
+      <ConfirmSpendDialog {...dialog} />
+    </div>
+  );
+}
+
+export function CampaignAds({ campaignId, platform, onChanged, className }: CampaignAdsProps) {
+  const base = `/ad-campaigns/${encodeURIComponent(String(campaignId))}`;
+  const { ask, dialog, failure } = useConfirmAction();
+  const [archived, setArchived] = useState(false);
+  const [editing, setEditing] = useState<string | null>(null);
+  const [adding, setAdding] = useState(false);
+  const [fresh, setFresh] = useState<Record<Key, string>>({ name: "", headline: "", primary_text: "", description: "", cta: "", destination_url: "" });
+  const list = useG8Query((signal) => g8Get(`${base}/ads`, { include_archived: archived || undefined }, { signal }), [campaignId, archived]);
+  const ads = rowsOf<Rec>(asRec(list.data?.data).ads);
+  const opened = ads.find((a) => str(a.id) === editing);
+  const changed = (): void => { void list.refetch(); onChanged?.(); };
+  const where = platform || "the platform";
+  const freshBody = Object.fromEntries(Object.entries(fresh).filter(([, v]) => v.trim() !== "").map(([k, v]) => [k, v.trim()]));
+  const freshBad = fresh.destination_url.trim() !== "" && !isHttpUrl(fresh.destination_url);
+
+  return (
+    <div className={className}>
+      <SectionCard title="Ads in this campaign" description="Each ad is a version of the copy and image that is shown."
+        actions={<div className="flex items-center gap-2"><label className="flex items-center gap-1 text-xs"><input type="checkbox" checked={archived} onChange={(e) => setArchived(e.target.checked)} />Show archived</label><Button size="sm" onClick={() => setAdding(true)}>Add an ad</Button></div>}>
+        {list.error ? <ApiError error={list.error} title="Could not load the ads" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? <Skeleton className="h-24 w-full" aria-busy="true" /> : ads.length === 0 ? (
+          <EmptyState compact title="No ads yet" description="Add an ad to this campaign, or generate creatives in the Creatives tab." />
+        ) : (
+          <ul className="grid gap-2">
+            {ads.map((a) => {
+              const status = str(a.status);
+              const live = status === "active";
+              return (
+                <li key={str(a.id)} className="grid gap-2 rounded-md border p-3">
+                  <div className="flex items-center justify-between gap-2">
+                    <div className="min-w-0"><span className="block truncate text-sm font-medium">{str(a.headline) || str(a.name) || `Ad ${str(a.slot_index)}`}</span><span className="text-muted-foreground line-clamp-2 text-xs">{str(a.primary_text)}</span></div>
+                    <StatusPill tone={tone(status)}>{status || "unknown"}</StatusPill>
+                  </div>
+                  {str(a.error_message) ? <p role="alert" className="text-error-foreground text-xs">{str(a.error_message)}</p> : null}
+                  {status !== "archived" ? (
+                    <div className="flex flex-wrap gap-1">
+                      <Button size="sm" variant="outline" aria-label={`Edit ${str(a.name) || str(a.headline) || "ad"}`} onClick={() => setEditing(str(a.id))}>Edit</Button>
+                      {live || status === "paused" ? <Button size="sm" variant="outline" aria-label={`${live ? "Pause" : "Activate"} ${str(a.name) || str(a.headline) || "ad"}`} onClick={() => ask({
+                        tier: "external", title: `${live ? "Pause" : "Activate"} "${str(a.name) || str(a.headline) || "this ad"}"`, confirmLabel: live ? "Pause ad" : "Activate ad",
+                        description: live ? `The ad stops being shown on ${where}.` : `The ad starts being shown on ${where} and spends from the campaign budget once approved.`,
+                        run: () => g8Post(`${base}/ads/${encodeURIComponent(str(a.id))}/status`, { status: live ? "paused" : "active" }), onDone: changed,
+                      })}>{live ? "Pause" : "Activate"}</Button> : null}
+                      <Button size="sm" variant="ghost" aria-label={`Archive ${str(a.name) || str(a.headline) || "ad"}`} onClick={() => ask({
+                        tier: "destructive", title: `Archive "${str(a.name) || str(a.headline) || "this ad"}"`, confirmLabel: "Archive ad", affected: 1,
+                        description: `The ad is taken down on ${where} and hidden here. It can be shown again with "Show archived".`, tolerateStatus: [404],
+                        run: () => g8Delete(`${base}/ads/${encodeURIComponent(str(a.id))}`), onDone: changed,
+                      })}>Archive</Button>
+                    </div>
+                  ) : null}
+                </li>
+              );
+            })}
+          </ul>
+        )}
+        {num(asRec(list.data?.data).count) !== undefined && num(asRec(list.data?.data).count)! > ads.length ? <p role="note" className="text-muted-foreground mt-2 text-xs">Showing {ads.length} of {String(asRec(list.data?.data).count)} ads.</p> : null}
+      </SectionCard>
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      <FormSheet open={Boolean(opened)} onOpenChange={(o) => { if (!o) setEditing(null); }} title="Edit ad" description="Only the fields you change are sent." width="lg">
+        {opened ? <AdEditor key={str(opened.id)} ad={opened} base={base} onClose={() => setEditing(null)} onSaved={changed} /> : null}
+      </FormSheet>
+      <FormSheet open={adding} onOpenChange={setAdding} title="Add an ad" description={`Adds an ad to this live campaign on ${where}.`} width="lg"
+        footer={<><Button variant="outline" onClick={() => setAdding(false)}>Cancel</Button><Button disabled={Object.keys(freshBody).length === 0 || freshBad} onClick={() => ask({
+          tier: "external", title: "Add this ad to the campaign", confirmLabel: "Add ad",
+          description: `The ad is created on ${where} and goes to review. It may start spending once approved.`,
+          run: async () => { await g8Post(`${base}/ads`, freshBody); setFresh({ name: "", headline: "", primary_text: "", description: "", cta: "", destination_url: "" }); setAdding(false); }, onDone: changed,
+        })}>Add ad</Button></>}>
+        {FIELDS.map(({ key, label }) => <div key={key}><Label htmlFor={`cn-${key}`} className="mb-1">{label}</Label><Input id={`cn-${key}`} value={fresh[key]} onChange={(e) => setFresh({ ...fresh, [key]: e.target.value })} /></div>)}
+        {freshBad ? <p role="alert" className="text-error-foreground text-xs">Enter a full address starting with https://.</p> : null}
+      </FormSheet>
+      <ConfirmSpendDialog {...dialog} />
+    </div>
+  );
+}

package/blocks/social-ads/components/campaign-detail.tsx

@@ -3,7 +3,8 @@
 /**
  * CampaignDetail: the complete screen for one ad campaign. Finds the campaign by id (so `?id=` deep links work) and shows
  * every field plus its results for a window, and the actions that fit it: refresh its review status, retry a failed launch,
- * stop and delete. Date-only values are shown in UTC; spend is in the campaign's own currency.
+ * stop and delete. The Ads tab lists, edits, pauses, archives and adds the individual ads (CampaignAds); the Edit tab
+ * previews and applies changes to the live campaign (CampaignEditor). Date-only values are shown in UTC; spend is in the campaign's own currency.
  *
  * SDK operations, in order:
  *   1. listAdCampaigns       GET    /ad-campaigns                      (read)
@@ -27,6 +28,8 @@ import type { AdCampaign, CampaignMetric } from "../lib/social-ads-types";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { AskButton, useConfirmAction } from "@/g8/components/confirmed-action";
 import { useBrand } from "@/g8/hooks/use-brand";
+import { CampaignAds } from "./campaign-ads";
+import { CampaignEditor } from "./campaign-editor";
 
 export interface CampaignDetailProps {
   campaignId: number;
@@ -121,6 +124,8 @@ export function CampaignDetail({ campaignId, onClose, onExpand, onCollapse, onCh
         </SectionCard>
       ),
     },
+    { id: "ads", label: "Ads", content: <CampaignAds campaignId={campaign.id} platform={campaign.platform} onChanged={reload} /> },
+    { id: "edit", label: "Edit", content: <CampaignEditor campaignId={campaign.id} onChanged={reload} /> },
   ];
 
   return (

package/blocks/social-ads/components/campaign-editor.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+/**
+ * CampaignEditor: change a campaign that already exists on an ad platform. Rename it, change the daily budget, the end
+ * date or the spend cap, and pause or resume it. Every change is previewed first and pushed to the platform only after
+ * a confirmation.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. getAdCampaign                GET  /ad-campaigns/{id}                  (read; the saved values the form starts from)
+ *   2. getCampaignEditableFields    GET  /ad-campaigns/{id}/editable         (read; which fields this platform and state accept)
+ *   3. previewAdCampaignEdit        POST /ad-campaigns/{id}/edit-preview     (reads the platform, changes nothing; shows the changes and their consequences)
+ *   4. updateAdCampaign             PUT  /ad-campaigns/{id}                  (EXTERNAL, confirmed: changes the live campaign; only changed fields are sent)
+ *
+ * The form is read-only until both reads have loaded, so it can never save blanks over a real campaign. A field the
+ * platform will not accept is disabled with the platform's own reason. A 200 is not blanket success: a `partial` result
+ * lists which changes failed. The spend cap has no saved value to show, so it only changes when you type one.
+ */
+import { useState } from "react";
+import { Pause, Play } from "lucide-react";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useConfirmAction } from "@/g8/components/confirmed-action";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { asRec, campaignChanges, capabilityOf, dateInput, num, parseMoney, rowsOf, str } from "../lib/ads-extra";
+import type { CampaignEdit, Rec } from "../lib/ads-extra";
+
+export interface CampaignEditorProps {
+  campaignId: number;
+  /** Called after a change reached the platform, so lists and results refresh. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+const strings = (v: unknown): string[] => rowsOf<unknown>(v).map((x) => (typeof x === "string" ? x : str(asRec(x).description) || str(asRec(x).field) || JSON.stringify(x)));
+
+function Form({ campaign, editable, onChanged }: { campaign: Rec; editable: Rec; onChanged: () => void }) {
+  const base = `/ad-campaigns/${encodeURIComponent(str(campaign.id))}`;
+  const { ask, dialog, failure } = useConfirmAction();
+  // Only what the person typed is held as `edits`, shown over the saved copy: a reload never wipes typing, and a field they did not touch follows the server.
+  const saved = { name: str(campaign.name), daily_budget: num(campaign.daily_budget) == null ? "" : String(campaign.daily_budget), end_date: dateInput(campaign.end_date), spend_cap: "" };
+  const [edits, setEdits] = useState<Partial<typeof saved>>({});
+  const draft = { ...saved, ...edits };
+  const setDraft = (next: typeof saved): void => setEdits(Object.fromEntries(Object.entries(next).filter(([k, v]) => v !== saved[k as keyof typeof saved])) as Partial<typeof saved>);
+  const [review, setReview] = useState<{ body: CampaignEdit; changes: string[]; consequences: string[]; warnings: string[] } | null>(null);
+  const [outcome, setOutcome] = useState<{ ok: boolean; lines: string[] } | null>(null);
+  const body = campaignChanges(campaign, draft);
+  const cap = (f: string) => capabilityOf(editable, f);
+  const platform = str(campaign.platform);
+  const currency = str(campaign.currency, "USD");
+  const paused = str(campaign.status) === "paused";
+
+  const preview = useG8Mutation(async () => {
+    const d = asRec((await g8Post(`${base}/edit-preview`, body)).data);
+    setReview({ body, changes: strings(d.changes), consequences: strings(d.consequences), warnings: strings(d.warnings) });
+  });
+  const apply = (b: CampaignEdit | { action: "pause" | "resume" }, title: string, lines: string[]): void => ask({
+    tier: "external", title, confirmLabel: "Apply to the platform",
+    description: <><p>This changes the live campaign on {platform || "the platform"}. {platform ? `${platform} may review it again and a budget change can restart its learning phase.` : ""}</p>{lines.length ? <ul className="mt-2 list-disc pl-5 text-sm">{lines.map((l, i) => <li key={i}>{l}</li>)}</ul> : null}</>,
+    run: async () => {
+      const d = asRec((await g8Put(base, b)).data);
+      const failed = str(d.status) === "partial";
+      setOutcome({ ok: !failed, lines: [...strings(d.changes), ...strings(d.warnings)] });
+      setReview(null);
+      setEdits({});
+    },
+    onDone: onChanged,
+  });
+
+  const field = (key: "name" | "daily_budget" | "end_date" | "spend_cap", label: string, type: string, help?: string) => {
+    const c = cap(key);
+    return (
+      <div>
+        <Label htmlFor={`ce-${key}`} className="mb-1">{label}</Label>
+        <Input id={`ce-${key}`} type={type} value={draft[key]} disabled={!c.editable} onChange={(e) => { setDraft({ ...draft, [key]: e.target.value }); setReview(null); setOutcome(null); }} />
+        {!c.editable ? <p className="text-muted-foreground mt-1 text-xs">{c.reason ?? "The platform does not allow changing this right now."}</p> : help ? <p className="text-muted-foreground mt-1 text-xs">{help}</p> : null}
+      </div>
+    );
+  };
+  const budgetBad = draft.daily_budget.trim() !== "" && cap("daily_budget").editable && parseMoney(draft.daily_budget) === undefined;
+
+  return (
+    <div className="grid gap-4">
+      <form className="grid gap-3 sm:grid-cols-2" onSubmit={(e) => { e.preventDefault(); if (Object.keys(body).length) void preview.mutate(undefined); }}>
+        {field("name", "Name", "text")}
+        {field("daily_budget", `Daily budget (${currency})`, "text", "Spent per day once the platform approves the campaign.")}
+        {field("end_date", "End date", "date")}
+        {field("spend_cap", `Spend cap (${currency})`, "text", "Pauses the campaign once this much is spent. Leave empty to keep the current cap.")}
+        {budgetBad ? <p role="alert" className="text-error-foreground text-xs sm:col-span-2">Enter a positive amount, for example 50 or 49.99.</p> : null}
+        <div className="flex gap-2 sm:col-span-2">
+          <Button type="submit" variant="outline" loading={preview.loading} disabled={Object.keys(body).length === 0 || budgetBad}>Review changes</Button>
+          {cap("status").editable ? (
+            <Button type="button" variant="ghost" onClick={() => apply({ action: paused ? "resume" : "pause" }, paused ? "Resume this campaign" : "Pause this campaign", [paused ? "The campaign starts delivering and spending again." : "The campaign stops delivering and spending."])}>
+              {paused ? <Play className="size-4" /> : <Pause className="size-4" />}{paused ? "Resume campaign" : "Pause campaign"}
+            </Button>
+          ) : null}
+        </div>
+      </form>
+      {preview.error ? <ApiError error={preview.error} title="Could not preview the changes" /> : null}
+      {review ? (
+        <SectionCard title="Review before applying" description="Nothing has changed yet.">
+          {review.changes.length ? <ul className="list-disc pl-5 text-sm">{review.changes.map((c, i) => <li key={i}>{c}</li>)}</ul> : <p className="text-sm">The platform reports no difference for these values.</p>}
+          {review.consequences.map((c, i) => <p key={i} className="text-muted-foreground mt-2 text-xs">{c}</p>)}
+          {review.warnings.map((w, i) => <p key={i} role="alert" className="mt-2 text-sm">{w}</p>)}
+          <div className="mt-3 flex gap-2"><Button onClick={() => apply(review.body, "Apply these changes", review.changes)}>Apply changes</Button><Button variant="ghost" onClick={() => setReview(null)}>Cancel</Button></div>
+        </SectionCard>
+      ) : null}
+      {outcome ? (
+        <p role="status" className="text-sm">{outcome.ok ? "Changes applied." : "Some changes were not applied."}{outcome.lines.length ? ` ${outcome.lines.join(" ")}` : ""}</p>
+      ) : null}
+      {failure ? <ApiError error={failure} title="The platform did not accept the change" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </div>
+  );
+}
+
+export function CampaignEditor({ campaignId, onChanged, className }: CampaignEditorProps) {
+  const base = `/ad-campaigns/${encodeURIComponent(String(campaignId))}`;
+  const campaign = useG8Query((signal) => g8Get(base, undefined, { signal }), [campaignId]);
+  const editable = useG8Query((signal) => g8Get(`${base}/editable`, undefined, { signal }), [campaignId]);
+  const error = campaign.error ?? editable.error;
+  return (
+    <div className={className}>
+      <SectionCard title="Edit campaign" description="Changes go to the ad platform after you confirm.">
+        {error ? <ApiError error={error} title="Could not load the campaign" onRetry={() => { void campaign.refetch(); void editable.refetch(); }} /> : !campaign.data || !editable.data ? <Skeleton className="h-32 w-full" aria-busy="true" /> : (
+          <Form key={campaignId} campaign={asRec(campaign.data.data)} editable={asRec(editable.data.data)} onChanged={() => { void campaign.refetch(); void editable.refetch(); onChanged?.(); }} />
+        )}
+      </SectionCard>
+    </div>
+  );
+}