@graph8/sdk 0.308.1 → 0.357.0

package/blocks/integrations/README.md

@@ -0,0 +1,75 @@
+# integrations
+
+Show which CRMs and workspace tools are connected, keep a CRM in sync, and manage signed webhooks. The
+Apollo / Salesforce "integrations" settings screen.
+
+Depends on: `foundation`. Install: `npx @graph8/sdk add integrations`.
+
+## Components
+
+| Component | What it does | Tiers |
+|---|---|---|
+| `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 |
+
+`external` and `destructive` actions open `ConfirmSpendDialog` first (they write to the customer's CRM,
+change where data is sent, or remove a subscription).
+
+## The flow, in order
+
+1. **Connect a CRM (the human).** OAuth consent runs only in the graph8 app. `IntegrationList` links there
+   (`connectUrl`). The agent cannot do this step.
+2. **Read status.** `IntegrationList` -> `listCrmSyncs` (provider, status, last sync) and `listConnections`
+   (each connection's `connection_id` and `provider_config_key`, needed to disconnect).
+3. **Open a CRM.** `SyncStatus provider="hubspot"` -> `getCrmStatus` returns `connection_id`.
+4. **Switch syncing.** `setPushSyncEnabled` / `setPullSyncEnabled` with that `connection_id` (confirmed). The
+   response's `job_id` feeds `getSyncJob`, polled until the job ends (no streams).
+5. **Push on demand.** `pushContactsToCrm` with `records` in the provider's field names (`getCrmFields`
+   lists them). The result gives `pushed_count`, `failed_count` and per-record `errors`.
+6. **Webhooks.** `WebhookManager` -> `listWebhookEvents` -> `createWebhook` (confirmed). Store the returned
+   secret as `G8_WEBHOOK_SECRET`. Receive with `recipes/verify-webhook-route.ts`.
+
+## Verifying webhooks (server side only)
+
+Deliveries carry `X-Studio-Signature` and `X-Studio-Timestamp`. On the server call
+`g8.webhooks.constructEvent(rawBody, signature, timestamp, process.env.G8_WEBHOOK_SECRET, { toleranceSeconds: 300 })`
+BEFORE parsing or trusting the body; it throws on a bad signature or a stale timestamp. The secret must never
+reach the browser, which is why `WebhookManager` only displays it once at creation or rotation.
+
+## Prerequisites
+
+- 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"`).
+
+## Defaults (do not ask the human)
+
+- Connect link: `https://app.graph8.com/studio/settings?tab=integrations`. Tolerance: 300 s.
+- **Ask the human**: which events to subscribe to, and the endpoint URL.
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| `list_crm_syncs_crm_syncs_get` | GET /crm-syncs | read | IntegrationList |
+| `list_connections_integrations_connections_get` | GET /integrations/connections | read | IntegrationList |
+| `get_slack_status_integrations_slack_status_get` | GET /integrations/slack/status | read | IntegrationList |
+| `get_google_workspace_status_integrations_google_workspace_get` | GET /integrations/google-workspace | read | IntegrationList |
+| `get_roam_status_integrations_roam_status_get` | GET /integrations/roam/status | read | IntegrationList |
+| `delete_connection_integrations_connections__connection_id__delete` | DELETE /integrations/connections/{connection_id} | destructive | IntegrationList |
+| `get_crm_status_crm_syncs__provider__status_get` | GET /crm-syncs/{provider}/status | read | SyncStatus |
+| `get_crm_fields_crm_syncs__provider__fields_get` | GET /crm-syncs/{provider}/fields | read | SyncStatus |
+| `set_push_sync_enabled_integrations_crm_sync_push_enabled_put` | PUT /integrations/crm-sync/push-enabled | external | SyncStatus |
+| `set_pull_sync_enabled_integrations_crm_sync_pull_enabled_put` | PUT /integrations/crm-sync/pull-enabled | external | SyncStatus |
+| `get_sync_job_integrations_crm_sync_jobs__job_id__get` | GET /integrations/crm-sync/jobs/{job_id} | read | SyncStatus |
+| `push_contacts_to_crm_crm_syncs__provider__contacts_push_post` | POST /crm-syncs/{provider}/contacts/push | external | SyncStatus |
+| `list_webhooks_webhooks_get` | GET /webhooks | read | WebhookManager |
+| `list_webhook_events_webhooks_events_get` | GET /webhooks/events | read | WebhookManager |
+| `create_webhook_webhooks_post` | POST /webhooks | external | WebhookManager |
+| `update_webhook_webhooks__webhook_id__patch` | PATCH /webhooks/{webhook_id} | external | WebhookManager |
+| `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 |
+
+Recipes (`recipes/`): `verify-webhook-route.ts`, `register-webhook.ts`, `crm-sync-health.ts`, `push-contacts-to-crm.ts`.

package/blocks/integrations/block.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "integrations",
+  "title": "Integrations & webhooks",
+  "summary": "Show CRM, Slack and Google connections, run CRM syncs, and manage signed webhooks.",
+  "features": [
+    "integration status list with connect and disconnect",
+    "CRM sync health, continuous push and pull, manual push",
+    "webhook subscriptions with secret reveal, rotation and delivery log"
+  ],
+  "dependsOn": [
+    "foundation"
+  ],
+  "operations": [
+    "list_crm_syncs_crm_syncs_get",
+    "list_connections_integrations_connections_get",
+    "get_slack_status_integrations_slack_status_get",
+    "get_google_workspace_status_integrations_google_workspace_get",
+    "get_roam_status_integrations_roam_status_get",
+    "delete_connection_integrations_connections__connection_id__delete",
+    "get_crm_status_crm_syncs__provider__status_get",
+    "get_crm_fields_crm_syncs__provider__fields_get",
+    "set_push_sync_enabled_integrations_crm_sync_push_enabled_put",
+    "set_pull_sync_enabled_integrations_crm_sync_pull_enabled_put",
+    "get_sync_job_integrations_crm_sync_jobs__job_id__get",
+    "push_contacts_to_crm_crm_syncs__provider__contacts_push_post",
+    "list_webhooks_webhooks_get",
+    "list_webhook_events_webhooks_events_get",
+    "create_webhook_webhooks_post",
+    "update_webhook_webhooks__webhook_id__patch",
+    "rotate_webhook_secret_webhooks__webhook_id__rotate_secret_post",
+    "list_webhook_deliveries_webhooks__webhook_id__deliveries_get",
+    "delete_webhook_webhooks__webhook_id__delete"
+  ],
+  "components": [
+    {
+      "name": "IntegrationList",
+      "file": "components/integration-list.tsx",
+      "purpose": "Status of the five CRMs plus Slack, Google Workspace and Roam; connect links to the app; disconnect is confirmed.",
+      "operations": [
+        "list_crm_syncs_crm_syncs_get",
+        "list_connections_integrations_connections_get",
+        "get_slack_status_integrations_slack_status_get",
+        "get_google_workspace_status_integrations_google_workspace_get",
+        "get_roam_status_integrations_roam_status_get",
+        "delete_connection_integrations_connections__connection_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "destructive"
+      ]
+    },
+    {
+      "name": "SyncStatus",
+      "file": "components/sync-status.tsx",
+      "purpose": "One CRM's health, continuous push/pull switches, job progress and a manual contact push. Writes are confirmed.",
+      "operations": [
+        "get_crm_status_crm_syncs__provider__status_get",
+        "get_crm_fields_crm_syncs__provider__fields_get",
+        "set_push_sync_enabled_integrations_crm_sync_push_enabled_put",
+        "set_pull_sync_enabled_integrations_crm_sync_pull_enabled_put",
+        "get_sync_job_integrations_crm_sync_jobs__job_id__get",
+        "push_contacts_to_crm_crm_syncs__provider__contacts_push_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "WebhookManager",
+      "file": "components/webhook-manager.tsx",
+      "purpose": "Create, pause, rotate and delete webhook subscriptions, show the secret once, and browse deliveries.",
+      "operations": [
+        "list_webhooks_webhooks_get",
+        "list_webhook_events_webhooks_events_get",
+        "create_webhook_webhooks_post",
+        "update_webhook_webhooks__webhook_id__patch",
+        "rotate_webhook_secret_webhooks__webhook_id__rotate_secret_post",
+        "list_webhook_deliveries_webhooks__webhook_id__deliveries_get",
+        "delete_webhook_webhooks__webhook_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/integrations-utils.ts",
+      "purpose": "CRM provider list and labels, status types and envelope helpers shared by the integrations components."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/verify-webhook-route.ts",
+      "title": "Receive graph8 webhooks in a Next.js route and verify the signature",
+      "when": "After a webhook subscription exists; verification is server-side only."
+    },
+    {
+      "file": "recipes/register-webhook.ts",
+      "title": "Subscribe a URL to graph8 events",
+      "when": "Wiring a server to graph8 (external tier: get approval)."
+    },
+    {
+      "file": "recipes/crm-sync-health.ts",
+      "title": "Check every CRM connection is healthy",
+      "when": "A scheduled health check or status page."
+    },
+    {
+      "file": "recipes/push-contacts-to-crm.ts",
+      "title": "Push contacts to a connected CRM",
+      "when": "Sending graph8 contacts into a connected CRM (external tier: get approval)."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "crm-oauth-connected",
+      "description": "The CRM (HubSpot, Salesforce, Pipedrive, Zoho or SugarCRM) is connected through the graph8 app's OAuth screen. The API cannot run the consent flow.",
+      "where": "app",
+      "verify": "GET /crm-syncs/{provider}/status returns connected: true."
+    },
+    {
+      "id": "webhook-endpoint",
+      "description": "A public https route in the customer app receives webhooks and verifies them with constructEvent (recipes/verify-webhook-route.ts), with G8_WEBHOOK_SECRET set.",
+      "where": "app",
+      "verify": "A test delivery returns 200 and the route rejects a tampered body with 400."
+    },
+    {
+      "id": "integrations-admin",
+      "description": "The API key's user can manage integrations (disconnect and webhook writes need admin scopes).",
+      "where": "api",
+      "verify": "GET /webhooks returns 200 and POST /webhooks is not 403."
+    }
+  ],
+  "scopes": [
+    "integrations:delete",
+    "integrations:read",
+    "integrations:run",
+    "webhooks:delete",
+    "webhooks:read",
+    "webhooks:run"
+  ],
+  "defaults": [
+    {
+      "decision": "Where Connect sends the person",
+      "default": "https://app.graph8.com/studio/settings?tab=integrations (OAuth only runs in the app)",
+      "askHuman": false
+    },
+    {
+      "decision": "Which events a webhook subscribes to",
+      "default": "None: pick only the events the app handles",
+      "askHuman": true
+    },
+    {
+      "decision": "Webhook endpoint URL",
+      "default": "https://<your-domain>/api/webhooks/graph8",
+      "askHuman": true
+    },
+    {
+      "decision": "Timestamp tolerance when verifying",
+      "default": "300 seconds",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

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

@@ -0,0 +1,165 @@
+"use client";
+
+/**
+ * IntegrationList: every integration the workspace can use and whether it is connected: the five CRMs
+ * graph8 syncs with, plus Slack, Google Workspace and Roam.
+ *
+ * SDK operations, in order:
+ *   1. listCrmSyncs             GET    /crm-syncs                         (read; provider + status per CRM)
+ *   2. listConnections          GET    /integrations/connections          (read; the connection_id to disconnect)
+ *   3. getSlackStatus / getGoogleWorkspaceStatus / getRoamStatus  GET /integrations/...  (read)
+ *   4. deleteConnection         DELETE /integrations/connections/{connection_id}?provider_config_key=
+ *                               (destructive: confirmed with ConfirmSpendDialog first)
+ *
+ * Connecting is NOT done here: an OAuth consent screen can only run in the graph8 app, so "Connect"
+ * links the person to it (`connectUrl`). Disconnecting keeps records already synced.
+ */
+
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { useState } from "react";
+import { g8Delete, g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import {
+  arrayOf,
+  CRM_PROVIDERS,
+  formatWhen,
+  GRAPH8_APP_INTEGRATIONS_URL,
+  looksConnected,
+  PROVIDER_LABELS,
+} from "../lib/integrations-utils";
+import type { ConnectionRow, CrmProvider, CrmSyncRow } from "../lib/integrations-utils";
+
+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;
+  className?: string;
+}
+
+/** Only these mean "working". Anything else (not_connected, inactive, pending, error...) is not connected. */
+const CONNECTED_STATES = ["connected", "active", "ok", "healthy", "syncing", "synced", "enabled", "linked"];
+
+const CHAT_TOOLS = [
+  { key: "slack", label: "Slack", path: "/integrations/slack/status" },
+  { key: "google", label: "Google Workspace", path: "/integrations/google-workspace" },
+  { key: "roam", label: "Roam", path: "/integrations/roam/status" },
+] as const;
+
+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"}`}>
+      {label ?? (on ? "Connected" : "Not connected")}
+    </span>
+  );
+}
+
+function ChatTools() {
+  const state = useG8Query(async (signal) => {
+    const results = await Promise.allSettled(CHAT_TOOLS.map((t) => g8Get(t.path, undefined, { signal })));
+    return CHAT_TOOLS.map((t, i) => ({
+      ...t,
+      connected: results[i].status === "fulfilled" && looksConnected((results[i] as PromiseFulfilledResult<unknown>).value),
+    }));
+  }, []);
+  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">
+      {(state.data ?? []).map((t) => (
+        <li key={t.key} className="flex items-center justify-between px-3 py-2 text-sm">
+          <span>{t.label}</span>
+          <Pill on={t.connected} />
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export function IntegrationList({ connectUrl = GRAPH8_APP_INTEGRATIONS_URL, onOpenSync, className }: IntegrationListProps) {
+  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 }), []);
+  const remove = useG8Mutation(async (c: ConnectionRow) => {
+    await g8Delete(`/integrations/connections/${c.connection_id}`, { query: { provider_config_key: c.provider_config_key } });
+    await Promise.all([syncs.refetch(), connections.refetch()]);
+  });
+
+  const rows = arrayOf<CrmSyncRow>(syncs.data);
+  const conns = arrayOf<ConnectionRow>(connections.data);
+  const byProvider = (p: CrmProvider) => rows.find((r) => r.provider?.toLowerCase() === p);
+  // Exact provider match only. When there is more than one connection for a provider we cannot know which one
+  // the person means, so Disconnect is withheld and they are sent to the app.
+  const connectionsFor = (p: CrmProvider) =>
+    conns.filter((c) => (c.provider ?? "").toLowerCase() === p || (c.provider_config_key ?? "").toLowerCase().split(/[-_]/)[0] === p);
+  const connectionFor = (p: CrmProvider) => {
+    const all = connectionsFor(p);
+    const wanted = byProvider(p)?.connection_id;
+    return all.find((c) => wanted && c.connection_id === wanted) ?? (all.length === 1 ? all[0] : undefined);
+  };
+
+  if (syncs.error) return <ApiError error={syncs.error} onRetry={() => void syncs.refetch()} className={className} />;
+  if (syncs.loading && !syncs.data) return <Skeleton className={`h-40 w-full ${className ?? ""}`} />;
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`}>
+      <ul className="divide-y rounded border border-gray-200" aria-label="CRM integrations">
+        {CRM_PROVIDERS.map((p) => {
+          const row = byProvider(p);
+          const connected = Boolean(row && CONNECTED_STATES.includes(row.status?.toLowerCase()));
+          const connection = connectionFor(p);
+          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">
+                  {connected ? `Last sync: ${formatWhen(row?.last_sync_at)}` : "Connect to sync contacts and companies."}
+                </div>
+              </div>
+              <div className="flex items-center gap-2">
+                <Pill on={connected} label={row?.status && !connected ? row.status : undefined} />
+                {connected ? (
+                  <>
+                    <Button size="sm" variant="outline" onClick={() => onOpenSync?.(p)}>
+                      Manage sync
+                    </Button>
+                    <Button
+                      size="sm"
+                      variant="ghost"
+                      disabled={!connection?.connection_id || !connection.provider_config_key}
+                      onClick={() => connection && setDisconnecting({ provider: p, connection })}
+                    >
+                      Disconnect
+                    </Button>
+                  </>
+                ) : (
+                  <Button size="sm" asChild>
+                    <a href={connectUrl} target="_blank" rel="noreferrer">
+                      Connect in graph8
+                    </a>
+                  </Button>
+                )}
+              </div>
+            </li>
+          );
+        })}
+      </ul>
+      {remove.error ? <ApiError error={remove.error} onRetry={remove.reset} /> : null}
+      <ChatTools />
+      {disconnecting ? (
+        <ConfirmSpendDialog
+          open
+          tier="destructive"
+          title={`Disconnect ${PROVIDER_LABELS[disconnecting.provider]}`}
+          description="Syncs configured against this connection stop working. Records already synced stay."
+          confirmLabel="Disconnect"
+          confirming={remove.loading}
+          onCancel={() => setDisconnecting(null)}
+          onConfirm={() => void remove.mutate(disconnecting.connection).then(() => setDisconnecting(null))}
+        />
+      ) : null}
+    </div>
+  );
+}

package/blocks/integrations/components/sync-status.tsx

@@ -0,0 +1,223 @@
+"use client";
+
+/**
+ * SyncStatus: the health of one CRM connection, its continuous sync switches and a manual push.
+ *
+ * SDK operations, in order:
+ *   1. getCrmStatus          GET /crm-syncs/{provider}/status            (read; connected? connection_id)
+ *   2. getCrmFields          GET /crm-syncs/{provider}/fields?entity_type (read; the CRM's field list)
+ *   3. setPushSyncEnabled    PUT /integrations/crm-sync/push-enabled     (external: confirmed)
+ *      setPullSyncEnabled    PUT /integrations/crm-sync/pull-enabled     (external: confirmed)
+ *   4. getSyncJob            GET /integrations/crm-sync/jobs/{job_id}    (read; polled until the job ends)
+ *   5. pushContactsToCrm     POST /crm-syncs/{provider}/contacts/push    (external: confirmed with the count)
+ *
+ * Tiers: 3 and 5 write to the customer's CRM, so each opens ConfirmSpendDialog first. The `connection_id`
+ * from step 1 feeds step 3; the `job_id` that step 3 returns feeds step 4. The API has no read for the
+ * current on/off state, so the switches are explicit Enable / Disable buttons (idempotent).
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { formatWhen, PROVIDER_LABELS, TERMINAL_JOB_STATES } from "../lib/integrations-utils";
+import type { CrmProvider, CrmStatus } from "../lib/integrations-utils";
+
+export interface SyncStatusProps {
+  provider: CrmProvider;
+  /** Contact records (in the provider's field names) to offer a manual push for. */
+  records?: ReadonlyArray<Record<string, unknown>>;
+  className?: string;
+}
+
+type Direction = "push" | "pull";
+type Pending = { kind: "switch"; direction: Direction; enabled: boolean } | { kind: "push" };
+
+interface JobStatus {
+  job_id?: string | null;
+  status?: string | null;
+}
+
+function JobProgress({ jobId }: { jobId: string }) {
+  const job = useJobPoll<JobStatus>(
+    async (signal) => (await g8Get<JobStatus>(`/integrations/crm-sync/jobs/${jobId}`, undefined, { signal })).data,
+    {
+      isTerminal: (j) => TERMINAL_JOB_STATES.includes(String(j.status ?? "").toLowerCase()),
+    },
+  );
+  return (
+    <p role="status" className="text-sm text-gray-700" data-testid="sync-job">
+      Job {jobId}: {job.status?.status ?? "starting"}
+      {job.polling ? "..." : ""}
+      {job.error ? " (could not read the job status)" : ""}
+    </p>
+  );
+}
+
+export function SyncStatus({ provider, records, className }: SyncStatusProps) {
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [jobId, setJobId] = useState<string | null>(null);
+  const [pushed, setPushed] = useState<string | null>(null);
+  const [showFields, setShowFields] = useState(false);
+  const label = PROVIDER_LABELS[provider];
+  useEffect(() => {
+    // A different CRM is a different context: drop the previous one's job, result and pending confirmation.
+    setJobId(null);
+    setPushed(null);
+    setPending(null);
+    setShowFields(false);
+  }, [provider]);
+
+  // Tag the answer with the provider it was fetched for: useG8Query keeps the previous data while a refetch runs,
+  // and a write must never carry another CRM's connection_id.
+  const statusQuery = useG8Query(
+    async (signal) => ({ provider, res: await g8Get<CrmStatus>(`/crm-syncs/${provider}/status`, undefined, { signal }) }),
+    [provider],
+  );
+  const status = {
+    ...statusQuery,
+    data: statusQuery.data?.provider === provider ? statusQuery.data.res : undefined,
+    refetch: statusQuery.refetch,
+  };
+  const fields = useG8Query(
+    async (signal) =>
+      (
+        await g8Get<{ fields?: Array<{ name?: string; label?: string }> }>(
+          `/crm-syncs/${provider}/fields`,
+          { entity_type: "contact" },
+          { signal },
+        )
+      ).data?.fields ?? [],
+    [provider],
+    { enabled: showFields },
+  );
+  const connectionId = status.data?.data?.connection_id ?? undefined;
+
+  const run = useG8Mutation(async (p: Pending) => {
+    if (p.kind === "switch") {
+      const path = p.direction === "push" ? "/integrations/crm-sync/push-enabled" : "/integrations/crm-sync/pull-enabled";
+      const res = await g8Put<JobStatus>(path, { connection_id: connectionId, enabled: p.enabled });
+      setJobId(res.data?.job_id ?? null);
+    } else {
+      const res = await g8Post<{ pushed_count?: number; failed_count?: number }>(`/crm-syncs/${provider}/contacts/push`, {
+        records: records ?? [],
+      });
+      setPushed(`${res.data?.pushed_count ?? 0} pushed, ${res.data?.failed_count ?? 0} failed`);
+    }
+  });
+
+  if (status.error) return <ApiError error={status.error} onRetry={() => void status.refetch()} className={className} />;
+  if (status.loading && !status.data) return <Skeleton className={`h-32 w-full ${className ?? ""}`} />;
+  const s = status.data?.data;
+  if (!s?.connected) {
+    return (
+      <p role="status" className={`rounded border border-amber-200 bg-amber-50 p-3 text-sm text-amber-900 ${className ?? ""}`}>
+        {label} is not connected. {s?.message ?? "Connect it in graph8, then come back."}
+      </p>
+    );
+  }
+
+  const confirmCopy =
+    pending?.kind === "push"
+      ? {
+          title: `Push ${records?.length ?? 0} contacts to ${label}`,
+          description: "Creates or updates these contacts in your CRM.",
+          label: "Push contacts",
+        }
+      : pending
+        ? {
+            title: `${pending.enabled ? "Turn on" : "Turn off"} continuous ${pending.direction} with ${label}`,
+            description: pending.enabled
+              ? `graph8 will keep ${pending.direction === "push" ? "writing contacts to" : "reading contacts from"} your CRM.`
+              : "Syncing in this direction stops.",
+            label: pending.enabled ? "Turn on" : "Turn off",
+          }
+        : null;
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`}>
+      <div className="flex items-center justify-between">
+        <div>
+          <h3 className="font-medium">{label}</h3>
+          <p className="text-xs text-gray-500">Connected. Last sync: {formatWhen(s.last_sync_at)}</p>
+        </div>
+        <Button size="sm" variant="outline" onClick={() => void status.refetch()}>
+          Recheck
+        </Button>
+      </div>
+
+      {(["push", "pull"] as const).map((direction) => (
+        <div key={direction} className="flex items-center justify-between rounded border border-gray-200 px-3 py-2 text-sm">
+          <span>{direction === "push" ? "Send graph8 contacts to the CRM" : "Bring CRM contacts into graph8"}</span>
+          <span className="flex gap-2">
+            <Button
+              size="sm"
+              variant="outline"
+              disabled={!connectionId || statusQuery.loading}
+              onClick={() => setPending({ kind: "switch", direction, enabled: true })}
+            >
+              Enable {direction}
+            </Button>
+            <Button
+              size="sm"
+              variant="ghost"
+              disabled={!connectionId || statusQuery.loading}
+              onClick={() => setPending({ kind: "switch", direction, enabled: false })}
+            >
+              Disable {direction}
+            </Button>
+          </span>
+        </div>
+      ))}
+
+      {jobId ? <JobProgress key={jobId} jobId={jobId} /> : null}
+      {records && records.length > 0 ? (
+        <Button onClick={() => setPending({ kind: "push" })}>Push {records.length} contacts now</Button>
+      ) : null}
+      {pushed ? (
+        <p role="status" className="text-sm text-green-700">
+          {pushed}
+        </p>
+      ) : null}
+      {run.error ? <ApiError error={run.error} onRetry={run.reset} /> : null}
+
+      <div>
+        <Button size="sm" variant="link" className="px-0" onClick={() => setShowFields((v) => !v)}>
+          {showFields ? "Hide" : "Show"} contact fields
+        </Button>
+        {showFields ? (
+          fields.loading ? (
+            <Skeleton className="h-8 w-full" />
+          ) : fields.error ? (
+            <ApiError error={fields.error} />
+          ) : (
+            <ul className="mt-1 flex flex-wrap gap-1 text-xs">
+              {(fields.data ?? []).map((f, i) => (
+                <li key={i} className="rounded border border-gray-200 px-1.5 py-0.5">
+                  {f.label ?? f.name}
+                </li>
+              ))}
+            </ul>
+          )
+        ) : null}
+      </div>
+
+      {pending && confirmCopy ? (
+        <ConfirmSpendDialog
+          open
+          tier="external"
+          title={confirmCopy.title}
+          description={confirmCopy.description}
+          confirmLabel={confirmCopy.label}
+          confirming={run.loading}
+          onCancel={() => setPending(null)}
+          onConfirm={() => void run.mutate(pending).then(() => setPending(null))}
+        />
+      ) : null}
+    </div>
+  );
+}