@graph8/sdk 0.370.0 → 0.374.0

package/blocks/signals/lib/signals-types.ts

@@ -0,0 +1,228 @@
+"use client";
+
+/**
+ * Types, vocabularies and pure helpers for the signals block's social listening part.
+ *
+ * Every response of the social-listeners routes is an OPEN object in the contract, so the row types below follow the
+ * app's own models (social_listener/interfaces/fastapi/listeners_router.py), which the dev API forwards unchanged.
+ * Enums are copied from the request schemas (generated/schemas.ts), not from memory: the API refuses anything else.
+ * A count the channel did not report is null and shown as a dash, never as 0. Calls nothing.
+ */
+
+export type Platform = "x" | "linkedin" | "reddit" | "instagram" | "youtube";
+export type ListenerType = "brand" | "competitor" | "keyword" | "engagement" | "user";
+export type PostStatus = "new" | "reviewed" | "dismissed";
+export type EngagementType = "comment" | "reaction";
+
+export const PLATFORMS: { value: Platform; label: string }[] = [
+  { value: "x", label: "X" },
+  { value: "linkedin", label: "LinkedIn" },
+  { value: "reddit", label: "Reddit" },
+  { value: "instagram", label: "Instagram" },
+  { value: "youtube", label: "YouTube" },
+];
+export const LISTENER_TYPES: { value: ListenerType; label: string; hint: string }[] = [
+  { value: "brand", label: "Brand", hint: "Posts that mention your brand or products." },
+  { value: "competitor", label: "Competitor", hint: "Posts that mention a competitor." },
+  { value: "keyword", label: "Keyword", hint: "Posts that match a search query." },
+  { value: "engagement", label: "Engagement", hint: "Posts from people who look like your buyers." },
+  { value: "user", label: "Account", hint: "Everything one account posts." },
+];
+export const POST_STATUSES: { value: PostStatus; label: string }[] = [
+  { value: "new", label: "New" },
+  { value: "reviewed", label: "Reviewed" },
+  { value: "dismissed", label: "Dismissed" },
+];
+
+/** Minimum the API accepts for a poll interval (seconds). */
+export const MIN_POLL_SEC = 60;
+/** The API's page-size cap for the post and engagement reads. */
+export const PAGE_SIZE = 100;
+
+/**
+ * Credits per language-model pass of an auto-seed or a generated query. The API publishes no price; this is the backend
+ * constant (credit_server `social_listener_brand_query_build`, mirrored in frontend/features/social-listener/social-listener.costs.ts).
+ */
+export const AI_PASS_CREDITS = 5;
+
+export interface Listener {
+  id: string;
+  platform: string;
+  listener_type: string;
+  name: string;
+  query?: string | null;
+  target_handle?: string | null;
+  filters?: Record<string, unknown> | null;
+  poll_interval_sec?: number | null;
+  monthly_credit_cap?: number | null;
+  is_active: boolean;
+  paused_reason?: string | null;
+  last_polled_at?: string | null;
+  source_list_id?: string | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+}
+export interface ListenerDetailData { listener: Listener; match_count?: number | null; credit_burn?: number | null }
+
+export interface MatchedPost {
+  post_external_id: string;
+  platform: string;
+  matched_listener_ids?: string[];
+  author_handle?: string | null;
+  author_name?: string | null;
+  author_followers?: number | null;
+  author_verified?: boolean | null;
+  author_profile_image_url?: string | null;
+  text?: string | null;
+  post_url?: string | null;
+  created_at?: string | null;
+  like_count?: number | null;
+  reply_count?: number | null;
+  repost_count?: number | null;
+  view_count?: number | null;
+  classifier_score?: number | null;
+  engagement_intent?: string | null;
+  resolved_mashup_contact_id?: string | null;
+  status?: string | null;
+}
+export interface PostEngagement {
+  engagement_external_id: string;
+  engagement_type: string;
+  reaction_type?: string | null;
+  author_handle?: string | null;
+  author_name?: string | null;
+  author_url?: string | null;
+  author_headline?: string | null;
+  text?: string | null;
+  created_at?: string | null;
+}
+export interface TopAccount {
+  author_external_id: string;
+  author_handle?: string | null;
+  author_name?: string | null;
+  author_url?: string | null;
+  author_headline?: string | null;
+  platform: string;
+  posts_engaged?: number | null;
+  comments?: number | null;
+  reactions?: number | null;
+  last_engaged_at?: string | null;
+}
+export interface SourceList {
+  audience_id: number;
+  list_title?: string | null;
+  audience_type?: string | null;
+  contact_count?: number | null;
+  is_active?: boolean | null;
+  is_dynamic?: boolean | null;
+  last_synced_at?: string | null;
+  total_listeners_created?: number | null;
+  channel_coverage?: Record<string, number> | null;
+}
+export interface SocialStats {
+  monthly_credit_burn?: number | null;
+  posts_matched?: number | null;
+  posts_reviewed?: number | null;
+  posts_dismissed?: number | null;
+  contacts_resolved?: number | null;
+  x_api_spend_usd?: number | null;
+  listeners_active?: number | null;
+  listeners_paused?: number | null;
+}
+export interface ChannelRule { enabled?: boolean; monthly_credit_cap?: number; per_poll_result_cap?: number; max_comments_per_post?: number; max_reactions_per_post?: number; fetch_engagements?: boolean }
+export interface CaptureRule { enabled?: boolean; min_followers?: number; only_when_classified?: boolean }
+export interface SocialSettings {
+  monthly_credit_cap?: number | null;
+  other_channels_monthly_credit_cap?: number | null;
+  alert_threshold_pct?: number | null;
+  auto_pause_on_cap?: boolean | null;
+  auto_archive_days?: number | null;
+  auto_create_contacts?: boolean | null;
+  classifier_model?: string | null;
+  channel_settings?: Record<string, ChannelRule> | null;
+  contact_capture?: Record<string, CaptureRule> | null;
+}
+export interface XStatus { connected?: boolean; mode?: string | null; x_app_username?: string | null; connected_at?: string | null; degraded_reason?: string | null }
+export interface XMode { auth_mode?: string | null; byo_connected?: boolean | null; shared_available?: boolean | null; shared_cap_total?: number | null; shared_cap_remaining?: number | null }
+export interface SeedJob { job_id?: string; status?: string; stage?: string; error?: string | null; result?: { brand_created?: number; competitors_created?: number; keywords_created?: number; engagement_created?: number; skipped?: string[] } | null }
+export interface CostPreview { posts_per_day_estimate?: number | null; credits_per_month_estimate?: number | null; x_usd_per_month_estimate?: number | null; cached?: boolean; note?: string | null }
+
+/** The rows of an open `{ items: [] }` payload (the dev API surfaces every list as `items`). */
+export function itemsOf<T>(data: unknown): T[] {
+  const d = data as { items?: unknown } | T[] | null | undefined;
+  if (Array.isArray(d)) return d;
+  return Array.isArray(d?.items) ? (d.items as T[]) : [];
+}
+export function totalOf(data: unknown): number | undefined {
+  const t = (data as { total?: unknown } | null | undefined)?.total;
+  return typeof t === "number" ? t : undefined;
+}
+
+export const platformLabel = (p: string | null | undefined): string => PLATFORMS.find((x) => x.value === p)?.label ?? (p ? p : "");
+export const typeLabel = (t: string | null | undefined): string => LISTENER_TYPES.find((x) => x.value === t)?.label ?? (t ? t : "");
+/** A number, or null when the channel did not report one (unknown is not zero). */
+export const num = (n: number | null | undefined): number | null => (typeof n === "number" && Number.isFinite(n) ? n : null);
+export const fmt = (n: number | null | undefined): string => { const v = num(n); return v === null ? "-" : v.toLocaleString(); };
+export const when = (iso: string | null | undefined): string => {
+  if (!iso) return "-";
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? "-" : new Date(t).toLocaleString(undefined, { dateStyle: "medium", timeStyle: "short" });
+};
+export const cadence = (sec: number | null | undefined): string => {
+  const s = num(sec);
+  if (s === null) return "-";
+  if (s % 3600 === 0) return `every ${s / 3600} h`;
+  if (s % 60 === 0) return `every ${s / 60} min`;
+  return `every ${s} s`;
+};
+/** Credits per month a poll cadence cannot bound: only the cap does, so the cap is what a confirm states. */
+export const capText = (cap: number | null | undefined): string => {
+  const c = num(cap);
+  return c === null ? "no cap reported" : c === 0 ? "no per-listener cap" : `capped at ${c.toLocaleString()} credits a month`;
+};
+export const statusOf = (l: Pick<Listener, "is_active">): "active" | "paused" => (l.is_active ? "active" : "paused");
+
+/**
+ * Only the fields that changed. A cleared text or number is NOT sent: the dev API builds the inner body with
+ * `model_dump(exclude_none=True)`, so a null would be dropped and the save would report something that never happened.
+ */
+export function listenerDiff(before: Listener, next: { name: string; query: string; target_handle: string; poll_interval_sec: number | null; monthly_credit_cap: number | null }): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (next.name.trim() !== before.name) out.name = next.name.trim();
+  if (next.query.trim() && next.query.trim() !== (before.query ?? "")) out.query = next.query.trim();
+  if (next.target_handle.trim() && next.target_handle.trim() !== (before.target_handle ?? "")) out.target_handle = next.target_handle.trim();
+  if (next.poll_interval_sec !== null && next.poll_interval_sec !== num(before.poll_interval_sec)) out.poll_interval_sec = next.poll_interval_sec;
+  if (next.monthly_credit_cap !== null && next.monthly_credit_cap !== num(before.monthly_credit_cap)) out.monthly_credit_cap = next.monthly_credit_cap;
+  return out;
+}
+
+/** A page of a POST-search read: rows plus whether another page follows (from the reported total, else a full page). */
+export function morePages(data: unknown, rows: number, page: number, size: number): boolean {
+  const t = totalOf(data);
+  return t !== undefined ? page * size < t : rows >= size;
+}
+
+/** The sequences a person can enrol into: live ones only. */
+export interface SequenceRow { id: string; name?: string | null; status?: string | null }
+export const isLiveSequence = (s: SequenceRow): boolean => ["live", "waiting", "running", "active"].includes(String(s.status ?? "").toLowerCase());
+
+/** Top-level numeric settings: key, label, max (when the API bounds it). */
+export const SETTING_NUMBERS: { key: "monthly_credit_cap" | "other_channels_monthly_credit_cap" | "alert_threshold_pct" | "auto_archive_days"; label: string; max?: number; hint: string }[] = [
+  { key: "monthly_credit_cap", label: "Monthly credit cap (X)", hint: "The org-wide ceiling on social listening credits." },
+  { key: "other_channels_monthly_credit_cap", label: "Monthly credit cap (other channels)", hint: "LinkedIn, Reddit, Instagram and YouTube together. 0 means no org-wide ceiling." },
+  { key: "alert_threshold_pct", label: "Alert at (% of cap)", max: 100, hint: "You are alerted when spend reaches this share of the cap." },
+  { key: "auto_archive_days", label: "Archive posts after (days)", hint: "Older matched posts are archived." },
+];
+export const CHANNEL_NUMBERS: { key: "monthly_credit_cap" | "per_poll_result_cap" | "max_comments_per_post" | "max_reactions_per_post"; label: string }[] = [
+  { key: "monthly_credit_cap", label: "Monthly credit cap" },
+  { key: "per_poll_result_cap", label: "Posts per poll" },
+  { key: "max_comments_per_post", label: "Comments per post" },
+  { key: "max_reactions_per_post", label: "Reactions per post" },
+];
+
+/** Whole non-negative integer from a text box, or null when empty / invalid. */
+export function wholeNumber(text: string, max?: number): number | null {
+  if (text.trim() === "") return null;
+  const n = Number(text);
+  return Number.isInteger(n) && n >= 0 && (max === undefined || n <= max) ? n : null;
+}

