@graph8/sdk 0.370.0 → 0.374.0

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

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

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

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

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

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

package/blocks/social-ads/components/creative-concepts.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+/**
+ * CreativeConcepts: a concept board. Describe the ad and get 3 to 6 creative directions to react to before any image is
+ * generated; nothing is saved. Pick the one you like and hand its brief to your generator.
+ *
+ * SDK operations:
+ *   1. generateAdConcepts  POST /ad-creatives/concepts { brief?, count }   (BILLABLE, confirmed; one AI pass; saves nothing)
+ *
+ * The API quotes no price in advance and the balance is not checked here, so the dialog says what runs. Each concept is
+ * a name, a hook, a tone, a layout and two brand colours. `onUse` receives a ready-to-use brief for the chosen concept.
+ */
+import { useState } from "react";
+import { Button, Input, Label } 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 { SectionCard } from "@/g8/components/screen/section-card";
+import { g8Post } from "@/g8/lib/g8-client";
+import { rowsOf, str } from "../lib/ads-extra";
+import type { Rec } from "../lib/ads-extra";
+
+export interface CreativeConceptsProps {
+  /** Called with a brief built from the chosen concept (its name, hook, tone and layout). */
+  onUse?: (brief: string, concept: Rec) => void;
+  className?: string;
+}
+
+/** A hex colour the API sent, or undefined: a rogue value is never put in a style. */
+export function safeHex(v: unknown): string | undefined {
+  const t = str(v);
+  return /^#[0-9a-f]{3,8}$/i.test(t) ? t : undefined;
+}
+
+export function conceptBrief(c: Rec): string {
+  const tone = rowsOf<string>(c.tone).map(String).join(", ");
+  return [`Concept: ${str(c.name)}.`, str(c.hook) ? `Hook: ${str(c.hook)}.` : "", tone ? `Tone: ${tone}.` : "", str(c.layout) ? `Layout: ${str(c.layout)}.` : ""].filter(Boolean).join(" ");
+}
+
+export function CreativeConcepts({ onUse, className }: CreativeConceptsProps) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const [brief, setBrief] = useState("");
+  const [count, setCount] = useState(4);
+  const [items, setItems] = useState<Rec[] | null>(null);
+  const go = (): void => ask({
+    tier: "billable", title: `Get ${count} creative concepts`, confirmLabel: "Get concepts",
+    description: "One AI pass writes the directions. Nothing is saved and no image is generated. Uses credits; the API gives no price in advance and your balance is not checked here.",
+    run: async () => { const res = await g8Post("/ad-creatives/concepts", { brief: brief.trim() || undefined, count }); setItems(rowsOf<Rec>(res.data, "concepts")); },
+  });
+  return (
+    <SectionCard className={className} title="Concept board" description="React to a few directions before generating anything.">
+      <form className="mb-3 flex flex-wrap items-end gap-2" onSubmit={(e) => { e.preventDefault(); go(); }}>
+        <div className="min-w-60 flex-1"><Label htmlFor="cc-brief" className="mb-1">Brief for the concepts</Label><Input id="cc-brief" value={brief} maxLength={2000} onChange={(e) => setBrief(e.target.value)} /></div>
+        <div><Label htmlFor="cc-count" className="mb-1">How many</Label><select id="cc-count" className="border-input bg-background h-9 rounded-md border px-2 text-sm" value={count} onChange={(e) => setCount(Number(e.target.value))}>{[3, 4, 5, 6].map((n) => <option key={n} value={n}>{n}</option>)}</select></div>
+        <Button type="submit">Get concepts</Button>
+      </form>
+      {items === null ? <EmptyState compact title="No concepts yet" /> : items.length === 0 ? <EmptyState compact title="No concepts came back" description="Try a more specific brief." /> : (
+        <ul className="grid gap-3 sm:grid-cols-2">
+          {items.map((c, i) => (
+            <li key={i} className="grid gap-1 rounded-md border p-3">
+              <div className="flex items-center gap-2"><span className="size-4 rounded border" style={{ background: safeHex(c.bg) }} aria-hidden /><span className="size-4 rounded border" style={{ background: safeHex(c.accent) }} aria-hidden /><span className="text-sm font-medium">{str(c.name)}</span></div>
+              <p className="text-sm">{str(c.hook)}</p>
+              <p className="text-muted-foreground text-xs">{rowsOf<string>(c.tone).join(", ")}{str(c.layout) ? ` · ${str(c.layout)}` : ""}</p>
+              {onUse ? <div><Button size="sm" variant="outline" aria-label={`Use ${str(c.name)}`} onClick={() => onUse(conceptBrief(c), c)}>Use this concept</Button></div> : null}
+            </li>
+          ))}
+        </ul>
+      )}
+      {failure ? <ApiError error={failure} title="Could not get concepts" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </SectionCard>
+  );
+}

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

