@graph8/sdk 0.373.0 → 0.374.0

package/blocks/signals/components/social-settings.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+/**
+ * SocialSettings: the org-wide spend ceilings and capture rules for social listening. These decide whether an
+ * over-eager listener can keep spending, so every save is confirmed with the before and after of each limit.
+ *
+ * SDK operations, in order:
+ *   1. getSocialSettings (GET /social-listeners/settings)    read      the full settings are read before the form shows (edit-before-load)
+ *   2. updateSocialSettings (PATCH /social-listeners/settings) billable tier, ADMIN ONLY (a 403 is explained); ConfirmSpendDialog lists each change
+ * Only changed fields are sent. A channel or capture rule that changed is sent whole (the API rebuilds a rule from its
+ * defaults), but only with the fields the API reported plus the ones edited: nothing is filled in. The API answers a complete
+ * rule for every channel it holds; a channel it does not report is not shown, because there is nothing to edit.
+ * A cleared number is not sent: the API cannot unset one.
+ */
+
+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 { SectionCard } from "@/g8/components/screen/section-card";
+import { g8Get, g8Patch } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { CHANNEL_NUMBERS, LISTENER_TYPES, PLATFORMS, SETTING_NUMBERS, fmt, num, wholeNumber } from "../lib/signals-types";
+import type { CaptureRule, ChannelRule, SocialSettings } from "../lib/signals-types";
+
+
+export function SocialSettingsPanel() {
+  const q = useG8Query((signal) => g8Get<SocialSettings>("/social-listeners/settings", {}, { signal }).then((r) => r.data), [], { key: ["signals", "settings"] });
+  if (q.error && !q.data) return <ApiError error={q.error} title="Could not load settings" onRetry={() => void q.refetch()} />;
+  if (!q.data) return <Skeleton className="h-48 w-full" aria-label="Loading settings" />;
+  return <SettingsFields key={q.updatedAt ?? 0} settings={q.data} />;
+}
+
+function SettingsFields({ settings }: { settings: SocialSettings }) {
+  const [numbers, setNumbers] = useState<Record<string, string>>(() => Object.fromEntries(SETTING_NUMBERS.map((f) => [f.key, settings[f.key] == null ? "" : String(settings[f.key])])));
+  const [pause, setPause] = useState(Boolean(settings.auto_pause_on_cap));
+  const [create, setCreate] = useState(Boolean(settings.auto_create_contacts));
+  const reportedChannels = PLATFORMS.filter((p) => settings.channel_settings?.[p.value]);
+  const reportedCapture = LISTENER_TYPES.filter((t) => settings.contact_capture?.[t.value]);
+  const [channels, setChannels] = useState<Record<string, ChannelRule>>(() => Object.fromEntries(reportedChannels.map((p) => [p.value, { ...settings.channel_settings![p.value] }])));
+  const [capture, setCapture] = useState<Record<string, CaptureRule>>(() => Object.fromEntries(reportedCapture.map((t) => [t.value, { ...settings.contact_capture![t.value] }])));
+  const [confirm, setConfirm] = useState(false);
+  // What was typed into a channel or capture number box, kept as text so it can be emptied while retyping; applied once it is a whole number.
+  const [raw, setRaw] = useState<Record<string, string>>({});
+  const setNum = (id: string, text: string, apply: (n: number) => void): void => { setRaw((r) => ({ ...r, [id]: text })); const n = wholeNumber(text); if (n !== null) apply(n); };
+
+  const body: Record<string, unknown> = {};
+  const lines: string[] = [];
+  for (const f of SETTING_NUMBERS) {
+    const next = wholeNumber(numbers[f.key] ?? "", f.max);
+    if (next !== null && next !== num(settings[f.key])) { body[f.key] = next; lines.push(`${f.label}: ${fmt(settings[f.key])} to ${next.toLocaleString()}`); }
+  }
+  if (pause !== Boolean(settings.auto_pause_on_cap)) { body.auto_pause_on_cap = pause; lines.push(`Pause at the cap: ${pause ? "on" : "off (spending continues past the cap)"}`); }
+  if (create !== Boolean(settings.auto_create_contacts)) { body.auto_create_contacts = create; lines.push(`Create contacts from matched authors: ${create ? "on" : "off"}`); }
+  const chBody: Record<string, ChannelRule> = {};
+  for (const p of reportedChannels) if (JSON.stringify(settings.channel_settings![p.value]) !== JSON.stringify(channels[p.value])) {
+    chBody[p.value] = channels[p.value];
+    const before = settings.channel_settings![p.value] as Record<string, unknown>;
+    for (const [k, v] of Object.entries(channels[p.value])) if (before[k] !== v) lines.push(`${p.label} ${k.replace(/_/g, " ")}: ${before[k] === undefined ? "-" : typeof before[k] === "number" ? (before[k] as number).toLocaleString() : String(before[k])} to ${typeof v === "number" ? v.toLocaleString() : String(v)}`);
+  }
+  if (Object.keys(chBody).length) body.channel_settings = chBody;
+  const capBody: Record<string, CaptureRule> = {};
+  for (const t of reportedCapture) if (JSON.stringify(settings.contact_capture![t.value]) !== JSON.stringify(capture[t.value])) { capBody[t.value] = capture[t.value]; lines.push(`Contact capture for ${t.label.toLowerCase()} listeners`); }
+  if (Object.keys(capBody).length) body.contact_capture = capBody;
+  const invalid = SETTING_NUMBERS.some((f) => numbers[f.key] !== "" && wholeNumber(numbers[f.key], f.max) === null) || Object.values(raw).some((t) => wholeNumber(t) === null);
+
+  const save = useG8Mutation((): Promise<unknown> => g8Patch("/social-listeners/settings", body), { onSuccess: () => setConfirm(false), invalidates: [["signals", "settings"], ["signals", "stats"]] });
+  const setCh = (p: string, patch: Partial<ChannelRule>): void => setChannels((c) => ({ ...c, [p]: { ...c[p], ...patch } }));
+  const setCap = (t: string, patch: Partial<CaptureRule>): void => setCapture((c) => ({ ...c, [t]: { ...c[t], ...patch } }));
+
+  return (
+    <form className="grid gap-4" onSubmit={(e) => { e.preventDefault(); if (lines.length && !invalid) setConfirm(true); }}>
+      <SectionCard title="Spend limits" description="These bound what social listening can cost your workspace. Changing them needs an admin.">
+        <div className="grid gap-3 sm:grid-cols-2">
+          {SETTING_NUMBERS.map((f) => (
+            <div key={f.key}><Label htmlFor={`g8-ss-${f.key}`} className="mb-1">{f.label}</Label><Input id={`g8-ss-${f.key}`} inputMode="numeric" value={numbers[f.key]} onChange={(e) => setNumbers((n) => ({ ...n, [f.key]: e.target.value }))} /><p className="text-muted-foreground mt-1 text-xs">{f.hint}</p></div>
+          ))}
+          <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={pause} onChange={(e) => setPause(e.target.checked)} />Stop polling when the cap is reached</label>
+          <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={create} onChange={(e) => setCreate(e.target.checked)} />Create contacts from matched authors</label>
+        </div>
+      </SectionCard>
+      <SectionCard title="Channels" description="Per-channel ceilings and whether to fetch who engaged with each post (this multiplies what a poll costs).">
+        <div className="grid gap-3">
+          {reportedChannels.map((p) => (
+            <fieldset key={p.value} className="grid gap-2 rounded-md border p-3">
+              <legend className="px-1 text-sm font-medium">{p.label}</legend>
+              <div className="flex flex-wrap gap-4">
+                <label className="flex items-center gap-1 text-sm"><input type="checkbox" aria-label={`${p.label} enabled`} checked={channels[p.value].enabled === true} onChange={(e) => setCh(p.value, { enabled: e.target.checked })} />Enabled</label>
+                <label className="flex items-center gap-1 text-sm"><input type="checkbox" aria-label={`${p.label} fetch engagements`} checked={channels[p.value].fetch_engagements === true} onChange={(e) => setCh(p.value, { fetch_engagements: e.target.checked })} />Fetch engagements</label>
+              </div>
+              <div className="grid gap-2 sm:grid-cols-4">
+                {CHANNEL_NUMBERS.map((f) => (
+                  <div key={f.key}><Label htmlFor={`g8-ss-${p.value}-${f.key}`} className="mb-1 text-xs">{f.label}</Label><Input id={`g8-ss-${p.value}-${f.key}`} inputMode="numeric" value={raw[`${p.value}.${f.key}`] ?? (channels[p.value][f.key] == null ? "" : String(channels[p.value][f.key]))} onChange={(e) => setNum(`${p.value}.${f.key}`, e.target.value, (n) => setCh(p.value, { [f.key]: n }))} /></div>
+                ))}
+              </div>
+            </fieldset>
+          ))}
+        </div>
+      </SectionCard>
+      <SectionCard title="Contact capture" description="When the author of a matched post becomes a contact, by listener type.">
+        <div className="grid gap-2">
+          {reportedCapture.map((t) => (
+            <div key={t.value} className="flex flex-wrap items-center gap-4 rounded-md border p-2 text-sm">
+              <span className="w-24 font-medium">{t.label}</span>
+              <label className="flex items-center gap-1"><input type="checkbox" aria-label={`${t.label} capture enabled`} checked={capture[t.value].enabled === true} onChange={(e) => setCap(t.value, { enabled: e.target.checked })} />Capture</label>
+              <label className="flex items-center gap-1"><input type="checkbox" aria-label={`${t.label} only when classified`} checked={capture[t.value].only_when_classified === true} onChange={(e) => setCap(t.value, { only_when_classified: e.target.checked })} />Only when scored</label>
+              <label className="flex items-center gap-1">Min followers<Input aria-label={`${t.label} minimum followers`} className="w-24" inputMode="numeric" value={raw[`${t.value}.min_followers`] ?? (capture[t.value].min_followers == null ? "" : String(capture[t.value].min_followers))} onChange={(e) => setNum(`${t.value}.min_followers`, e.target.value, (n) => setCap(t.value, { min_followers: n }))} /></label>
+            </div>
+          ))}
+        </div>
+      </SectionCard>
+      {invalid ? <p role="alert" className="text-error text-xs">Limits must be whole numbers, 0 or more (the alert share at most 100). A limit can't be unset; enter a number.</p> : null}
+      {save.error ? <ApiError error={save.error} title="Could not save the settings" /> : null}
+      <div><Button type="submit" disabled={lines.length === 0 || invalid}>Save settings</Button></div>
+      <ConfirmSpendDialog
+        open={confirm}
+        tier="billable"
+        title="Change the social listening limits?"
+        description={<><ul className="list-disc pl-5 text-sm">{lines.map((l) => <li key={l}>{l}</li>)}</ul><p className="mt-2">Raising a cap or turning off the pause lets listeners spend more credits.</p>{save.error ? <ApiError error={save.error} title="Could not save the settings" /> : null}</>}
+        confirmLabel="Save"
+        confirming={save.loading}
+        onCancel={() => setConfirm(false)}
+        onConfirm={() => void save.mutate(undefined)}
+      />
+    </form>
+  );
+}

package/blocks/signals/components/source-lists.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+/**
+ * SourceLists: graph8 lists that feed account listeners, and one-step creation of a listener per profile on a list.
+ *
+ * SDK operations, in order:
+ *   1. listSourceLists (GET /social-listeners/source-lists)              read      lists already used as a source
+ *   2. listLists (GET /lists), through ListSelect                         read      the list to turn into listeners
+ *   3. bulkCreateListenersFromList (POST /social-listeners/bulk-from-list) billable  creates one `user` listener per social profile on the list
+ *      and per chosen channel; ConfirmSpendDialog states the most listeners it can create (list size x channels, from the list itself)
+ *      and that spend then follows the per-listener caps. Handles resolve later, so creation itself spends nothing.
+ */
+
+import { useState } from "react";
+import { Button, Label, Skeleton } 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 { SectionCard } from "@/g8/components/screen/section-card";
+import { ListSelect } from "@/g8/crm/components/list-select";
+import type { ListSelectOption } from "@/g8/crm/components/list-select";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { PLATFORMS, fmt, itemsOf, num, when } from "../lib/signals-types";
+import type { Platform, SourceList } from "../lib/signals-types";
+
+interface BulkResult { list_title?: string; created_count?: number; skipped_no_handle?: number; skipped_duplicate?: number; sample_handles?: string[] }
+const SELECT = "border-input bg-background h-9 w-full rounded-md border px-2 text-sm";
+
+export function SourceLists() {
+  const [list, setList] = useState<ListSelectOption | null>(null);
+  const [channels, setChannels] = useState<Platform[]>(["x"]);
+  const [confirm, setConfirm] = useState(false);
+  const sources = useG8Query((signal) => g8Get<unknown>("/social-listeners/source-lists", {}, { signal }).then((r) => itemsOf<SourceList>(r.data)), [], { key: ["signals", "sources"] });
+  const run = useG8Mutation(async (): Promise<BulkResult> => (await g8Post<BulkResult>("/social-listeners/bulk-from-list", { list_id: Number(list!.id), platforms: channels })).data, {
+    onSuccess: () => setConfirm(false),
+    invalidates: [["signals", "sources"], ["signals", "listeners"], ["signals", "stats"]],
+  });
+  const size = num(list?.contact_count);
+  const max = size === null ? null : size * channels.length;
+  const toggle = (p: Platform): void => setChannels((c) => (c.includes(p) ? c.filter((x) => x !== p) : [...c, p]));
+  const r = run.data;
+
+  return (
+    <div className="grid gap-4">
+      <SectionCard title="Watch the people on a list" description="Creates one account listener for every social profile on the list, on each channel you tick.">
+        <div className="grid gap-3">
+          <div><Label htmlFor="g8-sl-src" className="mb-1">List</Label><ListSelect id="g8-sl-src" label="List" type="contacts" emptyOption="Choose a list" value={list?.id ?? ""} valueLabel={list?.title} selectClassName={SELECT} onChange={setList} /></div>
+          <fieldset className="flex flex-wrap gap-3"><legend className="mb-1 text-sm font-medium">Channels</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>
+          <div><Button disabled={!list || channels.length === 0} onClick={() => setConfirm(true)}>Create listeners</Button></div>
+          {r ? <p role="status" className="text-sm">{plural(r.created_count ?? 0, "listener")} created for {r.list_title ?? "the list"}; {r.skipped_no_handle ?? 0} skipped for no handle, {r.skipped_duplicate ?? 0} already watched.</p> : null}
+        </div>
+      </SectionCard>
+      <SectionCard title="Lists already feeding listeners">
+        {sources.error ? <ApiError error={sources.error} title="Could not load source lists" onRetry={() => void sources.refetch()} /> : sources.loading && !sources.data ? <Skeleton className="h-16 w-full" /> : (sources.data ?? []).length === 0 ? (
+          <EmptyState compact title="No source lists yet" description="Pick a list above to start watching its people." />
+        ) : (
+          <ul className="grid gap-2">{(sources.data ?? []).map((s) => (
+            <li key={s.audience_id} className="rounded-md border p-2 text-sm"><span className="font-medium">{s.list_title || "-"}</span><span className="text-muted-foreground block text-xs">{fmt(s.contact_count)} contacts · {fmt(s.total_listeners_created)} listeners created · {s.is_dynamic ? "re-scanned as contacts are added" : "one-time"} · last synced {when(s.last_synced_at)}</span></li>
+          ))}</ul>
+        )}
+      </SectionCard>
+      <ConfirmSpendDialog
+        open={confirm}
+        tier="billable"
+        title={`Create listeners for ${list?.title ?? "this list"}?`}
+        affected={max ?? undefined}
+        description={(
+          <>
+            <p>{max === null ? "The list does not report its size." : `Up to ${plural(max, "listener")} are created (${plural(size ?? 0, "contact")} on ${plural(channels.length, "channel")}); people with no profile are skipped.`} Creating them spends nothing. Each listener then spends credits as it reads posts, up to its own monthly cap and the org-wide caps.</p>
+            {run.error ? <ApiError error={run.error} title="Could not create the listeners" /> : null}
+          </>
+        )}
+        confirmLabel="Create"
+        confirming={run.loading}
+        onCancel={() => setConfirm(false)}
+        onConfirm={() => void run.mutate(undefined)}
+      />
+    </div>
+  );
+}

package/blocks/signals/components/top-engagers.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+/**
+ * TopEngagers: the accounts that engage with your matched posts most often (the warm audience).
+ *
+ * SDK operations: listTopEngagedAccounts (GET /social-listeners/engagements/top-accounts)  read. One read of up to 200
+ * rows (the API's cap); when it comes back full the list says it shows the first 200. Filters: window, channel, and a
+ * minimum number of posts (omitted unless typed, so the API's own default applies).
+ */
+
+import { useState } from "react";
+import { ExternalLink } from "lucide-react";
+import { Input, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { FirstNotice } from "@/g8/components/paging-notices";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { PLATFORMS, fmt, itemsOf, platformLabel, when } from "../lib/signals-types";
+import type { TopAccount } from "../lib/signals-types";
+
+const LIMIT = 200;
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+
+export function TopEngagers() {
+  const [days, setDays] = useState("30");
+  const [platform, setPlatform] = useState("");
+  const [minPosts, setMinPosts] = useState("");
+  const min = minPosts.trim() === "" ? undefined : Number(minPosts);
+  const minOk = min === undefined || (Number.isInteger(min) && min >= 1);
+  const q = useG8Query(
+    (signal) => g8Get<unknown>("/social-listeners/engagements/top-accounts", { days: Number(days), platform: platform || undefined, min_posts: minOk ? min : undefined, limit: LIMIT }, { signal }).then((r) => itemsOf<TopAccount>(r.data)),
+    [days, platform, minOk ? min : undefined],
+    { key: ["signals", "top", days, platform, minOk ? min ?? "" : ""] },
+  );
+  const rows = q.data ?? [];
+  return (
+    <div className="grid gap-3">
+      <div className="flex flex-wrap items-center gap-2">
+        <select aria-label="Window" className={SELECT} value={days} onChange={(e) => setDays(e.target.value)}>{[7, 30, 90, 365].map((d) => <option key={d} value={d}>Last {d} days</option>)}</select>
+        <select aria-label="Channel" className={SELECT} value={platform} onChange={(e) => setPlatform(e.target.value)}><option value="">All channels</option>{PLATFORMS.map((p) => <option key={p.value} value={p.value}>{p.label}</option>)}</select>
+        <Input aria-label="Minimum posts engaged" className="w-44" inputMode="numeric" placeholder="Minimum posts" value={minPosts} onChange={(e) => setMinPosts(e.target.value)} />
+        {!minOk ? <span role="alert" className="text-error text-xs">Use a whole number, 1 or more.</span> : null}
+      </div>
+      {q.error ? <ApiError error={q.error} title="Could not load top engagers" onRetry={() => void q.refetch()} /> : q.loading && !q.data ? <Skeleton className="h-24 w-full" aria-label="Loading top engagers" /> : rows.length === 0 ? (
+        <EmptyState compact title="No repeat engagers yet" description="Accounts appear when they engage with more than one matched post." />
+      ) : (
+        <table className="w-full text-sm">
+          <thead><tr className="text-muted-foreground text-left text-xs"><th className="p-2">Account</th><th className="p-2">Channel</th><th className="p-2">Posts</th><th className="p-2">Comments</th><th className="p-2">Reactions</th><th className="p-2">Last engaged</th></tr></thead>
+          <tbody>
+            {rows.map((a) => (
+              <tr key={`${a.platform}:${a.author_external_id}`} className="border-t">
+                <td className="p-2"><span className="flex items-center gap-2"><EntityAvatar name={a.author_name || a.author_handle || "?"} size="sm" /><span><span className="block font-medium">{a.author_name || a.author_handle || "-"}</span><span className="text-muted-foreground block text-xs">{a.author_headline || "-"}</span></span>{a.author_url && /^https?:\/\//.test(a.author_url) ? <a href={a.author_url} target="_blank" rel="noreferrer noopener" aria-label={`Open ${a.author_name || a.author_handle || "profile"}`}><ExternalLink className="size-3" /></a> : null}</span></td>
+                <td className="p-2">{platformLabel(a.platform)}</td>
+                <td className="p-2 tabular-nums">{fmt(a.posts_engaged)}</td>
+                <td className="p-2 tabular-nums">{fmt(a.comments)}</td>
+                <td className="p-2 tabular-nums">{fmt(a.reactions)}</td>
+                <td className="p-2">{when(a.last_engaged_at)}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      )}
+      <FirstNotice shown={rows.length} limit={LIMIT} noun="accounts" />
+    </div>
+  );
+}

package/blocks/signals/components/x-integration.tsx

@@ -0,0 +1,129 @@
+"use client";
+
+/**
+ * XIntegration: which X credentials listeners poll with, and connecting or removing your own X developer app.
+ *
+ * SDK operations, in order:
+ *   1. getXIntegration (GET /social-listeners/integrations/x)           read      whether your own credentials are stored (never what they are)
+ *   2. getXEffectiveMode (GET /social-listeners/integrations/x/mode)    read      which credentials are ACTUALLY in use and the shared allowance left
+ *   3. listListeners (GET /social-listeners)                            read      to count the X listeners a disconnect affects
+ *   4. testXCredentials (POST /social-listeners/integrations/x/test)    billable tier: a live call to X, stores nothing; ConfirmSpendDialog
+ *   5. connectXCredentials (POST /social-listeners/integrations/x)      billable tier, external account: stores the key and secret write-only; ConfirmSpendDialog
+ *   6. disconnectXCredentials (DELETE /social-listeners/integrations/x) destructive: pauses X listeners; ConfirmSpendDialog with the real count
+ * The key and secret live only in this form's state and are cleared as soon as a call is sent; they are never shown again.
+ * Nothing connects on its own: every call is a confirmed click.
+ */
+
+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 { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { fmt, itemsOf, when } from "../lib/signals-types";
+import type { Listener, XMode, XStatus } from "../lib/signals-types";
+
+type Step = "test" | "connect" | "disconnect" | null;
+interface TestResult { ok?: boolean; x_app_username?: string | null; error?: string | null }
+
+export function XIntegration() {
+  const brand = useBrand();
+  const [apiKey, setApiKey] = useState("");
+  const [apiSecret, setApiSecret] = useState("");
+  const [step, setStep] = useState<Step>(null);
+  const status = useG8Query((signal) => g8Get<XStatus>("/social-listeners/integrations/x", {}, { signal }).then((r) => r.data), [], { key: ["signals", "x", "status"] });
+  const mode = useG8Query((signal) => g8Get<XMode>("/social-listeners/integrations/x/mode", {}, { signal }).then((r) => r.data), [], { key: ["signals", "x", "mode"] });
+  const listeners = useG8Query((signal) => g8Get<unknown>("/social-listeners", {}, { signal }).then((r) => itemsOf<Listener>(r.data)), [], { key: ["signals", "listeners"] });
+  const known = listeners.data !== undefined;
+  const activeX = (listeners.data ?? []).filter((l) => l.platform === "x" && l.is_active).length;
+
+  const send = (path: string): Promise<TestResult> => {
+    const body = { api_key: apiKey.trim(), api_secret: apiSecret.trim() };
+    setApiKey(""); setApiSecret("");
+    return g8Post<TestResult>(path, body).then((r) => r.data);
+  };
+  // The fields are cleared when a call is sent, so the dialog closes on failure too: confirming again would post empty strings.
+  const test = useG8Mutation(() => send("/social-listeners/integrations/x/test"), { onSuccess: () => setStep(null), onError: () => setStep(null) });
+  const connect = useG8Mutation(() => send("/social-listeners/integrations/x"), { onSuccess: () => setStep(null), onError: () => setStep(null), invalidates: [["signals", "x"], ["signals", "listeners"]] });
+  const disconnect = useG8Mutation((): Promise<unknown> => g8Delete("/social-listeners/integrations/x"), { onSuccess: () => setStep(null), invalidates: [["signals", "x"], ["signals", "listeners"], ["signals", "stats"]] });
+  const filled = apiKey.trim() !== "" && apiSecret.trim() !== "";
+  const s = status.data;
+
+  return (
+    <div className="grid gap-4">
+      <SectionCard title="X credentials in use" description={`Listeners on X poll with your own developer app when one is connected, otherwise with the shared allowance from ${brand.linkLabel}.`}>
+        {status.error ? <ApiError error={status.error} title="Could not read the X connection" onRetry={() => void status.refetch()} /> : status.loading && !s ? <Skeleton className="h-16 w-full" /> : (
+          <div className="grid gap-3">
+            <p className="flex flex-wrap items-center gap-2 text-sm">Your own app <StatusPill tone={s?.connected ? "positive" : "neutral"}>{s?.connected ? "connected" : "not connected"}</StatusPill>{s?.degraded_reason ? <StatusPill tone="warning">{s.degraded_reason}</StatusPill> : null}</p>
+            <KeyValueList columns={2} items={[
+              { label: "In use", value: mode.data?.auth_mode ?? "" },
+              { label: "App", value: s?.x_app_username ?? "" },
+              { label: "Connected", value: s?.connected_at ? when(s.connected_at) : "" },
+              { label: "Shared allowance left", value: mode.data?.shared_available ? `${fmt(mode.data.shared_cap_remaining)} of ${fmt(mode.data.shared_cap_total)}` : mode.data ? "Shared mode is not available" : "" },
+            ]} />
+            {mode.error ? <ApiError compact error={mode.error} title="Could not read the X mode" onRetry={() => void mode.refetch()} /> : null}
+            {s?.connected ? (
+              <div className="grid gap-1">
+                <div><Button variant="outline" size="sm" disabled={!known} onClick={() => setStep("disconnect")}>Disconnect your X app</Button></div>
+                {listeners.error ? <ApiError compact error={listeners.error} title="Could not count the X listeners this would pause" onRetry={() => void listeners.refetch()} /> : !known ? <p className="text-muted-foreground text-xs">Counting the X listeners this would pause...</p> : null}
+              </div>
+            ) : null}
+          </div>
+        )}
+      </SectionCard>
+      <SectionCard title={s?.connected ? "Replace your X app" : "Connect your X app"} description="The key and secret are write-only: stored encrypted, never shown again. Test them first so a typo does not pause your listeners.">
+        <form className="grid gap-3 sm:max-w-md" autoComplete="off" onSubmit={(e) => e.preventDefault()}>
+          <div><Label htmlFor="g8-sl-xkey" className="mb-1">API key</Label><Input id="g8-sl-xkey" type="password" autoComplete="off" value={apiKey} onChange={(e) => setApiKey(e.target.value)} /></div>
+          <div><Label htmlFor="g8-sl-xsecret" className="mb-1">API secret</Label><Input id="g8-sl-xsecret" type="password" autoComplete="off" value={apiSecret} onChange={(e) => setApiSecret(e.target.value)} /></div>
+          <div className="flex gap-2">
+            <Button type="button" variant="outline" disabled={!filled} onClick={() => setStep("test")}>Test credentials</Button>
+            <Button type="button" disabled={!filled} onClick={() => setStep("connect")}>Connect</Button>
+          </div>
+          <p className="text-muted-foreground text-xs">Testing clears both fields so the secret is not kept on screen: type them again to connect.</p>
+          {test.data ? <p role="status" className="text-sm">{test.data.ok ? `The credentials work${test.data.x_app_username ? ` (app ${test.data.x_app_username})` : ""}. Nothing was stored.` : `The credentials were refused${test.data.error ? `: ${test.data.error}` : ""}. Nothing was stored.`}</p> : null}
+          {connect.data ? <p role="status" className="text-sm">Connected{connect.data.x_app_username ? ` as ${connect.data.x_app_username}` : ""}.</p> : null}
+          {test.error ? <ApiError error={test.error} title="The test did not run" /> : null}
+          {connect.error ? <ApiError error={connect.error} title="Could not connect" /> : null}
+        </form>
+      </SectionCard>
+      <ConfirmSpendDialog
+        open={step === "test"}
+        tier="billable"
+        title="Test these X credentials?"
+        estimatedCredits={0}
+        description={<p>{brand.linkLabel} calls X once with this key and secret to check them. Nothing is stored. The fields are cleared when you confirm.</p>}
+        confirmLabel="Test"
+        confirming={test.loading}
+        onCancel={() => setStep(null)}
+        onConfirm={() => void test.mutate(undefined)}
+      />
+      <ConfirmSpendDialog
+        open={step === "connect"}
+        tier="billable"
+        title="Connect this X developer app?"
+        description={<p>Your key and secret are stored encrypted and X polls then bill your app directly instead of the shared allowance from {brand.linkLabel}. Existing X listeners keep running under it. The fields are cleared when you confirm.</p>}
+        confirmLabel="Connect"
+        confirming={connect.loading}
+        onCancel={() => setStep(null)}
+        onConfirm={() => void connect.mutate(undefined)}
+      />
+      <ConfirmSpendDialog
+        open={step === "disconnect"}
+        tier="destructive"
+        title="Disconnect your X app?"
+        affected={known ? activeX : undefined}
+        description={<><p>{plural(activeX, "active X listener")} {activeX === 1 ? "is" : "are"} paused. If shared mode is available they resume under it; if not, they stay paused and stop matching.</p>{disconnect.error ? <ApiError error={disconnect.error} title="Could not disconnect" /> : null}</>}
+        confirmLabel="Disconnect"
+        confirming={disconnect.loading}
+        onCancel={() => setStep(null)}
+        onConfirm={() => void disconnect.mutate(undefined)}
+      />
+    </div>
+  );
+}