@graph8/sdk 0.370.0 → 0.374.0

package/blocks/signals/components/matched-posts.tsx

@@ -0,0 +1,195 @@
+"use client";
+
+/**
+ * MatchedPosts: the posts your listeners matched, with filters, paging and triage.
+ *
+ * SDK operations, in order:
+ *   1. searchMatchedPosts (POST /social-listeners/posts/search)              read      a database read of what the worker stored; paged, 100 a page
+ *   2. markPost (POST /social-listeners/posts/{post_id}/mark)                billable   tier only: ConfirmSpendDialog states 0 credits (graph8 documents it as graph-only)
+ *   3. savePostAuthorAsContact (POST /social-listeners/posts/{post_id}/save-contact) billable tier: creates a contact, no enrichment, no credits; confirmed
+ *   4. listSequences (GET /sequences)                                        read      live sequences, paged, when "Add to sequence" opens
+ *   5. addPostAuthorToSequence (POST /social-listeners/posts/{post_id}/add-to-sequence) external  asks the sequencer to enrol a real person: ConfirmSpendDialog
+ * A post is identified by its platform AND its id (the same id means different posts on different channels). Counts the
+ * channel did not report are dashes. The confirm for "add to sequence" says the API only accepts the request.
+ */
+
+import { useState } from "react";
+import { Check, ExternalLink, ListPlus, MessageSquare, UserPlus, X } from "lucide-react";
+import { Button, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, 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 { LoadMore } from "@/g8/components/paging-notices";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { byPage } from "@/g8/lib/paging";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useLoadMoreList } from "@/g8/hooks/use-load-more-list";
+import { PAGE_SIZE, POST_STATUSES, PLATFORMS, fmt, isLiveSequence, itemsOf, morePages, platformLabel, when } from "../lib/signals-types";
+import type { Listener, MatchedPost, SequenceRow } from "../lib/signals-types";
+import { PostEngagements } from "./post-engagements";
+
+export interface MatchedPostsProps {
+  /** Fix the listener filter (a listener's own matches). */
+  listenerId?: string;
+  /** Listeners for the filter box; omit to hide it. */
+  listeners?: Listener[];
+  /** Link to the contact behind an author (for example to your contact page). */
+  renderContact?: (post: MatchedPost) => React.ReactNode;
+}
+
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+const keyOf = (p: Pick<MatchedPost, "platform" | "post_external_id">): string => `${p.platform}:${p.post_external_id}`;
+type Action = { kind: "mark"; post: MatchedPost; status: "reviewed" | "dismissed" } | { kind: "contact"; post: MatchedPost } | { kind: "sequence"; post: MatchedPost; sequence: SequenceRow };
+
+/** Live sequences, paged through (the API answers a page at a time). */
+async function liveSequences(signal: AbortSignal): Promise<SequenceRow[]> {
+  const out: SequenceRow[] = [];
+  for (let page = 1; page <= 50; page++) {
+    const env = await g8Get<SequenceRow[]>("/sequences", { page, limit: 100 }, { signal });
+    const rows = itemsOf<SequenceRow>(env.data);
+    out.push(...rows.filter(isLiveSequence));
+    if (!env.pagination?.has_next || rows.length === 0) break;
+  }
+  return out;
+}
+
+export function MatchedPosts({ listenerId, listeners, renderContact }: MatchedPostsProps) {
+  const [status, setStatus] = useState("");
+  const [platform, setPlatform] = useState("");
+  const [listener, setListener] = useState("");
+  const [withContact, setWithContact] = useState(false);
+  const [hideLow, setHideLow] = useState(false);
+  const [since, setSince] = useState("");
+  const [until, setUntil] = useState("");
+  const [engagersOf, setEngagersOf] = useState<MatchedPost | null>(null);
+  const [picking, setPicking] = useState<MatchedPost | null>(null);
+  const [sequenceId, setSequenceId] = useState("");
+  const [action, setAction] = useState<Action | null>(null);
+  const [done, setDone] = useState<string | null>(null);
+  const effectiveListener = listenerId ?? listener;
+
+  const list = useLoadMoreList<MatchedPost>(byPage(PAGE_SIZE, async (page, signal) => {
+    const body: Record<string, unknown> = { page, limit: PAGE_SIZE };
+    if (status) body.status = status;
+    if (platform) body.platform = platform;
+    if (effectiveListener) body.listener_id = effectiveListener;
+    if (withContact) body.has_contact = true;
+    if (hideLow) body.hide_low_confidence = true;
+    // Local midnight, not UTC: a date picked in the browser means that day where the person is.
+    if (since) body.since = new Date(`${since}T00:00:00`).toISOString();
+    if (until) body.until = new Date(`${until}T23:59:59.999`).toISOString();
+    const env = await g8Post<unknown>("/social-listeners/posts/search", body, { signal });
+    const rows = itemsOf<MatchedPost>(env.data);
+    return { rows, hasNext: morePages(env.data, rows.length, page, PAGE_SIZE) };
+  }), [status, platform, effectiveListener, withContact, hideLow, since, until], { key: ["signals", "posts", { status, platform, effectiveListener, withContact, hideLow, since, until }] });
+
+  const sequences = useG8Query(liveSequences, [], { enabled: picking !== null, key: ["signals", "sequences", "live"] });
+  const run = useG8Mutation(async (a: Action): Promise<void> => {
+    const path = `/social-listeners/posts/${encodeURIComponent(a.post.post_external_id)}`;
+    const query = { platform: a.post.platform };
+    if (a.kind === "mark") await g8Post(`${path}/mark`, { status: a.status }, { query });
+    else if (a.kind === "contact") await g8Post(`${path}/save-contact`, undefined, { query });
+    else await g8Post(`${path}/add-to-sequence`, { sequence_id: a.sequence.id, platform: a.post.platform });
+  }, {
+    onSuccess: (_r, a) => {
+      setAction(null);
+      setDone(a.kind === "mark" ? `Marked ${a.status}.` : a.kind === "contact" ? "Saved as a contact." : `Requested enrolment in ${a.sequence.name ?? "the sequence"}. The sequencer enrols the person afterwards.`);
+      void list.refetch();
+    },
+    invalidates: [["signals", "stats"]],
+  });
+
+  const posts = list.data ?? [];
+  const confirmCopy = (a: Action | null): { title: string; tier: "billable" | "external"; body: string; label: string; credits?: number } => {
+    if (!a) return { title: "", tier: "billable", body: "", label: "Confirm" };
+    const who = a.post.author_name || a.post.author_handle || "this author";
+    if (a.kind === "mark") return { title: `Mark this post from ${who} as ${a.status}?`, tier: "billable", credits: 0, label: a.status === "reviewed" ? "Mark reviewed" : "Dismiss", body: "Only the post's triage state changes. Nothing is sent and no credits are spent." };
+    if (a.kind === "contact") return { title: `Save ${who} as a contact?`, tier: "billable", credits: 0, label: "Save contact", body: "A contact is created from what the post already carries, or the existing one is linked. Nothing is enriched and no credits are spent." };
+    return { title: `Enrol ${who} in ${a.sequence.name ?? "this sequence"}?`, tier: "external", label: "Request enrolment", body: "The author is resolved to a contact and an enrolment request is queued. The sequencer then starts sending to a real person; a success here means the request was accepted, not that they are enrolled." };
+  };
+  const copy = confirmCopy(action);
+
+  return (
+    <div className="grid gap-3">
+      <div className="flex flex-wrap items-center gap-2">
+        <select aria-label="Filter by status" className={SELECT} value={status} onChange={(e) => setStatus(e.target.value)}><option value="">Any status</option>{POST_STATUSES.map((s) => <option key={s.value} value={s.value}>{s.label}</option>)}</select>
+        <select aria-label="Filter by 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>
+        {listeners && !listenerId ? <select aria-label="Filter by listener" className={SELECT} value={listener} onChange={(e) => setListener(e.target.value)}><option value="">All listeners</option>{listeners.map((l) => <option key={l.id} value={l.id}>{l.name}</option>)}</select> : null}
+        <input type="date" aria-label="Posted from" className={SELECT} value={since} onChange={(e) => setSince(e.target.value)} />
+        <input type="date" aria-label="Posted until" className={SELECT} value={until} onChange={(e) => setUntil(e.target.value)} />
+        <label className="flex items-center gap-1 text-sm"><input type="checkbox" checked={withContact} onChange={(e) => setWithContact(e.target.checked)} />Author is a contact</label>
+        <label className="flex items-center gap-1 text-sm"><input type="checkbox" checked={hideLow} onChange={(e) => setHideLow(e.target.checked)} />Hide low confidence</label>
+      </div>
+      {done ? <p role="status" className="text-sm">{done}</p> : null}
+      {run.error ? <ApiError error={run.error} title="The action did not go through" /> : null}
+      {list.error ? <ApiError error={list.error} title="Could not load posts" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? (
+        <div aria-busy="true" className="grid gap-2"><Skeleton className="h-20 w-full" /><Skeleton className="h-20 w-full" /></div>
+      ) : posts.length === 0 ? (
+        <EmptyState compact title="No matched posts" description="Posts appear here once a listener finds them. Nothing matches these filters yet." />
+      ) : (
+        <ul className="grid gap-2">
+          {posts.map((p) => (
+            <li key={keyOf(p)} className="grid gap-2 rounded-md border p-3">
+              <div className="flex flex-wrap items-center gap-2">
+                <EntityAvatar name={p.author_name || p.author_handle || "?"} imageUrl={p.author_profile_image_url} size="sm" />
+                <span className="font-medium">{p.author_name || "-"}</span>
+                <span className="text-muted-foreground text-xs">{p.author_handle ? `@${p.author_handle.replace(/^@/, "")}` : ""} · {platformLabel(p.platform)} · {fmt(p.author_followers)} followers · {when(p.created_at)}</span>
+                <StatusPill tone={p.status === "new" ? "info" : p.status === "reviewed" ? "positive" : "neutral"}>{p.status ?? "-"}</StatusPill>
+                {p.engagement_intent ? <StatusPill tone="neutral">{p.engagement_intent}</StatusPill> : null}
+              </div>
+              <p className="whitespace-pre-wrap text-sm">{p.text || "-"}</p>
+              <p className="text-muted-foreground text-xs">Likes {fmt(p.like_count)} · Replies {fmt(p.reply_count)} · Reposts {fmt(p.repost_count)} · Views {fmt(p.view_count)} · Fit {typeof p.classifier_score === "number" ? p.classifier_score.toFixed(2) : "-"}</p>
+              <div className="flex flex-wrap items-center gap-1">
+                <Button size="sm" variant="ghost" aria-label={`Mark reviewed ${keyOf(p)}`} disabled={p.status === "reviewed"} onClick={() => setAction({ kind: "mark", post: p, status: "reviewed" })}><Check className="size-4" />Reviewed</Button>
+                <Button size="sm" variant="ghost" aria-label={`Dismiss ${keyOf(p)}`} disabled={p.status === "dismissed"} onClick={() => setAction({ kind: "mark", post: p, status: "dismissed" })}><X className="size-4" />Dismiss</Button>
+                {p.resolved_mashup_contact_id ? (renderContact?.(p) ?? <span className="text-muted-foreground text-xs">Already a contact</span>) : <Button size="sm" variant="ghost" aria-label={`Save author as contact ${keyOf(p)}`} onClick={() => setAction({ kind: "contact", post: p })}><UserPlus className="size-4" />Save as contact</Button>}
+                <Button size="sm" variant="ghost" aria-label={`Add author to sequence ${keyOf(p)}`} onClick={() => { setSequenceId(""); setPicking(p); }}><ListPlus className="size-4" />Add to sequence</Button>
+                <Button size="sm" variant="ghost" aria-label={`Engagers of ${keyOf(p)}`} onClick={() => setEngagersOf(p)}><MessageSquare className="size-4" />Engagers</Button>
+                {p.post_url && /^https?:\/\//.test(p.post_url) ? <a className="text-muted-foreground inline-flex items-center gap-1 text-xs underline" href={p.post_url} target="_blank" rel="noreferrer noopener"><ExternalLink className="size-3" />View post</a> : null}
+              </div>
+            </li>
+          ))}
+        </ul>
+      )}
+      <LoadMore shown={posts.length} noun="posts" hasMore={list.hasMore} loading={list.loadingMore} onLoadMore={list.loadMore} />
+      <Sheet open={picking !== null} onOpenChange={(o) => { if (!o) setPicking(null); }}>
+        <SheetContent className="w-full sm:max-w-md">
+          <SheetHeader><SheetTitle>Add to sequence</SheetTitle><SheetDescription>The author of this post is enrolled in the sequence you pick, after you confirm.</SheetDescription></SheetHeader>
+          <div className="space-y-3 p-4">
+            {sequences.error ? <ApiError error={sequences.error} title="Could not load sequences" onRetry={() => void sequences.refetch()} /> : null}
+            {sequences.loading && !sequences.data ? <Skeleton className="h-9 w-full" aria-label="Loading sequences" /> : null}
+            {sequences.data && sequences.data.length === 0 ? <EmptyState compact title="No live sequences" description="Launch a sequence first." /> : null}
+            {sequences.data && sequences.data.length > 0 ? (
+              <>
+                <label htmlFor="g8-sl-seq" className="text-sm font-medium">Sequence</label>
+                <select id="g8-sl-seq" className={`${SELECT} w-full`} value={sequenceId} onChange={(e) => setSequenceId(e.target.value)}><option value="">Choose a sequence</option>{sequences.data.map((s) => <option key={s.id} value={s.id}>{s.name || "Untitled sequence"}</option>)}</select>
+                <Button disabled={!sequenceId} onClick={() => { const s = sequences.data?.find((x) => x.id === sequenceId); if (s && picking) { setAction({ kind: "sequence", post: picking, sequence: s }); setPicking(null); } }}>Continue</Button>
+              </>
+            ) : null}
+          </div>
+        </SheetContent>
+      </Sheet>
+      <Sheet open={engagersOf !== null} onOpenChange={(o) => { if (!o) setEngagersOf(null); }}>
+        <SheetContent className="w-full sm:max-w-xl overflow-y-auto">
+          <SheetHeader><SheetTitle>Engagers</SheetTitle><SheetDescription>People who commented on or reacted to this post.</SheetDescription></SheetHeader>
+          <div className="p-4">{engagersOf ? <PostEngagements key={keyOf(engagersOf)} post={engagersOf} /> : null}</div>
+        </SheetContent>
+      </Sheet>
+      <ConfirmSpendDialog
+        open={action !== null}
+        tier={copy.tier}
+        title={copy.title}
+        estimatedCredits={copy.credits}
+        recipients={action?.kind === "sequence" ? 1 : undefined}
+        description={<><p>{copy.body}</p>{run.error ? <ApiError error={run.error} title="The action did not go through" /> : null}</>}
+        confirmLabel={copy.label}
+        confirming={run.loading}
+        onCancel={() => setAction(null)}
+        onConfirm={() => { if (action) void run.mutate(action); }}
+      />
+    </div>
+  );
+}

package/blocks/signals/components/post-engagements.tsx

@@ -0,0 +1,114 @@
+"use client";
+
+/**
+ * PostEngagements: who commented on or reacted to one matched post, and a one-step way to turn them into a list.
+ *
+ * SDK operations, in order:
+ *   1. searchPostEngagements (POST /social-listeners/posts/{post_id}/engagements/search) read     stored rows only; paged, 100 a page
+ *   2. listLists (GET /lists), through ListSelect                                         read     the existing list to add to
+ *   3. addEngagersToList (POST /social-listeners/posts/{post_id}/engagements/add-to-list) billable tier: CREATES CONTACTS for people not in graph8
+ *      yet; ConfirmSpendDialog, sized from the engager count the API reported for the SAME comment/reaction filter it sends.
+ * An empty result can mean nobody engaged or that engagement fetching is off for the channel (Settings tab).
+ */
+
+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 { EmptyState } from "@/g8/components/empty-state";
+import { LoadMore } from "@/g8/components/paging-notices";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { ListSelect } from "@/g8/crm/components/list-select";
+import type { ListSelectOption } from "@/g8/crm/components/list-select";
+import { g8Post } from "@/g8/lib/g8-client";
+import { byPage } from "@/g8/lib/paging";
+import { plural } from "@/g8/lib/plural";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useLoadMoreList } from "@/g8/hooks/use-load-more-list";
+import { PAGE_SIZE, itemsOf, morePages, totalOf, when } from "../lib/signals-types";
+import type { MatchedPost, PostEngagement } from "../lib/signals-types";
+
+export interface PostEngagementsProps {
+  post: Pick<MatchedPost, "platform" | "post_external_id">;
+}
+
+interface AddResult { audience_id?: string; audience_name?: string; contacts_created?: number; contacts_matched?: number; skipped_no_identity?: number; total_engagers?: number }
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+
+export function PostEngagements({ post }: PostEngagementsProps) {
+  const brand = useBrand();
+  const [type, setType] = useState("");
+  const [target, setTarget] = useState<ListSelectOption | null>(null);
+  const [newName, setNewName] = useState("");
+  // The total belongs to the filter it was read for; a different filter must not show it while its own read is in flight.
+  const [read, setRead] = useState<{ type: string; total: number | undefined }>({ type: "", total: undefined });
+  const [confirm, setConfirm] = useState(false);
+  const path = `/social-listeners/posts/${encodeURIComponent(post.post_external_id)}/engagements`;
+
+  const list = useLoadMoreList<PostEngagement>(byPage(PAGE_SIZE, async (page, signal) => {
+    const body: Record<string, unknown> = { platform: post.platform, page, limit: PAGE_SIZE };
+    if (type) body.engagement_type = type;
+    const env = await g8Post<unknown>(`${path}/search`, body, { signal });
+    const rows = itemsOf<PostEngagement>(env.data);
+    setRead({ type, total: totalOf(env.data) });
+    return { rows, hasNext: morePages(env.data, rows.length, page, PAGE_SIZE) };
+  }), [post.platform, post.post_external_id, type], { key: ["signals", "engagements", post.platform, post.post_external_id, type] });
+
+  const add = useG8Mutation(async (): Promise<AddResult> => {
+    const body: Record<string, unknown> = { platform: post.platform };
+    if (type) body.engagement_type = type;
+    if (target) body.audience_id = String(target.id);
+    else body.audience_name = newName.trim();
+    return (await g8Post<AddResult>(`${path}/add-to-list`, body)).data;
+  }, { onSuccess: () => setConfirm(false), invalidates: [["signals", "stats"], ["lists"]] });
+
+  const rows = list.data ?? [];
+  const ready = rows.length > 0 && !list.loading && (target !== null || newName.trim() !== "");
+  const total = read.type === type ? read.total : undefined;
+  const size = total ?? rows.length;
+  const r = add.data;
+
+  return (
+    <div className="grid gap-3">
+      <div className="flex flex-wrap items-center gap-2">
+        <select aria-label="Engagement type" className={SELECT} value={type} onChange={(e) => setType(e.target.value)}>
+          <option value="">Comments and reactions</option><option value="comment">Comments</option><option value="reaction">Reactions</option>
+        </select>
+        <span className="text-muted-foreground text-xs" role="status">{list.data ? `${size.toLocaleString()} ${size === 1 ? "engager" : "engagers"}` : ""}</span>
+      </div>
+      {list.error ? <ApiError error={list.error} title="Could not load engagers" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? <Skeleton className="h-16 w-full" aria-label="Loading engagers" /> : rows.length === 0 ? (
+        <EmptyState compact title="No engagers stored" description="Nobody has engaged yet, or engagement fetching is off for this channel (see Settings)." />
+      ) : (
+        <ul className="grid gap-2">
+          {rows.map((e) => (
+            <li key={e.engagement_external_id} className="grid gap-1 rounded-md border p-2 text-sm">
+              <span className="flex flex-wrap items-center gap-2"><span className="font-medium">{e.author_name || e.author_handle || "-"}</span><StatusPill tone="neutral">{e.engagement_type}</StatusPill><span className="text-muted-foreground text-xs">{e.author_headline || "-"} · {when(e.created_at)}</span></span>
+              {e.text ? <span className="text-muted-foreground">{e.text}</span> : null}
+            </li>
+          ))}
+        </ul>
+      )}
+      <LoadMore shown={rows.length} noun="engagers" hasMore={list.hasMore} loading={list.loadingMore} onLoadMore={list.loadMore} />
+      <div className="grid gap-2 rounded-md border p-3">
+        <p className="text-sm font-medium">Add these people to a list</p>
+        <div><Label htmlFor="g8-sl-eng-list" className="mb-1">Existing list</Label><ListSelect id="g8-sl-eng-list" label="Existing list" emptyOption="Create a new list instead" value={target?.id ?? ""} valueLabel={target?.title} selectClassName={`${SELECT} w-full`} onChange={setTarget} /></div>
+        {target === null ? <div><Label htmlFor="g8-sl-eng-name" className="mb-1">New list name</Label><Input id="g8-sl-eng-name" maxLength={255} value={newName} onChange={(e) => setNewName(e.target.value)} /></div> : null}
+        <div><Button disabled={!ready} onClick={() => setConfirm(true)}>Add to list</Button></div>
+        {r ? <p role="status" className="text-sm">Added to {r.audience_name ?? "the list"}: {r.contacts_created ?? 0} new contacts, {r.contacts_matched ?? 0} matched, {r.skipped_no_identity ?? 0} skipped for no identity.</p> : null}
+      </div>
+      <ConfirmSpendDialog
+        open={confirm}
+        tier="billable"
+        title={`Add ${plural(size, "engager")} to ${target?.title ?? (newName.trim() || "a new list")}?`}
+        estimatedCredits={0}
+        affected={size}
+        description={<><p>People with no {brand.linkLabel} contact yet are created as contacts, so this grows your contact database as well as the list. No enrichment runs and no credits are spent.</p>{add.error ? <ApiError error={add.error} title="Could not add the engagers" /> : null}</>}
+        confirmLabel="Add to list"
+        confirming={add.loading}
+        onCancel={() => setConfirm(false)}
+        onConfirm={() => void add.mutate(undefined)}
+      />
+    </div>
+  );
+}