@@ -3,7 +3,8 @@
 /**
  * CreativeDetail: the complete screen for one AI ad creative. Finds it by id (so `?id=` deep links work), shows the image and every
  * copy field, and offers every action: edit headline, primary text, description and call to action; make a new image (billable);
- * move it to the gallery; delete. A creative that is still generating re-reads itself until it finishes.
+ * move it to the gallery; delete. A creative that is still generating re-reads itself until it finishes. The AI tools tab edits by
+ * instruction, rewrites a field, reviews, makes other sizes and more (CreativeTools); Revisions lists and restores earlier versions.
  *
  * SDK operations, in order:
  *   1. listAdCreatives          GET    /ad-creatives?limit=100                   (read)
@@ -28,6 +29,8 @@ import { StatusPill } from "@/g8/components/screen/status-pill";
 import type { AdCreative } from "../lib/social-ads-types";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { AskButton, useConfirmAction } from "@/g8/components/confirmed-action";
+import { CreativeRevisions } from "./creative-revisions";
+import { CreativeTools } from "./creative-tools";
 
 export interface CreativeDetailProps {
   creativeId: string;
@@ -139,6 +142,8 @@ export function CreativeDetail({ creativeId, onClose, onExpand, onCollapse, onCh
         </SectionCard>
       ),
     },
+    { id: "ai", label: "AI tools", content: <CreativeTools creativeId={creativeId} platform={creative.platform} status={creative.status} onChanged={changed} /> },
+    { id: "revisions", label: "Revisions", content: <CreativeRevisions creativeId={creativeId} onRestored={changed} /> },
   ];
   return (
     <>

package/blocks/social-ads/components/creative-gallery.tsx

@@ -7,7 +7,7 @@
  *
  * SDK operations, in order:
  *   1. getAdCreativeSpecs       GET    /ad-creatives/specs                         (read)  { platforms, specs: { platform: { format: { label } } }, ctas }
- *   2. listAdCreatives          GET    /ad-creatives?status&platform&limit&offset  (read)  { items }
+ *   2. listAdCreatives          GET    /ad-creatives?status&platform&limit&offset  (read)  { items }; 50 at a time, "Load more" reads the next 50
  *   3. createAdCreative         POST   /ad-creatives { platform, ad_format, prompt, name }  (billable)  ConfirmSpendDialog first; 201 with status "generating"
  *      While any card is `generating` the list is re-read with useJobPoll (no streams) until none is.
  *   5. updateAdCreative         PATCH  /ad-creatives/{id} { headline, primary_text, description, cta }  (write)
@@ -15,6 +15,7 @@
  *   7. moveAdCreativeToGallery  POST   /ad-creatives/{id}/move-to-gallery          (write)  needs the ads launch permission
  *   8. deleteAdCreative         DELETE /ad-creatives/{id}                          (destructive)
  * The API quotes no price for generation: the dialog says credits are used and the balance is not checked here.
+ * A "Concept board" (CreativeConcepts, billable and confirmed) offers directions to react to; choosing one fills the brief.
  */
 
 import { useState } from "react";
@@ -24,9 +25,13 @@ 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 { useLoadMoreList } from "@/g8/hooks/use-load-more-list";
+import { byOffset, hasNextOf } from "@/g8/lib/paging";
+import { LoadMore } from "@/g8/components/paging-notices";
 import { useJobPoll } from "@/g8/hooks/use-job-poll";
 import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
 import { listOf } from "../lib/social-ads-types";
