@graph8/sdk 0.303.0 → 0.357.0

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

@@ -0,0 +1,121 @@
+"use client";
+
+/**
+ * CreativeGallery: AI-made ad creatives (copy plus image) for Meta, LinkedIn, Google and X. Generate one from a
+ * brief, follow it while it generates, edit its copy, regenerate the image, move it to the gallery (ready to use) or
+ * delete it. Generation and regeneration spend credits and are confirmed; every card has its own busy state.
+ *
+ * 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 }
+ *   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)
+ *   6. regenerateAdCreativeImage POST  /ad-creatives/{id}/regenerate-image         (billable)  ConfirmSpendDialog first
+ *   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.
+ */
+
+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 { 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 type { AdCreative } from "../lib/social-ads-types";
+
+export interface CreativeGalleryProps {
+  /** Show only creatives in this state. Default: all working creatives. */
+  status?: "draft" | "completed" | "gallery";
+  className?: string;
+}
+
+interface Specs { platforms: string[]; specs: Record<string, Record<string, { label: string }>> }
+type Pending = { kind: "create" } | { kind: "regenerate" | "delete"; creative: AdCreative };
+
+export function CreativeGallery({ status, className }: CreativeGalleryProps) {
+  const [platform, setPlatform] = useState("");
+  const [form, setForm] = useState({ platform: "meta", format: "", prompt: "", name: "" });
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [editing, setEditing] = useState<{ id: string; headline: string; primary_text: string } | null>(null);
+  const [busy, setBusy] = useState<string | null>(null);
+  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 items = list.data ?? [];
+  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") });
+
+  const formats = Object.entries(specs.data?.specs?.[form.platform] ?? {});
+  const format = form.format || formats[0]?.[0] || "";
+
+  const run = async (id: string, work: () => Promise<unknown>, tolerate404 = false) => {
+    setBusy(id);
+    setFailure(null);
+    try { await work(); } catch (err) { if (!(tolerate404 && (err as { status?: number })?.status === 404)) setFailure(err); }
+    finally { setBusy(null); setPending(null); await list.refetch(); }
+  };
+  const confirmPending = () => {
+    if (!pending) return;
+    if (pending.kind === "create") return void run("new", async () => { await g8Post("/ad-creatives", { platform: form.platform, ad_format: format, prompt: form.prompt.trim() || undefined, name: form.name.trim() || undefined }); setForm({ ...form, prompt: "", name: "" }); });
+    const id = pending.creative.id;
+    if (pending.kind === "regenerate") return void run(id, () => g8Post(`/ad-creatives/${id}/regenerate-image`, {}));
+    return void run(id, () => g8Delete(`/ad-creatives/${id}`), true);
+  };
+  const saveCopy = () => editing && void run(editing.id, async () => { await g8Patch(`/ad-creatives/${editing.id}`, { headline: editing.headline, primary_text: editing.primary_text }); setEditing(null); });
+
+  const tier: ConfirmTier = pending?.kind === "delete" ? "destructive" : "billable";
+  const name = pending && pending.kind !== "create" ? pending.creative.name : "";
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <form className="flex flex-wrap items-end gap-2" onSubmit={(e) => { e.preventDefault(); if (format) setPending({ kind: "create" }); }}>
+        <select aria-label="New creative platform" className="h-9 rounded-md border bg-background px-2" value={form.platform} onChange={(e) => setForm({ ...form, platform: e.target.value, format: "" })}>
+          {(specs.data?.platforms ?? ["meta", "linkedin", "google", "x"]).map((p) => <option key={p} value={p}>{p}</option>)}
+        </select>
+        <select aria-label="Format" className="h-9 rounded-md border bg-background px-2" value={format} onChange={(e) => setForm({ ...form, format: e.target.value })}>
+          {formats.map(([key, spec]) => <option key={key} value={key}>{spec.label}</option>)}
+        </select>
+        <div className="flex flex-col gap-1"><Label htmlFor="cg-prompt">What is the ad about?</Label><Input id="cg-prompt" value={form.prompt} onChange={(e) => setForm({ ...form, prompt: e.target.value })} maxLength={2000} /></div>
+        <Button type="submit" loading={busy === "new"} disabled={!format || busy != null}>Generate</Button>
+      </form>
+      {specs.error ? <ApiError error={specs.error} title="Could not load the formats" onRetry={() => void specs.refetch()} /> : null}
+      <select aria-label="Filter platform" className="h-9 w-40 rounded-md border bg-background px-2" value={platform} onChange={(e) => setPlatform(e.target.value)}><option value="">All platforms</option>{(specs.data?.platforms ?? []).map((p) => <option key={p} value={p}>{p}</option>)}</select>
+      {list.error ? <ApiError error={list.error} title="Could not load creatives" onRetry={() => void list.refetch()} /> : null}
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      {list.loading && !list.data ? <Skeleton className="h-32 w-full" /> : null}
+      {!list.loading && !list.error && items.length === 0 ? <EmptyState title="No creatives yet" description="Describe an ad above and generate the first one." /> : null}
+      <ul className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+        {items.map((c) => (
+          <li key={c.id} className="flex flex-col gap-2 rounded-md border p-3" data-testid="creative" aria-busy={c.status === "generating" || busy === c.id}>
+            {c.image_url ? <img src={c.image_url} alt={c.headline ?? c.name} className="aspect-video w-full rounded object-cover" /> : <div className="flex aspect-video items-center justify-center rounded bg-muted text-xs text-muted-foreground">{c.status === "generating" ? "Generating..." : "No image"}</div>}
+            <p className="text-xs text-muted-foreground">{c.platform} · {c.ad_format} · {c.status}</p>
+            {editing?.id === c.id ? (
+              <div className="flex flex-col gap-1">
+                <Input aria-label="Headline" value={editing.headline} onChange={(e) => setEditing({ ...editing, headline: e.target.value })} />
+                <Input aria-label="Primary text" value={editing.primary_text} onChange={(e) => setEditing({ ...editing, primary_text: e.target.value })} />
+                <div className="flex gap-1"><Button size="sm" loading={busy === c.id} onClick={saveCopy}>Save</Button><Button size="sm" variant="ghost" onClick={() => setEditing(null)}>Cancel</Button></div>
+              </div>
+            ) : <div><p className="text-sm font-medium">{c.headline || c.name}</p><p className="line-clamp-2 text-sm text-muted-foreground">{c.primary_text}</p></div>}
+            {c.status === "failed" && c.error_message ? <p className="text-xs text-destructive">{c.error_message}</p> : null}
+            <div className="flex flex-wrap gap-1">
+              <Button size="sm" variant="ghost" disabled={busy != null || c.status === "generating"} onClick={() => setEditing({ id: c.id, headline: c.headline ?? "", primary_text: c.primary_text ?? "" })}>Edit copy</Button>
+              <Button size="sm" variant="ghost" loading={busy === c.id} disabled={busy != null || c.status === "generating"} onClick={() => setPending({ kind: "regenerate", creative: c })}>New image</Button>
+              {c.status !== "gallery" && c.status !== "generating" ? <Button size="sm" variant="outline" disabled={busy != null} onClick={() => void run(c.id, () => g8Post(`/ad-creatives/${c.id}/move-to-gallery`, {}))}>Move to gallery</Button> : null}
+              <Button size="sm" variant="ghost" disabled={busy != null} onClick={() => setPending({ kind: "delete", creative: c })}>Delete</Button>
+            </div>
+          </li>
+        ))}
+      </ul>
+      <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."}
+        confirmLabel={pending?.kind === "delete" ? "Delete" : "Generate"} confirming={busy != null} onConfirm={confirmPending} onCancel={() => setPending(null)} />
+    </div>
+  );
+}

