@graph8/sdk 0.362.0 → 0.373.0

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

@@ -0,0 +1,194 @@
+"use client";
+
+/**
+ * AudienceSyncDetail: the complete screen for one audience sync (a graph8 list sent to an ad platform). Finds it by id (so `?id=`
+ * deep links work) and shows status, cadence, last and next run, and the last error. Tabs: Overview, Runs, Errors, Launch campaign.
+ * Actions: sync now, pause or resume, launch a campaign that targets the audience, delete.
+ *
+ * SDK operations, in order:
+ *   1. listAudienceSyncs   GET    /audience-syncs                    (read)
+ *   2. listSyncErrors      GET    /audience-syncs/{id}/errors        (read)
+ *   3. listSyncRuns        GET    /audience-syncs/{id}/runs          (billable tier, confirmed before loading)
+ *   4. triggerAudienceSync POST   /audience-syncs/{id}/trigger       (external, confirmed)
+ *   5. updateAudienceSync  PATCH  /audience-syncs/{id}               (external, confirmed; pause or resume)
+ *   6. launchAdCampaign    POST   /audience-syncs/{id}/launch        (external, confirmed with the daily budget; HTTP 200 may carry status "error")
+ *   7. deleteAudienceSync  DELETE /audience-syncs/{id}               (destructive, confirmed; 404 counts as done)
+ */
+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";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { formatInstant, formatMoney, launchOutcome, listOf } from "../lib/social-ads-types";
+import type { AudienceSyncConfig } from "../lib/social-ads-types";
+import { AskButton, useConfirmAction } from "@/g8/components/confirmed-action";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface AudienceSyncDetailProps {
+  syncId: number;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  onChanged?: () => void;
+  /** Called after a campaign was launched. */
+  onLaunched?: () => void;
+}
+
+interface SyncRun {
+  id: number;
+  status?: string | null;
+  started_at?: string | null;
+  finished_at?: string | null;
+  members_added?: number | null;
+  members_removed?: number | null;
+  total_members?: number | null;
+  error_message?: string | null;
+}
+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: 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> : (
+        <ul className="space-y-1 text-sm">
+          {runs.map((r) => (
+            <li key={r.id} className="flex justify-between gap-3">
+              <span>{r.status ?? "unknown"}{r.error_message ? `: ${r.error_message}` : ""}</span>
+              <span className="text-xs text-muted-foreground tabular-nums">
+                {[r.total_members != null ? `${r.total_members.toLocaleString()} members` : null, r.members_added != null ? `+${r.members_added}` : null, r.members_removed != null ? `-${r.members_removed}` : null, r.started_at ? formatInstant(r.started_at) : null].filter(Boolean).join(" · ")}
+              </span>
+            </li>
+          ))}
+        </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))} />
+    </SectionCard>
+  );
+}
+
+export function AudienceSyncDetail({ syncId, onClose, onExpand, onCollapse, onChanged, onLaunched }: AudienceSyncDetailProps) {
+  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: ERROR_LIMIT }, { signal })).data), [syncId]);
+  const [launch, setLaunch] = useState(EMPTY_LAUNCH);
+  const [confirmLaunch, setConfirmLaunch] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
+  const sync = (list.data ?? []).find((s) => s.id === syncId);
+  const changed = () => { void list.refetch(); onChanged?.(); };
+  const doLaunch = useG8Mutation(async () => {
+    const res = await g8Post(`/audience-syncs/${syncId}/launch`, {
+      name: launch.name.trim(), objective: launch.objective.trim() || undefined, daily_budget: Number(launch.daily_budget), currency: launch.currency,
+      destination_url: launch.destination_url.trim(), creative_image_url: launch.creative_image_url.trim() || undefined, headline: launch.headline.trim() || undefined,
+      primary_text: launch.primary_text.trim() || undefined, start_date: launch.start_date || undefined, end_date: launch.end_date || undefined,
+    });
+    const outcome = launchOutcome(res.data);
+    if (!outcome.ok) throw new Error(outcome.message);
+    setLaunch(EMPTY_LAUNCH);
+    setNotice(outcome.message ?? "Campaign sent to the platform.");
+    onLaunched?.();
+  });
+
+  if (list.error) return <ApiError error={list.error} title="Could not load the sync" onRetry={() => void list.refetch()} />;
+  if (!list.data) return <Skeleton className="h-40 w-full" />;
+  if (!sync) return <EmptyState title="Sync not found" description="It may have been deleted." />;
+
+  const datesOk = !launch.start_date || !launch.end_date || launch.end_date >= launch.start_date;
+  const ready = launch.name.trim() && Number(launch.daily_budget) > 0 && /^https?:\/\//.test(launch.destination_url.trim()) && datesOk;
+  const name = sync.platform_audience_name || `List ${sync.audience_id}`;
+
+  const actions = (
+    <div className="flex flex-wrap gap-1">
+      <AskButton ask={ask} label="Sync now" tier="external" title={`Sync "${name}" to ${sync.platform} now`} confirmLabel="Sync now" disabled={!sync.is_active}
+        description={`Pushes the current members of the list to ${sync.platform}.`} run={() => g8Post(`/audience-syncs/${syncId}/trigger`, {})} onDone={() => { setNotice("Sync started."); changed(); }} />
+      <AskButton ask={ask} label={sync.is_active ? "Pause" : "Resume"} tier="external" title={`${sync.is_active ? "Pause" : "Resume"} the ${sync.platform} sync`} confirmLabel={sync.is_active ? "Pause" : "Resume"}
+        description={sync.is_active ? "The audience stops refreshing; people already there stay." : `Resumes refreshing the audience on ${sync.platform}.`}
+        run={() => g8Patch(`/audience-syncs/${syncId}`, { is_active: !sync.is_active })} onDone={changed} />
+      <AskButton ask={ask} label="Delete" variant="ghost" tier="destructive" title={`Delete the ${sync.platform} sync`} confirmLabel="Delete" tolerateStatus={[404]}
+        description={`${brand.linkLabel} stops syncing. The audience that already exists on the platform is not removed from here.`} run={() => g8Delete(`/audience-syncs/${syncId}`)} onDone={() => { changed(); onClose?.(); }} />
+    </div>
+  );
+
+  const input = (key: keyof typeof EMPTY_LAUNCH, label: string, type = "text") => (
+    <div className="flex flex-col gap-1" key={key}>
+      <Label htmlFor={`sd-${key}`}>{label}</Label>
+      <Input id={`sd-${key}`} type={type} value={launch[key]} onChange={(e) => setLaunch({ ...launch, [key]: e.target.value })} />
+    </div>
+  );
+  const tabs = [
+    {
+      id: "overview",
+      label: "Overview",
+      content: (
+        <div className="space-y-3">
+          <KeyValueList columns={2} items={[
+            { label: "Platform", value: sync.platform },
+            { label: "List", value: `${sync.audience_id}` },
+            { label: "Mode", value: sync.mode },
+            { label: "Refresh every", value: `${sync.refresh_cadence_hours} h` },
+            { label: "Last sync", value: sync.last_sync_at ? formatInstant(sync.last_sync_at) : "not synced yet" },
+            { label: "Next sync", value: sync.next_sync_at ? formatInstant(sync.next_sync_at) : "-" },
+          ]} />
+          {sync.status_detail ? <p className="text-sm text-muted-foreground">{sync.status_detail}</p> : null}
+          {sync.last_sync_error ? <p role="alert" className="text-sm text-error-foreground">{sync.last_sync_error}</p> : null}
+          {notice ? <p role="status" className="text-sm text-muted-foreground">{notice}</p> : null}
+        </div>
+      ),
+    },
+    { id: "runs", label: "Runs", content: <Runs syncId={syncId} /> },
+    {
+      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><FirstNotice shown={(errors.data ?? []).length} limit={ERROR_LIMIT} noun="errors" /></>
+      ),
+    },
+    {
+      id: "launch",
+      label: "Launch campaign",
+      content: (
+        <SectionCard title="Launch a campaign on this audience" description={`Creates the campaign on ${sync.platform}. Spend is billed by the platform.`}>
+          <form className="grid gap-2 sm:grid-cols-2" onSubmit={(e) => { e.preventDefault(); if (ready) setConfirmLaunch(true); }}>
+            {input("name", "Campaign name")}{input("objective", "Objective")}{input("daily_budget", "Daily budget", "number")}{input("destination_url", "Landing page URL")}
+            {input("creative_image_url", "Image URL (required on Google)")}{input("headline", "Headline")}{input("primary_text", "Primary text")}
+            <div className="flex flex-col gap-1"><Label htmlFor="sd-currency">Currency</Label>
+              <select id="sd-currency" className="h-9 rounded-md border bg-background px-2" value={launch.currency} onChange={(e) => setLaunch({ ...launch, currency: e.target.value })}>{["USD", "EUR", "GBP", "CAD", "AUD"].map((c) => <option key={c} value={c}>{c}</option>)}</select></div>
+            {input("start_date", "Start date", "date")}{input("end_date", "End date", "date")}
+            <div><Button type="submit" size="sm" disabled={!ready || doLaunch.loading}>Review launch</Button>{!datesOk ? <p role="alert" className="mt-1 text-xs text-error-foreground">The end date is before the start date.</p> : null}</div>
+          </form>
+          {doLaunch.error ? <ApiError error={doLaunch.error} title="Launch failed" /> : null}
+          <ConfirmSpendDialog open={confirmLaunch} tier="external" title={`Launch a campaign on ${sync.platform}`} confirmLabel="Launch" confirming={doLaunch.loading}
+            description={`Creates the campaign on ${sync.platform}, targeting the synced audience, at ${formatMoney(Number(launch.daily_budget), launch.currency)} per day. Once the platform approves it, it spends from your ad account; ${brand.linkLabel} credits are not used for that spend.`}
+            onCancel={() => setConfirmLaunch(false)} onConfirm={() => void doLaunch.mutate(undefined).then(() => setConfirmLaunch(false))} />
+        </SectionCard>
+      ),
+    },
+  ];
+  return (
+    <>
+      <DetailPanel title={name} subtitle={`on ${sync.platform}`} badges={<StatusPill tone={sync.is_active ? "positive" : "neutral"}>{sync.is_active ? sync.status ?? "active" : "paused"}</StatusPill>} actions={actions} tabs={tabs} onClose={onClose} onExpand={onExpand} onCollapse={onCollapse} />
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </>
+  );
+}

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";
@@ -32,10 +33,13 @@ import { ListPicker } from "@/g8/lists/components/list-picker";
 import type { ListSummary } from "@/g8/lists/components/list-picker";
 import { AD_PLATFORMS, formatInstant, formatMoney, launchOutcome, listOf } from "../lib/social-ads-types";
 import type { AudienceSyncConfig } from "../lib/social-ads-types";
