@graph8/sdk 0.370.0 → 0.374.0

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

@@ -0,0 +1,133 @@
+"use client";
+
+/**
+ * ThreadActions: the small things you do to one conversation besides replying: mark it read (or, on LinkedIn,
+ * unread), take a tag off, take a teammate off, and block the sender.
+ *
+ * SDK operations, in order (the thread's own id and channel decide the route):
+ *   Read state   POST /inbox/emails/{id}/mark-read                                          (aiInbox.markInboxEmailRead)   write
+ *                POST /inbox/sms/{id}/mark-read                                             (aiInbox.markInboxSmsRead)     write
+ *                POST /inbox/linkedin/accounts/{account}/conversations/{id}/read|unread     (aiInbox.markInboxLinkedinConversationRead|Unread) write
+ *                There is no "mark unread" for email or SMS in the API, so those offer only "Mark as read".
+ *   Remove tag   DELETE /inbox/channels/{id}/tags?tag_id&channel_type                       (aiInbox.removeChannelTag)     DESTRUCTIVE -> ConfirmSpendDialog
+ *   Unassign     DELETE /inbox/channels/{id}/assign?assignee_email&channel_type             (aiInbox.unassignChannel)      DESTRUCTIVE -> ConfirmSpendDialog
+ *   Block sender POST /inbox/blocked-senders { mailbox, sender_email }                     (aiInbox.blockInboxSender)     write, email threads only;
+ *                asked inline first because future mail from them stops arriving (BlockedSenders can undo it)
+ * Applying a tag and assigning are TagAndAssign. Nothing here sends a message.
+ */
+import { useState } from "react";
+import { Ban, CheckCheck, MailOpen, X } from "lucide-react";
+import { Button } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { g8Delete, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { canMarkRead, canMarkUnread, channelTypeOf } from "../lib/inbox-manage";
+import type { InboxThread } from "../lib/inbox-types";
+
+type Pending = { kind: "tag"; id: string; name: string } | { kind: "assignee"; email: string; name: string } | null;
+
+export interface ThreadActionsProps {
+  thread: InboxThread;
+  /** Called after any change; reload the thread here. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+function readPath(thread: InboxThread, read: boolean): string | null {
+  const id = encodeURIComponent(thread.id);
+  if (thread.channel === "sms") return read ? `/inbox/sms/${id}/mark-read` : null;
+  if (thread.channel === "linkedin") {
+    return thread.linkedin_account_id == null ? null : `/inbox/linkedin/accounts/${thread.linkedin_account_id}/conversations/${id}/${read ? "read" : "unread"}`;
+  }
+  return read ? `/inbox/emails/${id}/mark-read` : null;
+}
+
+export function ThreadActions({ thread, onChanged, className }: ThreadActionsProps) {
+  const [pending, setPending] = useState<Pending>(null);
+  const [blocking, setBlocking] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
+  const channelType = channelTypeOf(thread.channel);
+  const sender = thread.channel === "email" ? (thread.contact?.email ?? "") : "";
+  const channelQuery = { channel_type: channelType, linkedin_account_id: thread.channel === "linkedin" ? thread.linkedin_account_id : undefined };
+  const done = (message: string) => { setNotice(message); onChanged?.(); };
+
+  const mark = useG8Mutation(async (read: boolean) => {
+    const path = readPath(thread, read);
+    if (!path) throw new Error("This conversation cannot be marked that way.");
+    await g8Post(path);
+    done(read ? "Marked as read." : "Marked as unread.");
+  }, { invalidates: ["inbox"] });
+  const remove = useG8Mutation(async (p: NonNullable<Pending>) => {
+    const base = `/inbox/channels/${encodeURIComponent(thread.id)}`;
+    if (p.kind === "tag") await g8Delete(`${base}/tags`, { query: { ...channelQuery, tag_id: p.id } });
+    else await g8Delete(`${base}/assign`, { query: { ...channelQuery, assignee_email: p.email } });
+    done(p.kind === "tag" ? `Removed the tag "${p.name}".` : `Unassigned ${p.name}.`);
+  }, { invalidates: ["inbox"] });
+  const block = useG8Mutation(async () => {
+    await g8Post("/inbox/blocked-senders", { mailbox: thread.mailbox, sender_email: sender });
+    setBlocking(false);
+    done(`Blocked ${sender}.`);
+  }, { invalidates: ["inbox"] });
+
+  const confirm = async () => {
+    const current = pending;
+    if (!current) return;
+    try {
+      await remove.mutateAsync(current);
+    } catch {
+      /* surfaced below */
+    }
+    setPending(null);
+  };
+  const canBlock = thread.channel === "email" && Boolean(thread.mailbox) && Boolean(sender);
+  const label = (n: string | null | undefined, fallback: string) => n || fallback;
+
+  return (
+    <section aria-label="Conversation actions" className={`space-y-3 rounded-lg border p-3 text-sm ${className ?? ""}`}>
+      <h3 className="font-medium">Manage conversation</h3>
+      <div className="flex flex-wrap gap-2">
+        {canMarkRead(thread) ? <Button size="sm" variant="outline" loading={mark.loading} onClick={() => void mark.mutate(true)}><MailOpen className="mr-1 size-4" aria-hidden />Mark as read</Button> : null}
+        {canMarkUnread(thread) ? <Button size="sm" variant="outline" disabled={mark.loading} onClick={() => void mark.mutate(false)}>Mark as unread</Button> : null}
+        {canBlock && !blocking ? <Button size="sm" variant="outline" onClick={() => setBlocking(true)}><Ban className="mr-1 size-4" aria-hidden />Block sender</Button> : null}
+      </div>
+      {blocking ? (
+        <div role="group" aria-label="Block this sender" className="flex flex-wrap items-center gap-2 rounded-md border border-border p-2">
+          <span>Stop receiving mail from {sender} in {thread.mailbox}?</span>
+          <Button size="sm" loading={block.loading} onClick={() => void block.mutate(undefined)}>Block {sender}</Button>
+          <Button size="sm" variant="ghost" onClick={() => setBlocking(false)}>Cancel</Button>
+        </div>
+      ) : null}
+      {thread.tags.length > 0 || thread.assignees.length > 0 ? (
+        <ul aria-label="Remove from conversation" className="space-y-1">
+          {thread.tags.filter((t) => t.id).map((t) => (
+            <li key={`t-${t.id}`} className="flex items-center justify-between gap-2">
+              <span>Tag: {label(t.name, String(t.id))}</span>
+              <Button size="sm" variant="ghost" aria-label={`Remove tag ${label(t.name, String(t.id))}`} onClick={() => setPending({ kind: "tag", id: String(t.id), name: label(t.name, String(t.id)) })}><X className="size-4" aria-hidden /></Button>
+            </li>
+          ))}
+          {thread.assignees.map((a) => (
+            <li key={`a-${a.email}`} className="flex items-center justify-between gap-2">
+              <span>Assigned to {label(a.name, a.email)}</span>
+              <Button size="sm" variant="ghost" aria-label={`Unassign ${label(a.name, a.email)}`} onClick={() => setPending({ kind: "assignee", email: a.email, name: label(a.name, a.email) })}><X className="size-4" aria-hidden /></Button>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+      {[mark.error, remove.error, block.error].map((e, i) => (e ? <ApiError key={i} error={e} title="Could not update the conversation" /> : null))}
+      {notice ? <p role="status" className="text-xs text-muted-foreground"><CheckCheck className="mr-1 inline size-3" aria-hidden />{notice}</p> : null}
+
+      <ConfirmSpendDialog
+        open={pending != null}
+        tier="destructive"
+        title={pending?.kind === "tag" ? `Remove the tag "${pending.name}"?` : `Unassign ${pending?.name ?? ""}?`}
+        description={pending?.kind === "tag" ? "The tag comes off this conversation only. Other conversations keep it." : "They no longer own this conversation. You can assign them again later."}
+        confirmLabel={pending?.kind === "tag" ? "Remove tag" : "Unassign"}
+        affected={1}
+        confirming={remove.loading}
+        onConfirm={() => void confirm()}
+        onCancel={() => setPending(null)}
+      />
+    </section>
+  );
+}

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

@@ -18,6 +18,7 @@ import { ApiError } from "@/g8/components/api-error";
 import { EmptyState } from "@/g8/components/empty-state";
 import { useInboxThread } from "../hooks/use-inbox-thread";
 import { contactLabel, formatWhen, stripHtml, type InboxMessage, type InboxThread } from "../lib/inbox-types";
+import { isNotFound } from "../lib/inbox-manage";
 
 export interface ThreadViewProps {
   /** A row from InboxList. Only `id` and `channel` are required; the rest is loaded fresh. */
@@ -50,7 +51,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>
@@ -73,6 +74,7 @@ function ThreadHeader({ thread }: { thread: InboxThread }) {
 export function ThreadView({ thread: row, children, className }: ThreadViewProps) {
   const { data, loading, error, refetch } = useInboxThread(row.id, row.channel);
 
+  if (isNotFound(error)) return <EmptyState title="Conversation not found" description="It may have been removed, or it is not shared with this API key. Hidden conversations answer exactly like missing ones." />;
   if (error) return <ApiError error={error} title="Could not load this conversation" onRetry={() => void refetch()} />;
   if (loading && !data) {
     return (

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

@@ -0,0 +1,31 @@
+"use client";
+
+/**
+ * useInboxMailboxes: EVERY mailbox the caller can see, with whether they may send as it. One page of 100 is read, then the
+ * next, until the API says there is no more (at most 20 pages); `truncated` is true when that cap was hit, and the picker
+ * must say so (FirstNotice). A mailbox beyond the first page can therefore never be silently missing from a sender picker.
+ *
+ * SDK operations: GET /inbox/mailboxes/paginated?page&page_size (aiInbox.listInboxMailboxesPaginated), read tier.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useAllPages } from "@/g8/hooks/use-all-pages";
+import { hasNextOf } from "@/g8/lib/paging";
+import { mailboxChoices } from "../lib/inbox-manage";
+import type { MailboxChoice } from "../lib/inbox-manage";
+
+const PAGE = 100;
+
+export function useInboxMailboxes(options: { enabled?: boolean } = {}) {
+  const all = useAllPages<MailboxChoice>(
+    async (page, signal) => {
+      const env = await g8Get("/inbox/mailboxes/paginated", { page, page_size: PAGE }, { signal });
+      const rows = mailboxChoices(env);
+      return { rows, hasNext: hasNextOf(env, PAGE, rows.length) };
+    },
+    [],
+    { enabled: options.enabled, pageSize: PAGE },
+  );
+  const seen = new Set<string>();
+  const items = all.items.filter((m) => !seen.has(m.address.toLowerCase()) && seen.add(m.address.toLowerCase()));
+  return { ...all, items, data: all.loaded ? items : undefined };
+}

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

@@ -0,0 +1,227 @@
+"use client";
+
+/**
+ * Pure helpers for the inbox management parts: composing a new message, managing tags and blocked senders,
+ * server-side search, and the per-thread actions (read state, unassign, remove a tag). No SDK calls here.
+ *
+ * Several of these endpoints answer with an open `{ items: [...] }` payload (no response schema in the
+ * contract), so every reader below is defensive: it accepts a bare list, `{ items }`, or the named list the
+ * route actually uses, and skips rows it cannot make sense of.
+ */
+import type { InboxChannel, InboxTag, InboxThread } from "./inbox-types";
+import { stripHtml } from "./inbox-types";
+
+/** Rows from a bare list, `{ data: [...] }`, `{ items: [...] }` or a named list such as `{ tags: [...] }`. */
+export function rowsFrom<T = Record<string, unknown>>(payload: unknown, ...names: string[]): T[] {
+  const list = (v: unknown): T[] | null => (Array.isArray(v) ? (v as T[]) : null);
+  const direct = list(payload);
+  if (direct) return direct;
+  const obj = (payload ?? {}) as Record<string, unknown>;
+  const inner = (obj.data && typeof obj.data === "object" ? (obj.data as Record<string, unknown>) : obj) as Record<string, unknown>;
+  return list(inner) ?? list(inner.items) ?? names.map((n) => list(inner[n])).find(Boolean) ?? list(obj.items) ?? [];
+}
+
+// --- Compose ----------------------------------------------------------------------------------------------------
+
+export interface MailboxChoice {
+  /** The address the message is sent from (`from_mailbox`). */
+  address: string;
+  label: string;
+  /** False when the caller may see the mailbox but not send as it; `reason` says why. */
+  canSend: boolean;
+  reason?: string;
+}
+
+/** Sender choices from `GET /inbox/mailboxes/paginated` (rows carry `can_send` / `send_blocked_reason`). */
+export function mailboxChoices(payload: unknown): MailboxChoice[] {
+  const out: MailboxChoice[] = [];
+  const seen = new Set<string>();
+  for (const row of rowsFrom<Record<string, unknown>>(payload, "mailboxes")) {
+    const address = String(row?.mailbox ?? row?.email ?? "").trim();
+    if (!address || seen.has(address.toLowerCase())) continue;
+    seen.add(address.toLowerCase());
+    const canSend = row.can_send !== false;
+    const reason = typeof row.send_blocked_reason === "string" ? row.send_blocked_reason : undefined;
+    out.push({ address, label: address, canSend, reason: canSend ? undefined : (reason ?? "not allowed to send as this mailbox") });
+  }
+  return out;
+}
+
+const EMAIL = /^[^\s@,;<>]+@[^\s@,;<>]+\.[^\s@,;<>]+$/;
+export const isEmail = (value: string): boolean => EMAIL.test(value.trim());
+
+/** Split "a@x.com, b@y.com; c@z.com" into trimmed, de-duplicated addresses (case-insensitive). */
+export function splitAddresses(value: string): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const part of value.split(/[,;\n]/)) {
+    const v = part.trim();
+    if (v && !seen.has(v.toLowerCase())) {
+      seen.add(v.toLowerCase());
+      out.push(v);
+    }
+  }
+  return out;
+}
+
+/** A phone number the SMS route will accept: E.164 (`+` then 8 to 15 digits). */
+export const isPhone = (value: string): boolean => /^\+[1-9]\d{7,14}$/.test(value.replace(/[\s().-]/g, ""));
+export const normalizePhone = (value: string): string => value.replace(/[\s().-]/g, "");
+
+const escapeHtml = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+/** The compose API takes an HTML body; what people type is plain text. Paragraphs become `<p>`, newlines `<br>`. */
+export function textToHtml(text: string): string {
+  return text
+    .trim()
+    .split(/\n{2,}/)
+    .map((p) => `<p>${escapeHtml(p).replace(/\n/g, "<br>")}</p>`)
+    .join("");
+}
+
+export interface EmailComposeInput {
+  from: string;
+  to: string;
+  cc?: string;
+  subject: string;
+  body: string;
+}
+
+/** What is still missing before an email may be sent, in the order the form asks for it. Empty means ready. */
+export function emailComposeProblems(input: EmailComposeInput): string[] {
+  const problems: string[] = [];
+  if (!input.from.trim()) problems.push("Choose the mailbox to send from.");
+  const to = splitAddresses(input.to);
+  if (to.length === 0) problems.push("Add at least one recipient.");
+  else if (to.some((a) => !isEmail(a))) problems.push("One of the recipient addresses is not valid.");
+  if (splitAddresses(input.cc ?? "").some((a) => !isEmail(a))) problems.push("One of the Cc addresses is not valid.");
+  if (!input.subject.trim()) problems.push("Add a subject.");
+  if (!input.body.trim()) problems.push("Write the message.");
+  return problems;
+}
+
+export interface SmsComposeInput {
+  from: string;
+  to: string;
+  body: string;
+}
+
+export function smsComposeProblems(input: SmsComposeInput): string[] {
+  const problems: string[] = [];
+  if (!input.from.trim()) problems.push("Choose the number to text from.");
+  if (!input.to.trim()) problems.push("Add the phone number to text.");
+  else if (!isPhone(input.to)) problems.push("Use the full number with country code, for example +14155550100.");
+  if (!input.body.trim()) problems.push("Write the message.");
+  return problems;
+}
+
+// --- Tags -------------------------------------------------------------------------------------------------------
+
+export interface ManagedTag {
+  id: string;
+  name: string;
+  description: string;
+  color: string;
+  /** Built-in tags: "system" cannot be edited or deleted, "sdr_ai" cannot be renamed or deleted. */
+  policy: "system" | "sdr_ai" | "user";
+}
+
+/** Tags from `GET /workflows/inbox-tags` (`{ tags: [...], total }`, with or without an envelope). */
+export function managedTags(payload: unknown): ManagedTag[] {
+  const out: ManagedTag[] = [];
+  for (const row of rowsFrom<Record<string, unknown>>(payload, "tags")) {
+    const id = row?.id == null ? "" : String(row.id);
+    if (!id) continue;
+    const policy = row.policy === "system" || row.policy === "sdr_ai" || row.is_system === true ? (row.policy === "sdr_ai" ? "sdr_ai" : "system") : "user";
+    out.push({ id, name: String(row.name ?? id), description: String(row.description ?? ""), color: String(row.color ?? ""), policy });
+  }
+  return out;
+}
+
+export const asInboxTags = (tags: ManagedTag[]): InboxTag[] => tags.map((t) => ({ id: t.id, name: t.name }));
+
+export const canEditTag = (tag: ManagedTag): boolean => tag.policy !== "system";
+export const canRenameTag = (tag: ManagedTag): boolean => tag.policy === "user";
+export const canDeleteTag = (tag: ManagedTag): boolean => tag.policy === "user";
+
+/** Only the fields that changed, for `PUT /inbox/tags/{id}` (which writes exactly what it is sent). */
+export function tagChanges(
+  loaded: Pick<ManagedTag, "name" | "description" | "color">,
+  draft: { name: string; description: string; color: string },
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (draft.name.trim() !== loaded.name) out.name = draft.name.trim();
+  if (draft.description.trim() !== loaded.description) out.description = draft.description.trim();
+  if (draft.color.trim() !== loaded.color) out.color = draft.color.trim();
+  return out;
+}
+
+export const isHexColor = (v: string): boolean => v === "" || /^#[0-9a-f]{6}$/i.test(v.trim());
+
+// --- Blocked senders --------------------------------------------------------------------------------------------
+
+export interface BlockedSender {
+  id: string;
+  email: string;
+  mailbox: string;
+  reason: string;
+}
+
+export function blockedSenders(payload: unknown): BlockedSender[] {
+  const out: BlockedSender[] = [];
+  for (const row of rowsFrom<Record<string, unknown>>(payload, "blocked_senders", "senders")) {
+    const id = row?.id == null ? "" : String(row.id);
+    const email = String(row?.sender_email ?? row?.email ?? "");
+    if (id && email) out.push({ id, email, mailbox: String(row.mailbox ?? ""), reason: String(row.reason ?? "") });
+  }
+  return out;
+}
+
+// --- Per-thread actions -----------------------------------------------------------------------------------------
+
+/** The `channel_type` the `/inbox/channels/{id}/...` routes use for a thread of this channel. */
+export function channelTypeOf(channel: InboxChannel | string): "email" | "sms" | "heyreach" {
+  return channel === "sms" ? "sms" : channel === "linkedin" ? "heyreach" : "email";
+}
+
+/** Marking a thread unread exists only for LinkedIn; email and SMS can only be marked read. */
+export const canMarkUnread = (thread: Pick<InboxThread, "channel" | "linkedin_account_id">): boolean =>
+  thread.channel === "linkedin" && thread.linkedin_account_id != null;
+
+/** Can this thread be marked read at all? (LinkedIn needs its account id for the route.) */
+export const canMarkRead = (thread: Pick<InboxThread, "channel" | "linkedin_account_id">): boolean =>
+  thread.channel !== "linkedin" || thread.linkedin_account_id != null;
+
+// --- Server-side search -----------------------------------------------------------------------------------------
+
+export interface SearchHit {
+  id: string;
+  channel: "email" | "linkedin";
+  title: string;
+  subtitle: string;
+  preview: string;
+  when?: string;
+}
+
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+
+/** A search result row (email thread or LinkedIn conversation) as a list entry. Null when it has no usable id. */
+export function searchHit(channel: "email" | "linkedin", row: Record<string, unknown>): SearchHit | null {
+  const id = row.id ?? row.email_id ?? row.thread_id ?? row.conversation_id ?? row.chat_id;
+  if (id == null || id === "") return null;
+  const contact = (row.contact ?? {}) as Record<string, unknown>;
+  const first = Array.isArray(row.messages) ? ((row.messages as Array<Record<string, unknown>>)[0] ?? {}) : {};
+  const who = str(contact.name) || str(row.contact_name) || str(row.from_name) || str(row.from_email) || str(row.sender) || str(contact.email);
+  const title = str(row.subject) || who || (channel === "linkedin" ? "LinkedIn conversation" : "Email conversation");
+  const preview = stripHtml(str(row.snippet) || str(row.preview) || str(row.last_message) || str(first.content) || str(row.body)).replace(/\s+/g, " ").slice(0, 140);
+  const when = str(row.updated_at) || str(row.last_message_at) || str(row.created_at) || undefined;
+  return { id: String(id), channel, title, subtitle: who && who !== title ? who : str(row.mailbox), preview, when };
+}
+
+// --- Hidden or missing threads ------------------------------------------------------------------------------------
+
+/**
+ * The dev API answers a uniform 404 for a thread that does not exist AND for one this key may not see (an org key sees
+ * shared threads only), so the two cannot be told apart. Views say so instead of showing a generic failure.
+ */
+export const isNotFound = (error: unknown): boolean => (error as { status?: number } | null)?.status === 404;

package/blocks/integrations/README.md

@@ -11,7 +11,11 @@ Depends on: `foundation`. Install: `npx @graph8/sdk add integrations`.
 
 - **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
@@ -21,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).
@@ -50,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)
 
@@ -80,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`.