package/blocks/social-ads/components/post-composer.tsx

@@ -0,0 +1,122 @@
+"use client";
+
+/**
+ * PostComposer: write a social post, optionally with AI drafts, then save it as a draft, schedule it or publish it.
+ * Publishing reaches real audiences, so scheduling and publishing are confirmed with the account, the exact time
+ * (in the viewer's zone, named) and what will happen.
+ *
+ * SDK operations, in order:
+ *   1. listSocialAccounts    GET   /social/accounts                      (read)  the account `id` is `account_ref`; capacity { publish_used, publish_limit }
+ *   2. generateSocialPost    POST  /social/posts/generate { instructions, variants }  (billable)  returns { variants: [{ frame, body }], credits_used };
+ *        saves nothing. ConfirmSpendDialog first; no advance price, so the dialog says credits are used and the balance is not checked.
+ *   3. createSocialPost      POST  /social/posts { body, account_ref, post_type, media, idempotency_key }  (write)  makes a DRAFT. The new id is kept at once
+ *        so a retry after a later step failed updates this post instead of creating a second one.
+ *      updateSocialPost      PATCH /social/posts/{post_id}                (write)  when the draft already exists
+ *   4. scheduleSocialPost    POST  /social/posts/{post_id}/schedule { scheduled_at }  (external)  an ISO instant; ConfirmSpendDialog first
+ *   5. publishSocialPost     POST  /social/posts/{post_id}/publish        (external)  now; ConfirmSpendDialog first
+ */
+
+import { useRef, useState } from "react";
+import { Button, Input, Label, Textarea } 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 { g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useSocialAccounts } from "../hooks/use-social-accounts";
+import { formatInstant, isFuture, localInputToIso } from "../lib/social-ads-types";
+import type { PostVariant, SocialPost } from "../lib/social-ads-types";
+
+export interface PostComposerProps {
+  /** Called after a post was saved, scheduled or published. */
+  onSaved?: (post: SocialPost, action: "draft" | "scheduled" | "published") => void;
+  className?: string;
+}
+
+type Action = "schedule" | "publish";
+const newKey = () => globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+export function PostComposer({ onSaved, className }: PostComposerProps) {
+  const { accounts, loading, error, refetch } = useSocialAccounts();
+  const [account, setAccount] = useState("");
+  const [body, setBody] = useState("");
+  const [imageUrl, setImageUrl] = useState("");
+  const [when, setWhen] = useState("");
+  const [brief, setBrief] = useState("");
+  const [variants, setVariants] = useState<PostVariant[]>([]);
+  const [confirm, setConfirm] = useState<Action | "generate" | null>(null);
+  const [notice, setNotice] = useState<string | null>(null);
+  // Retry-safety: the draft made by step 1 is remembered so a retry updates it instead of creating a second post.
+  const draft = useRef<{ id: string; key: string } | null>(null);
+  const key = useRef(newKey());
+
+  const chosen = accounts.find((a) => a.id === (account || accounts[0]?.id));
+  const media = imageUrl.trim() ? [{ kind: "image", url: imageUrl.trim(), alt: "" }] : [];
+  const payload = { body: body.trim(), account_ref: chosen?.id, post_type: media.length ? "image" : "text", media };
+  const when_ = when && isFuture(when) ? localInputToIso(when) : null;
+  const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+
+  const reset = () => { draft.current = null; key.current = newKey(); setBody(""); setImageUrl(""); setWhen(""); setBrief(""); setVariants([]); setConfirm(null); };
+  const ensure = async (): Promise<SocialPost> => {
+    if (draft.current) return (await g8Patch<SocialPost>(`/social/posts/${draft.current.id}`, payload)).data;
+    const created = (await g8Post<SocialPost>("/social/posts", { ...payload, idempotency_key: key.current })).data;
+    draft.current = { id: created.id, key: key.current };
+    return created;
+  };
+
+  const save = useG8Mutation(ensure, { onSuccess: (p) => { setNotice("Draft saved."); onSaved?.(p, "draft"); } });
+  const go = useG8Mutation(async (action: Action) => {
+    const post = await ensure();
+    const res = action === "schedule" ? await g8Post<SocialPost>(`/social/posts/${post.id}/schedule`, { scheduled_at: when_ }) : await g8Post<{ post: SocialPost }>(`/social/posts/${post.id}/publish`, {});
+    return { post: action === "schedule" ? (res.data as SocialPost) : (res.data as { post: SocialPost }).post, action };
+  }, { onSuccess: ({ post, action }) => { const msg = action === "schedule" ? `Scheduled for ${formatInstant(post.scheduled_at ?? when_)}.` : "Publishing started."; reset(); setNotice(msg); onSaved?.(post, action === "schedule" ? "scheduled" : "published"); },
+    onError: () => setConfirm(null) });
+  const generate = useG8Mutation(async () => (await g8Post<{ variants: PostVariant[]; credits_used: number }>("/social/posts/generate", { instructions: brief.trim() || undefined, variants: 3 })).data, {
+    onSuccess: (r) => { setConfirm(null); setVariants(r.variants); setNotice(`${r.credits_used} credits used for ${r.variants.length} drafts.`); },
+  });
+
+  if (error) return <ApiError error={error} title="Could not load social accounts" onRetry={() => void refetch()} />;
+  if (!loading && accounts.length === 0) return <EmptyState title="No social account connected" description="Connect a LinkedIn account in graph8 (Settings, Channels), then come back. It cannot be done through the API." />;
+
+  const ready = body.trim().length > 0 && Boolean(chosen);
+  const dialog = confirm === "publish"
+    ? { title: `Publish now to ${chosen?.display_name ?? chosen?.provider}`, description: "The post goes live immediately on your connected account and cannot be recalled from here.", label: "Publish" }
+    : { title: `Schedule for ${formatInstant(when_)}`, description: `Posts to ${chosen?.display_name ?? chosen?.provider} at that moment (${zone}). Until then you can cancel it from the post list.`, label: "Schedule" };
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <div className="flex flex-col gap-1">
+        <Label htmlFor="sp-account">Post as</Label>
+        <select id="sp-account" className="h-9 rounded-md border bg-background px-2" value={chosen?.id ?? ""} onChange={(e) => setAccount(e.target.value)}>
+          {accounts.map((a) => <option key={a.id} value={a.id}>{a.display_name || a.provider} ({a.provider})</option>)}
+        </select>
+        {chosen ? <p className="text-xs text-muted-foreground">{chosen.capacity.publish_used} of {chosen.capacity.publish_limit} posts used in this window.</p> : null}
+      </div>
+
+      <div className="flex flex-col gap-1">
+        <Label htmlFor="sp-brief">Ask AI for drafts (optional)</Label>
+        <div className="flex gap-2"><Input id="sp-brief" value={brief} onChange={(e) => setBrief(e.target.value)} placeholder="Announce our new integration, friendly tone" /><Button variant="outline" onClick={() => setConfirm("generate")}>Draft with AI</Button></div>
+        {generate.error ? <ApiError error={generate.error} title="Could not generate drafts" /> : null}
+        {variants.map((v) => <div key={v.frame + v.body.slice(0, 20)} className="rounded-md border p-2 text-sm"><p className="mb-1 text-xs text-muted-foreground">{v.frame}</p><p>{v.body}</p><Button size="sm" variant="ghost" onClick={() => setBody(v.body)}>Use this</Button></div>)}
+      </div>
+
+      <div className="flex flex-col gap-1"><Label htmlFor="sp-body">Post</Label><Textarea id="sp-body" rows={6} value={body} onChange={(e) => setBody(e.target.value)} /><p className="text-xs text-muted-foreground">{body.length.toLocaleString()} characters</p></div>
+      <div className="flex flex-col gap-1"><Label htmlFor="sp-image">Image URL (optional, must be publicly reachable)</Label><Input id="sp-image" value={imageUrl} onChange={(e) => setImageUrl(e.target.value)} /></div>
+      <div className="flex flex-col gap-1"><Label htmlFor="sp-when">Schedule for ({zone})</Label><Input id="sp-when" type="datetime-local" value={when} onChange={(e) => setWhen(e.target.value)} />
+        {when && !when_ ? <p role="alert" className="text-xs text-destructive">Pick a time at least a minute from now.</p> : null}</div>
+
+      {[save.error, go.error].filter(Boolean).map((e, i) => <ApiError key={i} error={e} title="That did not work" />)}
+      <div className="flex flex-wrap gap-2">
+        <Button variant="outline" loading={save.loading} disabled={!ready} onClick={() => void save.mutate(undefined)}>Save draft</Button>
+        <Button disabled={!ready || !when_} onClick={() => setConfirm("schedule")}>Schedule</Button>
+        <Button variant="outline" disabled={!ready} onClick={() => setConfirm("publish")}>Publish now</Button>
+      </div>
+      {notice ? <p role="status" className="text-sm text-muted-foreground">{notice}</p> : null}
+
+      <ConfirmSpendDialog open={confirm === "generate"} tier="billable" title="Draft 3 posts with AI" description="Uses credits. The API gives no price in advance and your balance is not checked here. Nothing is saved or posted."
+        confirmLabel="Draft posts" confirming={generate.loading} onConfirm={() => void generate.mutate(undefined)} onCancel={() => setConfirm(null)} />
+      <ConfirmSpendDialog open={confirm === "schedule" || confirm === "publish"} tier="external" title={dialog.title} description={dialog.description} confirmLabel={dialog.label}
+        confirming={go.loading} onConfirm={() => void go.mutate(confirm as Action)} onCancel={() => setConfirm(null)} />
+    </div>
+  );
+}

