@graph8/sdk 0.308.1 → 0.357.0

package/blocks/social-ads/block.json

@@ -0,0 +1,256 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "social-ads",
+  "title": "Social & ads",
+  "summary": "Compose, schedule and publish social posts; see ad campaigns and their results; generate ad creatives; sync a list to an ad platform and launch a campaign.",
+  "features": [
+    "post composer with AI drafts, draft/schedule/publish, retry-safe and shown in the viewer's time zone",
+    "post list by status with publish, cancel and delete, each with its own spinner",
+    "ad campaigns across Meta, LinkedIn, Google and X with results for 7, 30 or 90 days, status refresh and launch retry",
+    "AI ad creative gallery: generate, follow, edit copy, regenerate the image, move to the gallery",
+    "audience sync from a list to an ad platform, push now, pause, errors, and campaign launch"
+  ],
+  "dependsOn": [
+    "lists"
+  ],
+  "operations": [
+    "cancel_social_post_social_posts__post_id__cancel_post",
+    "create_ad_creative_ad_creatives_post",
+    "create_audience_sync_audience_syncs_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",
+    "generate_social_post_social_posts_generate_post",
+    "get_ad_creative_specs_ad_creatives_specs_get",
+    "get_ad_creative_status_ad_creatives__creative_id__status_get",
+    "get_per_campaign_metrics_ad_campaigns_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_creatives_ad_creatives_get",
+    "list_audience_syncs_audience_syncs_get",
+    "list_social_accounts_social_accounts_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_gallery_ad_creatives__creative_id__move_to_gallery_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_image_ad_creatives__creative_id__regenerate_image_post",
+    "retry_campaign_launch_ad_campaigns__campaign_id__retry_post",
+    "schedule_social_post_social_posts__post_id__schedule_post",
+    "trigger_audience_sync_audience_syncs__config_id__trigger_post",
+    "update_ad_creative_ad_creatives__creative_id__patch",
+    "update_audience_sync_audience_syncs__config_id__patch",
+    "update_social_post_social_posts__post_id__patch"
+  ],
+  "components": [
+    {
+      "name": "PostComposer",
+      "file": "components/post-composer.tsx",
+      "purpose": "Write a post, optionally draft it with AI (billable), save a draft, schedule it for a time in your zone or publish now; scheduling and publishing are confirmed (external).",
+      "operations": [
+        "list_social_accounts_social_accounts_get",
+        "generate_social_post_social_posts_generate_post",
+        "create_social_post_social_posts_post",
+        "update_social_post_social_posts__post_id__patch",
+        "schedule_social_post_social_posts__post_id__schedule_post",
+        "publish_social_post_social_posts__post_id__publish_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "external"
+      ]
+    },
+    {
+      "name": "SocialPostList",
+      "file": "components/social-post-list.tsx",
+      "purpose": "Posts by status with their times; publish, cancel a scheduled post or delete, each confirmed and each row with its own busy state.",
+      "operations": [
+        "list_social_posts_social_posts_get",
+        "publish_social_post_social_posts__post_id__publish_post",
+        "cancel_social_post_social_posts__post_id__cancel_post",
+        "delete_social_post_social_posts__post_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "AdCampaignList",
+      "file": "components/ad-campaign-list.tsx",
+      "purpose": "Ad campaigns with budget, date-only dates and results; refresh review status, retry a failed launch, delete.",
+      "operations": [
+        "list_ad_campaigns_ad_campaigns_get",
+        "get_per_campaign_metrics_ad_campaigns_metrics_get",
+        "refresh_campaign_status_ad_campaigns__campaign_id__status_refresh_post",
+        "refresh_all_campaign_statuses_ad_campaigns_status_refresh_post",
+        "retry_campaign_launch_ad_campaigns__campaign_id__retry_post",
+        "delete_ad_campaign_ad_campaigns__campaign_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CreativeGallery",
+      "file": "components/creative-gallery.tsx",
+      "purpose": "Generate AI ad creatives (billable), follow them while they generate, edit copy, regenerate the image (billable), move to the gallery, delete.",
+      "operations": [
+        "get_ad_creative_specs_ad_creatives_specs_get",
+        "list_ad_creatives_ad_creatives_get",
+        "create_ad_creative_ad_creatives_post",
+        "update_ad_creative_ad_creatives__creative_id__patch",
+        "regenerate_ad_creative_image_ad_creatives__creative_id__regenerate_image_post",
+        "move_ad_creative_to_gallery_ad_creatives__creative_id__move_to_gallery_post",
+        "delete_ad_creative_ad_creatives__creative_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "AudienceSync",
+      "file": "components/audience-sync.tsx",
+      "purpose": "Send a list to an ad platform as an audience, push now, pause or resume, read errors, delete, and launch a campaign on it; every step confirmed with the list size or the daily budget (external).",
+      "operations": [
+        "list_audience_syncs_audience_syncs_get",
+        "create_audience_sync_audience_syncs_post",
+        "trigger_audience_sync_audience_syncs__config_id__trigger_post",
+        "update_audience_sync_audience_syncs__config_id__patch",
+        "list_sync_errors_audience_syncs__config_id__errors_get",
+        "launch_ad_campaign_audience_syncs__config_id__launch_post",
+        "delete_audience_sync_audience_syncs__config_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useSocialAccounts",
+      "file": "hooks/use-social-accounts.ts",
+      "purpose": "Connected social accounts; the account id is the account_ref posts take.",
+      "operations": [
+        "list_social_accounts_social_accounts_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/social-ads-types.ts",
+      "purpose": "Post, account, campaign, creative and sync shapes; time helpers (localInputToIso, formatInstant, formatDateOnly), metricsFor and listOf."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/schedule-post.ts",
+      "title": "Draft a social post with AI, then schedule or publish it",
+      "when": "Posting to a connected LinkedIn account. Generating is billable and saves nothing; scheduling and publishing are external, so get approval for the account and the instant. Keep the created post id so a retry reuses it."
+    },
+    {
+      "file": "recipes/creative-to-gallery.ts",
+      "title": "Generate an ad creative, wait for it, tweak the copy, move it to the gallery",
+      "when": "Producing ad images and copy before a launch. Generation is billable with no advance price. Poll the status until it leaves generating."
+    },
+    {
+      "file": "recipes/sync-audience-and-launch.ts",
+      "title": "Sync a list to an ad platform and launch a campaign on it",
+      "when": "Retargeting from a list. Both steps are external (data goes to the platform, the campaign spends from the ad account). The ad account must already be connected in graph8; dates are YYYY-MM-DD."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "lists-installed",
+      "where": "app",
+      "description": "The lists block is installed (the CLI does it): audiences come from the list picker.",
+      "verify": "components/g8/lists/ exists."
+    },
+    {
+      "id": "proxy-allowlist",
+      "where": "app",
+      "description": "allowedPrefixes in the /api/g8 route includes `social`, `ad-campaigns`, `ad-creatives`, `audience-syncs` and `lists`.",
+      "verify": "GET /api/g8/social/accounts returns 200 when signed in."
+    },
+    {
+      "id": "social-account",
+      "where": "api",
+      "description": "A LinkedIn account is connected in graph8 (Settings, Channels). Connecting needs a browser sign-in and cannot be done through the API.",
+      "verify": "GET /social/accounts returns at least one account."
+    },
+    {
+      "id": "ad-accounts",
+      "where": "api",
+      "description": "Each ad platform account (Meta, LinkedIn, Google, X) is connected in graph8 through the platform's sign-in. Without it, creating a sync or launching fails.",
+      "verify": "Creating a sync for the platform succeeds."
+    },
+    {
+      "id": "credits",
+      "where": "api",
+      "description": "The workspace has credits for AI drafts and ad creatives. The API has no balance read and no advance price for these, so the UI only says credits are used. Ad spend itself is billed by the ad platform.",
+      "verify": "A draft generates."
+    }
+  ],
+  "scopes": [
+    "ads:delete",
+    "ads:read",
+    "ads:run",
+    "campaigns:delete",
+    "campaigns:read",
+    "campaigns:run",
+    "campaigns:write",
+    "integrations:delete",
+    "integrations:read",
+    "integrations:run"
+  ],
+  "defaults": [
+    {
+      "decision": "Account a post uses",
+      "default": "The first connected account; the person can switch",
+      "askHuman": false
+    },
+    {
+      "decision": "AI drafts per request",
+      "default": "3",
+      "askHuman": false
+    },
+    {
+      "decision": "Schedule time zone",
+      "default": "The viewer's own zone, named in the confirmation",
+      "askHuman": false
+    },
+    {
+      "decision": "Audience sync mode and cadence",
+      "default": "Mirror, refreshed every 24 hours",
+      "askHuman": false
+    },
+    {
+      "decision": "Campaign daily budget, dates and destination URL",
+      "default": "None: always typed by the person",
+      "askHuman": true
+    },
+    {
+      "decision": "Who may publish, sync or launch",
+      "default": "Anyone the proxy's authorize lets through",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

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

@@ -0,0 +1,136 @@
+"use client";
+
+/**
+ * AdCampaignList: your ad campaigns on Meta, LinkedIn, Google and X with their status, budget, dates and the
+ * results of the last N days. Refresh a campaign's review status from its platform, retry a failed launch, or delete
+ * one. Launching a NEW campaign is AudienceSync (it starts from a synced audience).
+ *
+ * SDK operations, in order:
+ *   1. listAdCampaigns            GET    /ad-campaigns?platform                 (read)  an array of campaigns; `platform_campaign_id` (else `sync_config_id`) joins them to metrics
+ *   2. getPerCampaignMetrics      GET    /ad-campaigns/metrics?days&platform    (read)  { days, metrics: [{ sync_config_id, platform_campaign_id, impressions, clicks, spend, currency }] }
+ *   3. refreshCampaignStatus      POST   /ad-campaigns/{id}/status-refresh      (external)  asks the ad platform; ConfirmSpendDialog first
+ *      refreshAllCampaignStatuses POST   /ad-campaigns/status-refresh           (external)  every refreshable campaign
+ *   4. retryCampaignLaunch        POST   /ad-campaigns/{id}/retry               (external)  re-sends a failed launch to the platform
+ *   5. deleteAdCampaign           DELETE /ad-campaigns/{id}                     (destructive)  STOPS the live campaign on the platform, then removes it.
+ *        A 502 means the platform refused: the campaign is STILL LIVE and spending, and the list says so.
+ * Retry answers HTTP 200 with `status: "error"` in the body when refused: that is shown as a failure, never as success.
+ * Start and end dates are date-only: shown in UTC so they never slide a day. Spend is in the campaign's own currency.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import type { ConfirmTier } from "@/g8/components/confirm-spend-dialog";
+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 { AD_PLATFORMS, formatDateOnly, formatMoney, launchOutcome, listOf, metricsFor } from "../lib/social-ads-types";
+import type { AdCampaign, CampaignMetric } from "../lib/social-ads-types";
+
+export interface AdCampaignListProps {
+  /** Change to reload, for example after AudienceSync launched a campaign. */
+  refreshKey?: number;
+  className?: string;
+}
+
+type Pending = { kind: "refresh" | "retry" | "delete"; campaign: AdCampaign } | { kind: "refreshAll" };
+const COLUMNS = 8;
+
+function copyFor(p: Pending | null): { tier: ConfirmTier; title: string; text: string; label: string } {
+  if (!p) return { tier: "external", title: "", text: "", label: "Confirm" };
+  if (p.kind === "refreshAll") return { tier: "external", title: "Refresh every campaign's status", text: "Asks each ad platform for the current review state of every campaign. Can take a while; campaigns that did refresh keep their new state if it times out.", label: "Refresh all" };
+  const name = p.campaign.name;
+  if (p.kind === "refresh") return { tier: "external", title: `Refresh "${name}"`, text: `Asks ${p.campaign.platform} for this campaign's current review state.`, label: "Refresh" };
+  if (p.kind === "retry") return { tier: "external", title: `Retry launching "${name}"`, text: `Sends the campaign to ${p.campaign.platform} again. It may start spending on that platform once approved.`, label: "Retry launch" };
+  return { tier: "destructive", title: `Stop and delete "${name}"`, text: `Stops the campaign on ${p.campaign.platform} first, then removes it from graph8 together with its history. This cannot be undone. If ${p.campaign.platform} refuses to stop it, the campaign stays live and keeps spending.`, label: "Stop and delete" };
+}
+
+export function AdCampaignList({ refreshKey = 0, className }: AdCampaignListProps) {
+  const [platform, setPlatform] = useState("");
+  const [days, setDays] = useState(30);
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [failure, setFailure] = useState<unknown>(null);
+
+  const campaigns = useG8Query(async (signal) => listOf<AdCampaign>((await g8Get("/ad-campaigns", { platform: platform || undefined }, { signal })).data), [platform, refreshKey]);
+  const metrics = useG8Query(
+    async (signal) => listOf<CampaignMetric>((await g8Get("/ad-campaigns/metrics", { days, platform: platform || undefined }, { signal })).data, "metrics"),
+    [days, platform, refreshKey],
+  );
+  const rows = campaigns.data ?? [];
+
+  const act = async () => {
+    if (!pending) return;
+    const id = pending.kind === "refreshAll" ? "all" : String(pending.campaign.id);
+    setBusy(id);
+    setFailure(null);
+    try {
+      if (pending.kind === "refreshAll") await g8Post("/ad-campaigns/status-refresh", {});
+      else if (pending.kind === "refresh") await g8Post(`/ad-campaigns/${id}/status-refresh`, {});
+      else if (pending.kind === "retry") {
+        const outcome = launchOutcome((await g8Post(`/ad-campaigns/${id}/retry`, {})).data);
+        if (!outcome.ok) setFailure(new Error(outcome.message));
+      }
+      else await g8Delete(`/ad-campaigns/${id}`);
+    } catch (err) {
+      const status = (err as { status?: number })?.status;
+      if (pending.kind === "delete" && status === 502) setFailure(new Error(`${pending.campaign.platform} refused to stop "${pending.campaign.name}". It is STILL LIVE on the platform and may keep spending: stop it in the platform's own ads manager.`));
+      else if (!(pending.kind === "delete" && status === 404)) setFailure(err);
+    } finally {
+      setBusy(null);
+      setPending(null);
+      await Promise.all([campaigns.refetch(), metrics.refetch()]);
+    }
+  };
+
+  const copy = copyFor(pending);
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center gap-2">
+        <select aria-label="Platform" className="h-9 rounded-md border bg-background px-2" value={platform} onChange={(e) => setPlatform(e.target.value)}>
+          <option value="">All platforms</option>{AD_PLATFORMS.map((p) => <option key={p} value={p}>{p}</option>)}
+        </select>
+        <select aria-label="Results window" className="h-9 rounded-md border bg-background px-2" value={days} onChange={(e) => setDays(Number(e.target.value))}>
+          {[7, 30, 90].map((d) => <option key={d} value={d}>Last {d} days</option>)}
+        </select>
+        <Button size="sm" variant="outline" loading={busy === "all"} disabled={busy != null || rows.length === 0} onClick={() => setPending({ kind: "refreshAll" })}>Refresh all statuses</Button>
+      </div>
+      {campaigns.error ? <ApiError error={campaigns.error} title="Could not load campaigns" onRetry={() => void campaigns.refetch()} /> : null}
+      {metrics.error ? <p role="status" className="text-xs text-muted-foreground">Results are unavailable right now.</p> : null}
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      <div className="overflow-x-auto rounded-md border">
+        <Table>
+          <TableHeader><TableRow>{["Campaign", "Platform", "Status", "Budget / day", "Dates", "Impressions", "Clicks", ""].map((h) => <TableHead key={h || "actions"}>{h}</TableHead>)}</TableRow></TableHeader>
+          <TableBody>
+            {campaigns.loading && !campaigns.data ? <TableRow><TableCell colSpan={COLUMNS}><Skeleton className="h-8 w-full" /></TableCell></TableRow> : null}
+            {!campaigns.loading && !campaigns.error && rows.length === 0 ? <TableRow><TableCell colSpan={COLUMNS}><EmptyState title="No ad campaigns" description="Launch one from a synced audience." /></TableCell></TableRow> : null}
+            {rows.map((c) => {
+              const m = metricsFor(c, metrics.data ?? []);
+              const mine = busy === String(c.id);
+              return (
+                <TableRow key={c.id} data-testid="campaign">
+                  <TableCell><div className="font-medium">{c.name}</div>{m ? <div className="text-xs text-muted-foreground">{formatMoney(m.spend, m.currency ?? c.currency)} spent</div> : null}</TableCell>
+                  <TableCell>{c.platform}</TableCell>
+                  <TableCell>{c.status}</TableCell>
+                  <TableCell>{formatMoney(c.daily_budget, c.currency)}</TableCell>
+                  <TableCell>{formatDateOnly(c.start_date)}{c.end_date ? ` to ${formatDateOnly(c.end_date)}` : ""}</TableCell>
+                  <TableCell>{m ? m.impressions.toLocaleString() : "-"}</TableCell>
+                  <TableCell>{m ? m.clicks.toLocaleString() : "-"}</TableCell>
+                  <TableCell>
+                    <div className="flex gap-1">
+                      <Button size="sm" variant="ghost" loading={mine} disabled={busy != null} onClick={() => setPending({ kind: "refresh", campaign: c })}>Refresh</Button>
+                      {c.status === "failed" ? <Button size="sm" variant="outline" disabled={busy != null} onClick={() => setPending({ kind: "retry", campaign: c })}>Retry</Button> : null}
+                      <Button size="sm" variant="ghost" disabled={busy != null} onClick={() => setPending({ kind: "delete", campaign: c })}>Delete</Button>
+                    </div>
+                  </TableCell>
+                </TableRow>
+              );
+            })}
+          </TableBody>
+        </Table>
+      </div>
+      <ConfirmSpendDialog open={pending != null} tier={copy.tier} title={copy.title} description={copy.text} confirmLabel={copy.label} confirming={busy != null} onConfirm={() => void act()} onCancel={() => setPending(null)} />
+    </div>
+  );
+}

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

@@ -0,0 +1,150 @@
+"use client";
+
+/**
+ * AudienceSync: send a graph8 list to an ad platform as a custom audience (Meta, LinkedIn, Google, X), keep it in sync,
+ * and launch an ad campaign that targets it. Everything here sends people's data to a third party or can start ad
+ * spend, so every action is confirmed with the real scope: which list, how many people, which platform.
+ *
+ * SDK operations, in order:
+ *   1. listAudienceSyncs     GET    /audience-syncs                         (read)  an array of sync configs
+ *   2. createAudienceSync    POST   /audience-syncs { audience_id, platform, mode, refresh_cadence_hours }  (external)  409 if the list+platform pair exists;
+ *        the ad account must already be connected in graph8 (OAuth happens in the app only). ConfirmSpendDialog first with the list size.
+ *   3. triggerAudienceSync   POST   /audience-syncs/{id}/trigger            (external)  push now; ConfirmSpendDialog first
+ *   4. updateAudienceSync    PATCH  /audience-syncs/{id} { is_active }      (external)  pause or resume; ConfirmSpendDialog first
+ *   5. listSyncErrors        GET    /audience-syncs/{id}/errors?limit       (read)  shown under a sync on request
+ *   6. launchAdCampaign      POST   /audience-syncs/{id}/launch { name, objective, daily_budget, ... }  (external)  creates the campaign on the platform;
+ *        ConfirmSpendDialog first with the daily budget in its currency. Start and end are date-only (YYYY-MM-DD), sent as typed, and the end may not
+ *        be before the start. HTTP 200 does NOT mean launched: a refused launch answers 200 with `status: "error"` and a `message` in the body, shown as a failure.
+ *        Google needs `creative_image_url` (a square image); a CreativeGallery image URL fits.
+ *   7. deleteAudienceSync    DELETE /audience-syncs/{id}                     (destructive)  stops syncing; the audience stays on the platform
+ * Each sync has its own busy state; deleting treats a 404 as already 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 type { ConfirmTier } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+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";
+
+export interface AudienceSyncProps {
+  /** Called after a campaign was launched, for example to refresh an AdCampaignList. */
+  onLaunched?: () => void;
+  className?: string;
+}
+
+type Pending =
+  | { kind: "create"; list: ListSummary }
+  | { kind: "trigger" | "toggle" | "delete"; sync: AudienceSyncConfig }
+  | { kind: "launch"; sync: AudienceSyncConfig };
+
+const listSize = (l: ListSummary) => l.total ?? l.contact_count ?? l.company_count ?? undefined;
+
+export function AudienceSync({ onLaunched, className }: AudienceSyncProps) {
+  const [list, setList] = useState<ListSummary | null>(null);
+  const [platform, setPlatform] = useState<string>("meta");
+  const [mode, setMode] = useState("mirror");
+  const [cadence, setCadence] = useState(24);
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [busy, setBusy] = useState<number | "new" | null>(null);
+  const [failure, setFailure] = useState<unknown>(null);
+  const [errorsFor, setErrorsFor] = useState<number | null>(null);
+  const [launch, setLaunch] = useState({ syncId: 0, name: "", objective: "", daily_budget: "", currency: "USD", destination_url: "", creative_image_url: "", headline: "", primary_text: "", start_date: "", end_date: "" });
+  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 work = async (id: number | "new", fn: () => Promise<unknown>, tolerate404 = false) => {
+    setBusy(id);
+    setFailure(null);
+    try { await fn(); } catch (err) { if (!(tolerate404 && (err as { status?: number })?.status === 404)) setFailure(err); }
+    finally { setBusy(null); setPending(null); await syncs.refetch(); }
+  };
+  const confirm = () => {
+    if (!pending) return;
+    if (pending.kind === "create") return void work("new", async () => { await g8Post("/audience-syncs", { audience_id: pending.list.id, platform, mode, refresh_cadence_hours: cadence }); setList(null); });
+    const id = pending.sync.id;
+    if (pending.kind === "trigger") return void work(id, async () => { await g8Post(`/audience-syncs/${id}/trigger`, {}); setNotice("Sync started."); });
+    if (pending.kind === "toggle") return void work(id, () => g8Patch(`/audience-syncs/${id}`, { is_active: !pending.sync.is_active }));
+    if (pending.kind === "delete") return void work(id, () => g8Delete(`/audience-syncs/${id}`), true);
+    return void work(id, async () => {
+      const res = await g8Post(`/audience-syncs/${id}/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 });
+      // HTTP 200 does not mean launched: a refused launch answers 200 with status "error" in the body.
+      const outcome = launchOutcome(res.data);
+      if (!outcome.ok) throw new Error(outcome.message);
+      setLaunch({ ...launch, syncId: 0, name: "", daily_budget: "", creative_image_url: "" });
+      setNotice(outcome.message ?? "Campaign sent to the platform.");
+      onLaunched?.();
+    });
+  };
+
+  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));
+  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">
+        <h3 className="text-sm font-medium">Send a list to an ad platform</h3>
+        <ListPicker value={list?.id ?? null} onChange={setList} />
+        <div className="flex flex-wrap items-end gap-2">
+          <select aria-label="Platform" className="h-9 rounded-md border bg-background px-2" value={platform} onChange={(e) => setPlatform(e.target.value)}>{AD_PLATFORMS.map((p) => <option key={p} value={p}>{p}</option>)}</select>
+          <select aria-label="Mode" className="h-9 rounded-md border bg-background px-2" value={mode} onChange={(e) => setMode(e.target.value)}><option value="mirror">Mirror (remove people who leave the list)</option><option value="append_only">Only add people</option></select>
+          <div className="flex flex-col gap-1"><Label htmlFor="as-cadence">Refresh every (hours)</Label><Input id="as-cadence" type="number" min={0} max={720} value={cadence} onChange={(e) => setCadence(Number(e.target.value))} /></div>
+          <Button loading={busy === "new"} disabled={!list || busy != null} onClick={() => list && setPending({ kind: "create", list })}>Create sync</Button>
+        </div>
+      </section>
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      {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}
+      <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>
+                <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>
+                <Button size="sm" variant="ghost" disabled={busy != null} onClick={() => setPending({ kind: "toggle", sync: s })}>{s.is_active ? "Pause" : "Resume"}</Button>
+                <Button size="sm" variant="ghost" onClick={() => setErrorsFor(errorsFor === s.id ? null : s.id)}>Errors</Button>
+                <Button size="sm" variant="ghost" onClick={() => setLaunch({ ...launch, syncId: launch.syncId === s.id ? 0 : s.id })}>Launch campaign</Button>
+                <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}
+            {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]) => (
+                  <div key={key} className="flex flex-col gap-1"><Label htmlFor={`as-${key}`}>{label}</Label><Input id={`as-${key}`} value={launch[key]} onChange={(e) => setLaunch({ ...launch, [key]: e.target.value })} /></div>
+                ))}
+                <div className="flex flex-col gap-1"><Label htmlFor="as-currency">Currency</Label><select id="as-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>
+                <div className="flex flex-col gap-1"><Label htmlFor="as-start">Start date</Label><Input id="as-start" type="date" value={launch.start_date} onChange={(e) => setLaunch({ ...launch, start_date: e.target.value })} /></div>
+                <div className="flex flex-col gap-1"><Label htmlFor="as-end">End date</Label><Input id="as-end" type="date" value={launch.end_date} onChange={(e) => setLaunch({ ...launch, end_date: e.target.value })} /></div>
+                <div><Button type="submit" disabled={!readyToLaunch || busy != null}>Review launch</Button>{!datesOk ? <p role="alert" className="mt-1 text-xs text-destructive">The end date is before the start date.</p> : null}</div>
+              </form>
+            ) : null}
+          </li>
+        ))}
+      </ul>
+      <ConfirmSpendDialog open={pending != null} tier={meta.tier} title={meta.title} description={meta.text} recipients={meta.recipients} affected={meta.affected} confirmLabel={meta.label} confirming={busy != null} onConfirm={confirm} onCancel={() => setPending(null)} />
+    </div>
+  );
+}
+
+function describe(p: Pending | null, platform: string, budget: string): { 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.` };
+}