@graph8/sdk 0.362.0 → 0.373.0

package/blocks/inbox/components/record-conversations-tab.tsx

@@ -0,0 +1,154 @@
+"use client";
+
+/**
+ * RecordConversationsTab: the email conversations with one contact, newest first, "Load more" for older ones. Opening a row
+ * shows its messages. Use it as an `extraDetailTabs` entry of ContactsScreen:
+ *   { id: "conversations", label: "Conversations", render: (c) => <RecordConversationsTab email={c.work_email} onOpenThread={(sel) => router.push(`/inbox?id=${sel}`)} /> }
+ *
+ * SDK operations, in order:
+ *   1. listInboxMailboxes  GET  /inbox/mailboxes                          (read; the mailboxes this key can read: search requires them)
+ *   2. searchInboxEmails   POST /inbox/emails/search?page=&page_size=     (read; body `{ mailboxes, search_emails: [email] }`, 10 per page)
+ *   3. getReply            GET  /inbox/{id}?channel=email                 (read; only when a row is opened)
+ * The inbox has no filter by contact id, so the contact is matched by email address (sender or recipient): `email` plus any
+ * `alsoEmails`. A contact with no usable address has no conversations to show. SMS and LinkedIn threads are not matched here.
+ *
+ * Hidden threads: the API answers a thread the key may not see exactly like one that does not exist (404, the same text).
+ * A row that 404s on open says "not available to you" instead of an error with a retry button.
+ */
+
+import { useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { MessagesSquare } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { usePaginated } from "@/g8/hooks/use-paginated";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useInboxThread } from "../hooks/use-inbox-thread";
+import { formatWhen, stripHtml, type InboxMessage } from "../lib/inbox-types";
+
+const PAGE_SIZE = 10;
+
+/** One thread of POST /inbox/emails/search. Only the fields shown here are read; all are optional. */
+interface FoundThread { id?: string | number | null; email_id?: string | number | null; subject?: string | null; updated_at?: string | null; created_at?: string | null; status?: string | null; messages?: InboxMessage[] | null }
+
+const idOf = (t: FoundThread): string => String(t.id ?? t.email_id ?? "");
+const statusOf = (e: unknown): number | undefined => (e as { status?: number } | null)?.status;
+
+/** Mailbox addresses from GET /inbox/mailboxes (rows are mailbox records; the address is `email`). */
+function mailboxAddresses(env: unknown): string[] {
+  const data = (env as { data?: unknown } | null)?.data;
+  const rows = Array.isArray(data) ? data : ((data as { items?: unknown } | null)?.items ?? []);
+  const out = new Set<string>();
+  for (const r of Array.isArray(rows) ? rows : []) {
+    const row = r as { email?: string | null; mailbox?: string | null };
+    const address = (row.email ?? row.mailbox ?? "").trim();
+    if (address) out.add(address);
+  }
+  return [...out];
+}
+
+function Opened({ id }: { id: string }) {
+  const t = useInboxThread(id, "email");
+  if (t.error) {
+    return statusOf(t.error) === 404
+      ? <p role="status" className="p-3 text-sm text-muted-foreground">This conversation is not available to you. It may have been removed, or it belongs to a mailbox you cannot read.</p>
+      : <div className="p-3"><ApiError error={t.error} title="Could not load this conversation" onRetry={() => void t.refetch()} /></div>;
+  }
+  if (!t.data) return <Skeleton className="m-3 h-16 w-auto" aria-label="Loading conversation" />;
+  const messages = t.data.messages.filter((m) => !m.is_draft);
+  if (messages.length === 0) return <p className="p-3 text-sm text-muted-foreground">No messages in this conversation yet.</p>;
+  return (
+    <ol className="space-y-2 p-3" aria-label="Messages">
+      {messages.map((m, i) => (
+        <li key={m.message_id ?? i} className="rounded-md border p-3 text-sm">
+          <p className="mb-1 flex flex-wrap gap-2 text-xs text-muted-foreground"><span className="font-medium text-foreground">{m.from_address ?? "Unknown sender"}</span>{m.date ? <span>{formatWhen(m.date)}</span> : null}</p>
+          <p className="whitespace-pre-wrap">{stripHtml(m.content) || "(no content)"}</p>
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+export interface RecordConversationsTabProps {
+  /** The contact's email address. Without one the tab explains there is nothing to match. */
+  email: string | null | undefined;
+  /** Other addresses of the contact (personal or additional emails; a comma-separated string is fine). Threads with any of them are shown. */
+  alsoEmails?: ReadonlyArray<string | null | undefined>;
+  /** Route to the conversation in your inbox screen; receives the inbox selection ("email:<id>"). Without it the rows link to `${inboxPath}?id=email:<id>`. */
+  onOpenThread?: (selection: string) => void;
+  /** Path of your inbox screen for the plain links. Default "/inbox". */
+  inboxPath?: string;
+}
+
+export function RecordConversationsTab({ email, alsoEmails = [], onOpenThread, inboxPath = "/inbox" }: RecordConversationsTabProps) {
+  const addresses = [...new Set([email, ...alsoEmails].flatMap((e) => (e ?? "").split(",")).map((e) => e.trim()).filter((e) => e !== "" && !e.includes("*") && e.includes("@")))];
+  const usable = addresses.length > 0;
+  const boxes = useG8Query(async (signal) => mailboxAddresses(await g8Get("/inbox/mailboxes", undefined, { signal })), [usable], { enabled: usable });
+  const mailboxes = boxes.data ?? [];
+
+  if (!usable) return <EmptyState compact icon={<MessagesSquare className="size-8" />} title="No email address" description="Conversations are matched by email address, and this contact has none to match." />;
+  if (boxes.error) return <ApiError error={boxes.error} title="Could not load mailboxes" onRetry={() => void boxes.refetch()} />;
+  if (!boxes.data) return <Skeleton className="h-24 w-full" aria-label="Loading conversations" />;
+  if (mailboxes.length === 0) return <EmptyState compact icon={<MessagesSquare className="size-8" />} title="No mailbox connected" description="Connect a mailbox to see the conversations you have with this contact." />;
+  // Mounted only once the mailboxes are known, so its first render is already "loading" (no empty-state flash before the first search).
+  return <ConversationList addresses={addresses} mailboxes={mailboxes} onOpenThread={onOpenThread} inboxPath={inboxPath} />;
+}
+
+interface ConversationListProps { addresses: string[]; mailboxes: string[]; onOpenThread?: (selection: string) => void; inboxPath: string }
+
+function ConversationList({ addresses, mailboxes, onOpenThread, inboxPath }: ConversationListProps) {
+  const [open, setOpen] = useState<string | null>(null);
+  const list = usePaginated<FoundThread>(async (cursor, signal) => {
+    const page = cursor ? Number(cursor) || 1 : 1;
+    const env = await g8Post<{ items?: FoundThread[] }>(`/inbox/emails/search?page=${page}&page_size=${PAGE_SIZE}`, { mailboxes, search_emails: addresses }, { signal });
+    const items = (env.data?.items ?? []).filter((t) => idOf(t) !== "");
+    const more = (env as { pagination?: { has_next?: boolean } }).pagination?.has_next ?? items.length >= PAGE_SIZE;
+    return { data: items, pagination: { next_cursor: more && items.length > 0 ? String(page + 1) : null } } as never;
+  }, [addresses.join(","), mailboxes.join("|")]);
+
+  if (list.error) return <ApiError error={list.error} title="Could not load conversations" onRetry={() => void list.reload()} />;
+  if (list.loading && list.items.length === 0) return <Skeleton className="h-24 w-full" aria-label="Loading conversations" />;
+  if (list.items.length === 0) return <EmptyState compact icon={<MessagesSquare className="size-8" />} title="No conversations yet" description="Emails sent to or received from this contact show up here." />;
+
+  return (
+    <div className="space-y-2">
+      <ul className="divide-y rounded-md border" aria-label="Conversations">
+        {list.items.map((t) => {
+          const id = idOf(t);
+          const last = (t.messages ?? []).filter((m) => !m.is_draft).slice(-1)[0];
+          const isOpen = open === id;
+          const selection = `email:${id}`;
+          return (
+            <li key={id}>
+              <div className="flex items-center justify-between gap-3 p-3 text-sm">
+                <button type="button" aria-expanded={isOpen} className="min-w-0 flex-1 text-left" onClick={() => setOpen(isOpen ? null : id)}>
+                  <span className="block truncate font-medium">{t.subject || "(no subject)"}</span>
+                  <span className="block truncate text-xs text-muted-foreground">{[formatWhen(t.updated_at ?? t.created_at), last ? stripHtml(last.content).slice(0, 80) : null].filter(Boolean).join(" · ")}</span>
+                </button>
+                <a
+                  href={`${inboxPath}?id=${encodeURIComponent(selection)}`}
+                  className="shrink-0 text-xs text-muted-foreground hover:underline"
+                  onClick={(e) => {
+                    if (!onOpenThread || e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+                    e.preventDefault();
+                    onOpenThread(selection);
+                  }}
+                >
+                  Open in inbox
+                </a>
+              </div>
+              {isOpen ? <Opened id={id} /> : null}
+            </li>
+          );
+        })}
+      </ul>
+      {list.hasMore ? (
+        <div className="flex items-center justify-between text-sm text-muted-foreground">
+          <span role="status">Showing {list.items.length.toLocaleString()} conversations</span>
+          <Button size="sm" variant="outline" loading={list.loadingMore} onClick={() => void list.loadMore()}>Load more</Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/blocks/inbox/components/reply-composer.tsx

@@ -9,7 +9,13 @@
  *      Returns { content (HTML), plain_content }; it delivers NOTHING.
  *   2. POST /inbox/{reply_id}/send   (inbox.sendReply)   EXTERNAL   -> ConfirmSpendDialog first
  *      Reaches a real person and cannot be recalled. A fixed Idempotency-Key per compose makes a double
- *      click or a retry safe.
+ *      click or a retry safe. Sends `from_address` = the thread's own sender (email mailbox, SMS number,
+ *      LinkedIn account id) and `to` = the thread's contact, so the reply leaves from the mailbox the
+ *      conversation is on. Before this the composer sent neither sender nor (for SMS) number, and the API
+ *      refused every email reply with 400 "'from_address' (mailbox) is required".
+ *   Only when an SMS or LinkedIn thread names no sender, one read fills a sender picker:
+ *      GET /sms/phone-numbers (channels.listSmsPhoneNumbers) or
+ *      GET /inbox/linkedin/accounts (aiInbox.listInboxLinkedinAccounts)   READ
  *
  * Both calls are gated by tier: nothing is billed or sent until the person clicks the dialog's button.
  */
@@ -18,9 +24,10 @@ import { useIdempotencyKey } from "../lib/idempotency";
 import { Button, Input, Textarea } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
-import { g8Post } from "@/g8/lib/g8-client";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
-import { replyRecipient, stripHtml, type InboxThread } from "../lib/inbox-types";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { replyRecipient, replySender, senderOptions, stripHtml, type InboxThread } from "../lib/inbox-types";
 
 type DraftOperation = "generate_from_scratch" | "shorten" | "expand" | "fix_grammar_spelling";
 type Pending = { kind: "draft"; operation: DraftOperation } | { kind: "send" } | null;
@@ -51,10 +58,22 @@ export function ReplyComposer({ thread, onSent, className }: ReplyComposerProps)
   const [body, setBody] = useState("");
   const [subject, setSubject] = useState(thread.subject ? (/^re:/i.test(thread.subject) ? thread.subject : `Re: ${thread.subject}`) : "");
   const [to, setTo] = useState(replyRecipient(thread));
+  const threadSender = replySender(thread);
+  const [from, setFrom] = useState(threadSender);
   const [tone, setTone] = useState<(typeof TONES)[number]>("professional");
   const [objective, setObjective] = useState<(typeof OBJECTIVES)[number]>("follow_up");
   const [pending, setPending] = useState<Pending>(null);
-  const idempotency = useIdempotencyKey(JSON.stringify([thread.channel, thread.id, body, to, channel === "email" ? subject : null]));
+  const idempotency = useIdempotencyKey(JSON.stringify([thread.channel, thread.id, body, to, from, channel === "email" ? subject : null]));
+  // SMS and LinkedIn cannot send without a sender; when the thread does not name one, offer the org's.
+  const needsSenderPick = !threadSender && (channel === "sms" || channel === "linkedin");
+  const senders = useG8Query(
+    async (signal) => {
+      const path = channel === "sms" ? "/sms/phone-numbers" : "/inbox/linkedin/accounts";
+      return senderOptions(channel, (await g8Get<unknown>(path, undefined, { signal })).data);
+    },
+    [channel, needsSenderPick],
+    { enabled: needsSenderPick },
+  );
   const threadKey = `${thread.channel}:${thread.id}`;
   const currentThread = useRef(threadKey);
   currentThread.current = threadKey;
@@ -64,6 +83,7 @@ export function ReplyComposer({ thread, onSent, className }: ReplyComposerProps)
     setBody("");
     setSubject(thread.subject ? (/^re:/i.test(thread.subject) ? thread.subject : `Re: ${thread.subject}`) : "");
     setTo(replyRecipient(thread));
+    setFrom(replySender(thread));
     setPending(null);
     draft.reset();
     send.reset();
@@ -85,11 +105,18 @@ export function ReplyComposer({ thread, onSent, className }: ReplyComposerProps)
   const send = useG8Mutation(async () => {
     const env = await g8Post<{ message_id?: string | null; status: string }>(
       `/inbox/${encodeURIComponent(thread.id)}/send`,
-      { body, channel, subject: channel === "email" ? subject : undefined, to: to || undefined },
+      {
+        body,
+        channel,
+        subject: channel === "email" ? subject : undefined,
+        to: to || undefined,
+        // Empty only for an email thread the list did not label; the API then uses the thread's mailbox.
+        from_address: from || undefined,
+      },
       { idempotencyKey: idempotency.get() },
     );
     return env.data;
-  });
+  }, { invalidates: ["inbox"] });
 
   const confirm = async () => {
     const current = pending;
@@ -112,7 +139,8 @@ export function ReplyComposer({ thread, onSent, className }: ReplyComposerProps)
   };
 
   const busy = draft.loading || send.loading;
-  const canSend = body.trim().length > 0 && (channel === "linkedin" || to.trim().length > 0) && !busy;
+  const hasSender = channel === "email" || from.trim().length > 0;
+  const canSend = body.trim().length > 0 && (channel === "linkedin" || to.trim().length > 0) && hasSender && !busy;
   const canTransform = body.trim().length > 0 && !busy;
   const canDraft = Boolean(draftChannel(channel));
 
@@ -121,7 +149,33 @@ export function ReplyComposer({ thread, onSent, className }: ReplyComposerProps)
       {channel === "email" ? (
         <Input aria-label="Subject" placeholder="Subject" value={subject} onChange={(e) => setSubject(e.target.value)} />
       ) : null}
-      <Input aria-label="To" placeholder={channel === "sms" ? "Phone number" : "Recipient"} value={to} onChange={(e) => setTo(e.target.value)} />
+      {needsSenderPick ? (
+        <div className="space-y-1 text-sm">
+          <select
+            aria-label="Send from"
+            className="h-9 w-full rounded-md border bg-background px-2"
+            value={from}
+            disabled={senders.loading}
+            onChange={(e) => setFrom(e.target.value)}
+          >
+            <option value="">{senders.loading ? "Loading senders..." : channel === "sms" ? "Choose the number to text from" : "Choose the LinkedIn account to send from"}</option>
+            {(senders.data ?? []).map((o) => (
+              <option key={o.value} value={o.value}>
+                {o.label}
+              </option>
+            ))}
+          </select>
+          {senders.error ? <ApiError error={senders.error} title="Could not load your senders" onRetry={() => void senders.refetch()} /> : null}
+          {!senders.loading && !senders.error && senders.data?.length === 0 ? (
+            <p className="text-muted-foreground">{channel === "sms" ? "No SMS numbers on this account yet." : "No LinkedIn accounts connected yet."}</p>
+          ) : null}
+        </div>
+      ) : from ? (
+        <p className="text-xs text-muted-foreground">From {channel === "linkedin" ? "your LinkedIn account" : from}</p>
+      ) : null}
+      {channel !== "linkedin" ? (
+        <Input aria-label="To" placeholder={channel === "sms" ? "Phone number" : "Recipient"} value={to} onChange={(e) => setTo(e.target.value)} />
+      ) : null}
       <Textarea aria-label="Reply" rows={6} placeholder="Write your reply" value={body} onChange={(e) => setBody(e.target.value)} />
 
       {canDraft ? (
@@ -172,7 +226,9 @@ export function ReplyComposer({ thread, onSent, className }: ReplyComposerProps)
         open={pending?.kind === "send"}
         tier="external"
         title={`Send this ${channel} reply?`}
-        description={`It goes to ${to || "the contact"} from your connected ${channel === "email" ? "mailbox" : channel} account.`}
+        description={`It goes to ${to || "the contact"} from ${
+          channel === "email" ? (from || "the thread's mailbox") : channel === "sms" ? from : "your LinkedIn account"
+        }.`}
         recipients={1}
         confirming={send.loading}
         onConfirm={() => void confirm()}

package/blocks/inbox/components/tag-and-assign.tsx

@@ -23,6 +23,7 @@ import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import type { InboxTag, InboxThread } from "../lib/inbox-types";
 import { ThreadBadge } from "./thread-badge";
+import { pluralWord } from "@/g8/lib/plural";
 
 type Pending = { kind: "tag"; ids: string[] } | { kind: "assign"; email: string } | null;
 interface TeamUser {
@@ -70,9 +71,10 @@ export function TagAndAssign({ thread, availableTags = [], onChanged, className
   const tag = useG8Mutation(async (ids: string[]) => {
     // Only the NEW ids: association can fire tag automations, so already-applied tags are not re-sent.
     return g8Post(`/inbox/${encodeURIComponent(thread.id)}/tag`, { tag_ids: ids.filter((id) => !applied.has(id)) }, { query: channelQuery });
-  });
+  }, { invalidates: ["inbox"] });
   const assign = useG8Mutation(async (email: string) =>
     g8Post(`/inbox/${encodeURIComponent(thread.id)}/assign`, { assignee_email: email }, { query: channelQuery }),
+    { invalidates: ["inbox"] },
   );
 
   const addTag = async () => {
@@ -132,7 +134,7 @@ export function TagAndAssign({ thread, availableTags = [], onChanged, className
           </Button>
         </div>
         <Button size="sm" disabled={selected.length === 0 || tag.loading} onClick={() => setPending({ kind: "tag", ids: selected })}>
-          Apply {selected.length > 0 ? `${selected.length} ` : ""}tag{selected.length === 1 ? "" : "s"}
+          Apply {selected.length > 0 ? `${selected.length} ` : ""}{pluralWord(selected.length, "tag")}
         </Button>
         {createTag.error ? <ApiError error={createTag.error} title="Could not create the tag" /> : null}
         {tag.error ? <ApiError error={tag.error} title="Could not apply the tags" /> : null}

package/blocks/inbox/components/thread-badge.tsx

@@ -8,8 +8,8 @@ import type { ReactNode } from "react";
 
 const TONES = {
   neutral: "bg-muted text-foreground",
-  info: "bg-blue-100 text-blue-900 dark:bg-blue-950 dark:text-blue-100",
-  warn: "bg-amber-100 text-amber-900 dark:bg-amber-950 dark:text-amber-100",
+  info: "bg-info text-info-foreground",
+  warn: "bg-warning text-warning-foreground",
 } as const;
 
 export function ThreadBadge({ children, tone = "neutral" }: { children: ReactNode; tone?: keyof typeof TONES }) {

package/blocks/inbox/components/thread-view.tsx

@@ -50,7 +50,7 @@ function MessageBubble({ message, outbound }: { message: InboxMessage; outbound:
 function ThreadHeader({ thread }: { thread: InboxThread }) {
   return (
     <header className="space-y-1 border-b pb-3">
-      <h2 className="text-base font-semibold">{thread.subject || contactLabel(thread)}</h2>
+      <h2 className="text-base font-medium">{thread.subject || contactLabel(thread)}</h2>
       <p className="text-sm text-muted-foreground">
         {contactLabel(thread)}
         {thread.contact?.company ? ` at ${thread.contact.company}` : ""} · <span className="capitalize">{thread.channel}</span>

package/blocks/inbox/hooks/use-inbox-thread.ts

@@ -19,6 +19,6 @@ export function useInboxThread(threadId: string | null | undefined, channel: str
       return env.data;
     },
     [threadId, channel],
-    { enabled: Boolean(threadId) },
+    { enabled: Boolean(threadId), key: ["inbox", "detail", threadId ?? null, channel ?? null] },
   );
 }

package/blocks/inbox/hooks/use-inbox-threads.ts

@@ -35,6 +35,7 @@ export function useInboxThreads(filters: InboxFilters, page = 1, pageSize = 25)
       return { threads: env.data ?? [], hasNext: Boolean(env.pagination?.has_next), total: (env.pagination as { total?: number } | undefined)?.total };
     },
     [filters.channel, filters.status, filters.tag, filters.sequenceId, page, pageSize],
+    { key: ["inbox", "list", { channel: filters.channel, status: filters.status, tag: filters.tag, sequenceId: filters.sequenceId, page, pageSize }] },
   );
   return { ...query, threads: query.data?.threads ?? [], hasNext: query.data?.hasNext ?? false, total: query.data?.total };
 }

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

@@ -46,6 +46,14 @@ export interface InboxThread {
   assignees: InboxAssignee[];
   created_at?: string | null;
   updated_at?: string | null;
+  /** Email: the connected mailbox the thread belongs to; a reply is sent from it. */
+  mailbox?: string | null;
+  /** SMS: your number the thread runs on; a reply is sent from it. */
+  from_number?: string | null;
+  /** SMS: the contact's number; a reply goes to it. */
+  to_number?: string | null;
+  /** LinkedIn: the account the conversation belongs to; a reply is sent from it. */
+  linkedin_account_id?: number | null;
 }
 
 /** Statuses `GET /inbox?status=` accepts (case-insensitive). Anything else is a 422. */
@@ -95,6 +103,44 @@ export function formatWhen(iso: string | null | undefined): string {
 /** Default recipient for a reply: the contact's address on the thread's channel. */
 export function replyRecipient(thread: InboxThread): string {
   const c = thread.contact;
-  if (thread.channel === "sms") return c?.phone ?? "";
+  if (thread.channel === "sms") return thread.to_number || c?.phone || "";
   return c?.email ?? "";
 }
+
+/**
+ * Default sender for a reply, as `POST /inbox/{id}/send` expects it in `from_address`: the thread's mailbox
+ * (email), your number on the thread (SMS) or the numeric LinkedIn account id. Empty when the thread does not
+ * say; the API then defaults email itself, and SMS/LinkedIn need a sender picked.
+ */
+export function replySender(thread: InboxThread): string {
+  if (thread.channel === "sms") return thread.from_number ?? "";
+  if (thread.channel === "linkedin") return thread.linkedin_account_id != null ? String(thread.linkedin_account_id) : "";
+  return thread.mailbox ?? "";
+}
+
+export interface SenderOption {
+  value: string;
+  label: string;
+}
+
+/**
+ * Senders for a picker from `GET /sms/phone-numbers` or `GET /inbox/linkedin/accounts`. Both answer with an
+ * untyped `{ items: [...] }` envelope (no response schema in the contract), so this reads defensively.
+ */
+export function senderOptions(channel: string, payload: unknown): SenderOption[] {
+  const raw = Array.isArray(payload) ? payload : ((payload as { items?: unknown[] } | null)?.items ?? []);
+  const out: SenderOption[] = [];
+  for (const item of raw as Array<Record<string, unknown>>) {
+    if (!item || typeof item !== "object") continue;
+    if (channel === "sms") {
+      const number = item.phone_number ?? item.number ?? item.phone;
+      if (typeof number === "string" && number) out.push({ value: number, label: String(item.friendly_name ?? item.label ?? number) });
+      continue;
+    }
+    const id = item.id ?? item.account_id ?? item.linkedin_account_id;
+    if (typeof id !== "number" && !(typeof id === "string" && /^\d+$/.test(id))) continue;
+    const name = [item.first_name ?? item.firstName, item.last_name ?? item.lastName].filter(Boolean).join(" ");
+    out.push({ value: String(id), label: String(name || item.name || item.email || item.emailAddress || `Account ${id}`) });
+  }
+  return out;
+}

package/blocks/inbox/recipes/01-triage-and-reply.ts

@@ -32,11 +32,21 @@ const draft = await g8.api.aiInbox.generateInboxDraft({
 });
 const html = (draft.data as { content?: string }).content ?? "";
 
-// 4. EXTERNAL: send. Reuse the same idempotency key if you retry this exact call.
+// 4. EXTERNAL: send from the thread's own mailbox (`mailbox`) to its contact. Reuse the same idempotency key if
+// you retry this exact call. When `from_address` / `to` are omitted the API fills both from the thread, but
+// graph8 APIs older than contract 1.374.0 refuse the send with 400, so name them.
+const mailbox = full.data.mailbox ?? undefined;
+const contactEmail = (full.data.contact as { email?: string | null } | null | undefined)?.email ?? undefined;
 const sent = await g8.api.inbox.sendReply(
   {
     path: { reply_id: thread.id },
-    body: { channel: "email", body: html, subject: full.data.subject ? `Re: ${full.data.subject}` : null },
+    body: {
+      channel: "email",
+      body: html,
+      subject: full.data.subject ? `Re: ${full.data.subject}` : null,
+      from_address: mailbox,
+      to: contactEmail,
+    },
   },
   { idempotencyKey: randomUUID() },
 );

package/blocks/integrations/README.md

@@ -5,6 +5,19 @@ Apollo / Salesforce "integrations" settings screen.
 
 Depends on: `foundation`. Install: `npx @graph8/sdk add integrations`.
 
+## Screens
+
+`IntegrationsScreen` (`components/integrations-screen.tsx`) is the finished page: copy it as your route. No props are required.
+
+- **Connections tab**: the five CRMs and the workspace tools. "Manage sync" opens a side panel with sync switches, job progress and a manual
+  push (deep link `?id=hubspot`; a webhook is `?tab=webhooks&id=<webhook id>`). Connecting is a link out to the graph8 app, because OAuth consent only runs there.
+- A connected CRM's panel also has: **Health** (live status, connection record, CRM account, last historic import), **Sync now** (push or pull contacts, deals and leads as background jobs you can follow, with a lead push preview; each sync asks first), **CRM records** (browse contacts, companies, deals, leads and the activity log inside the CRM, read only), **Fields** (the CRM's fields beside graph8's) and **Historic import** (scan, review the counts, import, then sync later changes).
+- **SugarCRM** is the one CRM the API can sign in to (instance address, user, password), so its panel has a **Connection** tab instead of a link-out; the other four link out to graph8.
+- **Webhooks tab**: create, pause, rotate and delete webhooks, read deliveries. The secret is shown once.
+- **Tools tab**: Slack, Google Workspace and Roam with live status and a "Connect in graph8" link for any that is not connected; Google also has a connection test and a Drive folder browser.
+- **Ad accounts tab**: the ad platforms graph8 can sync audiences to, their accounts, a warning for any account the platform has paused, and a connect link-out.
+- Props (all optional): `connectUrl`, `defaultWebhookUrl`, `pushRecords`, `toolbarActions`, `renderDetailActions(record)`, `extraDetailTabs` (each `{ id, label, render(record) }`), where `record` is `{ kind: "crm", provider }` or `{ kind: "webhook", id }`.
+
 ## Components
 
 | Component | What it does | Tiers |
@@ -12,6 +25,14 @@ Depends on: `foundation`. Install: `npx @graph8/sdk add integrations`.
 | `IntegrationList` | HubSpot, Salesforce, Pipedrive, Zoho and SugarCRM status, plus Slack, Google Workspace and Roam. Connect links to the app; Disconnect is confirmed. | read, destructive |
 | `SyncStatus` | One CRM: health, enable/disable continuous push and pull, job progress, manual contact push. | read, external |
 | `WebhookManager` | Create, pause, rotate and delete webhooks; secret shown once; delivery log; server-side verification note. | read, external, destructive |
+| `ConnectionHealth` | One CRM connection: live status, record, account metadata, last historic import. | read |
+| `SyncTriggers` | Run a sync now (contacts, deals, leads, push or pull), with a limit, a lead preview and job progress. | read, external |
+| `CrmRecords` | Browse the records and activity log inside a connected CRM, read only. | read |
+| `FieldMappings` | The CRM's fields next to the graph8 fields they can map to. | read |
+| `MigrationPanel` | Scan a CRM, review, import its history, sync later changes. | read, external, destructive |
+| `SugarCrmConnect` | Connect, check, update and remove a SugarCRM login. | read, external, destructive |
+| `WorkspaceTools` | Slack, Google Workspace and Roam status, connect link-outs, Google test and Drive browser. | read |
+| `AdAccounts` | Ad platforms, accounts and paused-account warnings. | read |
 
 `external` and `destructive` actions open `ConfirmSpendDialog` first (they write to the customer's CRM,
 change where data is sent, or remove a subscription).
@@ -41,7 +62,8 @@ reach the browser, which is why `WebhookManager` only displays it once at creati
 
 - CRM connected via the app's OAuth screen (`where: "app"`). Verify: `GET /crm-syncs/{provider}/status` -> `connected: true`.
 - A public https webhook route with `G8_WEBHOOK_SECRET` set (`where: "app"`).
-- The API key's user has integrations/webhooks admin rights (`where: "api"`).
+- The API key's user has integrations/webhooks admin rights (`where: "api"`). Migrations and the SugarCRM sign-in need an organisation admin.
+- The proxy `allowedPrefixes` include `integrations`, `crm-syncs`, `webhooks` and `audience-syncs` (the ad platform reads).
 
 ## Defaults (do not ask the human)
 
@@ -71,5 +93,45 @@ reach the browser, which is why `WebhookManager` only displays it once at creati
 | `rotate_webhook_secret_webhooks__webhook_id__rotate_secret_post` | POST /webhooks/{webhook_id}/rotate-secret | external | WebhookManager |
 | `list_webhook_deliveries_webhooks__webhook_id__deliveries_get` | GET /webhooks/{webhook_id}/deliveries | read | WebhookManager |
 | `delete_webhook_webhooks__webhook_id__delete` | DELETE /webhooks/{webhook_id} | destructive | WebhookManager |
+| `cancel_migration_integrations_migrations__migration_id__cancel_post` | POST /integrations/migrations/{migration_id}/cancel | destructive | MigrationPanel |
+| `confirm_migration_integrations_migrations__migration_id__confirm_post` | POST /integrations/migrations/{migration_id}/confirm | external | MigrationPanel |
+| `disconnect_sugarcrm_integrations_sugarcrm_delete` | DELETE /integrations/sugarcrm | destructive | SugarCrmConnect |
+| `discover_crm_fields_integrations_crm_fields_get` | GET /integrations/crm/fields | read | FieldMappings |
+| `get_crm_company_integrations_crm_connections__connection_id__companies__company_id__get` | GET /integrations/crm/connections/{connection_id}/companies/{company_id} | read | CrmRecords |
+| `get_crm_connection_integrations_crm_connections__connection_id__get` | GET /integrations/crm/connections/{connection_id} | read | ConnectionHealth |
+| `get_crm_connection_metadata_integrations_crm_connections__connection_id__metadata_get` | GET /integrations/crm/connections/{connection_id}/metadata | read | ConnectionHealth |
+| `get_crm_connection_status_integrations_crm_connections__connection_id__status_get` | GET /integrations/crm/connections/{connection_id}/status | read | ConnectionHealth |
+| `get_crm_contact_integrations_crm_connections__connection_id__contacts__contact_id__get` | GET /integrations/crm/connections/{connection_id}/contacts/{contact_id} | read | CrmRecords |
+| `get_crm_deal_integrations_crm_connections__connection_id__deals__deal_id__get` | GET /integrations/crm/connections/{connection_id}/deals/{deal_id} | read | CrmRecords |
+| `get_crm_lead_integrations_crm_connections__connection_id__leads__lead_id__get` | GET /integrations/crm/connections/{connection_id}/leads/{lead_id} | read | CrmRecords |
+| `get_last_completed_migration_integrations_connections__connection_id__last_migration_get` | GET /integrations/connections/{connection_id}/last-migration | read | ConnectionHealth, MigrationPanel |
+| `get_migration_status_integrations_migrations__migration_id__get` | GET /integrations/migrations/{migration_id} | read | MigrationPanel |
+| `get_webhook_webhooks__webhook_id__get` | GET /webhooks/{webhook_id} | read | WebhookDetail |
+| `list_ad_account_health_audience_syncs_account_health_get` | GET /audience-syncs/account-health | read | AdAccounts |
+| `list_ad_accounts_audience_syncs_accounts_get` | GET /audience-syncs/accounts | read | AdAccounts |
+| `list_ad_platforms_audience_syncs_platforms_get` | GET /audience-syncs/platforms | read | AdAccounts |
+| `list_crm_activities_integrations_crm_activities_get` | GET /integrations/crm/activities | read | CrmRecords |
+| `list_crm_companies_integrations_crm_connections__connection_id__companies_get` | GET /integrations/crm/connections/{connection_id}/companies | read | CrmRecords |
+| `list_crm_contact_activities_integrations_crm_connections__connection_id__contacts__contact_id__activities_get` | GET /integrations/crm/connections/{connection_id}/contacts/{contact_id}/activities | read | CrmRecords |
+| `list_crm_contacts_integrations_crm_connections__connection_id__contacts_get` | GET /integrations/crm/connections/{connection_id}/contacts | read | CrmRecords |
+| `list_crm_deals_integrations_crm_connections__connection_id__deals_get` | GET /integrations/crm/connections/{connection_id}/deals | read | CrmRecords |
+| `list_crm_leads_integrations_crm_connections__connection_id__leads_get` | GET /integrations/crm/connections/{connection_id}/leads | read | CrmRecords |
+| `list_google_drive_folder_files_integrations_google_workspace_folders__folder_id__files_get` | GET /integrations/google-workspace/folders/{folder_id}/files | read | WorkspaceTools |
+| `list_google_drive_folders_integrations_google_workspace_folders_get` | GET /integrations/google-workspace/folders | read | WorkspaceTools |
+| `list_lead_statuses_integrations_crm_sync_leads_statuses_get` | GET /integrations/crm-sync/leads/statuses | read | SyncTriggers |
+| `list_mappable_graph8_fields_integrations_crm_fields_mappable_get` | GET /integrations/crm/fields/mappable | read | FieldMappings |
+| `preview_lead_push_integrations_crm_sync_leads_push_preview_get` | GET /integrations/crm-sync/leads/push-preview | read | SyncTriggers |
+| `pull_all_contacts_integrations_crm_sync_contacts_pull_post` | POST /integrations/crm-sync/contacts/pull | external | SyncTriggers |
+| `pull_all_deals_integrations_crm_sync_deals_pull_post` | POST /integrations/crm-sync/deals/pull | external | SyncTriggers |
+| `pull_all_leads_integrations_crm_sync_leads_pull_post` | POST /integrations/crm-sync/leads/pull | external | SyncTriggers |
+| `push_all_contacts_integrations_crm_sync_contacts_push_post` | POST /integrations/crm-sync/contacts/push | external | SyncTriggers |
+| `push_all_deals_integrations_crm_sync_deals_push_post` | POST /integrations/crm-sync/deals/push | external | SyncTriggers |
+| `push_all_leads_integrations_crm_sync_leads_push_post` | POST /integrations/crm-sync/leads/push | external | SyncTriggers |
+| `start_delta_sync_integrations_migrations_delta_sync_post` | POST /integrations/migrations/delta-sync | external | MigrationPanel |
+| `start_migration_discovery_integrations_migrations_discovery_post` | POST /integrations/migrations/discovery | external | MigrationPanel |
+| `test_google_workspace_connection_integrations_google_workspace_test_post` | POST /integrations/google-workspace/test | read | WorkspaceTools |
+| `validate_sugarcrm_integrations_sugarcrm_validate_post` | POST /integrations/sugarcrm/validate | read | SugarCrmConnect |
+
+Not offered on purpose: CRM pass-through writes (create, update and delete a contact, company, deal, lead or meeting directly in the CRM, and the batch versions) because they bypass graph8's records and field mapping (they stay in recipes and `g8.api.integrations`); the embedded connection session token and `saveConnection` (the OAuth consent screen only runs in the graph8 app); syncing a graph8 list or audience (needs a list picker and starts from the Lists screen); Google Ads conversions and video assets (the Ads screen owns audience syncs).
 
 Recipes (`recipes/`): `verify-webhook-route.ts`, `register-webhook.ts`, `crm-sync-health.ts`, `push-contacts-to-crm.ts`.