+import { DEFAULT_BRAND, useBrand } from "@/g8/hooks/use-brand";
 
 export interface AudienceSyncProps {
   /** Called after a campaign was launched, for example to refresh an AdCampaignList. */
   onLaunched?: () => void;
+  /** Called when a person opens a sync (show an AudienceSyncDetail). */
+  onSelectSync?: (sync: AudienceSyncConfig) => void;
   className?: string;
 }
 
@@ -46,7 +50,11 @@ type Pending =
 
 const listSize = (l: ListSummary) => l.total ?? l.contact_count ?? l.company_count ?? undefined;
 
-export function AudienceSync({ onLaunched, className }: AudienceSyncProps) {
+/** 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);
   const [platform, setPlatform] = useState<string>("meta");
   const [mode, setMode] = useState("mirror");
@@ -59,7 +67,7 @@ export function AudienceSync({ onLaunched, className }: AudienceSyncProps) {
   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);
@@ -87,7 +95,7 @@ export function AudienceSync({ onLaunched, className }: AudienceSyncProps) {
 
   const datesOk = !launch.start_date || !launch.end_date || launch.end_date >= launch.start_date; // YYYY-MM-DD compares as text
   const readyToLaunch = launch.name.trim() && Number(launch.daily_budget) > 0 && /^https?:\/\//.test(launch.destination_url.trim()) && datesOk;
-  const meta = describe(pending, platform, formatMoney(Number(launch.daily_budget), launch.currency));
+  const meta = describe(pending, platform, formatMoney(Number(launch.daily_budget), launch.currency), brand.linkLabel);
   return (
     <div className={`flex flex-col gap-5 ${className ?? ""}`}>
       <section className="flex flex-col gap-2 rounded-md border p-3" aria-label="New audience sync">
@@ -104,12 +112,12 @@ export function AudienceSync({ onLaunched, className }: AudienceSyncProps) {
       {notice ? <p role="status" className="text-sm text-muted-foreground">{notice}</p> : null}
       {syncs.error ? <ApiError error={syncs.error} title="Could not load syncs" onRetry={() => void syncs.refetch()} /> : null}
       {syncs.loading && !syncs.data ? <Skeleton className="h-20 w-full" /> : null}
-      {!syncs.loading && !syncs.error && (syncs.data ?? []).length === 0 ? <EmptyState title="No audience syncs yet" description="Pick a list above and the platform to send it to. The ad account must be connected in graph8 first." /> : null}
+      {!syncs.loading && !syncs.error && (syncs.data ?? []).length === 0 ? <EmptyState title="No audience syncs yet" description={`Pick a list above and the platform to send it to. The ad account must be connected in ${brand.linkLabel} first.`} /> : null}
       <ul className="flex flex-col gap-2">
         {(syncs.data ?? []).map((s) => (
           <li key={s.id} className="flex flex-col gap-2 rounded-md border p-3" data-testid="sync" aria-busy={busy === s.id}>
             <div className="flex flex-wrap items-center justify-between gap-2">
-              <div><p className="text-sm font-medium">{s.platform_audience_name || `List ${s.audience_id}`} on {s.platform}</p>
+              <div>{onSelectSync ? <button type="button" className="text-left text-sm font-medium hover:underline" onClick={() => onSelectSync(s)}>{s.platform_audience_name || `List ${s.audience_id}`} on {s.platform}</button> : <p className="text-sm font-medium">{s.platform_audience_name || `List ${s.audience_id}`} on {s.platform}</p>}
                 <p className="text-xs text-muted-foreground">{s.is_active ? s.status ?? "active" : "paused"} · {s.last_sync_at ? `last synced ${formatInstant(s.last_sync_at)}` : "not synced yet"}{s.last_sync_error ? ` · ${s.last_sync_error}` : ""}</p></div>
               <div className="flex flex-wrap gap-1">
                 <Button size="sm" variant="outline" loading={busy === s.id} disabled={busy != null || !s.is_active} onClick={() => setPending({ kind: "trigger", sync: s })}>Sync now</Button>
@@ -119,7 +127,7 @@ export function AudienceSync({ onLaunched, className }: AudienceSyncProps) {
                 <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]) => (
@@ -139,12 +147,12 @@ export function AudienceSync({ onLaunched, className }: AudienceSyncProps) {
   );
 }
 
-function describe(p: Pending | null, platform: string, budget: string): { tier: ConfirmTier; title: string; text: string; label: string; recipients?: number; affected?: number } {
+function describe(p: Pending | null, platform: string, budget: string, brandLabel: string = DEFAULT_BRAND.linkLabel): { tier: ConfirmTier; title: string; text: string; label: string; recipients?: number; affected?: number } {
   if (!p) return { tier: "external", title: "", text: "", label: "Confirm" };
   if (p.kind === "create") return { tier: "external", title: `Send "${p.list.title}" to ${platform}`, label: "Create sync", recipients: listSize(p.list), text: `Sends the contacts of this list to ${platform} as a custom audience (matched on hashed identifiers) and keeps it refreshed. Anyone matched becomes targetable by your ads there.` };
   const s = p.sync;
   if (p.kind === "trigger") return { tier: "external", title: `Sync "${s.platform_audience_name || s.audience_id}" to ${s.platform} now`, label: "Sync now", text: `Pushes the current members of the list to ${s.platform}.` };
   if (p.kind === "toggle") return { tier: "external", title: `${s.is_active ? "Pause" : "Resume"} the ${s.platform} sync`, label: s.is_active ? "Pause" : "Resume", text: s.is_active ? "The audience stops refreshing; people already there stay." : `Resumes refreshing the audience on ${s.platform}.` };
-  if (p.kind === "delete") return { tier: "destructive", title: `Delete the ${s.platform} sync`, label: "Delete", text: "graph8 stops syncing. The audience that already exists on the platform is not removed from here." };
-  return { tier: "external", title: `Launch a campaign on ${s.platform}`, label: "Launch", text: `Creates the campaign on ${s.platform}, targeting the synced audience, at ${budget} per day. Once the platform approves it, it spends from your ad account; graph8 credits are not used for that spend.` };
+  if (p.kind === "delete") return { tier: "destructive", title: `Delete the ${s.platform} sync`, label: "Delete", text: `${brandLabel} stops syncing. The audience that already exists on the platform is not removed from here.` };
+  return { tier: "external", title: `Launch a campaign on ${s.platform}`, label: "Launch", text: `Creates the campaign on ${s.platform}, targeting the synced audience, at ${budget} per day. Once the platform approves it, it spends from your ad account; ${brandLabel} credits are not used for that spend.` };
 }

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

@@ -0,0 +1,138 @@
+"use client";
+
+/**
+ * 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. 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)
+ *   2. getPerCampaignMetrics GET    /ad-campaigns/metrics?days         (read)
+ *   3. refreshCampaignStatus POST   /ad-campaigns/{id}/status-refresh  (external, confirmed)
+ *   4. retryCampaignLaunch   POST   /ad-campaigns/{id}/retry           (external, confirmed; HTTP 200 may carry status "error")
+ *   5. deleteAdCampaign      DELETE /ad-campaigns/{id}                 (destructive, confirmed; 502 = still live on the platform)
+ */
+import { useState } from "react";
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { formatDateOnly, formatInstant, formatMoney, launchOutcome, listOf, metricsFor } from "../lib/social-ads-types";
+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;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  onChanged?: () => void;
+  /** Open the audience sync this campaign targets. */
+  onOpenSync?: (syncId: number) => void;
+}
+
+const tone = (s: string) => (["active", "approved", "running"].includes(s) ? "positive" : s === "failed" || s === "rejected" ? "negative" : s === "paused" ? "neutral" : "info") as "positive" | "negative" | "neutral" | "info";
+
+export function CampaignDetail({ campaignId, onClose, onExpand, onCollapse, onChanged, onOpenSync }: CampaignDetailProps) {
+  const brand = useBrand();
+  const { ask, dialog, failure } = useConfirmAction();
+  const [days, setDays] = useState(30);
+  const list = useG8Query(async (signal) => listOf<AdCampaign>((await g8Get("/ad-campaigns", undefined, { signal })).data), []);
+  const metrics = useG8Query(async (signal) => listOf<CampaignMetric>((await g8Get("/ad-campaigns/metrics", { days }, { signal })).data, "metrics"), [days]);
+  const campaign = (list.data ?? []).find((c) => c.id === campaignId);
+  const reload = () => {
+    void list.refetch();
+    void metrics.refetch();
+    onChanged?.();
+  };
+
+  if (list.error) return <ApiError error={list.error} title="Could not load the campaign" onRetry={() => void list.refetch()} />;
+  if (!list.data) return <Skeleton className="h-40 w-full" />;
+  if (!campaign) return <EmptyState title="Campaign not found" description="It may have been deleted." />;
+  const m = metricsFor(campaign, metrics.data ?? []);
+
+  const actions = (
+    <div className="flex flex-wrap gap-1">
+      <AskButton ask={ask} label="Refresh status" tier="external" title={`Refresh "${campaign.name}"`} confirmLabel="Refresh"
+        description={`Asks ${campaign.platform} for this campaign's current review state.`} run={() => g8Post(`/ad-campaigns/${campaign.id}/status-refresh`, {})} onDone={reload} />
+      {campaign.status === "failed" ? (
+        <AskButton ask={ask} label="Retry launch" tier="external" title={`Retry launching "${campaign.name}"`} confirmLabel="Retry launch"
+          description={`Sends the campaign to ${campaign.platform} again. It may start spending on that platform once approved.`}
+          run={async () => {
+            const outcome = launchOutcome((await g8Post(`/ad-campaigns/${campaign.id}/retry`, {})).data);
+            if (!outcome.ok) throw new Error(outcome.message);
+          }}
+          onDone={reload} />
+      ) : null}
+      <AskButton ask={ask} label="Stop and delete" variant="ghost" tier="destructive" title={`Stop and delete "${campaign.name}"`} confirmLabel="Stop and delete"
+        description={`Stops the campaign on ${campaign.platform} first, then removes it from ${brand.linkLabel} together with its history. This cannot be undone. If ${campaign.platform} refuses to stop it, the campaign stays live and keeps spending.`}
+        tolerateStatus={[404]}
+        mapError={(err) => ((err as { status?: number })?.status === 502 ? new Error(`${campaign.platform} refused to stop "${campaign.name}". It is STILL LIVE and may keep spending: stop it in the platform's own ads manager.`) : err)}
+        run={() => g8Delete(`/ad-campaigns/${campaign.id}`)} onDone={() => { reload(); onClose?.(); }} />
+    </div>
+  );
+
+  const tabs = [
+    {
+      id: "overview",
+      label: "Overview",
+      content: (
+        <div className="space-y-4">
+          <KeyValueList columns={2} items={[
+            { label: "Platform", value: campaign.platform },
+            { label: "Objective", value: campaign.objective ?? "-" },
+            { label: "Daily budget", value: formatMoney(campaign.daily_budget, campaign.currency) },
+            { label: "Ads", value: campaign.ad_count ?? "-" },
+            { label: "Starts", value: formatDateOnly(campaign.start_date) || "-" },
+            { label: "Ends", value: formatDateOnly(campaign.end_date) || "-" },
+            { label: "Launched", value: campaign.launched_at ? formatInstant(campaign.launched_at) : "-" },
+            { label: "Platform campaign id", value: campaign.platform_campaign_id ?? "-" },
+          ]} />
+          {onOpenSync ? <button type="button" className="text-sm underline" onClick={() => onOpenSync(campaign.sync_config_id)}>Open its audience sync</button> : null}
+        </div>
+      ),
+    },
+    {
+      id: "results",
+      label: "Results",
+      content: (
+        <SectionCard title="Results" description={`Last ${days} days`} actions={
+          <select aria-label="Results window" className="h-8 rounded-md border bg-background px-2 text-sm" value={days} onChange={(e) => setDays(Number(e.target.value))}>
+            {[7, 30, 90].map((d) => <option key={d} value={d}>Last {d} days</option>)}
+          </select>
+        }>
+          {metrics.error ? <p className="text-sm text-muted-foreground">Results are unavailable right now.</p> : m ? (
+            <KeyValueList columns={2} items={[
+              { label: "Spend", value: formatMoney(m.spend, m.currency ?? campaign.currency) },
+              { label: "Impressions", value: m.impressions.toLocaleString() },
+              { label: "Clicks", value: m.clicks.toLocaleString() },
+              { label: "Conversions", value: m.conversions != null ? m.conversions.toLocaleString() : "-" },
+              { label: "CTR", value: m.impressions ? `${((m.clicks / m.impressions) * 100).toFixed(2)}%` : "-" },
+              { label: "CPC", value: m.clicks ? formatMoney(m.spend / m.clicks, m.currency ?? campaign.currency) : "-" },
+            ]} />
+          ) : <p className="text-sm text-muted-foreground">No results yet for this window.</p>}
+        </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 (
+    <>
+      <DetailPanel title={campaign.name} subtitle={campaign.platform} badges={<StatusPill tone={tone(campaign.status)}>{campaign.status}</StatusPill>} actions={actions} tabs={tabs} onClose={onClose} onExpand={onExpand} onCollapse={onCollapse} />
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </>
+  );
+}