@graph8/sdk 0.370.0 → 0.374.0

package/blocks/signals/block.json

@@ -0,0 +1,287 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "signals",
+  "title": "Signals (social listening)",
+  "summary": "Watch X, LinkedIn, Reddit, Instagram and YouTube for posts about you, your competitors and your keywords: listeners, matched posts, engagers, starter seeds, spend limits and your own X app.",
+  "features": [
+    "create, edit, pause, resume and delete listeners with a cost estimate and a monthly cap",
+    "posts matched by every listener, triaged, saved as contacts or added to a sequence (confirmed)",
+    "who engaged with a post, turned into a list (confirmed)",
+    "the accounts that engage most",
+    "a listener per profile on a list",
+    "starter listeners from your keywords, brand, competitors and buyer profile",
+    "org-wide spend caps, per-channel ceilings and contact capture",
+    "connect or remove your own X developer app",
+    "a contact's matched posts as a tab"
+  ],
+  "dependsOn": [
+    "intent"
+  ],
+  "operations": [
+    "add_engagers_to_list_social_listeners_posts__post_id__engagements_add_to_list_post",
+    "add_post_author_to_sequence_social_listeners_posts__post_id__add_to_sequence_post",
+    "auto_seed_all_listeners_social_listeners_auto_seed_all_post",
+    "auto_seed_brand_listener_social_listeners_auto_seed_brand_post",
+    "auto_seed_competitor_listeners_social_listeners_auto_seed_competitors_post",
+    "auto_seed_engagement_listeners_social_listeners_auto_seed_engagement_post",
+    "auto_seed_keyword_listeners_social_listeners_auto_seed_keywords_post",
+    "bulk_create_listeners_from_list_social_listeners_bulk_from_list_post",
+    "connect_x_credentials_social_listeners_integrations_x_post",
+    "create_listener_social_listeners_post",
+    "delete_listener_social_listeners__listener_id__delete",
+    "disconnect_x_credentials_social_listeners_integrations_x_delete",
+    "generate_listener_query_social_listeners_queries_generate_post",
+    "get_auto_seed_status_social_listeners_auto_seed_status_get",
+    "get_listener_social_listeners__listener_id__get",
+    "get_social_settings_social_listeners_settings_get",
+    "get_social_stats_social_listeners_stats_get",
+    "get_x_effective_mode_social_listeners_integrations_x_mode_get",
+    "get_x_integration_social_listeners_integrations_x_get",
+    "list_listeners_social_listeners_get",
+    "list_lists_lists_get",
+    "list_posts_by_contact_social_listeners_posts_by_contact__contact_id__get",
+    "list_sequences_sequences_get",
+    "list_source_lists_social_listeners_source_lists_get",
+    "list_top_engaged_accounts_social_listeners_engagements_top_accounts_get",
+    "mark_post_social_listeners_posts__post_id__mark_post",
+    "preview_listener_cost_social_listeners_preview_cost_post",
+    "save_post_author_as_contact_social_listeners_posts__post_id__save_contact_post",
+    "search_matched_posts_social_listeners_posts_search_post",
+    "search_post_engagements_social_listeners_posts__post_id__engagements_search_post",
+    "test_x_credentials_social_listeners_integrations_x_test_post",
+    "update_listener_social_listeners__listener_id__patch",
+    "update_social_settings_social_listeners_settings_patch"
+  ],
+  "components": [
+    {
+      "name": "SocialListenersScreen",
+      "file": "components/social-listeners-screen.tsx",
+      "purpose": "Finished social listening workspace: listeners with search, filters and totals, a deep-linkable detail (overview, matches, edit), create, pause and resume, delete, posts, top engagers, sources and starter seeds, spend limits and the X connection.",
+      "operations": [
+        "delete_listener_social_listeners__listener_id__delete",
+        "get_listener_social_listeners__listener_id__get",
+        "get_social_stats_social_listeners_stats_get",
+        "list_listeners_social_listeners_get",
+        "update_listener_social_listeners__listener_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "ListenerForm",
+      "file": "components/listener-form.tsx",
+      "purpose": "Create a listener (type, channel, query or account, interval, monthly cap) with a cost estimate and an optional generated query, or edit one; edit reads the full record first and sends only changed fields.",
+      "operations": [
+        "create_listener_social_listeners_post",
+        "generate_listener_query_social_listeners_queries_generate_post",
+        "get_listener_social_listeners__listener_id__get",
+        "preview_listener_cost_social_listeners_preview_cost_post",
+        "update_listener_social_listeners__listener_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "MatchedPosts",
+      "file": "components/matched-posts.tsx",
+      "purpose": "Posts your listeners matched, filtered and paged; mark reviewed or dismissed, save an author as a contact, add the author to a live sequence, and open the engagers. Every write is confirmed.",
+      "operations": [
+        "add_post_author_to_sequence_social_listeners_posts__post_id__add_to_sequence_post",
+        "list_sequences_sequences_get",
+        "mark_post_social_listeners_posts__post_id__mark_post",
+        "save_post_author_as_contact_social_listeners_posts__post_id__save_contact_post",
+        "search_matched_posts_social_listeners_posts_search_post"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "external"
+      ]
+    },
+    {
+      "name": "PostEngagements",
+      "file": "components/post-engagements.tsx",
+      "purpose": "Who commented on or reacted to one matched post, and a confirmed one-step add of those people to a new or existing list.",
+      "operations": [
+        "add_engagers_to_list_social_listeners_posts__post_id__engagements_add_to_list_post",
+        "list_lists_lists_get",
+        "search_post_engagements_social_listeners_posts__post_id__engagements_search_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "TopEngagers",
+      "file": "components/top-engagers.tsx",
+      "purpose": "The accounts that engage with your matched posts most often, by window, channel and minimum posts.",
+      "operations": [
+        "list_top_engaged_accounts_social_listeners_engagements_top_accounts_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SourceLists",
+      "file": "components/source-lists.tsx",
+      "purpose": "Lists already feeding account listeners, and a confirmed one-step listener per social profile on a list and channel.",
+      "operations": [
+        "bulk_create_listeners_from_list_social_listeners_bulk_from_list_post",
+        "list_lists_lists_get",
+        "list_source_lists_social_listeners_source_lists_get"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "AutoSeedPanel",
+      "file": "components/auto-seed-panel.tsx",
+      "purpose": "Starter listeners from your keywords, brand, competitors and buyer profile, or all at once in the background; each is confirmed with its credits and the last run is followed.",
+      "operations": [
+        "auto_seed_all_listeners_social_listeners_auto_seed_all_post",
+        "auto_seed_brand_listener_social_listeners_auto_seed_brand_post",
+        "auto_seed_competitor_listeners_social_listeners_auto_seed_competitors_post",
+        "auto_seed_engagement_listeners_social_listeners_auto_seed_engagement_post",
+        "auto_seed_keyword_listeners_social_listeners_auto_seed_keywords_post",
+        "get_auto_seed_status_social_listeners_auto_seed_status_get"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "SocialSettingsPanel",
+      "file": "components/social-settings.tsx",
+      "purpose": "Org-wide spend caps, per-channel ceilings and contact capture rules; admin only; every change is confirmed with before and after.",
+      "operations": [
+        "get_social_settings_social_listeners_settings_get",
+        "update_social_settings_social_listeners_settings_patch"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "XIntegration",
+      "file": "components/x-integration.tsx",
+      "purpose": "Which X credentials listeners poll with, test and connect your own X developer app (write-only, confirmed), and disconnect it (confirmed with the count of listeners it pauses).",
+      "operations": [
+        "connect_x_credentials_social_listeners_integrations_x_post",
+        "disconnect_x_credentials_social_listeners_integrations_x_delete",
+        "get_x_effective_mode_social_listeners_integrations_x_mode_get",
+        "get_x_integration_social_listeners_integrations_x_get",
+        "list_listeners_social_listeners_get",
+        "test_x_credentials_social_listeners_integrations_x_test_post"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "destructive"
+      ]
+    },
+    {
+      "name": "RecordSocialTab",
+      "file": "components/record-social-tab.tsx",
+      "purpose": "One contact's matched social posts; drop into ContactsScreen extraDetailTabs.",
+      "operations": [
+        "list_posts_by_contact_social_listeners_posts_by_contact__contact_id__get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/signals-types.ts",
+      "purpose": "Listener, post, engagement, settings and X types; the API's exact vocabularies (channels, listener types, statuses); the changed-fields diff; paging and number helpers."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/preview-and-create-a-listener.ts",
+      "title": "Estimate a listener's cost, then create it with a cap",
+      "when": "Starting to watch a keyword or competitor; creating spends credits as posts are read, so a person confirms the cap."
+    },
+    {
+      "file": "recipes/triage-matched-posts.ts",
+      "title": "Read new matched posts and mark them reviewed",
+      "when": "A daily triage queue for social signals."
+    },
+    {
+      "file": "recipes/spend-against-caps.ts",
+      "title": "Compare this month's credit spend with the org-wide cap",
+      "when": "A budget alert for social listening."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "signals-scopes",
+      "description": "The key needs intent:read to read, intent:run to create or change listeners and settings, and intent:delete to delete a listener. Settings changes also need an org admin.",
+      "where": "api",
+      "verify": "GET /social-listeners/stats returns 200, not 403."
+    },
+    {
+      "id": "credit-balance",
+      "description": "Reading posts spends credits as they arrive. Set a monthly cap on every listener and review the org-wide caps in Settings before creating many.",
+      "where": "app",
+      "verify": "The owner reviewed the caps."
+    },
+    {
+      "id": "x-credentials",
+      "description": "X listeners poll with graph8's shared allowance or your own X developer app. Without either, creating an X listener answers 400.",
+      "where": "api",
+      "verify": "GET /social-listeners/integrations/x/mode shows an auth mode."
+    }
+  ],
+  "scopes": [
+    "intent:delete",
+    "intent:read",
+    "intent:run",
+    "lists:read",
+    "sequences:read"
+  ],
+  "defaults": [
+    {
+      "decision": "Poll interval and monthly cap for a new listener",
+      "default": "Not sent: the app's own defaults apply unless the person types a value",
+      "askHuman": false
+    },
+    {
+      "decision": "Which sequence an author is added to",
+      "default": "None: a person always picks a live sequence",
+      "askHuman": true
+    },
+    {
+      "decision": "Pausing versus deleting a listener",
+      "default": "Pause (keeps the matched posts); delete only when asked, after a confirmation",
+      "askHuman": false
+    },
+    {
+      "decision": "Auto-seed passes that use a language model",
+      "default": "Never without the person confirming the credits",
+      "askHuman": false
+    },
+    {
+      "decision": "Connecting an X developer app",
+      "default": "Never automatic: test first, then a person confirms",
+      "askHuman": true
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
+  }
+}

package/blocks/signals/components/auto-seed-panel.tsx

@@ -0,0 +1,111 @@
+"use client";
+
+/**
+ * AutoSeedPanel: create starter listeners from what graph8 already knows about your business.
+ *
+ * SDK operations, in order:
+ *   1. getAutoSeedStatus (GET /social-listeners/auto-seed-status)           read      the most recent run on open, and the run just started, polled
+ *   2. autoSeedKeywordListeners (POST /social-listeners/auto-seed/keywords)  billable tier, charges nothing (reads keywords you already have)
+ *   3. autoSeedBrandListener (POST /social-listeners/auto-seed/brand)        billable  one language-model pass, 5 credits
+ *   4. autoSeedCompetitorListeners (POST /social-listeners/auto-seed/competitors) billable one pass, 5 credits
+ *   5. autoSeedEngagementListeners (POST /social-listeners/auto-seed/engagement) billable one pass, 5 credits however many channels
+ *   6. autoSeedAllListeners (POST /social-listeners/auto-seed/all)           billable  up to three passes (15 credits) AFTER the 202, so the confirm says so
+ * Every action is confirmed with the credits it can spend. The per-pass price is the backend constant (AI_PASS_CREDITS).
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { Wand2 } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { AI_PASS_CREDITS, PLATFORMS } from "../lib/signals-types";
+import type { Platform, SeedJob } from "../lib/signals-types";
+
+type Kind = "keywords" | "brand" | "competitors" | "engagement" | "all";
+const SEEDS: { kind: Kind; label: string; hint: string; passes: number; path: string; channels: boolean }[] = [
+  { kind: "keywords", label: "From your keywords", hint: "One listener per keyword you already track. Free.", passes: 0, path: "keywords", channels: false },
+  { kind: "brand", label: "Your brand", hint: "Reads your brand documents for names to watch.", passes: 1, path: "brand", channels: false },
+  { kind: "competitors", label: "Competitors", hint: "Reads your brand documents for competitor names.", passes: 1, path: "competitors", channels: false },
+  { kind: "engagement", label: "Buyer engagement", hint: "Query buckets shaped like your ideal customer.", passes: 1, path: "engagement", channels: true },
+  { kind: "all", label: "All of them", hint: "Brand, competitors, keywords and engagement in one background run.", passes: 3, path: "all", channels: true },
+];
+const DONE = new Set(["done", "failed"]);
+
+export function AutoSeedPanel({ onSeeded }: { onSeeded?: () => void }) {
+  const brand = useBrand();
+  const [channels, setChannels] = useState<Platform[]>(["x"]);
+  const [confirm, setConfirm] = useState<Kind | null>(null);
+  const [note, setNote] = useState<string | null>(null);
+  const jobId = useRef<string | undefined>(undefined);
+
+  const last = useG8Query((signal) => g8Get<SeedJob>("/social-listeners/auto-seed-status", {}, { signal }).then((r) => r.data), [], { key: ["signals", "seed-status"] });
+  const poll = useJobPoll<SeedJob>((signal) => g8Get<SeedJob>("/social-listeners/auto-seed-status", { job_id: jobId.current }, { signal }).then((r) => r.data), {
+    isTerminal: (s) => DONE.has(String(s.status)),
+    enabled: false,
+    onDone: () => { void last.refetch(); onSeeded?.(); },
+  });
+  useEffect(() => { if (last.data?.status === "running" && last.data.job_id && !poll.polling) { jobId.current = last.data.job_id; poll.start(); } }, [last.data?.status, last.data?.job_id]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const seed = SEEDS.find((s) => s.kind === confirm);
+  const run = useG8Mutation(async (s: (typeof SEEDS)[number]): Promise<Record<string, unknown>> => {
+    const body = s.channels ? { channels } : undefined;
+    return (await g8Post<Record<string, unknown>>(`/social-listeners/auto-seed/${s.path}`, body)).data;
+  }, {
+    onSuccess: (r, s) => {
+      setConfirm(null);
+      if (s.kind === "all") { jobId.current = typeof r.job_id === "string" ? r.job_id : undefined; setNote("The run started in the background. Credits are charged as each pass completes."); poll.start(); }
+      else { setNote(`${s.label}: done.`); onSeeded?.(); }
+    },
+    invalidates: [["signals", "listeners"], ["signals", "stats"], ["signals", "seed-status"]],
+  });
+  const toggle = (p: Platform): void => setChannels((c) => (c.includes(p) ? c.filter((x) => x !== p) : [...c, p]));
+  const shown = poll.status ?? last.data;
+  const credits = (seed?.passes ?? 0) * AI_PASS_CREDITS;
+
+  return (
+    <SectionCard title={`Start from what ${brand.linkLabel} knows`} description="Create starter listeners instead of writing queries. Each one asks first." icon={<Wand2 className="size-4" />}>
+      <div className="grid gap-3">
+        <fieldset className="flex flex-wrap gap-3"><legend className="mb-1 text-sm font-medium">Channels for buyer engagement and the full run</legend>{PLATFORMS.map((p) => <label key={p.value} className="flex items-center gap-1 text-sm"><input type="checkbox" checked={channels.includes(p.value)} onChange={() => toggle(p.value)} />{p.label}</label>)}</fieldset>
+        <ul className="grid gap-2">
+          {SEEDS.map((s) => (
+            <li key={s.kind} className="flex flex-wrap items-center justify-between gap-2 rounded-md border p-2">
+              <span><span className="block text-sm font-medium">{s.label}</span><span className="text-muted-foreground block text-xs">{s.hint}</span></span>
+              <Button size="sm" variant="outline" aria-label={`Seed ${s.label}`} disabled={(s.channels && channels.length === 0) || poll.polling} onClick={() => setConfirm(s.kind)}>Create</Button>
+            </li>
+          ))}
+        </ul>
+        {note ? <p role="status" className="text-sm">{note}</p> : null}
+        {last.loading && !last.data ? <Skeleton className="h-5 w-48" /> : null}
+        {last.error ? <ApiError compact error={last.error} title="Could not read the last run" onRetry={() => void last.refetch()} /> : null}
+        {shown?.status ? (
+          <p className="flex flex-wrap items-center gap-2 text-sm" role="status">Last run <StatusPill tone={shown.status === "failed" ? "negative" : shown.status === "done" ? "positive" : "info"}>{shown.status}</StatusPill>{shown.stage && shown.status === "running" ? `at ${shown.stage}` : ""}
+            {shown.result ? ` · ${shown.result.brand_created ?? 0} brand, ${shown.result.competitors_created ?? 0} competitor, ${shown.result.keywords_created ?? 0} keyword, ${shown.result.engagement_created ?? 0} engagement listeners created` : ""}{shown.error ? ` · ${shown.error}` : ""}</p>
+        ) : null}
+        {poll.error ? <ApiError compact error={poll.error} title="Could not follow the run" onRetry={() => poll.start()} /> : null}
+      </div>
+      <ConfirmSpendDialog
+        open={seed !== undefined}
+        tier="billable"
+        title={`Create ${seed?.label.toLowerCase() ?? ""} listeners?`}
+        estimatedCredits={credits}
+        description={(
+          <>
+            <p>{seed?.passes === 0 ? "This reads keywords you already track and charges nothing to create the listeners." : `${seed?.passes === 3 ? "Up to three" : "One"} language-model ${seed?.passes === 1 ? "pass" : "passes"} at ${AI_PASS_CREDITS} credits each.`}{seed?.kind === "all" ? " The run is in the background and the charges land after it starts." : ""} The new listeners then spend credits as they read posts, within their monthly caps.</p>
+            {run.error ? <ApiError error={run.error} title="The listeners were not created" /> : null}
+          </>
+        )}
+        confirmLabel="Create"
+        confirming={run.loading}
+        onCancel={() => setConfirm(null)}
+        onConfirm={() => { if (seed) void run.mutate(seed); }}
+      />
+    </SectionCard>
+  );
+}

package/blocks/signals/components/listener-form.tsx

@@ -0,0 +1,184 @@
+"use client";
+
+/**
+ * ListenerForm: create a listener (what to watch, on which channel, how often, the monthly credit cap) or edit one.
+ *
+ * SDK operations, in order:
+ *   1. getListener (GET /social-listeners/{listener_id})          read      edit only: the FULL record is read before the form shows
+ *   2. previewListenerCost (POST /social-listeners/preview-cost)  read      an estimate, charges nothing
+ *   3. generateListenerQuery (POST /social-listeners/queries/generate) billable  a language-model call; ConfirmSpendDialog, 5 credits a pass
+ *   4. createListener (POST /social-listeners)                    billable  ConfirmSpendDialog; a brand listener with no query also pays for one generated query
+ *   5. updateListener (PATCH /social-listeners/{listener_id})     billable  ConfirmSpendDialog; only changed fields are sent
+ * Nothing is invented: the poll interval and the credit cap are sent only when the person typed them, and the confirm
+ * says what bounds the spend (the cap) instead of a made-up total. After a save the listener caches are refreshed.
+ */
+
+import { useState } from "react";
+import { Sparkles } from "lucide-react";
+import { Button, Input, Label, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { AI_PASS_CREDITS, LISTENER_TYPES, MIN_POLL_SEC, PLATFORMS, capText, fmt, listenerDiff, num, typeLabel } from "../lib/signals-types";
+import type { CostPreview, Listener, ListenerDetailData, ListenerType, Platform } from "../lib/signals-types";
+
+export interface ListenerFormProps {
+  /** Edit this listener; omit to create one. */
+  listener?: Listener;
+  onSaved: (listener: Listener) => void;
+  onCancel?: () => void;
+}
+
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm disabled:opacity-50";
+
+/** Edit mode reads the full record first: a list row may omit fields, and saving a form seeded from it would blank them. */
+export function ListenerForm({ listener, onSaved, onCancel }: ListenerFormProps) {
+  const full = useG8Query(
+    (signal) => g8Get<ListenerDetailData>(`/social-listeners/${encodeURIComponent(listener!.id)}`, {}, { signal }).then((r) => r.data.listener),
+    [listener?.id],
+    { enabled: Boolean(listener), key: ["signals", "listener", listener?.id ?? ""], placeholderData: listener },
+  );
+  if (!listener) return <ListenerFields onSaved={onSaved} onCancel={onCancel} />;
+  if (full.error && (!full.data || full.isPlaceholderData)) return <ApiError error={full.error} title="Could not load this listener" onRetry={() => void full.refetch()} />;
+  if (!full.data || full.isPlaceholderData || full.data.id !== listener.id) return <Skeleton className="h-40 w-full" aria-label="Loading listener" />;
+  return <ListenerFields key={full.data.id} listener={full.data} onSaved={onSaved} onCancel={onCancel} />;
+}
+
+function ListenerFields({ listener, onSaved, onCancel }: ListenerFormProps) {
+  const brand = useBrand();
+  const editing = Boolean(listener);
+  const [type, setType] = useState<ListenerType>((listener?.listener_type as ListenerType) ?? "keyword");
+  const [platform, setPlatform] = useState<Platform>((listener?.platform as Platform) ?? "x");
+  const [name, setName] = useState(listener?.name ?? "");
+  const [query, setQuery] = useState(listener?.query ?? "");
+  const [handle, setHandle] = useState(listener?.target_handle ?? "");
+  const [poll, setPoll] = useState(listener?.poll_interval_sec != null ? String(listener.poll_interval_sec) : "");
+  const [cap, setCap] = useState(listener?.monthly_credit_cap != null ? String(listener.monthly_credit_cap) : "");
+  const [describe, setDescribe] = useState("");
+  const [confirm, setConfirm] = useState<"save" | "generate" | null>(null);
+
+  const pollN = poll.trim() === "" ? null : Number(poll);
+  const capN = cap.trim() === "" ? null : Number(cap);
+  const pollOk = pollN === null || (Number.isInteger(pollN) && pollN >= MIN_POLL_SEC);
+  const capOk = capN === null || (Number.isInteger(capN) && capN >= 0);
+  const isUser = type === "user";
+  const brandNoQuery = !editing && type === "brand" && query.trim() === "";
+  // The API cannot unset a query once it is set (a null is dropped), so clearing one is refused here rather than reported as saved.
+  const clearedQuery = editing && Boolean(listener?.query) && !isUser && query.trim() === "";
+  const valid = name.trim() !== "" && pollOk && capOk && !clearedQuery && (isUser ? handle.trim() !== "" : type === "brand" || query.trim() !== "");
+  const diff = listener ? listenerDiff(listener, { name, query, target_handle: handle, poll_interval_sec: pollN, monthly_credit_cap: capN }) : {};
+  const changed = Object.keys(diff).length > 0;
+
+  const cost = useG8Mutation(async (): Promise<CostPreview> => {
+    const body: Record<string, unknown> = { listener_type: type, platform };
+    if (query.trim()) body.query = query.trim();
+    if (isUser && handle.trim()) body.target_handle = handle.trim();
+    if (pollN !== null) body.poll_interval_sec = pollN;
+    return (await g8Post<CostPreview>("/social-listeners/preview-cost", body)).data;
+  });
+  const generate = useG8Mutation(async (): Promise<{ query?: string; suggested_name?: string }> => (await g8Post<{ query?: string; suggested_name?: string }>("/social-listeners/queries/generate", { listener_type: type, description: describe.trim() })).data, {
+    onSuccess: (r) => { setConfirm(null); if (r.query) setQuery(r.query); if (r.suggested_name && !name.trim()) setName(r.suggested_name); },
+  });
+  const save = useG8Mutation(async (): Promise<Listener> => {
+    if (listener) return (await g8Patch<Listener>(`/social-listeners/${encodeURIComponent(listener.id)}`, diff)).data;
+    const body: Record<string, unknown> = { listener_type: type, platform, name: name.trim() };
+    if (query.trim()) body.query = query.trim();
+    if (isUser) body.target_handle = handle.trim();
+    if (pollN !== null) body.poll_interval_sec = pollN;
+    if (capN !== null) body.monthly_credit_cap = capN;
+    return (await g8Post<Listener>("/social-listeners", body)).data;
+  }, { onSuccess: (saved) => { setConfirm(null); onSaved(saved); }, invalidates: (saved) => [["signals", "listeners"], ["signals", "listener", saved.id], ["signals", "stats"]] });
+
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (valid && (!editing || changed)) setConfirm("save"); }}>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div>
+          <Label htmlFor="g8-sl-type" className="mb-1">What to watch</Label>
+          <select id="g8-sl-type" className={SELECT} value={type} disabled={editing} onChange={(e) => setType(e.target.value as ListenerType)}>
+            {LISTENER_TYPES.map((t) => <option key={t.value} value={t.value}>{t.label}</option>)}
+          </select>
+          <p className="text-muted-foreground mt-1 text-xs">{editing ? `${typeLabel(type)} is fixed once a listener exists.` : LISTENER_TYPES.find((t) => t.value === type)?.hint}</p>
+        </div>
+        <div>
+          <Label htmlFor="g8-sl-platform" className="mb-1">Channel</Label>
+          <select id="g8-sl-platform" className={SELECT} value={platform} disabled={editing} onChange={(e) => setPlatform(e.target.value as Platform)}>
+            {PLATFORMS.map((p) => <option key={p.value} value={p.value}>{p.label}</option>)}
+          </select>
+        </div>
+      </div>
+      <div><Label htmlFor="g8-sl-name" className="mb-1">Name</Label><Input id="g8-sl-name" value={name} onChange={(e) => setName(e.target.value)} placeholder="Competitor mentions" /></div>
+      {isUser ? (
+        <div><Label htmlFor="g8-sl-handle" className="mb-1">Account handle</Label><Input id="g8-sl-handle" value={handle} onChange={(e) => setHandle(e.target.value)} placeholder="@handle" /></div>
+      ) : (
+        <div>
+          <Label htmlFor="g8-sl-query" className="mb-1">Search query{type === "brand" ? " (optional)" : ""}</Label>
+          <Textarea id="g8-sl-query" rows={2} value={query} onChange={(e) => setQuery(e.target.value)} />
+          {clearedQuery ? <p role="note" className="text-warning-foreground mt-1 text-xs">A query can't be removed once set; edit it or delete the listener.</p> : null}
+          {brandNoQuery ? <p className="text-warning-foreground mt-1 text-xs" role="note">With no query the app writes one with a language model, which is charged ({AI_PASS_CREDITS} credits).</p> : null}
+        </div>
+      )}
+      {!isUser ? (
+        <div className="grid gap-2 rounded-md border p-3">
+          <Label htmlFor="g8-sl-describe">Describe it and let {brand.linkLabel} write the query</Label>
+          <Textarea id="g8-sl-describe" rows={2} maxLength={1000} value={describe} onChange={(e) => setDescribe(e.target.value)} placeholder="People complaining about slow onboarding in CRM tools" />
+          <div><Button type="button" size="sm" variant="outline" disabled={describe.trim() === ""} onClick={() => setConfirm("generate")}><Sparkles className="size-4" />Write the query</Button></div>
+          {generate.error ? <ApiError error={generate.error} title="Could not write the query" /> : null}
+        </div>
+      ) : null}
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div><Label htmlFor="g8-sl-poll" className="mb-1">Check every (seconds, optional)</Label><Input id="g8-sl-poll" inputMode="numeric" value={poll} onChange={(e) => setPoll(e.target.value)} placeholder="The app's own default" /></div>
+        <div><Label htmlFor="g8-sl-cap" className="mb-1">Monthly credit cap (optional)</Label><Input id="g8-sl-cap" inputMode="numeric" value={cap} onChange={(e) => setCap(e.target.value)} placeholder="The app's own default" /></div>
+      </div>
+      {!pollOk ? <p role="alert" className="text-error text-xs">The interval must be a whole number of at least {MIN_POLL_SEC} seconds.</p> : null}
+      {!capOk ? <p role="alert" className="text-error text-xs">The cap must be a whole number, 0 or more.</p> : null}
+      <div className="grid gap-1">
+        <div><Button type="button" size="sm" variant="outline" loading={cost.loading} disabled={!(isUser ? handle.trim() : query.trim()) || !pollOk} onClick={() => void cost.mutate(undefined)}>Estimate monthly cost</Button></div>
+        {cost.data ? (
+          <p role="status" className="text-muted-foreground text-xs">
+            About {fmt(cost.data.posts_per_day_estimate)} posts a day, {fmt(cost.data.credits_per_month_estimate)} credits a month. {cost.data.note ?? ""}
+          </p>
+        ) : null}
+        {cost.error ? <ApiError error={cost.error} title="Could not estimate the cost" /> : null}
+      </div>
+      {save.error ? <ApiError error={save.error} title="Could not save the listener" /> : null}
+      <div className="flex gap-2">
+        <Button type="submit" disabled={!valid || (editing && !changed)}>{editing ? "Save changes" : "Create listener"}</Button>
+        {onCancel ? <Button type="button" variant="outline" onClick={onCancel}>Cancel</Button> : null}
+      </div>
+      <ConfirmSpendDialog
+        open={confirm === "generate"}
+        tier="billable"
+        title="Write a query with a language model?"
+        estimatedCredits={AI_PASS_CREDITS}
+        description={<p>One language-model call turns your description into a search query. You can edit the result before anything is created.</p>}
+        confirmLabel="Write query"
+        confirming={generate.loading}
+        onCancel={() => setConfirm(null)}
+        onConfirm={() => void generate.mutate(undefined)}
+      />
+      <ConfirmSpendDialog
+        open={confirm === "save"}
+        tier="billable"
+        title={editing ? `Save changes to ${listener!.name}?` : `Create the ${typeLabel(type).toLowerCase()} listener "${name.trim()}"?`}
+        estimatedCredits={brandNoQuery ? AI_PASS_CREDITS : undefined}
+        description={(
+          <>
+            <p>
+              {editing ? "The listener keeps polling with its new settings." : "The listener starts polling. Reading posts costs credits as they arrive."} Spend is bounded by its monthly cap: {capText(editing ? (capN ?? num(listener?.monthly_credit_cap)) : capN)}
+              {!editing && capN === null ? "; none was set here, so the org-wide caps in Settings apply" : ""}.
+            </p>
+            {editing && "target_handle" in diff ? <p>Changing the account re-resolves it against the channel, which uses X API quota.</p> : null}
+            {save.error ? <ApiError error={save.error} title="The listener was not saved" /> : null}
+          </>
+        )}
+        confirmLabel={editing ? "Save" : "Create"}
+        confirming={save.loading}
+        onCancel={() => setConfirm(null)}
+        onConfirm={() => void save.mutate(undefined)}
+      />
+    </form>
+  );
+}