@graph8/sdk 0.361.0 → 0.370.0

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

@@ -0,0 +1,152 @@
+"use client";
+
+/**
+ * AdsScreen: the finished paid-ads page. Three tabs:
+ *   Campaigns  Meta, LinkedIn, Google and X campaigns with budget, dates and results; refresh status, retry a failed launch,
+ *              stop and delete (AdCampaignList).
+ *   Audiences  send a list to an ad platform as a custom audience, keep it synced, and launch a campaign that targets it
+ *              (AudienceSync). A launched campaign moves you to the Campaigns tab.
+ *   Creatives  generate, edit and organize AI ad creatives (CreativeGallery).
+ *
+ * Every campaign, audience sync and creative opens a complete detail screen (`?id=`, full page with `?view=full`):
+ * CampaignDetail, AudienceSyncDetail (runs, errors, launch) and CreativeDetail (edit copy, new image, gallery, delete).
+ *
+ * SDK operations: one read of getPerCampaignMetrics (30 days) for the stat strip. Composes AdCampaignList (external +
+ * destructive), AudienceSync (external, sends people's data to a third party) and CreativeGallery (billable): every
+ * spend, send or delete is confirmed by those parts. Ad accounts are connected in the graph8 app (OAuth), see the link-out card.
+ */
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Target } from "lucide-react";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import type { StatItem } from "@/g8/components/screen/stat-strip";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { listOf } from "../lib/social-ads-types";
+import type { CampaignMetric } from "../lib/social-ads-types";
+import { AdCampaignList } from "./ad-campaign-list";
+import { AudienceSync } from "./audience-sync";
+import { AudienceSyncDetail } from "./audience-sync-detail";
+import { CampaignDetail } from "./campaign-detail";
+import { CreativeDetail } from "./creative-detail";
+import { CreativeGallery } from "./creative-gallery";
+import { brandUrl, useBrand } from "@/g8/hooks/use-brand";
+
+export interface AdsScreenProps {
+  /** Where "Connect ad accounts" sends people. Default: graph8 Settings > Integrations. */
+  connectUrl?: string;
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+/** Integrations settings on the platform's web app, resolved against the brand. */
+const APP_PATH = "/studio/settings?tab=integrations";
+const TABS = ["campaigns", "audiences", "creatives"] as const;
+type Tab = (typeof TABS)[number];
+
+function useStats(refreshKey: number): StatItem[] | undefined {
+  const q = useG8Query(async (signal) => listOf<CampaignMetric>((await g8Get("/ad-campaigns/metrics", { days: 30 }, { signal })).data, "metrics"), [refreshKey]);
+  if (q.error || !q.data) return undefined;
+  // The metrics payload is open-shaped in the contract: sum only values that are really numbers, and omit what is absent.
+  const rows = q.data;
+  const total = (k: "impressions" | "clicks" | "spend"): number | undefined => {
+    const nums = rows.map((r) => r[k]).filter((v): v is number => typeof v === "number");
+    return nums.length ? nums.reduce((s, v) => s + v, 0) : undefined;
+  };
+  const impressions = total("impressions");
+  const clicks = total("clicks");
+  const spend = total("spend");
+  const currencies = new Set(rows.map((r) => r.currency).filter(Boolean));
+  const items: StatItem[] = [];
+  if (spend != null) {
+    // Spend in several currencies cannot be added up honestly: show it only when there is one.
+    const cur = [...currencies][0] ?? "";
+    items.push({ label: "Spend (30 days)", value: currencies.size > 1 ? "Mixed currencies" : `${cur} ${spend.toLocaleString(undefined, { maximumFractionDigits: 2 })}`.trim() });
+  }
+  if (impressions != null) items.push({ label: "Impressions", value: impressions.toLocaleString() });
+  if (clicks != null) items.push({ label: "Clicks", value: clicks.toLocaleString() });
+  if (impressions && clicks != null) items.push({ label: "CTR", value: `${((clicks / impressions) * 100).toFixed(2)}%` });
+  return items.length ? items : undefined;
+}
+
+export function AdsScreen(props: AdsScreenProps) {
+  const brand = useBrand();
+  const connectUrl = props.connectUrl ?? brandUrl(brand, APP_PATH);
+  const [tabValue, setTab] = useUrlState("tab", "campaigns");
+  const tab: Tab = (TABS as readonly string[]).includes(tabValue) ? (tabValue as Tab) : "campaigns";
+  const [refreshKey, setRefreshKey] = useState(0);
+  const [id, setId] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const expanded = view === "full" && Boolean(id);
+  const stats = useStats(refreshKey);
+  const close = () => {
+    setId("");
+    setView("");
+  };
+  const bump = () => setRefreshKey((k) => k + 1);
+  const panel = {
+    onClose: close,
+    onExpand: expanded ? undefined : () => setView("full"),
+    onCollapse: expanded ? () => setView("") : undefined,
+    onChanged: bump,
+  };
+  const split = (list: ReactNode, detail: ReactNode) => (
+    <SplitView
+      detailOpen={Boolean(id)}
+      onCloseDetail={close}
+      expanded={expanded}
+      onExpandedChange={(next) => setView(next ? "full" : "")}
+      detailWidth="lg"
+      list={list}
+      detail={id ? detail : null}
+    />
+  );
+
+  return (
+    <ScreenLayout
+      title="Ads"
+      description="Sync audiences to ad platforms, launch campaigns and make creatives, with the results next to them."
+      icon={<Target className="size-5" />}
+      actions={props.toolbarActions}
+      tabs={[
+        { id: "campaigns", label: "Campaigns" },
+        { id: "audiences", label: "Audiences" },
+        { id: "creatives", label: "Creatives" },
+      ]}
+      activeTab={tab}
+      onTabChange={(next) => {
+        setTab(next);
+        close();
+      }}
+      stats={tab === "campaigns" ? stats : undefined}
+      className={props.className}
+    >
+      {tab === "campaigns" ? (
+        split(
+          <AdCampaignList refreshKey={refreshKey} onSelectCampaign={(c) => setId(String(c.id))} />,
+          <CampaignDetail key={id} campaignId={Number(id)} {...panel} onOpenSync={(syncId) => { setTab("audiences"); setId(String(syncId)); }} />,
+        )
+      ) : tab === "audiences" ? (
+        <div className="space-y-4">
+          <SectionCard title="Ad accounts" description={`Meta, LinkedIn, Google and X sign-in happens in ${brand.linkLabel}. Connect there, then sync audiences here.`}>
+            <a className="text-sm underline" href={connectUrl} target="_blank" rel="noreferrer">
+              Connect ad accounts in {brand.linkLabel}
+            </a>
+          </SectionCard>
+          {split(
+            <AudienceSync key={refreshKey} onSelectSync={(sync) => setId(String(sync.id))} onLaunched={() => { bump(); }} />,
+            <AudienceSyncDetail key={id} syncId={Number(id)} {...panel} onLaunched={() => { bump(); setTab("campaigns"); close(); }} />,
+          )}
+        </div>
+      ) : (
+        split(
+          <CreativeGallery key={refreshKey} onSelectCreative={(c) => setId(c.id)} />,
+          <CreativeDetail key={id} creativeId={id} {...panel} />,
+        )
+      )}
+    </ScreenLayout>
+  );
+}

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

@@ -0,0 +1,188 @@
+"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 { 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: "" };
+
+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")); });
+  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>
+      )}
+      {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: 10 }, { 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>
+      ),
+    },
+    {
+      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

@@ -32,10 +32,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 +49,8 @@ type Pending =
 
 const listSize = (l: ListSummary) => l.total ?? l.contact_count ?? l.company_count ?? undefined;
 
-export function AudienceSync({ onLaunched, className }: AudienceSyncProps) {
+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");
@@ -87,7 +91,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 +108,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>
@@ -139,12 +143,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-detail.tsx

@@ -0,0 +1,133 @@
+"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. 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";
+
+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>
+      ),
+    },
+  ];
+
+  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} />
+    </>
+  );
+}