package/blocks/signals/recipes/preview-and-create-a-listener.ts

@@ -0,0 +1,16 @@
+/**
+ * @title Estimate a listener's cost, then create it with a monthly cap
+ * @when Starting to watch a keyword or competitor. Creating a listener makes it poll, and reading posts spends credits, so
+ * a person confirms the cap first. The estimate charges nothing.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function previewThenCreate(query: string, name: string, monthlyCreditCap: number, approved: boolean): Promise<{ estimateCreditsPerMonth: unknown; listenerId?: string }> {
+  const est = await g8.api.signals.previewListenerCost({ body: { listener_type: "keyword", platform: "x", query } });
+  const estimateCreditsPerMonth = (est.data as { credits_per_month_estimate?: unknown }).credits_per_month_estimate;
+  if (!approved) return { estimateCreditsPerMonth };
+  const made = await g8.api.signals.createListener({ body: { listener_type: "keyword", platform: "x", name, query, monthly_credit_cap: monthlyCreditCap } });
+  return { estimateCreditsPerMonth, listenerId: (made.data as { id?: string }).id };
+}

package/blocks/signals/recipes/spend-against-caps.ts

@@ -0,0 +1,14 @@
+/**
+ * @title Compare this month's credit spend with the org-wide cap
+ * @when A budget alert for social listening. A cap of 0 means no org-wide ceiling, which is not "at the limit".
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function spendVsCap(): Promise<{ spent: number | null; cap: number | null; share: number | null }> {
+  const [stats, settings] = await Promise.all([g8.api.signals.getSocialStats({}), g8.api.signals.getSocialSettings({})]);
+  const spent = (stats.data as { monthly_credit_burn?: number }).monthly_credit_burn ?? null;
+  const cap = (settings.data as { monthly_credit_cap?: number }).monthly_credit_cap ?? null;
+  return { spent, cap, share: spent !== null && cap ? spent / cap : null };
+}

package/blocks/signals/recipes/triage-matched-posts.ts

@@ -0,0 +1,18 @@
+/**
+ * @title Read new matched posts and mark them reviewed
+ * @when A daily triage queue for social signals. The read spends nothing (it reads what the worker stored); a post is
+ * identified by its channel AND its id.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function newPosts(limit = 50): Promise<Array<{ platform: string; id: string; text: string | null }>> {
+  const res = await g8.api.signals.searchMatchedPosts({ body: { status: "new", limit, page: 1 } });
+  const rows = ((res.data as { items?: Array<{ platform: string; post_external_id: string; text?: string | null }> }).items ?? []);
+  return rows.map((p) => ({ platform: p.platform, id: p.post_external_id, text: p.text ?? null }));
+}
+
+export async function markReviewed(platform: "x" | "linkedin" | "reddit" | "instagram" | "youtube", postId: string): Promise<void> {
+  await g8.api.signals.markPost({ path: { post_id: postId }, query: { platform }, body: { status: "reviewed" } });
+}

package/blocks/social-ads/README.md

@@ -137,3 +137,11 @@ Ask the person: campaign daily budget, dates and destination URL (always typed b
 | updateAdCreative | PATCH /ad-creatives/{creative_id} | write | CreativeGallery |
 | updateAudienceSync | PATCH /audience-syncs/{config_id} | external | AudienceSync |
 | updateSocialPost | PATCH /social/posts/{post_id} | write | PostComposer |
+
+## Depth added (C7c)
+
+- `CampaignDetail` gains **Ads** (`CampaignAds`: list, edit, pause or activate, archive, add; all external or destructive confirms) and **Edit** (`CampaignEditor`: name, daily budget, end date, spend cap, pause or resume; previewed, then an external confirm; fields the platform refuses are disabled with its reason).
+- `CreativeDetail` gains **AI tools** (`CreativeTools`: edit by instruction, rewrite a field with undo, review and apply, other sizes, retry, move to draft, save as template; billable passes are confirmed) and **Revisions** (`CreativeRevisions`). `CreativeGallery` loads past 50 and has a **Concept board** (`CreativeConcepts`, billable confirm).
+- `SocialScreen` gains **Ideas** (`SocialIdeas`, Draft a post opens the composer with the brief), **Performance** (`SocialPerformance`), a per-post Performance tab, and Disconnect on an account (destructive confirm).
+
+Not covered (and why): `createAdCreativeSet` and `readAdCreativeThroughPersona` need persona pickers; video clips, image-point edits, reskin, set-image and library ops need pickers or media editing; `uploadAdImage` is multipart; social autopilot (`saveSocialAutopilot`) auto-publishes and engagers (`addSocialEngagersToAudience`, `enrollSocialEngagers`) need list and sequence pickers; `getAudienceSync` is already covered by the list read.

package/blocks/social-ads/block.json

@@ -14,39 +14,64 @@
     "lists"
   ],
   "operations": [
+    "apply_ad_creative_review_findings_ad_creatives__creative_id__ai_review_apply_post",
+    "archive_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__delete",
     "cancel_social_post_social_posts__post_id__cancel_post",
+    "chat_edit_ad_creative_ad_creatives__creative_id__chat_edit_post",
     "create_ad_creative_ad_creatives_post",
+    "create_ad_creative_size_set_ad_creatives__creative_id__size_set_post",
     "create_audience_sync_audience_syncs_post",
+    "create_campaign_ad_ad_campaigns__campaign_id__ads_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",
+    "disconnect_social_account_social_accounts__account_id__delete",
+    "generate_ad_concepts_ad_creatives_concepts_post",
     "generate_social_post_social_posts_generate_post",
+    "get_ad_campaign_ad_campaigns__campaign_id__get",
+    "get_ad_creative_ad_creatives__creative_id__get",
     "get_ad_creative_specs_ad_creatives_specs_get",
     "get_ad_creative_status_ad_creatives__creative_id__status_get",
+    "get_campaign_editable_fields_ad_campaigns__campaign_id__editable_get",
     "get_per_campaign_metrics_ad_campaigns_metrics_get",
+    "get_social_analytics_social_analytics_get",
+    "get_social_post_metrics_social_posts__post_id__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_creative_revisions_ad_creatives__creative_id__revisions_get",
     "list_ad_creatives_ad_creatives_get",
     "list_audience_syncs_audience_syncs_get",
+    "list_campaign_ads_ad_campaigns__campaign_id__ads_get",
     "list_social_accounts_social_accounts_get",
+    "list_social_ideas_social_ideas_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_draft_ad_creatives__creative_id__move_to_draft_post",
     "move_ad_creative_to_gallery_ad_creatives__creative_id__move_to_gallery_post",
+    "preview_ad_campaign_edit_ad_campaigns__campaign_id__edit_preview_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_copy_ad_creatives__creative_id__regenerate_copy_post",
     "regenerate_ad_creative_image_ad_creatives__creative_id__regenerate_image_post",
+    "restore_ad_creative_revision_ad_creatives__creative_id__restore_revision_post",
+    "retry_ad_creative_generation_ad_creatives__creative_id__retry_post",
     "retry_campaign_launch_ad_campaigns__campaign_id__retry_post",
+    "review_ad_creative_ad_creatives__creative_id__ai_review_post",
+    "rewrite_ad_creative_field_ad_creatives__creative_id__rewrite_field_post",
+    "save_ad_creative_as_template_ad_creatives__creative_id__save_as_template_post",
     "schedule_social_post_social_posts__post_id__schedule_post",
+    "set_campaign_ad_status_ad_campaigns__campaign_id__ads__ad_id__status_post",
     "trigger_audience_sync_audience_syncs__config_id__trigger_post",
+    "update_ad_campaign_ad_campaigns__campaign_id__put",
     "update_ad_creative_ad_creatives__creative_id__patch",
     "update_audience_sync_audience_syncs__config_id__patch",
-    "update_social_post_social_posts__post_id__patch",
-    "get_ad_creative_ad_creatives__creative_id__get"
+    "update_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__patch",
+    "update_social_post_social_posts__post_id__patch"
   ],
   "components": [
     {
@@ -146,10 +171,12 @@
       "file": "components/social-screen.tsx",
       "purpose": "Finished social page: posts by status with a New post composer sheet, and connected accounts.",
       "operations": [
-        "list_social_posts_social_posts_get"
+        "list_social_posts_social_posts_get",
+        "disconnect_social_account_social_accounts__account_id__delete"
       ],
       "tiers": [
-        "read"
+        "read",
+        "destructive"
       ]
     },
     {
@@ -237,6 +264,108 @@
         "external",
         "destructive"
       ]
+    },
+    {
+      "name": "CampaignAds",
+      "file": "components/campaign-ads.tsx",
+      "purpose": "The ads inside a campaign: list, edit, pause or activate, archive and add (each confirmed).",
+      "operations": [
+        "update_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__patch",
+        "list_campaign_ads_ad_campaigns__campaign_id__ads_get",
+        "set_campaign_ad_status_ad_campaigns__campaign_id__ads__ad_id__status_post",
+        "archive_campaign_ad_ad_campaigns__campaign_id__ads__ad_id__delete",
+        "create_campaign_ad_ad_campaigns__campaign_id__ads_post"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "CampaignEditor",
+      "file": "components/campaign-editor.tsx",
+      "purpose": "Edit a live ad campaign: name, budget, end date, spend cap, pause or resume; previewed, then confirmed.",
+      "operations": [
+        "preview_ad_campaign_edit_ad_campaigns__campaign_id__edit_preview_post",
+        "update_ad_campaign_ad_campaigns__campaign_id__put",
+        "get_ad_campaign_ad_campaigns__campaign_id__get",
+        "get_campaign_editable_fields_ad_campaigns__campaign_id__editable_get"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "CreativeConcepts",
+      "file": "components/creative-concepts.tsx",
+      "purpose": "Concept board: creative directions to react to before generating (confirmed AI spend).",
+      "operations": [
+        "generate_ad_concepts_ad_creatives_concepts_post"
+      ],
+      "tiers": [
+        "billable"
+      ]
+    },
+    {
+      "name": "CreativeRevisions",
+      "file": "components/creative-revisions.tsx",
+      "purpose": "Saved versions of an ad creative with restore.",
+      "operations": [
+        "list_ad_creative_revisions_ad_creatives__creative_id__revisions_get",
+        "restore_ad_creative_revision_ad_creatives__creative_id__restore_revision_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "CreativeTools",
+      "file": "components/creative-tools.tsx",
+      "purpose": "AI tools for a creative: edit by instruction, rewrite a field, review, other sizes, retry, template.",
+      "operations": [
+        "get_ad_creative_specs_ad_creatives_specs_get",
+        "update_ad_creative_ad_creatives__creative_id__patch",
+        "apply_ad_creative_review_findings_ad_creatives__creative_id__ai_review_apply_post",
+        "move_ad_creative_to_draft_ad_creatives__creative_id__move_to_draft_post",
+        "save_ad_creative_as_template_ad_creatives__creative_id__save_as_template_post",
+        "chat_edit_ad_creative_ad_creatives__creative_id__chat_edit_post",
+        "regenerate_ad_creative_copy_ad_creatives__creative_id__regenerate_copy_post",
+        "rewrite_ad_creative_field_ad_creatives__creative_id__rewrite_field_post",
+        "review_ad_creative_ad_creatives__creative_id__ai_review_post",
+        "create_ad_creative_size_set_ad_creatives__creative_id__size_set_post",
+        "retry_ad_creative_generation_ad_creatives__creative_id__retry_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable"
+      ]
+    },
+    {
+      "name": "SocialIdeas",
+      "file": "components/social-ideas.tsx",
+      "purpose": "Post ideas mined from signals and content, with a Draft a post action.",
+      "operations": [
+        "list_social_ideas_social_ideas_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SocialPerformance",
+      "file": "components/social-performance.tsx",
+      "purpose": "Social post performance: totals and per-day numbers, and the numbers of one post.",
+      "operations": [
+        "get_social_analytics_social_analytics_get",
+        "get_social_post_metrics_social_posts__post_id__metrics_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [
@@ -253,6 +382,10 @@
     {
       "file": "lib/social-ads-types.ts",
       "purpose": "Post, account, campaign, creative and sync shapes; time helpers (localInputToIso, formatInstant, formatDateOnly), metricsFor and listOf."
+    },
+    {
+      "file": "lib/ads-extra.ts",
+      "purpose": "Helpers for the ads and social management components: open-dict readers, editable-field map, campaign edit diff."
     }
   ],
   "recipes": [

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

@@ -17,6 +17,7 @@
 import { useState } from "react";
 import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
@@ -55,10 +56,14 @@ interface SyncError { id: number; error_message?: string; started_at?: string }
 
 const EMPTY_LAUNCH = { name: "", objective: "", daily_budget: "", currency: "USD", destination_url: "", creative_image_url: "", headline: "", primary_text: "", start_date: "", end_date: "" };
 
+/** The runs and errors APIs have no paging: a full read is announced under the list. */
+const RUN_LIMIT = 20;
+const ERROR_LIMIT = 10;
+
 function Runs({ syncId }: { syncId: number }) {
   const [confirm, setConfirm] = useState(false);
   const [runs, setRuns] = useState<SyncRun[] | null>(null);
-  const load = useG8Mutation(async () => { setRuns(listOf<SyncRun>((await g8Get(`/audience-syncs/${syncId}/runs`, { limit: 20 })).data, "runs")); });
+  const load = useG8Mutation(async () => { setRuns(listOf<SyncRun>((await g8Get(`/audience-syncs/${syncId}/runs`, { limit: RUN_LIMIT })).data, "runs")); });
   return (
     <SectionCard title="Runs" description="Loading past runs is a billable read, so it asks first.">
       {runs == null ? <Button size="sm" variant="outline" onClick={() => setConfirm(true)}>Load runs</Button> : runs.length === 0 ? <p className="text-sm text-muted-foreground">No runs yet.</p> : (
@@ -73,6 +78,7 @@ function Runs({ syncId }: { syncId: number }) {
           ))}
         </ul>
       )}