package/blocks/social-ads/components/social-post-list.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+/**
+ * SocialPostList: your posts by status with their times, and the actions that fit each: publish a draft, cancel a
+ * scheduled post, delete one. Every action reaches the outside world or removes data, so each is confirmed, and each
+ * row shows its own spinner while ITS action runs.
+ *
+ * SDK operations, in order:
+ *   1. listSocialPosts     GET    /social/posts?status&page&page_size      (read)  { items, total, counts }; counts are per status for the whole org
+ *   2. publishSocialPost   POST   /social/posts/{post_id}/publish          (external)  ConfirmSpendDialog first
+ *   3. cancelSocialPost    POST   /social/posts/{post_id}/cancel           (destructive)  a scheduled post only; ConfirmSpendDialog first
+ *   4. deleteSocialPost    DELETE /social/posts/{post_id}                  (destructive)  ConfirmSpendDialog first (a 404 means it is already gone)
+ * Times are instants shown in the viewer's zone with the zone name.
+ */
+
+import { useState } from "react";
+import { Button, 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, g8Post } from "@/g8/lib/g8-client";
+import { formatInstant } from "../lib/social-ads-types";
+import type { SocialPost, SocialPostPage } from "../lib/social-ads-types";
+
+export interface SocialPostListProps {
+  /** Change to reload the list, for example after PostComposer saved a post. */
+  refreshKey?: number;
+  pageSize?: number;
+  className?: string;
+}
+
+type Pending = { kind: "publish" | "cancel" | "delete"; post: SocialPost };
+const STATUSES = ["all", "draft", "scheduled", "live", "failed", "cancelled"] as const;
+const COPY: Record<Pending["kind"], { tier: ConfirmTier; verb: string; text: string }> = {
+  publish: { tier: "external", verb: "Publish", text: "The post goes live now on the connected account and cannot be recalled from here." },
+  cancel: { tier: "destructive", verb: "Cancel post", text: "The scheduled post will not be published. It stays as a cancelled record." },
+  delete: { tier: "destructive", verb: "Delete", text: "The post is removed. A post that is already live stays live on the network." },
+};
+
+export function SocialPostList({ refreshKey = 0, pageSize = 20, className }: SocialPostListProps) {
+  const [status, setStatus] = useState<(typeof STATUSES)[number]>("all");
+  const [page, setPage] = useState(1);
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [failure, setFailure] = useState<unknown>(null);
+
+  const query = useG8Query(
+    async (signal) => (await g8Get<SocialPostPage>("/social/posts", { status: status === "all" ? undefined : status, page, page_size: pageSize }, { signal })).data,
+    [status, page, pageSize, refreshKey],
+  );
+  const items = query.data?.items ?? [];
+  const pages = Math.max(1, Math.ceil((query.data?.total ?? 0) / pageSize));
+
+  const act = async () => {
+    if (!pending) return;
+    const { kind, post } = pending;
+    setBusy(post.id);
+    setFailure(null);
+    try {
+      if (kind === "publish") await g8Post(`/social/posts/${post.id}/publish`, {});
+      else if (kind === "cancel") await g8Post(`/social/posts/${post.id}/cancel`, {});
+      else await g8Delete(`/social/posts/${post.id}`);
+    } catch (err) {
+      if (!(kind === "delete" && (err as { status?: number })?.status === 404)) setFailure(err);
+    } finally {
+      setBusy(null);
+      setPending(null);
+      await query.refetch();
+    }
+  };
+
+  const copy = pending ? COPY[pending.kind] : COPY.delete;
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <div role="tablist" aria-label="Post status" className="flex flex-wrap gap-2">
+        {STATUSES.map((s) => (
+          <Button key={s} role="tab" aria-selected={status === s} size="sm" variant={status === s ? "default" : "outline"} onClick={() => { setStatus(s); setPage(1); }}>
+            {s}{s !== "all" && query.data?.counts?.[s] != null ? ` (${query.data.counts[s]})` : ""}
+          </Button>
+        ))}
+      </div>
+      {query.error ? <ApiError error={query.error} title="Could not load posts" onRetry={() => void query.refetch()} /> : null}
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      {query.loading && !query.data ? <Skeleton className="h-24 w-full" /> : null}
+      {!query.loading && !query.error && items.length === 0 ? <EmptyState title="No posts here" description="Write one with the composer." /> : null}
+      <ul className="flex flex-col gap-2">
+        {items.map((p) => (
+          <li key={p.id} className="flex flex-wrap items-start justify-between gap-2 rounded-md border p-3" data-testid="post">
+            <div className="flex min-w-0 flex-1 flex-col gap-1">
+              <p className="line-clamp-3 text-sm">{p.body}</p>
+              <p className="text-xs text-muted-foreground">
+                {p.status}
+                {p.status === "scheduled" && p.scheduled_at ? ` for ${formatInstant(p.scheduled_at)}` : ""}
+                {p.status === "live" && p.published_at ? ` on ${formatInstant(p.published_at)}` : ""}
+                {p.failure_reason ? ` · ${p.failure_reason}` : ""}
+              </p>
+              {p.external_post_url ? <a className="text-xs underline" href={p.external_post_url} target="_blank" rel="noreferrer">View on the network</a> : null}
+            </div>
+            <div className="flex gap-1">
+              {["draft", "ready", "failed"].includes(p.status) ? <Button size="sm" variant="outline" loading={busy === p.id} disabled={busy != null} onClick={() => setPending({ kind: "publish", post: p })}>Publish</Button> : null}
+              {p.status === "scheduled" ? <Button size="sm" variant="outline" loading={busy === p.id} disabled={busy != null} onClick={() => setPending({ kind: "cancel", post: p })}>Cancel</Button> : null}
+              {p.status !== "publishing" ? <Button size="sm" variant="ghost" disabled={busy != null} onClick={() => setPending({ kind: "delete", post: p })}>Delete</Button> : null}
+            </div>
+          </li>
+        ))}
+      </ul>
+      {pages > 1 ? (
+        <div className="flex items-center gap-2 text-sm"><Button size="sm" variant="outline" disabled={page <= 1} onClick={() => setPage(page - 1)}>Previous</Button>Page {page} of {pages}<Button size="sm" variant="outline" disabled={page >= pages} onClick={() => setPage(page + 1)}>Next</Button></div>
+      ) : null}
+      <ConfirmSpendDialog open={pending != null} tier={copy.tier} title={`${copy.verb}: "${(pending?.post.body ?? "").slice(0, 60)}"`} description={copy.text} confirmLabel={copy.verb}
+        confirming={busy != null} onConfirm={() => void act()} onCancel={() => setPending(null)} />
+    </div>
+  );
+}