+import { CreativeConcepts } from "./creative-concepts";
 import type { AdCreative } from "../lib/social-ads-types";
 
 export interface CreativeGalleryProps {
@@ -40,6 +45,9 @@ export interface CreativeGalleryProps {
 interface Specs { platforms: string[]; specs: Record<string, Record<string, { label: string }>> }
 type Pending = { kind: "create" } | { kind: "regenerate" | "delete"; creative: AdCreative };
 
+/** Creatives per read; "Load more" appends the next page (the gallery used to stop silently at 50). */
+const CREATIVE_PAGE = 50;
+
 export function CreativeGallery({ status, onSelectCreative, className }: CreativeGalleryProps) {
   const [platform, setPlatform] = useState("");
   const [form, setForm] = useState({ platform: "meta", format: "", prompt: "", name: "" });
@@ -49,8 +57,13 @@ export function CreativeGallery({ status, onSelectCreative, className }: Creativ
   const [failure, setFailure] = useState<unknown>(null);
 
   const specs = useG8Query(async (signal) => (await g8Get<Specs>("/ad-creatives/specs", undefined, { signal })).data, []);
-  const list = useG8Query(async (signal) => listOf<AdCreative>((await g8Get("/ad-creatives", { status, platform: platform || undefined, limit: 50 }, { signal })).data), [status, platform]);
+  const list = useLoadMoreList(byOffset<AdCreative>(CREATIVE_PAGE, async (offset, signal) => {
+    const env = await g8Get("/ad-creatives", { status, platform: platform || undefined, limit: CREATIVE_PAGE, offset: offset || undefined }, { signal });
+    const rows = listOf<AdCreative>(env.data);
+    return { rows, hasNext: hasNextOf(env, CREATIVE_PAGE, rows.length) };
+  }), [status, platform]);
   const items = list.data ?? [];
+  const [boardOpen, setBoardOpen] = useState(false);
   const generating = items.filter((c) => c.status === "generating");
   useJobPoll(async () => (await list.refetch()) ?? ([{ status: "generating" }] as AdCreative[]), { enabled: generating.length > 0, intervalMs: 4000, maxAttempts: 100, isTerminal: (rows) => !rows.some((c) => c.status === "generating") });
 
@@ -122,6 +135,11 @@ export function CreativeGallery({ status, onSelectCreative, className }: Creativ
           </li>
         ))}
       </ul>
+      <LoadMore shown={items.length} noun="creatives" hasMore={list.hasMore} loading={list.loadingMore} onLoadMore={list.loadMore} />
+      <details className="rounded-md border p-3" onToggle={(e) => setBoardOpen((e.currentTarget as HTMLDetailsElement).open)}>
+        <summary className="cursor-pointer text-sm font-medium">Concept board</summary>
+        {boardOpen ? <CreativeConcepts className="mt-3" onUse={(brief) => setForm((f) => ({ ...f, prompt: brief.slice(0, 2000) }))} /> : null}
+      </details>
       <ConfirmSpendDialog open={pending != null} tier={tier}
         title={pending?.kind === "create" ? `Generate a ${form.platform} creative` : pending?.kind === "regenerate" ? `Make a new image for "${name}"` : `Delete "${name}"`}
         description={tier === "billable" ? "Uses credits (copy and image). The API gives no price in advance and your balance is not checked here." : "The creative and its revisions are removed."}

package/blocks/social-ads/components/creative-revisions.tsx

@@ -0,0 +1,57 @@
+"use client";
+
+/**
+ * CreativeRevisions: the saved versions of one ad creative (every edit, rewrite and regeneration is kept), with restore.
+ *
+ * SDK operations:
+ *   1. listAdCreativeRevisions   GET  /ad-creatives/{id}/revisions                    (read; oldest first, as the API returns them)
+ *   2. restoreAdCreativeRevision POST /ad-creatives/{id}/restore-revision { index }   (write; the creative takes that version's copy and image)
+ *
+ * Revisions are open dicts: each row shows whatever of `label`, `source`, `headline` and `created_at` it has. Restoring
+ * asks for a second click because it replaces what the creative shows now.
+ */
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { num, rowsOf, str, whenText } from "../lib/ads-extra";
+import type { Rec } from "../lib/ads-extra";
+
+export interface CreativeRevisionsProps {
+  creativeId: string;
+  /** Called after a revision was restored, so the detail reloads. */
+  onRestored?: () => void;
+  className?: string;
+}
+
+export function CreativeRevisions({ creativeId, onRestored, className }: CreativeRevisionsProps) {
+  const base = `/ad-creatives/${encodeURIComponent(creativeId)}`;
+  const list = useG8Query((signal) => g8Get(`${base}/revisions`, undefined, { signal }), [creativeId]);
+  const rows = rowsOf<Rec>(list.data?.data, "revisions");
+  const [sure, setSure] = useState<number | null>(null);
+  const restore = useG8Mutation((index: number) => g8Post(`${base}/restore-revision`, { index }), { onSuccess: () => { setSure(null); void list.refetch(); onRestored?.(); } });
+  return (
+    <SectionCard className={className} title="Revisions" description="Every change is kept. Restoring one replaces what the creative shows now.">
+      {list.error ? <ApiError error={list.error} title="Could not load the revisions" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? <Skeleton className="h-20 w-full" aria-busy="true" /> : rows.length === 0 ? (
+        <EmptyState compact title="No earlier versions" description="A version is kept each time the creative is edited." />
+      ) : (
+        <ul className="grid gap-2">
+          {rows.map((r, i) => {
+            const index = num(r.index) ?? i;
+            return (
+              <li key={index} className="flex items-center justify-between gap-3 rounded-md border p-3">
+                <div className="min-w-0 text-sm"><span className="font-medium">Version {index + 1}</span>{str(r.label) || str(r.source) ? <span className="text-muted-foreground"> {str(r.label) || str(r.source).replace(/_/g, " ")}</span> : null}<span className="text-muted-foreground block truncate text-xs">{whenText(r.created_at ?? r.at)}{str(r.headline) ? ` · ${str(r.headline)}` : ""}</span></div>
+                {sure === index ? <div className="flex gap-1"><Button size="sm" loading={restore.loading} onClick={() => void restore.mutate(index)}>Replace the current version</Button><Button size="sm" variant="ghost" onClick={() => setSure(null)}>Cancel</Button></div> : <Button size="sm" variant="outline" aria-label={`Restore version ${index + 1}`} onClick={() => setSure(index)}>Restore</Button>}
+              </li>
+            );
+          })}
+        </ul>
+      )}
+      {restore.error ? <ApiError error={restore.error} title="Could not restore that version" /> : null}
+    </SectionCard>
+  );
+}