+      {runs ? <FirstNotice shown={runs.length} limit={RUN_LIMIT} noun="runs" /> : null}
       {load.error ? <ApiError error={load.error} onRetry={load.reset} /> : null}
       <ConfirmSpendDialog open={confirm} tier="billable" title="Load sync runs" description="Listing the runs of a sync is classified billable by the API." confirmLabel="Load runs" confirming={load.loading}
         onCancel={() => setConfirm(false)} onConfirm={() => void load.mutate(undefined).then(() => setConfirm(false))} />
@@ -84,7 +90,7 @@ export function AudienceSyncDetail({ syncId, onClose, onExpand, onCollapse, onCh
   const brand = useBrand();
   const { ask, dialog, failure } = useConfirmAction();
   const list = useG8Query(async (signal) => listOf<AudienceSyncConfig>((await g8Get("/audience-syncs", undefined, { signal })).data), []);
-  const errors = useG8Query(async (signal) => listOf<SyncError>((await g8Get(`/audience-syncs/${syncId}/errors`, { limit: 10 }, { signal })).data), [syncId]);
+  const errors = useG8Query(async (signal) => listOf<SyncError>((await g8Get(`/audience-syncs/${syncId}/errors`, { limit: ERROR_LIMIT }, { signal })).data), [syncId]);
   const [launch, setLaunch] = useState(EMPTY_LAUNCH);
   const [confirmLaunch, setConfirmLaunch] = useState(false);
   const [notice, setNotice] = useState<string | null>(null);
@@ -154,7 +160,7 @@ export function AudienceSyncDetail({ syncId, onClose, onExpand, onCollapse, onCh
       id: "errors",
       label: "Errors",
       content: errors.loading ? <Skeleton className="h-8 w-full" /> : errors.error ? <ApiError error={errors.error} onRetry={() => void errors.refetch()} /> : (errors.data ?? []).length === 0 ? <p className="text-sm text-muted-foreground">No recent errors.</p> : (
-        <ul className="space-y-1 text-sm">{(errors.data ?? []).map((e) => <li key={e.id}>{e.started_at ? `${formatInstant(e.started_at)}: ` : ""}{e.error_message}</li>)}</ul>
+        <><ul className="space-y-1 text-sm">{(errors.data ?? []).map((e) => <li key={e.id}>{e.started_at ? `${formatInstant(e.started_at)}: ` : ""}{e.error_message}</li>)}</ul><FirstNotice shown={(errors.data ?? []).length} limit={ERROR_LIMIT} noun="errors" /></>
       ),
     },
     {

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

@@ -23,6 +23,7 @@
 import { useState } from "react";
 import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import type { ConfirmTier } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
@@ -49,6 +50,9 @@ type Pending =
 
 const listSize = (l: ListSummary) => l.total ?? l.contact_count ?? l.company_count ?? undefined;
 
+/** The errors API has no paging: a full read is announced under the list. */
+const ERROR_LIMIT = 5;
+
 export function AudienceSync({ onLaunched, onSelectSync, className }: AudienceSyncProps) {
   const brand = useBrand();
   const [list, setList] = useState<ListSummary | null>(null);
@@ -63,7 +67,7 @@ export function AudienceSync({ onLaunched, onSelectSync, className }: AudienceSy
   const [notice, setNotice] = useState<string | null>(null);
 
   const syncs = useG8Query(async (signal) => listOf<AudienceSyncConfig>((await g8Get("/audience-syncs", undefined, { signal })).data), []);
-  const errors = useG8Query(async (signal) => listOf<{ id: number; error_message?: string; started_at?: string }>((await g8Get(`/audience-syncs/${errorsFor}/errors`, { limit: 5 }, { signal })).data), [errorsFor], { enabled: errorsFor != null });
+  const errors = useG8Query(async (signal) => listOf<{ id: number; error_message?: string; started_at?: string }>((await g8Get(`/audience-syncs/${errorsFor}/errors`, { limit: ERROR_LIMIT }, { signal })).data), [errorsFor], { enabled: errorsFor != null });
 
   const work = async (id: number | "new", fn: () => Promise<unknown>, tolerate404 = false) => {
     setBusy(id);
@@ -123,7 +127,7 @@ export function AudienceSync({ onLaunched, onSelectSync, className }: AudienceSy
                 <Button size="sm" variant="ghost" disabled={busy != null} onClick={() => setPending({ kind: "delete", sync: s })}>Delete</Button>
               </div>
             </div>
-            {errorsFor === s.id ? <div className="text-xs">{errors.loading ? "Loading..." : (errors.data ?? []).length === 0 ? "No recent errors." : <ul>{(errors.data ?? []).map((e) => <li key={e.id}>{formatInstant(e.started_at)}: {e.error_message}</li>)}</ul>}</div> : null}
+            {errorsFor === s.id ? <div className="text-xs">{errors.loading ? "Loading..." : (errors.data ?? []).length === 0 ? "No recent errors." : <><ul>{(errors.data ?? []).map((e) => <li key={e.id}>{formatInstant(e.started_at)}: {e.error_message}</li>)}</ul><FirstNotice shown={(errors.data ?? []).length} limit={ERROR_LIMIT} noun="errors" /></>}</div> : null}
             {launch.syncId === s.id ? (
               <form className="grid gap-2 sm:grid-cols-2" onSubmit={(e) => { e.preventDefault(); if (readyToLaunch) setPending({ kind: "launch", sync: s }); }}>
                 {([["name", "Campaign name"], ["objective", "Objective"], ["daily_budget", "Daily budget"], ["destination_url", "Landing page URL"], ["creative_image_url", "Image URL (required on Google)"], ["headline", "Headline"], ["primary_text", "Primary text"]] as const).map(([key, label]) => (