package/blocks/social-ads/hooks/use-social-accounts.ts

@@ -0,0 +1,16 @@
+"use client";
+
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { listOf } from "../lib/social-ads-types";
+import type { SocialAccount } from "../lib/social-ads-types";
+
+/**
+ * Connected social accounts (`GET /social/accounts`). The account `id` is the `account_ref` every post call takes.
+ * Connecting an account (LinkedIn sign-in) can only be done in the graph8 app: an empty list means a person must
+ * connect one there first.
+ */
+export function useSocialAccounts() {
+  const query = useG8Query(async (signal) => listOf<SocialAccount>((await g8Get("/social/accounts", undefined, { signal })).data), []);
+  return { accounts: query.data ?? [], loading: query.loading, error: query.error, refetch: query.refetch };
+}

package/blocks/social-ads/lib/social-ads-types.ts

@@ -0,0 +1,167 @@
+"use client";
+
+/**
+ * Shapes and helpers for the social and ads components.
+ *
+ * TIME. A scheduled post is an INSTANT: the person picks a wall-clock time in their own zone
+ * (`<input type="datetime-local">`), `localInputToIso` turns it into the UTC instant the API stores, and
+ * `formatInstant` shows it back in the viewer's zone WITH the zone name, so "9:00 AM PDT" is never read as UTC.
+ * Campaign start and end dates are DATE-ONLY values: `formatDateOnly` shows them in UTC so they never slide a day
+ * in a western time zone, and a date-only value is sent back as `YYYY-MM-DD`, never through `toISOString()`.
+ */
+
+export type PostStatus = "draft" | "ready" | "scheduled" | "publishing" | "live" | "failed" | "cancelled" | string;
+
+export interface SocialAccount {
+  /** What `account_ref` takes everywhere else. */
+  id: string;
+  display_name?: string | null;
+  provider: string;
+  status?: string | null;
+  profile_url?: string | null;
+  capabilities: { publish_personal: boolean; publish_company: boolean; analytics: boolean; leads: boolean; media: boolean };
+  capacity: { publish_used: number; publish_limit: number };
+}
+
+export interface SocialPost {
+  id: string;
+  provider?: string | null;
+  account_ref?: string | null;
+  body: string;
+  media?: Array<{ kind?: string; url: string; alt?: string }> | null;
+  post_type: string;
+  status: PostStatus;
+  scheduled_at?: string | null;
+  published_at?: string | null;
+  external_post_url?: string | null;
+  failure_reason?: string | null;
+  created_at?: string | null;
+}
+
+export interface SocialPostPage { items: SocialPost[]; total: number; counts: Record<string, number> }
+
+export interface PostVariant { frame: string; body: string }
+
+export interface AdCampaign {
+  id: number;
+  sync_config_id: number;
+  /** The id of the campaign on the ad platform, set once launched. Metrics join on it. */
+  platform_campaign_id?: string | null;
+  platform: string;
+  name: string;
+  objective?: string | null;
+  status: string;
+  daily_budget?: number | null;
+  currency?: string | null;
+  start_date?: string | null;
+  end_date?: string | null;
+  ad_count?: number | null;
+  launched_at?: string | null;
+}
+
+export interface CampaignMetric { sync_config_id: number; platform_campaign_id?: string; currency?: string; impressions: number; clicks: number; conversions?: number; spend: number; ctr?: number; cpc?: number }
+
+export interface AdCreative {
+  id: string;
+  name: string;
+  platform: string;
+  ad_format: string;
+  status: "generating" | "draft" | "completed" | "gallery" | "failed" | string;
+  headline?: string | null;
+  primary_text?: string | null;
+  description?: string | null;
+  cta?: string | null;
+  image_url?: string | null;
+  error_message?: string | null;
+}
+
+export interface AudienceSyncConfig {
+  id: number;
+  audience_id: number;
+  platform: string;
+  platform_audience_name?: string | null;
+  mode: string;
+  refresh_cadence_hours: number;
+  is_active: boolean;
+  status?: string | null;
+  status_detail?: string | null;
+  last_sync_at?: string | null;
+  next_sync_at?: string | null;
+  last_sync_error?: string | null;
+}
+
+export const AD_PLATFORMS = ["meta", "linkedin", "google", "x"] as const;
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+/** "2026-10-20T09:00" typed in the viewer's zone -> the UTC instant, "2026-10-20T16:00:00.000Z" in Los Angeles. */
+export function localInputToIso(local: string): string {
+  const d = new Date(local);
+  if (Number.isNaN(d.getTime())) throw new Error("Pick a date and time");
+  return d.toISOString();
+}
+
+/** An instant -> the value a datetime-local input expects, in the viewer's zone. */
+export function isoToLocalInput(iso: string): string {
+  const d = new Date(iso);
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+/** An instant for display: the viewer's zone, with the zone name ("Oct 20, 2026, 9:00 AM PDT"). */
+export function formatInstant(iso: string | null | undefined): string {
+  if (!iso) return "";
+  return new Intl.DateTimeFormat(undefined, { month: "short", day: "numeric", year: "numeric", hour: "numeric", minute: "2-digit", timeZoneName: "short" }).format(new Date(iso));
+}
+
+/** A date-only value (YYYY-MM-DD, or a midnight-UTC timestamp) for display, in UTC so it never moves a day. */
+export function formatDateOnly(value: string | null | undefined): string {
+  if (!value) return "";
+  const d = new Date(/^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T00:00:00Z` : value);
+  return Number.isNaN(d.getTime()) ? value : new Intl.DateTimeFormat(undefined, { dateStyle: "medium", timeZone: "UTC" }).format(d);
+}
+
+export function isFuture(local: string, now = Date.now()): boolean {
+  const t = new Date(local).getTime();
+  return !Number.isNaN(t) && t > now + 60_000;
+}
+
+export function formatMoney(amount: number | null | undefined, currency?: string | null): string {
+  if (amount == null) return "-";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency: currency || "USD" }).format(amount);
+  } catch {
+    return `${amount.toFixed(2)} ${currency ?? ""}`.trim();
+  }
+}
+
+/**
+ * Metrics rows are grouped by (sync_config_id, platform, platform_campaign_id) and one sync can carry several campaigns, so join on the
+ * platform campaign id whenever the campaign has one; only a campaign without it (not launched yet) falls back to the sync.
+ */
+export function metricsFor(campaign: Pick<AdCampaign, "sync_config_id" | "platform_campaign_id">, metrics: CampaignMetric[]): CampaignMetric | undefined {
+  const rows = campaign.platform_campaign_id
+    ? metrics.filter((m) => m.sync_config_id === campaign.sync_config_id && m.platform_campaign_id === campaign.platform_campaign_id)
+    : metrics.filter((m) => m.sync_config_id === campaign.sync_config_id && !m.platform_campaign_id);
+  if (rows.length === 0) return undefined;
+  return rows.reduce((a, m) => ({ ...a, impressions: a.impressions + m.impressions, clicks: a.clicks + m.clicks, spend: a.spend + m.spend }));
+}
+
+/** Pick the array out of whichever envelope the endpoint used. */
+export function listOf<T>(data: unknown, key = "items"): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const v = (data as Record<string, unknown> | null | undefined)?.[key];
+  return Array.isArray(v) ? (v as T[]) : [];
+}
+
+export interface LaunchOutcome { ok: boolean; message?: string }
+
+/**
+ * Launch and retry answer a refused request with HTTP 200 and `status: "error"` in the body (the platform rejected it, the campaign or
+ * sync was not found, no audience yet). Read the body: a 200 alone is not a success. "partial" launched but needs a status check.
+ */
+export function launchOutcome(data: unknown): LaunchOutcome {
+  const d = (data ?? {}) as { status?: string; message?: string; reason?: string };
+  if (d.status === "error" || d.status === "failed" || d.status === "ineligible") return { ok: false, message: d.message || d.reason || `The platform did not accept the campaign (${d.status}).` };
+  if (d.status === "partial") return { ok: true, message: "Launched, but part of it was rejected. Refresh the status and review the ads." };
+  return { ok: true };
+}

package/blocks/social-ads/recipes/creative-to-gallery.ts

@@ -0,0 +1,41 @@
+/**
+ * @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 and has no advance price: get approval.
+ * Order: specs (platforms, formats, CTAs) -> create (201, status "generating") -> poll the status until it settles ->
+ * edit the copy -> move to the gallery (needs the ads launch permission). Formats are per platform: read them from the specs.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function formats(platform: string) {
+  const res = await g8.api.adCreatives.getAdCreativeSpecs();
+  const specs = (res.data as { specs: Record<string, Record<string, { label: string; aspect_ratio: string }>> }).specs;
+  return specs[platform] ?? {};
+}
+
+/** Billable. */
+export async function create(platform: string, adFormat: string, prompt: string) {
+  const res = await g8.api.adCreatives.createAdCreative({ body: { platform, ad_format: adFormat, prompt } });
+  return (res.data as { id: string }).id;
+}
+
+export async function waitForCreative(creativeId: string) {
+  let delay = 4000;
+  for (let i = 0; i < 60; i++) {
+    const res = await g8.api.adCreatives.getAdCreativeStatus({ path: { creative_id: creativeId } });
+    const s = res.data as { status: string; error_message?: string };
+    if (s.status !== "generating") return s;
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(20000, Math.round(delay * 1.3));
+  }
+  throw new Error(`creative ${creativeId} did not finish generating in time`);
+}
+
+export async function editCopy(creativeId: string, headline: string, primaryText: string) {
+  return g8.api.adCreatives.updateAdCreative({ path: { creative_id: creativeId }, body: { headline, primary_text: primaryText } });
+}
+
+export async function toGallery(creativeId: string) {
+  return g8.api.adCreatives.moveAdCreativeToGallery({ path: { creative_id: creativeId } });
+}

package/blocks/social-ads/recipes/schedule-post.ts

@@ -0,0 +1,51 @@
+/**
+ * @title Draft a social post with AI, then schedule or publish it
+ * @when Posting to a connected LinkedIn account. The account must already be connected in graph8 (sign-in cannot be done
+ * through the API); read `listSocialAccounts` first and use an account's `id` as `account_ref`. Generating drafts is
+ * BILLABLE and saves nothing; creating makes a DRAFT; scheduling and publishing are EXTERNAL (real audiences): get a
+ * human to approve the account and the time. `scheduled_at` is an instant: convert the wall-clock time the person
+ * gave in THEIR zone with `new Date("2026-10-20T09:00").toISOString()` (runs in that zone) or pass an explicit offset.
+ * Keep the created post id so a retry after a failure schedules the same post instead of creating a second.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function accounts() {
+  const res = await g8.api.socialPublishing.listSocialAccounts();
+  return (res.data as { items: Array<{ id: string; display_name?: string; provider: string; capacity: { publish_used: number; publish_limit: number } }> }).items;
+}
+
+/** Billable. Nothing is saved; pick a variant and create the post from it. */
+export async function draftWithAi(instructions: string) {
+  const res = await g8.api.socialPublishing.generateSocialPost({ body: { instructions, variants: 3 } });
+  return (res.data as { variants: Array<{ frame: string; body: string }>; credits_used: number }).variants;
+}
+
+export async function createDraft(accountRef: string, body: string, idempotencyKey: string) {
+  const res = await g8.api.socialPublishing.createSocialPost({ body: { body, account_ref: accountRef, post_type: "text", idempotency_key: idempotencyKey } });
+  return (res.data as { id: string }).id;
+}
+
+/** External. Only after a person approved this account and this instant. */
+export async function schedule(postId: string, scheduledAtIso: string) {
+  return g8.api.socialPublishing.scheduleSocialPost({ path: { post_id: postId }, body: { scheduled_at: scheduledAtIso } });
+}
+
+/** External, immediate. */
+export async function publishNow(postId: string) {
+  return g8.api.socialPublishing.publishSocialPost({ path: { post_id: postId } });
+}
+
+/** Statuses: draft, ready, scheduled, publishing, live, failed, cancelled. Poll after publishing. */
+export async function waitUntilLive(postId: string) {
+  let delay = 3000;
+  for (let i = 0; i < 40; i++) {
+    const res = await g8.api.socialPublishing.getSocialPost({ path: { post_id: postId } });
+    const post = res.data as { status: string; external_post_url?: string; failure_reason?: string };
+    if (["live", "failed", "cancelled"].includes(post.status)) return post;
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(20000, Math.round(delay * 1.4));
+  }
+  throw new Error(`post ${postId} did not finish publishing in time`);
+}