@graph8/sdk 0.362.0 → 0.373.0

package/blocks/integrations/components/crm-records.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+/**
+ * CrmRecords: look inside a connected CRM without leaving graph8. Contacts, Companies, Deals and Leads as lists (25 at a time, "Load more"
+ * pages through all of them), the CRM's own activity log, and a record's fields (plus a contact's activities) when you open one.
+ * Read only: changing CRM records from here is deliberately not offered (use the sync to push graph8 data; edit in the CRM itself).
+ * Not every CRM has every kind (Pipedrive has no leads in the same sense); a kind the CRM refuses shows its error with Retry.
+ *
+ * SDK operations, in order (connection_id from the connection):
+ *   1. listCrmContacts / listCrmCompanies / listCrmDeals / listCrmLeads   GET /integrations/crm/connections/{connection_id}/{kind}?limit&offset[&name]  (read)
+ *   2. getCrmContact / getCrmCompany / getCrmDeal / getCrmLead             GET /integrations/crm/connections/{connection_id}/{kind}/{id}   (read)
+ *   3. listCrmContactActivities   GET /integrations/crm/connections/{connection_id}/contacts/{contact_id}/activities?limit   (read)
+ *   4. listCrmActivities          GET /integrations/crm/activities?connection_id&limit&offset   (read)
+ */
+import { useEffect, useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { CRM_ENTITIES, crmRecordSubtitle, crmRecordTitle, flattenRecord } from "../lib/crm-utils";
+import type { CrmEntity, CrmRecord } from "../lib/crm-utils";
+import { FactList } from "../lib/facts";
+import { LoadMore, useLoadMoreList } from "../lib/load-more";
+import { arrayOf, formatWhen } from "../lib/integrations-utils";
+
+export interface CrmRecordsProps {
+  connectionId: string;
+  className?: string;
+}
+
+type Tab = CrmEntity | "activity";
+const enc = encodeURIComponent;
+
+function RecordFacts({ connectionId, entity, id }: { connectionId: string; entity: CrmEntity; id: string }) {
+  const rec = useG8Query((signal) => g8Get<CrmRecord>(`/integrations/crm/connections/${enc(connectionId)}/${entity}/${enc(id)}`, undefined, { signal }), [connectionId, entity, id]);
+  const acts = useG8Query((signal) => g8Get(`/integrations/crm/connections/${enc(connectionId)}/contacts/${enc(id)}/activities`, { limit: 20 }, { signal }), [connectionId, id], { enabled: entity === "contacts" });
+  const data = ((rec.data as { data?: CrmRecord } | undefined)?.data ?? {}) as CrmRecord;
+  const rows = arrayOf<Record<string, unknown>>(acts.data);
+  return (
+    <SectionCard title={crmRecordTitle(data) || "Record"} description={rec.loading ? "Loading..." : crmRecordSubtitle(data) || undefined}>
+      {rec.error ? <ApiError error={rec.error} title="Could not load the record" onRetry={() => void rec.refetch()} /> : null}
+      {rec.loading && !rec.data ? <Skeleton className="h-16 w-full" /> : null}
+      {rec.data ? <FactList data={flattenRecord(data)} empty="This record has no fields we can show." /> : null}
+      {entity === "contacts" ? (
+        <div className="mt-4">
+          <h4 className="mb-1 text-sm font-medium">Recent activity</h4>
+          {acts.error ? <ApiError compact error={acts.error} title="Could not load the activities" onRetry={() => void acts.refetch()} /> : null}
+          {acts.loading && !acts.data ? <Skeleton className="h-8 w-full" /> : null}
+          {acts.data && rows.length === 0 ? <p className="text-sm text-muted-foreground">No activity in the CRM.</p> : null}
+          {rows.length > 0 ? <><ul className="divide-y rounded-md border text-sm">{rows.map((a, i) => <li key={String(a.id ?? i)} className="px-3 py-1.5">{String(a.subject ?? a.type ?? a.title ?? "Activity")}<span className="ml-2 text-xs text-muted-foreground">{formatWhen(String(a.timestamp ?? a.created_at ?? a.date ?? "") || null)}</span></li>)}</ul>{rows.length >= 20 ? <p className="mt-1 text-xs text-muted-foreground">Showing the latest 20 activities.</p> : null}</> : null}
+        </div>
+      ) : null}
+    </SectionCard>
+  );
+}
+
+export function CrmRecords({ connectionId, className }: CrmRecordsProps) {
+  const [tab, setTab] = useState<Tab>("contacts");
+  const [search, setSearch] = useState("");
+  const [open, setOpen] = useState<string | null>(null);
+  useEffect(() => { setOpen(null); setSearch(""); }, [connectionId, tab]);
+  const q = search.trim();
+  const list = useLoadMoreList<CrmRecord>(async (offset, limit, signal) => {
+    const base = `/integrations/crm/connections/${enc(connectionId)}`;
+    const res = tab === "activity" ? await g8Get("/integrations/crm/activities", { connection_id: connectionId, limit, offset }, { signal })
+      : await g8Get(`${base}/${tab}`, { limit, offset, name: tab === "contacts" ? q || undefined : undefined }, { signal });
+    return arrayOf<CrmRecord>(res);
+  }, [connectionId, tab, q], { pageSize: 25 });
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <div role="tablist" aria-label="CRM record kinds" className="flex flex-wrap gap-1 border-b">
+        {([...CRM_ENTITIES, { id: "activity", label: "Activity log" }] as const).map((t) => (
+          <button key={t.id} type="button" role="tab" aria-selected={tab === t.id} onClick={() => setTab(t.id as Tab)} className={`px-3 py-2 text-sm ${tab === t.id ? "border-b-2 border-foreground font-medium" : "text-muted-foreground"}`}>{t.label}</button>
+        ))}
+      </div>
+      {tab === "contacts" ? <Toolbar search={{ value: search, onChange: setSearch, placeholder: "Search contacts by name" }} /> : null}
+      {list.error ? <ApiError error={list.error} title="Could not load these records" onRetry={list.reload} /> : null}
+      {list.loading ? <Skeleton className="h-24 w-full" aria-label="Loading records" /> : null}
+      <ul className="divide-y rounded-md border" aria-label="CRM records">
+        {list.items.map((r, i) => {
+          const id = String(r.id ?? "");
+          return tab === "activity" ? (
+            <li key={id || i} className="px-3 py-2 text-sm">{String(r.subject ?? r.type ?? r.title ?? "Activity")}<span className="ml-2 text-xs text-muted-foreground">{formatWhen(String(r.timestamp ?? r.created_at ?? r.date ?? "") || null)}</span></li>
+          ) : (
+            <li key={id || i} className={open === id ? "bg-accent" : ""}>
+              <button type="button" className="block w-full px-3 py-2 text-left text-sm" onClick={() => setOpen(open === id ? null : id)} disabled={!id}>
+                <span className="block font-medium">{crmRecordTitle(r)}</span><span className="block text-xs text-muted-foreground">{crmRecordSubtitle(r)}</span>
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+      {!list.loading && !list.error && list.items.length === 0 ? <EmptyState compact title={q ? "No contacts match" : "Nothing here"} description={tab === "activity" ? "The CRM has no activity for this connection yet." : "This CRM has no records of this kind."} /> : null}
+      <LoadMore list={list} noun="records" />
+      {open && tab !== "activity" ? <RecordFacts key={`${tab}:${open}`} connectionId={connectionId} entity={tab} id={open} /> : null}
+      {open ? <Button size="sm" variant="ghost" className="self-start" onClick={() => setOpen(null)}>Close record</Button> : null}
+    </div>
+  );
+}

package/blocks/integrations/components/field-mappings.tsx

@@ -0,0 +1,61 @@
+"use client";
+
+/**
+ * FieldMappings: which fields exist on each side of the sync. The CRM's fields for a kind of record (contact, company, deal) next to the
+ * graph8 fields they can map to, each searchable. Read only: the mapping itself is chosen in graph8 (the API has no call to save one),
+ * so this view is for checking that a field you expect on the CRM side exists before you sync.
+ *
+ * SDK operations, in order:
+ *   1. discoverCrmFields          GET /integrations/crm/fields?connection_id&entity_type        (read)  the CRM's fields
+ *   2. listMappableGraph8Fields   GET /integrations/crm/fields/mappable?object_type             (read)  graph8 fields a CRM field can map to
+ */
+import { useState } from "react";
+import { Input, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { arrayOf } from "../lib/integrations-utils";
+
+export interface FieldMappingsProps {
+  connectionId: string;
+  className?: string;
+}
+
+interface Field { name?: string; key?: string; label?: string; type?: string; field_type?: string }
+// The API accepts only the plural object names (CrmFieldEntityType / Graph8FieldObjectType).
+const KINDS = [{ id: "contacts", label: "Contacts" }, { id: "companies", label: "Companies" }, { id: "deals", label: "Deals" }];
+const nameOf = (f: Field): string => f.label ?? f.name ?? f.key ?? "";
+
+function FieldColumn({ title, query, filter }: { title: string; query: { data: unknown; error: unknown; loading: boolean; refetch: () => Promise<unknown> }; filter: string }) {
+  const rows = arrayOf<Field>(query.data).filter((f) => nameOf(f).toLowerCase().includes(filter.toLowerCase()));
+  return (
+    <SectionCard title={title} description={query.data ? `${rows.length} fields` : undefined} flush>
+      {query.error ? <div className="p-3"><ApiError error={query.error} title="Could not load the fields" onRetry={() => void query.refetch()} /></div> : null}
+      {query.loading && !query.data ? <Skeleton className="m-3 h-16" /> : null}
+      <ul className="max-h-80 divide-y overflow-y-auto text-sm">{rows.map((f, i) => <li key={`${nameOf(f)}-${i}`} className="flex justify-between gap-2 px-3 py-1.5"><span>{nameOf(f)}</span><span className="text-xs text-muted-foreground">{f.type ?? f.field_type ?? ""}</span></li>)}</ul>
+      {query.data && !query.error && rows.length === 0 ? <p className="px-3 py-2 text-sm text-muted-foreground">No fields match.</p> : null}
+    </SectionCard>
+  );
+}
+
+export function FieldMappings({ connectionId, className }: FieldMappingsProps) {
+  const brand = useBrand();
+  const [kind, setKind] = useState("contacts");
+  const [filter, setFilter] = useState("");
+  const crm = useG8Query((signal) => g8Get("/integrations/crm/fields", { connection_id: connectionId, entity_type: kind }, { signal }), [connectionId, kind]);
+  const mine = useG8Query((signal) => g8Get("/integrations/crm/fields/mappable", { object_type: kind }, { signal }), [kind]);
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      <div className="flex flex-wrap items-center gap-2">
+        <div role="group" aria-label="Record kind" className="flex gap-1">{KINDS.map((k) => <button key={k.id} type="button" aria-pressed={kind === k.id} onClick={() => setKind(k.id)} className={`rounded-md border px-3 py-1 text-sm ${kind === k.id ? "bg-foreground text-background" : ""}`}>{k.label}</button>)}</div>
+        <Input aria-label="Filter fields" className="h-8 max-w-xs" placeholder="Filter fields" value={filter} onChange={(e) => setFilter(e.target.value)} />
+      </div>
+      <div className="grid gap-4 md:grid-cols-2">
+        <FieldColumn title="In the CRM" query={crm} filter={filter} />
+        <FieldColumn title={`In ${brand.name}`} query={mine} filter={filter} />
+      </div>
+    </div>
+  );
+}

package/blocks/integrations/components/integration-list.tsx

@@ -26,17 +26,20 @@ import {
   arrayOf,
   CRM_PROVIDERS,
   formatWhen,
-  GRAPH8_APP_INTEGRATIONS_URL,
+  GRAPH8_APP_INTEGRATIONS_PATH,
   looksConnected,
   PROVIDER_LABELS,
 } from "../lib/integrations-utils";
 import type { ConnectionRow, CrmProvider, CrmSyncRow } from "../lib/integrations-utils";
+import { brandUrl, useBrand } from "@/g8/hooks/use-brand";
 
 export interface IntegrationListProps {
   /** Where "Connect" sends the person. Default: graph8 Settings > Integrations. */
   connectUrl?: string;
   /** Called when the person opens a CRM's sync panel (render SyncStatus for it). */
   onOpenSync?: (provider: CrmProvider) => void;
+  /** Called when a person opens any CRM, connected or not (show a CrmDetail). */
+  onSelectCrm?: (provider: CrmProvider) => void;
   className?: string;
 }
 
@@ -51,7 +54,7 @@ const CHAT_TOOLS = [
 
 function Pill({ on, label }: { on: boolean; label?: string }) {
   return (
-    <span className={`rounded px-2 py-0.5 text-xs font-medium ${on ? "bg-green-100 text-green-800" : "bg-gray-100 text-gray-700"}`}>
+    <span className={`rounded px-2 py-0.5 text-xs font-medium ${on ? "bg-positive text-positive-foreground" : "bg-muted text-foreground"}`}>
       {label ?? (on ? "Connected" : "Not connected")}
     </span>
   );
@@ -67,7 +70,7 @@ function ChatTools() {
   }, []);
   if (state.loading && !state.data) return <Skeleton className="h-10 w-full" />;
   return (
-    <ul className="divide-y rounded border border-gray-200" aria-label="Workspace tools">
+    <ul className="divide-y rounded border border-border" aria-label="Workspace tools">
       {(state.data ?? []).map((t) => (
         <li key={t.key} className="flex items-center justify-between px-3 py-2 text-sm">
           <span>{t.label}</span>
@@ -78,7 +81,9 @@ function ChatTools() {
   );
 }
 
-export function IntegrationList({ connectUrl = GRAPH8_APP_INTEGRATIONS_URL, onOpenSync, className }: IntegrationListProps) {
+export function IntegrationList({ connectUrl: connectUrlProp, onOpenSync, onSelectCrm, className }: IntegrationListProps) {
+  const brand = useBrand();
+  const connectUrl = connectUrlProp ?? brandUrl(brand, GRAPH8_APP_INTEGRATIONS_PATH);
   const [disconnecting, setDisconnecting] = useState<{ provider: CrmProvider; connection: ConnectionRow } | null>(null);
   const syncs = useG8Query((signal) => g8Get("/crm-syncs", undefined, { signal }), []);
   const connections = useG8Query((signal) => g8Get("/integrations/connections", undefined, { signal }), []);
@@ -105,7 +110,7 @@ export function IntegrationList({ connectUrl = GRAPH8_APP_INTEGRATIONS_URL, onOp
 
   return (
     <div className={`space-y-4 ${className ?? ""}`}>
-      <ul className="divide-y rounded border border-gray-200" aria-label="CRM integrations">
+      <ul className="divide-y rounded border border-border" aria-label="CRM integrations">
         {CRM_PROVIDERS.map((p) => {
           const row = byProvider(p);
           const connected = Boolean(row && CONNECTED_STATES.includes(row.status?.toLowerCase()));
@@ -113,8 +118,8 @@ export function IntegrationList({ connectUrl = GRAPH8_APP_INTEGRATIONS_URL, onOp
           return (
             <li key={p} className="flex flex-wrap items-center justify-between gap-2 px-3 py-3" data-provider={p}>
               <div>
-                <div className="font-medium">{PROVIDER_LABELS[p]}</div>
-                <div className="text-xs text-gray-500">
+                {onSelectCrm ? <button type="button" className="font-medium hover:underline" onClick={() => onSelectCrm(p)}>{PROVIDER_LABELS[p]}</button> : <div className="font-medium">{PROVIDER_LABELS[p]}</div>}
+                <div className="text-xs text-muted-foreground">
                   {connected ? `Last sync: ${formatWhen(row?.last_sync_at)}` : "Connect to sync contacts and companies."}
                 </div>
               </div>
@@ -137,7 +142,7 @@ export function IntegrationList({ connectUrl = GRAPH8_APP_INTEGRATIONS_URL, onOp
                 ) : (
                   <Button size="sm" asChild>
                     <a href={connectUrl} target="_blank" rel="noreferrer">
-                      Connect in graph8
+                      Connect in {brand.linkLabel}
                     </a>
                   </Button>
                 )}

package/blocks/integrations/components/integrations-screen.tsx

@@ -0,0 +1,152 @@
+"use client";
+
+/**
+ * IntegrationsScreen: the finished integrations settings page. Two tabs:
+ *   Connections  the five CRMs and the workspace tools with their status (IntegrationList). Every CRM, connected or not, opens its
+ *                complete detail screen (CrmDetail: connection, push/pull switches, job progress, manual push, disconnect; `?id=hubspot`).
+ *                "Connect in graph8" links out: the OAuth consent screen only runs in the graph8 app.
+ *   Webhooks     create webhooks (WebhookManager); each opens its complete detail screen (WebhookDetail: every field, edit, deliveries,
+ *                pause, rotate secret, delete; `?id=`). Every detail also opens as a full page with `?view=full`.
+ *
+ *   Tools      Slack, Google Workspace and Roam with live status, a connect link-out for each that is not connected, a Google connection
+ *              test and a Drive folder browser (WorkspaceTools).
+ *   Ad accounts  the ad platforms graph8 can sync audiences to, which are connected, their accounts, and a warning for any the platform
+ *              has paused (AdAccounts).
+ * A connected CRM's detail also has Health, Sync now, CRM records, Fields and Historic import tabs (see CrmDetail).
+ *
+ * SDK operations: two reads for the stat strip (GET /crm-syncs, GET /webhooks). Composes IntegrationList (read +
+ * destructive, confirmed), SyncStatus and SyncTriggers (external, confirmed), WebhookManager (external + destructive, confirmed),
+ * WorkspaceTools and AdAccounts (reads).
+ * Prerequisites: a CRM connected in the app (where: "app"); a public https route with G8_WEBHOOK_SECRET for webhooks.
+ */
+import type { ReactNode } from "react";
+import { useState } from "react";
+import { Plug } from "lucide-react";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import type { StatItem } from "@/g8/components/screen/stat-strip";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { arrayOf, CRM_PROVIDERS, GRAPH8_APP_INTEGRATIONS_PATH, PROVIDER_LABELS } from "../lib/integrations-utils";
+import type { CrmProvider, CrmSyncRow } from "../lib/integrations-utils";
+import { AdAccounts } from "./ad-accounts";
+import { IntegrationList } from "./integration-list";
+import { WorkspaceTools } from "./workspace-tools";
+import { CrmDetail } from "./crm-detail";
+import { WebhookDetail } from "./webhook-detail";
+import { WebhookManager } from "./webhook-manager";
+import { brandUrl, useBrand } from "@/g8/hooks/use-brand";
+
+export interface IntegrationsScreenProps {
+  /** Where "Connect" sends people. Default: graph8 Settings > Integrations. */
+  connectUrl?: string;
+  /** Pre-fill the webhook endpoint URL (your /api/webhooks/graph8 route). */
+  defaultWebhookUrl?: string;
+  /** Contact records (in the CRM's field names) offered for a manual push in the sync panel. */
+  pushRecords?: ReadonlyArray<Record<string, unknown>>;
+  toolbarActions?: ReactNode;
+  /** Buttons added to the open record's header: a CRM connection or a webhook. */
+  renderDetailActions?: (record: IntegrationRecord) => ReactNode;
+  /** Tabs added after the built-in ones on the open record. */
+  extraDetailTabs?: { id: string; label: string; render: (record: IntegrationRecord) => ReactNode }[];
+  className?: string;
+}
+
+/** The record open in the detail panel, passed to the slot props. */
+export type IntegrationRecord = { kind: "crm"; provider: CrmProvider } | { kind: "webhook"; id: string };
+
+const CONNECTED = ["connected", "active", "ok", "healthy", "syncing", "synced", "enabled", "linked"];
+
+function useStats(): StatItem[] | undefined {
+  const syncs = useG8Query((signal) => g8Get("/crm-syncs", undefined, { signal }), []);
+  const hooks = useG8Query((signal) => g8Get("/webhooks", undefined, { signal }), []);
+  if (syncs.error) return undefined;
+  const rows = arrayOf<CrmSyncRow>(syncs.data);
+  const connected = rows.filter((r) => CONNECTED.includes(r.status?.toLowerCase())).length;
+  const items: StatItem[] = [
+    { label: "CRMs connected", value: `${connected} of ${CRM_PROVIDERS.length}`, tone: connected ? "positive" : "neutral" },
+  ];
+  if (!hooks.error && hooks.data) items.push({ label: "Webhooks", value: arrayOf<unknown>(hooks.data).length });
+  return syncs.data ? items : undefined;
+}
+
+export function IntegrationsScreen(props: IntegrationsScreenProps) {
+  const brand = useBrand();
+  const connectUrl = props.connectUrl ?? brandUrl(brand, GRAPH8_APP_INTEGRATIONS_PATH);
+  const [tabValue, setTab] = useUrlState("tab", "connections");
+  const tab = ["webhooks", "tools", "ads"].includes(tabValue) ? tabValue : "connections";
+  const [id, setId] = useUrlState("id", "");
+  const [view, setView] = useUrlState("view", "");
+  const [, setMigration] = useUrlState("migration", "");
+  const expanded = view === "full" && Boolean(id);
+  const [tick, setTick] = useState(0);
+  const stats = useStats();
+  const close = () => {
+    setMigration("");
+    setId("");
+    setView("");
+  };
+  const panel = {
+    onClose: close,
+    onExpand: expanded ? undefined : () => setView("full"),
+    onCollapse: expanded ? () => setView("") : undefined,
+    onChanged: () => setTick((t) => t + 1),
+  };
+  const provider = (CRM_PROVIDERS as readonly string[]).includes(id) ? (id as CrmProvider) : null;
+  const slots = (record: IntegrationRecord) => ({
+    extraActions: props.renderDetailActions?.(record),
+    extraTabs: (props.extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(record) })),
+  });
+  const split = (list: ReactNode, detail: ReactNode, open: boolean) => (
+    <SplitView detailOpen={open} onCloseDetail={close} expanded={expanded} onExpandedChange={(next) => setView(next ? "full" : "")} detailWidth="lg" list={list} detail={open ? detail : null} />
+  );
+
+  return (
+    <ScreenLayout
+      title="Integrations"
+      description={`Connect your CRM, keep it in sync, and send ${brand.linkLabel} events to your own systems.`}
+      icon={<Plug className="size-5" />}
+      actions={props.toolbarActions}
+      tabs={[
+        { id: "connections", label: "Connections" },
+        { id: "webhooks", label: "Webhooks" },
+        { id: "tools", label: "Tools" },
+        { id: "ads", label: "Ad accounts" },
+      ]}
+      activeTab={tab}
+      onTabChange={(next) => {
+        setTab(next);
+        close();
+      }}
+      stats={stats}
+      className={props.className}
+    >
+      {tab === "connections" ? (
+        <div className="space-y-4">
+          <SectionCard title="Connecting an account" description={`Sign-in with your CRM happens in ${brand.linkLabel}. Connect there, then manage the sync here.`}>
+            <a className="text-sm underline" href={connectUrl} target="_blank" rel="noreferrer">
+              Connect in {brand.linkLabel}
+            </a>
+          </SectionCard>
+          {split(
+            <IntegrationList key={tick} connectUrl={connectUrl} onSelectCrm={(p) => { setMigration(""); setId(p); }} onOpenSync={(p) => { setMigration(""); setId(p); }} />,
+            provider ? <CrmDetail key={provider} provider={provider} connectUrl={connectUrl} records={props.pushRecords} {...panel} {...slots({ kind: "crm", provider })} /> : null,
+            provider != null,
+          )}
+        </div>
+      ) : tab === "tools" ? (
+        <WorkspaceTools connectUrl={connectUrl} />
+      ) : tab === "ads" ? (
+        <AdAccounts connectUrl={connectUrl} />
+      ) : (
+        split(
+          <WebhookManager key={tick} defaultUrl={props.defaultWebhookUrl} onSelectWebhook={(h) => setId(h.id)} />,
+          <WebhookDetail key={id} webhookId={id} {...panel} {...slots({ kind: "webhook", id })} />,
+          Boolean(id),
+        )
+      )}
+    </ScreenLayout>
+  );
+}

package/blocks/integrations/components/migration-panel.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+/**
+ * MigrationPanel: bring a CRM's history into graph8, and keep it current afterwards. Three steps for a connected CRM:
+ *   1. Scan   look at the CRM and count what is there (nothing is imported yet).
+ *   2. Review the counts per kind of record, the warnings, then Import (or Cancel). Importing copies the CRM's records into graph8.
+ *   3. Later  "Sync changes" brings in only what changed in the CRM since the last import.
+ * Progress is polled until the run reaches a resting state (waiting for you, finished, failed or cancelled). The last completed import,
+ * if any, is shown first. Scanning and importing change data and read a lot from the CRM, so each goes through ConfirmSpendDialog
+ * (external); cancelling a run is destructive and confirmed. Salesforce record owners that are not in the workspace need a decision or the API
+ * refuses the confirm, so each unmatched owner is sent as an "unassigned" decision (their records are imported without an owner; nothing is
+ * invited or reassigned from here). Choosing something else per owner is done in the app.
+ *
+ * SDK operations, in order:
+ *   1. getLastCompletedMigration  GET  /integrations/connections/{connection_id}/last-migration   (read)
+ *   2. startMigrationDiscovery    POST /integrations/migrations/discovery { connection_id, crm_type }   (external, confirmed)
+ *   3. getMigrationStatus         GET  /integrations/migrations/{migration_id}                     (read, polled)
+ *   4. confirmMigration           POST /integrations/migrations/{migration_id}/confirm {}          (external, confirmed)
+ *   5. cancelMigration            POST /integrations/migrations/{migration_id}/cancel              (destructive, confirmed)
+ *   6. startDeltaSync             POST /integrations/migrations/delta-sync { connection_id, recover_missing: false }   (external, confirmed)
+ * The id of a started run is kept in the page's address (?migration=), so reloading does not lose a run that is still going.
+ */
+import { useEffect, useRef, useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { FactList } from "../lib/facts";
+import { crmType, PROVIDER_LABELS } from "../lib/integrations-utils";
+import { useBrand } from "@/g8/hooks/use-brand";
+import type { CrmProvider } from "../lib/integrations-utils";
+
+export interface MigrationPanelProps {
+  connectionId: string;
+  provider: CrmProvider;
+  className?: string;
+}
+
+interface Migration { migration_id?: string; status: string; phase?: string | null; overall_percent?: number; eta_seconds?: number | null; entities?: Record<string, Record<string, unknown> | number>; warnings?: Array<{ message?: string; code?: string }>; errors?: Array<{ message?: string; code?: string }>; owners?: Array<{ sf_user_id?: string; match?: { status?: string } }> }
+type Ask = "scan" | "import" | "cancel" | "delta";
+const REST = ["awaiting_confirmation", "paused", "completed", "failed", "cancelled"];
+const enc = encodeURIComponent;
+const text = (w: { message?: string; code?: string }): string => w.message ?? w.code ?? "See the app for details.";
+
+/**
+ * Salesforce owners who are not in graph8 and have no match need a decision or the confirm is refused (422). The default keeps the import
+ * unattended and reversible: their records are imported unassigned (the "unassigned" action). Nothing is invited or reassigned from here.
+ */
+export function ownerDecisions(owners: Migration["owners"]): Array<{ sf_user_id: string; action: "unassigned" }> {
+  return (owners ?? []).filter((o) => o.sf_user_id && o.match?.status === "unmatched").map((o) => ({ sf_user_id: o.sf_user_id as string, action: "unassigned" as const }));
+}
+
+export function MigrationPanel({ connectionId, provider, className }: MigrationPanelProps) {
+  const brand = useBrand();
+  const label = PROVIDER_LABELS[provider];
+  const [id, setId] = useUrlState("migration", "");
+  const [ask, setAsk] = useState<Ask | null>(null);
+  // A run belongs to the connection it was started for: switching connection drops it (and its URL id) so it can never be confirmed under another CRM.
+  const first = useRef(true);
+  useEffect(() => { setAsk(null); if (first.current) { first.current = false; return; } setId(""); }, [connectionId]); // eslint-disable-line react-hooks/exhaustive-deps
+  const last = useG8Query((signal) => g8Get(`/integrations/connections/${enc(connectionId)}/last-migration`, undefined, { signal }), [connectionId]);
+  const poll = useJobPoll<Migration>(async (signal) => (await g8Get<Migration>(`/integrations/migrations/${enc(id)}`, undefined, { signal })).data, { isTerminal: (m) => REST.includes(String(m.status).toLowerCase()), enabled: Boolean(id), intervalMs: 3000, maxIntervalMs: 15000 });
+  useEffect(() => { if (id) poll.start(); }, [id]); // eslint-disable-line react-hooks/exhaustive-deps
+  const m = poll.status;
+  const status = String(m?.status ?? "").toLowerCase();
+
+  const started = (res: { data?: { migration_id?: string; id?: string } }) => { const next = res.data?.migration_id ?? res.data?.id; if (next) setId(next); setAsk(null); };
+  const scan = useG8Mutation(() => g8Post<{ migration_id?: string }>("/integrations/migrations/discovery", { connection_id: connectionId, crm_type: crmType(provider) }), { onSuccess: started, onError: () => setAsk(null) });
+  const delta = useG8Mutation(() => g8Post<{ migration_id?: string }>("/integrations/migrations/delta-sync", { connection_id: connectionId, recover_missing: false }), { onSuccess: started, onError: () => setAsk(null) });
+  const confirm = useG8Mutation(() => g8Post(`/integrations/migrations/${enc(id)}/confirm`, decisions.length ? { owner_decisions: decisions } : {}), { onSuccess: () => { setAsk(null); poll.start(); }, onError: () => setAsk(null) });
+  const cancel = useG8Mutation(() => g8Post(`/integrations/migrations/${enc(id)}/cancel`, {}), { onSuccess: () => { setAsk(null); poll.start(); }, onError: () => setAsk(null) });
+  const busy = ask === "scan" ? scan.loading : ask === "import" ? confirm.loading : ask === "cancel" ? cancel.loading : delta.loading;
+  const lastRun = ((last.data as { data?: { migration?: Record<string, unknown> | null } } | undefined)?.data?.migration) ?? null;
+  const entities = Object.entries(m?.entities ?? {});
+  const decisions = ownerDecisions(m?.owners);
+
+  const COPY: Record<Ask, { tier: "external" | "destructive"; title: string; description: string; confirm: string }> = {
+    scan: { tier: "external", title: `Scan ${label}`, description: `${brand.name} reads ${label} to count what it holds. Nothing is imported until you confirm the import.`, confirm: "Scan" },
+    import: { tier: "external", title: `Import from ${label}`, description: `Copies the ${label} records counted below into ${brand.name} and can take a long time.${decisions.length ? ` ${decisions.length} record owner${decisions.length === 1 ? " is" : "s are"} not in ${brand.name}; their records are imported unassigned.` : ""}`, confirm: "Import" },
+    cancel: { tier: "destructive", title: "Cancel this import", description: `The run stops where it is. Records already copied stay in ${brand.name}.`, confirm: "Cancel import" },
+    delta: { tier: "external", title: `Sync changes from ${label}`, description: `Brings in only the records that changed in ${label} since the last import.`, confirm: "Sync changes" },
+  };
+  const c = ask ? COPY[ask] : null;
+  const run = () => void (ask === "scan" ? scan : ask === "import" ? confirm : ask === "cancel" ? cancel : delta).mutate(undefined);
+
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <SectionCard title="Last completed import" actions={<Button size="sm" variant="ghost" onClick={() => void last.refetch()}>Recheck</Button>}>
+        {last.error ? <ApiError error={last.error} title="Could not check the last import" onRetry={() => void last.refetch()} /> : null}
+        {last.loading && !last.data ? <Skeleton className="h-8 w-full" /> : null}
+        {last.data && !last.error ? (lastRun ? <FactList data={lastRun} /> : <p className="text-sm text-muted-foreground">No import has completed for this connection.</p>) : null}
+      </SectionCard>
+      <div className="flex flex-wrap gap-2">
+        <Button onClick={() => setAsk("scan")}>Scan {label}</Button>
+        <Button variant="outline" onClick={() => setAsk("delta")}>Sync changes</Button>
+      </div>
+      {scan.error ? <ApiError error={scan.error} title="Could not start the scan" /> : null}
+      {delta.error ? <ApiError error={delta.error} title="Could not start the sync" /> : null}
+      {id ? (
+        <SectionCard title="Current run" description={id} actions={<Button size="sm" variant="ghost" onClick={() => setId("")}>Hide</Button>}>
+          {poll.error && !m ? <ApiError error={poll.error} title="Could not read the run" onRetry={() => poll.start()} /> : null}
+          {!m && !poll.error ? <Skeleton className="h-12 w-full" aria-label="Loading run" /> : null}
+          {m ? (
+            <div className="flex flex-col gap-3">
+              <div className="flex flex-wrap items-center gap-2">
+                <StatusPill tone={toneForStatus(status)} dot>{status.replace(/_/g, " ")}</StatusPill>
+                {m.phase ? <span className="text-xs text-muted-foreground">{String(m.phase).replace(/_/g, " ")}</span> : null}
+                {typeof m.overall_percent === "number" ? <span className="text-xs text-muted-foreground">{Math.round(m.overall_percent)}%</span> : null}
+                {poll.polling ? <span className="text-xs text-muted-foreground">updating</span> : null}
+              </div>
+              {entities.length ? <ul className="divide-y rounded-md border text-sm" aria-label="Records found">{entities.map(([k, v]) => <li key={k} className="flex justify-between px-3 py-1.5"><span>{k.replace(/_/g, " ")}</span><span className="text-muted-foreground">{typeof v === "number" ? v.toLocaleString() : Object.entries(v).filter(([, x]) => typeof x === "number").map(([n, x]) => `${n.replace(/_/g, " ")} ${(x as number).toLocaleString()}`).join(", ")}</span></li>)}</ul> : null}
+              {(m.warnings ?? []).map((w, i) => <p key={i} role="status" className="rounded-md border border-warning-foreground/25 bg-warning p-2 text-sm text-warning-foreground">{text(w)}</p>)}
+              {(m.errors ?? []).map((e, i) => <p key={i} role="alert" className="text-sm text-error-foreground">{text(e)}</p>)}
+              <div className="flex gap-2">
+                {status === "awaiting_confirmation" ? <Button onClick={() => setAsk("import")}>Import</Button> : null}
+                {!["completed", "failed", "cancelled"].includes(status) ? <Button variant="ghost" onClick={() => setAsk("cancel")}>Cancel</Button> : null}
+              </div>
+              {confirm.error ? <ApiError error={confirm.error} title="Could not start the import" /> : null}
+              {cancel.error ? <ApiError error={cancel.error} title="Could not cancel the run" /> : null}
+            </div>
+          ) : null}
+        </SectionCard>
+      ) : null}
+      <ConfirmSpendDialog open={c != null} tier={c?.tier ?? "external"} title={c?.title ?? ""} description={c?.description} confirmLabel={c?.confirm} confirming={busy} onConfirm={run} onCancel={() => setAsk(null)} />
+    </div>
+  );
+}