package/blocks/signals/components/record-social-tab.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+/**
+ * RecordSocialTab: the posts one contact has made that a listener matched. Drop it into ContactsScreen's `extraDetailTabs`.
+ *
+ * SDK operations: listPostsByContact (GET /social-listeners/posts/by-contact/{contact_id})  read. One read of up to 200
+ * posts (the API's cap); a full read says it shows the first 200. Nothing is written here.
+ */
+
+import { ExternalLink } from "lucide-react";
+import { 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 { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { fmt, itemsOf, platformLabel, when } from "../lib/signals-types";
+import type { MatchedPost } from "../lib/signals-types";
+
+const LIMIT = 200;
+
+export function RecordSocialTab({ contactId, onOpenListeners }: { contactId: number | string; onOpenListeners?: () => void }) {
+  const q = useG8Query(
+    (signal) => g8Get<unknown>(`/social-listeners/posts/by-contact/${encodeURIComponent(String(contactId))}`, { limit: LIMIT }, { signal }).then((r) => itemsOf<MatchedPost>(r.data)),
+    [contactId],
+    { key: ["signals", "by-contact", String(contactId)] },
+  );
+  if (q.error) return <ApiError error={q.error} title="Could not load this person's posts" onRetry={() => void q.refetch()} />;
+  if (q.loading && !q.data) return <Skeleton className="h-24 w-full" aria-label="Loading posts" />;
+  const rows = q.data ?? [];
+  if (rows.length === 0) {
+    return <EmptyState compact title="No matched posts" description="No listener has matched a post from this person yet." action={onOpenListeners ? <button type="button" className="text-sm underline" onClick={onOpenListeners}>Open social listening</button> : undefined} />;
+  }
+  return (
+    <div className="grid gap-2">
+      <ul className="grid gap-2">
+        {rows.map((p) => (
+          <li key={`${p.platform}:${p.post_external_id}`} className="grid gap-1 rounded-md border p-3 text-sm">
+            <span className="flex flex-wrap items-center gap-2"><span className="font-medium">{platformLabel(p.platform)}</span><span className="text-muted-foreground text-xs">{when(p.created_at)}</span><StatusPill tone={p.status === "new" ? "info" : "neutral"}>{p.status ?? "-"}</StatusPill></span>
+            <span className="whitespace-pre-wrap">{p.text || "-"}</span>
+            <span className="text-muted-foreground text-xs">Likes {fmt(p.like_count)} · Replies {fmt(p.reply_count)} · Views {fmt(p.view_count)}{p.post_url && /^https?:\/\//.test(p.post_url) ? <a className="ml-2 inline-flex items-center gap-1 underline" href={p.post_url} target="_blank" rel="noreferrer noopener"><ExternalLink className="size-3" />View post</a> : null}</span>
+          </li>
+        ))}
+      </ul>
+      <FirstNotice shown={rows.length} limit={LIMIT} noun="posts" />
+    </div>
+  );
+}

package/blocks/signals/components/social-listeners-screen.tsx

@@ -0,0 +1,250 @@
+"use client";
+
+/**
+ * SocialListenersScreen: the finished social listening workspace. No props needed.
+ *
+ * Composes: ScreenLayout (title, tabs, stats), Toolbar (search, type, channel and state filters), SplitView + DetailPanel
+ * (the selected listener, deep link `?id=`), FormSheet (new listener via ListenerForm), MatchedPosts, PostEngagements (inside
+ * MatchedPosts), TopEngagers, SourceLists, AutoSeedPanel, SocialSettingsPanel and XIntegration.
+ *
+ * Tabs (`?tab=`): Listeners (list and detail), Posts, Top engagers, Sources, Settings. A listener's detail (`?id=`) has
+ * Overview, Matches and Edit; `&view=full` shows it as a page.
+ *
+ * User flows: see every listener with its state and channel; search and filter; create one (with a cost estimate and an
+ * optional generated query); open one to see its matches, credit burn and settings; pause and resume it (confirmed); edit
+ * only what changed; delete it (confirmed, pausing keeps the posts); triage matched posts, save an author as a contact, add
+ * them to a sequence (confirmed); turn a post's engagers into a list; see the accounts that engage most; watch every
+ * profile on a list; seed starter listeners (each confirmed with its credits); change the org-wide spend limits and
+ * connect or remove your own X app (each confirmed).
+ *
+ * SDK operations: listListeners, getSocialStats (reads), updateListener (pause and resume, billable tier: confirmed),
+ * deleteListener (destructive: confirmed), getListener (read). Everything else lives in the composed parts.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Ear, Pause, Play, Plus, Trash2 } 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 { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Delete, g8Get, g8Patch } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { plural } from "@/g8/lib/plural";
+import { LISTENER_TYPES, PLATFORMS, cadence, capText, fmt, itemsOf, platformLabel, statusOf, typeLabel, when } from "../lib/signals-types";
+import type { Listener, ListenerDetailData, MatchedPost, SocialStats } from "../lib/signals-types";
+import { AutoSeedPanel } from "./auto-seed-panel";
+import { ListenerForm } from "./listener-form";
+import { MatchedPosts } from "./matched-posts";
+import { SocialSettingsPanel } from "./social-settings";
+import { SourceLists } from "./source-lists";
+import { TopEngagers } from "./top-engagers";
+import { XIntegration } from "./x-integration";
+
+export interface SocialListenersScreenProps {
+  renderRowActions?: (listener: Listener) => ReactNode;
+  renderDetailActions?: (listener: Listener) => ReactNode;
+  /** Render a link to the contact behind a matched post's author. */
+  renderContact?: (post: MatchedPost) => ReactNode;
+  extraDetailTabs?: { id: string; label: string; render: (listener: Listener) => ReactNode }[];
+  toolbarActions?: ReactNode;
+  className?: string;
+}
+
+type Tab = "listeners" | "posts" | "engagers" | "sources" | "settings";
+const TABS: Tab[] = ["listeners", "posts", "engagers", "sources", "settings"];
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+
+export function SocialListenersScreen({ renderRowActions, renderDetailActions, renderContact, extraDetailTabs, toolbarActions, className }: SocialListenersScreenProps) {
+  const [id, setId] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const [tabParam, setTabParam] = useUrlState("tab", "listeners");
+  const tab = (TABS.includes(tabParam as Tab) ? tabParam : "listeners") as Tab;
+  const [search, setSearch] = useState("");
+  const [typeFilter, setTypeFilter] = useState("");
+  const [platformFilter, setPlatformFilter] = useState("");
+  const [stateFilter, setStateFilter] = useState("");
+  const [creating, setCreating] = useState(false);
+  const [toDelete, setToDelete] = useState<Listener | null>(null);
+  const [toToggle, setToToggle] = useState<Listener | null>(null);
+
+  const list = useG8Query((signal) => g8Get<unknown>("/social-listeners", {}, { signal }).then((r) => itemsOf<Listener>(r.data)), [], { key: ["signals", "listeners"] });
+  const stats = useG8Query((signal) => g8Get<SocialStats>("/social-listeners/stats", {}, { signal }).then((r) => r.data), [], { key: ["signals", "stats"] });
+  const toggle = useG8Mutation((l: Listener) => g8Patch<Listener>(`/social-listeners/${encodeURIComponent(l.id)}`, { is_active: !l.is_active }), {
+    onSuccess: () => setToToggle(null),
+    invalidates: (_r, l) => [["signals", "listeners"], ["signals", "listener", l.id], ["signals", "stats"]],
+  });
+  const remove = useG8Mutation((l: Listener) => g8Delete(`/social-listeners/${encodeURIComponent(l.id)}`), {
+    onSuccess: (_r, l) => { setToDelete(null); if (l.id === id) closeDetail(); },
+    invalidates: [["signals"]],
+  });
+  function closeDetail(): void { setId(null); setView(null); }
+
+  const all = list.data ?? [];
+  const q = search.trim().toLowerCase();
+  const shown = all.filter((l) => (!typeFilter || l.listener_type === typeFilter) && (!platformFilter || l.platform === platformFilter) && (!stateFilter || statusOf(l) === stateFilter) && (!q || `${l.name} ${l.query ?? ""} ${l.target_handle ?? ""}`.toLowerCase().includes(q)));
+  const selected = all.find((l) => l.id === id);
+  const expandProps = { onExpand: () => setView("full"), onCollapse: view === "full" ? () => setView(null) : undefined };
+
+  const rows = list.error ? <ApiError error={list.error} title="Could not load listeners" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? (
+    <div aria-busy="true" className="grid gap-2"><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /></div>
+  ) : shown.length === 0 ? (
+    <EmptyState icon={<Ear className="size-8" />} title={all.length === 0 ? "No listeners yet" : "No listeners match"} description={all.length === 0 ? "A listener watches X, LinkedIn, Reddit, Instagram or YouTube for posts about your brand, competitors or keywords. Create one, or seed starters from the Sources tab." : "Try another search or filter."} action={all.length === 0 ? <Button onClick={() => setCreating(true)}>Create your first listener</Button> : undefined} />
+  ) : (
+    <>
+      <p role="status" className="text-muted-foreground mb-2 text-xs">{shown.length === all.length ? `All ${plural(all.length, "listener")}` : `${shown.length.toLocaleString()} of ${plural(all.length, "listener")}`}</p>
+      <ul className="grid gap-2">
+        {shown.map((l) => (
+          <li key={l.id} className={`flex flex-wrap items-center justify-between gap-2 rounded-md border p-3 ${l.id === id ? "bg-muted" : ""}`}>
+            <button type="button" className="min-w-0 flex-1 text-left" onClick={() => setId(l.id)}>
+              <span className="block truncate font-medium">{l.name}</span>
+              <span className="text-muted-foreground block truncate text-xs">{l.listener_type === "user" ? (l.target_handle ?? "-") : (l.query ?? "-")} · {platformLabel(l.platform)}</span>
+            </button>
+            <StatusPill tone="info">{typeLabel(l.listener_type)}</StatusPill>
+            <StatusPill tone={l.is_active ? "positive" : "neutral"}>{statusOf(l)}</StatusPill>
+            <div className="flex gap-1">
+              <Button size="sm" variant="ghost" aria-label={`${l.is_active ? "Pause" : "Resume"} ${l.name}`} onClick={() => setToToggle(l)}>{l.is_active ? <Pause className="size-4" /> : <Play className="size-4" />}</Button>
+              <Button size="sm" variant="ghost" aria-label={`Delete ${l.name}`} onClick={() => setToDelete(l)}><Trash2 className="size-4" /></Button>
+              {renderRowActions?.(l)}
+            </div>
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+
+  const detail = selected ? (
+    <DetailPanel
+      title={selected.name}
+      subtitle={selected.listener_type === "user" ? selected.target_handle ?? undefined : selected.query ?? undefined}
+      badges={<><StatusPill tone="info">{typeLabel(selected.listener_type)}</StatusPill><StatusPill tone={selected.is_active ? "positive" : "neutral"}>{statusOf(selected)}</StatusPill></>}
+      actions={<>{renderDetailActions?.(selected)}<Button size="sm" variant="outline" onClick={() => setToToggle(selected)}>{selected.is_active ? <Pause className="size-4" /> : <Play className="size-4" />}{selected.is_active ? "Pause" : "Resume"}</Button></>}
+      onClose={closeDetail}
+      {...expandProps}
+      tabs={[
+        { id: "overview", label: "Overview", content: <ListenerOverview key={selected.id} listener={selected} /> },
+        { id: "matches", label: "Matches", content: <MatchedPosts key={selected.id} listenerId={selected.id} renderContact={renderContact} /> },
+        { id: "edit", label: "Edit", content: <ListenerForm key={selected.id} listener={selected} onSaved={() => void list.refetch()} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selected) })),
+      ]}
+    />
+  ) : null;
+
+  const s = stats.data;
+  const listenersTab = (
+    <SplitView
+      list={(
+        <div className="grid gap-3">
+          <Toolbar
+            search={{ value: search, onChange: setSearch, placeholder: "Search listeners" }}
+            filters={(
+              <>
+                <select aria-label="Filter by type" className={SELECT} value={typeFilter} onChange={(e) => setTypeFilter(e.target.value)}><option value="">All types</option>{LISTENER_TYPES.map((t) => <option key={t.value} value={t.value}>{t.label}</option>)}</select>
+                <select aria-label="Filter by channel" className={SELECT} value={platformFilter} onChange={(e) => setPlatformFilter(e.target.value)}><option value="">All channels</option>{PLATFORMS.map((p) => <option key={p.value} value={p.value}>{p.label}</option>)}</select>
+                <select aria-label="Filter by state" className={SELECT} value={stateFilter} onChange={(e) => setStateFilter(e.target.value)}><option value="">Active and paused</option><option value="active">Active</option><option value="paused">Paused</option></select>
+              </>
+            )}
+            actions={toolbarActions}
+          />
+          {rows}
+        </div>
+      )}
+      detail={detail}
+      detailOpen={Boolean(selected)}
+      onCloseDetail={closeDetail}
+      expanded={view === "full"}
+      onExpandedChange={(e) => setView(e ? "full" : null)}
+      detailWidth="xl"
+    />
+  );
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Social listening"
+      description="Watch X, LinkedIn, Reddit, Instagram and YouTube for people talking about you, your competitors and your keywords."
+      icon={<Ear className="size-5" />}
+      actions={<Button size="sm" onClick={() => setCreating(true)}><Plus className="size-4" />New listener</Button>}
+      tabs={[{ id: "listeners", label: "Listeners", count: list.data ? all.length : undefined }, { id: "posts", label: "Posts" }, { id: "engagers", label: "Top engagers" }, { id: "sources", label: "Sources" }, { id: "settings", label: "Settings" }]}
+      activeTab={tab}
+      onTabChange={(next) => { setTabParam(next === "listeners" ? null : next); closeDetail(); }}
+      statsLoading={stats.loading && !stats.data}
+      stats={[
+        { label: "Active listeners", value: fmt(s?.listeners_active) },
+        { label: "Paused", value: fmt(s?.listeners_paused) },
+        { label: "Posts matched", value: fmt(s?.posts_matched), hint: `${fmt(s?.posts_reviewed)} reviewed, ${fmt(s?.posts_dismissed)} dismissed` },
+        { label: "Contacts resolved", value: fmt(s?.contacts_resolved) },
+        { label: "Credits this month", value: fmt(s?.monthly_credit_burn) },
+        { label: "X spend", value: typeof s?.x_api_spend_usd === "number" ? `$${s.x_api_spend_usd.toFixed(2)}` : "-" },
+      ]}
+    >
+      {stats.error ? <ApiError compact error={stats.error} title="Could not load the totals" onRetry={() => void stats.refetch()} /> : null}
+      {tab === "listeners" ? listenersTab : tab === "posts" ? <MatchedPosts listeners={all} renderContact={renderContact} /> : tab === "engagers" ? <TopEngagers /> : tab === "sources" ? (
+        <div className="grid gap-4 lg:grid-cols-2"><SourceLists /><AutoSeedPanel /></div>
+      ) : (
+        <div className="grid gap-6"><SocialSettingsPanel /><XIntegration /></div>
+      )}
+      <FormSheet open={creating} onOpenChange={setCreating} title="New listener" description="Nothing is created until you confirm.">
+        {creating ? <ListenerForm onCancel={() => setCreating(false)} onSaved={(created) => { setCreating(false); setTabParam(null); void list.refetch(); setId(created.id); }} /> : null}
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={toToggle !== null}
+        tier="billable"
+        title={`${toToggle?.is_active ? "Pause" : "Resume"} ${toToggle?.name ?? "this listener"}?`}
+        estimatedCredits={toToggle?.is_active ? 0 : undefined}
+        description={<><p>{toToggle?.is_active ? "Polling stops and its matched posts are kept. No credits are spent while it is paused." : `Polling restarts. Credits are spent as posts are read, ${capText(toToggle?.monthly_credit_cap)}.`}</p>{toggle.error ? <ApiError error={toggle.error} title="Could not change the listener" /> : null}</>}
+        confirmLabel={toToggle?.is_active ? "Pause" : "Resume"}
+        confirming={toggle.loading}
+        onCancel={() => setToToggle(null)}
+        onConfirm={() => { if (toToggle) void toggle.mutate(toToggle); }}
+      />
+      <ConfirmSpendDialog
+        open={toDelete !== null}
+        tier="destructive"
+        title={`Delete ${toDelete?.name ?? "this listener"}?`}
+        affected={1}
+        description={<><p>The listener stops for good. To stop the spend but keep the matched posts, pause it instead.</p>{remove.error ? <ApiError error={remove.error} title="Could not delete the listener" /> : null}</>}
+        confirmLabel="Delete"
+        confirming={remove.loading}
+        onCancel={() => setToDelete(null)}
+        onConfirm={() => { if (toDelete) void remove.mutate(toDelete); }}
+      />
+    </ScreenLayout>
+  );
+}
+
+function ListenerOverview({ listener }: { listener: Listener }) {
+  const full = useG8Query((signal) => g8Get<ListenerDetailData>(`/social-listeners/${encodeURIComponent(listener.id)}`, {}, { signal }).then((r) => r.data), [listener.id], { key: ["signals", "listener-detail", listener.id] });
+  const l = full.data?.listener ?? listener;
+  return (
+    <div className="grid gap-3">
+      {full.error ? <ApiError compact error={full.error} title="Could not load the totals" onRetry={() => void full.refetch()} /> : null}
+      <KeyValueList
+        columns={2}
+        items={[
+          { label: "Type", value: typeLabel(l.listener_type) },
+          { label: "Channel", value: platformLabel(l.platform) },
+          { label: "Matches so far", value: full.data ? fmt(full.data.match_count) : "..." },
+          { label: "Credits spent", value: full.data ? fmt(full.data.credit_burn) : "..." },
+          { label: "Query", value: l.query ?? "", wide: true },
+          { label: "Account", value: l.target_handle ?? "" },
+          { label: "Checks", value: cadence(l.poll_interval_sec) },
+          { label: "Monthly cap", value: l.monthly_credit_cap == null ? "" : l.monthly_credit_cap === 0 ? "No per-listener cap" : `${l.monthly_credit_cap.toLocaleString()} credits` },
+          { label: "Last checked", value: when(l.last_polled_at) },
+          { label: "Paused because", value: l.paused_reason ?? "" },
+          { label: "Created", value: when(l.created_at) },
+          { label: "Listener id", value: l.id, mono: true },
+        ]}
+      />
+    </div>
+  );
+}