@graph8/sdk 0.362.0 → 0.373.0

package/blocks/integrations/components/sugarcrm-connect.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+/**
+ * SugarCrmConnect: connect SugarCRM from here. Unlike HubSpot, Salesforce, Pipedrive and Zoho (whose sign-in screen only runs in the graph8
+ * app, so those link out), SugarCRM signs in with an instance address, a user and a password, which the API can take directly.
+ *   Not connected   the form; Connect signs in and stores the credentials (there is no way to check them before saving).
+ *   Connected       "Check connection" (free, reads the stored login), "Update credentials" (sign in again with new ones), "Remove".
+ * Connecting and updating sign in to your SugarCRM and store the credentials, so they go through ConfirmSpendDialog (external);
+ * removing is destructive and confirmed. The password is sent once through your server's proxy and is cleared from the form afterwards.
+ *
+ * SDK operations, in order:
+ *   1. validateSugarcrm    POST   /integrations/sugarcrm/validate                (read)  checks the stored credentials
+ *   2. connectSugarcrm     POST   /integrations/sugarcrm/connect { instance_url, username, password, client_id?, client_secret? }   (external, confirmed)
+ *   3. reconnectSugarcrm   POST   /integrations/sugarcrm/reconnect { same }       (external, confirmed)
+ *   4. disconnectSugarcrm  DELETE /integrations/sugarcrm                          (destructive, confirmed)
+ */
+import { useState } from "react";
+import { Button, Input, Label } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Delete, g8Post } from "@/g8/lib/g8-client";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface SugarCrmConnectProps {
+  /** Whether SugarCRM is connected now (from the sync list). */
+  connected: boolean;
+  /** After a connect, update or removal. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+interface Form { instance_url: string; username: string; password: string; client_id: string; client_secret: string }
+const BLANK: Form = { instance_url: "", username: "", password: "", client_id: "", client_secret: "" };
+type Ask = "connect" | "reconnect" | "remove";
+
+/** The request body: client id and secret only when typed (the instance's defaults apply otherwise). */
+export function sugarBody(f: Form): Record<string, string> {
+  return { instance_url: f.instance_url.trim().replace(/\/+$/, ""), username: f.username.trim(), password: f.password, ...(f.client_id.trim() ? { client_id: f.client_id.trim() } : {}), ...(f.client_secret ? { client_secret: f.client_secret } : {}) };
+}
+
+export function SugarCrmConnect({ connected, onChanged, className }: SugarCrmConnectProps) {
+  const brand = useBrand();
+  const [f, setF] = useState<Form>(BLANK);
+  const [ask, setAsk] = useState<Ask | null>(null);
+  const [showAdvanced, setShowAdvanced] = useState(false);
+  const [editing, setEditing] = useState(false);
+  const set = (patch: Partial<Form>) => setF((x) => ({ ...x, ...patch }));
+  const valid = /^https?:\/\/\S+$/i.test(f.instance_url.trim()) && f.username.trim() && f.password;
+  const done = () => { setF(BLANK); setAsk(null); setEditing(false); onChanged?.(); };
+
+  const connect = useG8Mutation((kind: "connect" | "reconnect") => g8Post(`/integrations/sugarcrm/${kind}`, sugarBody(f)), { onSuccess: done, onError: () => setAsk(null) });
+  const check = useG8Mutation(() => g8Post("/integrations/sugarcrm/validate", {}));
+  const remove = useG8Mutation(() => g8Delete("/integrations/sugarcrm"), { onSuccess: done, onError: () => setAsk(null) });
+  const verdict = (check.data as { data?: { valid?: boolean; connected?: boolean; message?: string } } | undefined)?.data;
+  const showForm = !connected || editing;
+
+  return (
+    <div className={`flex flex-col gap-3 ${className ?? ""}`}>
+      {connected ? (
+        <div className="flex flex-wrap items-center gap-2">
+          <Button size="sm" variant="outline" loading={check.loading} onClick={() => void check.mutate(undefined)}>Check connection</Button>
+          <Button size="sm" variant="outline" onClick={() => setEditing((v) => !v)}>{editing ? "Close" : "Update credentials"}</Button>
+          <Button size="sm" variant="ghost" onClick={() => setAsk("remove")}>Remove</Button>
+          {check.data !== undefined ? <span role="status" className="text-sm" data-testid="sugar-check">{verdict?.valid === false || verdict?.connected === false ? `Sign-in failed${verdict?.message ? `: ${verdict.message}` : ""}` : "Signed in to SugarCRM."}</span> : null}
+        </div>
+      ) : <p className="text-sm text-muted-foreground">Sign in to your SugarCRM instance to sync contacts, companies and deals.</p>}
+      {check.error ? <ApiError error={check.error} title="Could not check the connection" /> : null}
+      {showForm ? (
+        <form className="flex flex-col gap-3" onSubmit={(e) => { e.preventDefault(); if (valid) setAsk(connected ? "reconnect" : "connect"); }}>
+          <div className="flex flex-col gap-1"><Label htmlFor="sugar-url">Instance address</Label><Input id="sugar-url" type="url" placeholder="https://yourcompany.sugarondemand.com" value={f.instance_url} onChange={(e) => set({ instance_url: e.target.value })} /></div>
+          <div className="grid gap-3 sm:grid-cols-2">
+            <div className="flex flex-col gap-1"><Label htmlFor="sugar-user">User</Label><Input id="sugar-user" autoComplete="off" value={f.username} onChange={(e) => set({ username: e.target.value })} /></div>
+            <div className="flex flex-col gap-1"><Label htmlFor="sugar-pass">Password</Label><Input id="sugar-pass" type="password" autoComplete="new-password" value={f.password} onChange={(e) => set({ password: e.target.value })} /></div>
+          </div>
+          <button type="button" className="self-start text-xs underline" onClick={() => setShowAdvanced((v) => !v)}>{showAdvanced ? "Hide" : "Show"} client credentials</button>
+          {showAdvanced ? (
+            <div className="grid gap-3 sm:grid-cols-2">
+              <div className="flex flex-col gap-1"><Label htmlFor="sugar-cid">Client id (optional)</Label><Input id="sugar-cid" autoComplete="off" value={f.client_id} onChange={(e) => set({ client_id: e.target.value })} /></div>
+              <div className="flex flex-col gap-1"><Label htmlFor="sugar-secret">Client secret (optional)</Label><Input id="sugar-secret" type="password" autoComplete="new-password" value={f.client_secret} onChange={(e) => set({ client_secret: e.target.value })} /></div>
+            </div>
+          ) : null}
+          {connect.error ? <ApiError error={connect.error} title={connected ? "Could not update the credentials" : "Could not connect SugarCRM"} /> : null}
+          <div><Button type="submit" disabled={!valid}>{connected ? "Save credentials" : "Connect SugarCRM"}</Button></div>
+        </form>
+      ) : null}
+      {remove.error ? <ApiError error={remove.error} title="Could not remove the connection" /> : null}
+      <ConfirmSpendDialog open={ask === "connect" || ask === "reconnect"} tier="external" title={ask === "reconnect" ? "Update the SugarCRM credentials" : "Connect SugarCRM"}
+        description={`${brand.name} signs in to ${f.instance_url.trim() || "your instance"} as ${f.username.trim() || "this user"} and stores the credentials to sync on your behalf.`}
+        confirmLabel={ask === "reconnect" ? "Update" : "Connect"} confirming={connect.loading} onConfirm={() => ask && ask !== "remove" && void connect.mutate(ask)} onCancel={() => setAsk(null)} />
+      <ConfirmSpendDialog open={ask === "remove"} tier="destructive" title="Remove the SugarCRM connection" description="Syncs configured against it stop working and the stored credentials are deleted. Records already synced stay."
+        confirmLabel="Remove" confirming={remove.loading} onConfirm={() => void remove.mutate(undefined)} onCancel={() => setAsk(null)} />
+    </div>
+  );
+}

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

@@ -26,6 +26,7 @@ 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";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface SyncStatusProps {
   provider: CrmProvider;
@@ -50,7 +51,7 @@ function JobProgress({ jobId }: { jobId: string }) {
     },
   );
   return (
-    <p role="status" className="text-sm text-gray-700" data-testid="sync-job">
+    <p role="status" className="text-sm text-foreground" data-testid="sync-job">
       Job {jobId}: {job.status?.status ?? "starting"}
       {job.polling ? "..." : ""}
       {job.error ? " (could not read the job status)" : ""}
@@ -59,6 +60,7 @@ function JobProgress({ jobId }: { jobId: string }) {
 }
 
 export function SyncStatus({ provider, records, className }: SyncStatusProps) {
+  const brand = useBrand();
   const [pending, setPending] = useState<Pending | null>(null);
   const [jobId, setJobId] = useState<string | null>(null);
   const [pushed, setPushed] = useState<string | null>(null);
@@ -115,8 +117,8 @@ export function SyncStatus({ provider, records, className }: SyncStatusProps) {
   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 role="status" className={`rounded border border-warning-foreground/25 bg-warning p-3 text-sm text-warning-foreground ${className ?? ""}`}>
+        {label} is not connected. {s?.message ?? `Connect it in ${brand.linkLabel}, then come back.`}
       </p>
     );
   }
@@ -132,7 +134,7 @@ export function SyncStatus({ provider, records, className }: SyncStatusProps) {
         ? {
             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.`
+              ? `${brand.linkLabel} 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",
           }
@@ -143,7 +145,7 @@ export function SyncStatus({ provider, records, className }: SyncStatusProps) {
       <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>
+          <p className="text-xs text-muted-foreground">Connected. Last sync: {formatWhen(s.last_sync_at)}</p>
         </div>
         <Button size="sm" variant="outline" onClick={() => void status.refetch()}>
           Recheck
@@ -151,8 +153,8 @@ export function SyncStatus({ provider, records, className }: SyncStatusProps) {
       </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>
+        <div key={direction} className="flex items-center justify-between rounded border border-border px-3 py-2 text-sm">
+          <span>{direction === "push" ? `Send ${brand.linkLabel} contacts to the CRM` : `Bring CRM contacts into ${brand.linkLabel}`}</span>
           <span className="flex gap-2">
             <Button
               size="sm"
@@ -179,7 +181,7 @@ export function SyncStatus({ provider, records, className }: SyncStatusProps) {
         <Button onClick={() => setPending({ kind: "push" })}>Push {records.length} contacts now</Button>
       ) : null}
       {pushed ? (
-        <p role="status" className="text-sm text-green-700">
+        <p role="status" className="text-sm text-positive-foreground">
           {pushed}
         </p>
       ) : null}
@@ -197,7 +199,7 @@ export function SyncStatus({ provider, records, className }: SyncStatusProps) {
           ) : (
             <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">
+                <li key={i} className="rounded border border-border px-1.5 py-0.5">
                   {f.label ?? f.name}
                 </li>
               ))}

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

@@ -0,0 +1,134 @@
+"use client";
+
+/**
+ * SyncTriggers: run a sync now instead of waiting for the continuous one. For one connected CRM:
+ *   Contacts   send every graph8 contact to the CRM, or bring the CRM's contacts in (optionally only the first N).
+ *   Deals      the same for deals.
+ *   Leads      Salesforce only (the lead routes are Salesforce-specific). Check what a push would send (a free preview), choose which lead
+ *              status qualified and unqualified contacts get, then send leads. A large push needs an explicit acknowledgement of the previewed
+ *              count (large_population_confirmed). Bringing leads in runs the organisation's SAVED lead pull settings (only connection_id and
+ *              an optional limit are sent, so the saved scope is not overridden).
+ * Each sync is a background job: it appears under "Jobs" and is followed (polled) until it ends. Every sync changes data in the CRM
+ * or in graph8 and can touch thousands of records, so each one goes through ConfirmSpendDialog (external) that states its scope.
+ *
+ * SDK operations, in order:
+ *   1. pushAllContacts / pullAllContacts   POST /integrations/crm-sync/contacts/push|pull { connection_id, limit? }     (external, confirmed)
+ *   2. pushAllDeals / pullAllDeals         POST /integrations/crm-sync/deals/push|pull { connection_id, limit? }        (external, confirmed)
+ *   3. listLeadStatuses                    GET  /integrations/crm-sync/leads/statuses?connection_id                      (read)
+ *   4. previewLeadPush                     GET  /integrations/crm-sync/leads/push-preview?connection_id&source_mode&...  (read)
+ *   5. pushAllLeads / pullAllLeads         POST /integrations/crm-sync/leads/push|pull { connection_id, source_mode, ... }   (external, confirmed)
+ *   6. getSyncJob                          GET  /integrations/crm-sync/jobs/{job_id}                                     (read, polled)
+ * Syncing a graph8 list or audience needs a list picker and is started from the Lists screen.
+ */
+import { useEffect, useState } from "react";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { 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 { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { PROVIDER_LABELS, TERMINAL_JOB_STATES } from "../lib/integrations-utils";
+import { useBrand } from "@/g8/hooks/use-brand";
+import type { CrmProvider } from "../lib/integrations-utils";
+
+export interface SyncTriggersProps {
+  connectionId: string;
+  provider: CrmProvider;
+  className?: string;
+}
+
+interface Job { id: string; label: string }
+interface Plan { path: string; label: string; scope: string; body: Record<string, unknown> }
+interface JobStatus { job_id?: string | null; status?: string | null; processed?: number | null; total?: number | null; failed?: number | null }
+
+function JobRow({ job }: { job: Job }) {
+  const poll = useJobPoll<JobStatus>(async (signal) => (await g8Get<JobStatus>(`/integrations/crm-sync/jobs/${encodeURIComponent(job.id)}`, undefined, { signal })).data, { isTerminal: (j) => TERMINAL_JOB_STATES.includes(String(j.status ?? "").toLowerCase()) });
+  const st = String(poll.status?.status ?? "starting");
+  const s = poll.status;
+  return (
+    <li className="flex flex-wrap items-center justify-between gap-2 px-3 py-2 text-sm" data-testid={`job-${job.id}`}>
+      <span>{job.label}<span className="ml-2 text-xs text-muted-foreground">{job.id}</span></span>
+      <span className="flex items-center gap-2">
+        {s?.total ? <span className="text-xs text-muted-foreground">{s.processed ?? 0} of {s.total}{s.failed ? `, ${s.failed} failed` : ""}</span> : null}
+        <StatusPill tone={toneForStatus(st)} dot>{st}</StatusPill>{poll.polling ? <span className="text-xs text-muted-foreground">updating</span> : null}{poll.error ? <span className="text-xs text-error-foreground">could not read the status</span> : null}
+      </span>
+    </li>
+  );
+}
+
+export function SyncTriggers({ connectionId, provider, className }: SyncTriggersProps) {
+  const brand = useBrand();
+  const label = PROVIDER_LABELS[provider];
+  const [bigOk, setBigOk] = useState(false);
+  const [limit, setLimit] = useState("");
+  const [mode, setMode] = useState<"all_qualified" | "all_contacts">("all_qualified");
+  const [qualified, setQualified] = useState("");
+  const [unqualified, setUnqualified] = useState("");
+  const [plan, setPlan] = useState<Plan | null>(null);
+  const [jobs, setJobs] = useState<Job[]>([]);
+  useEffect(() => { setPlan(null); setJobs([]); setLimit(""); setQualified(""); setUnqualified(""); setBigOk(false); }, [connectionId]);
+
+  const statuses = useG8Query((signal) => g8Get("/integrations/crm-sync/leads/statuses", { connection_id: connectionId }, { signal }), [connectionId], { enabled: provider === "salesforce" });
+  const statusRows = (((statuses.data as { data?: { statuses?: Array<string | { value?: string; id?: string; label?: string; name?: string }> } } | undefined)?.data?.statuses) ?? []).map((s) => typeof s === "string" ? { value: s, label: s } : { value: s.value ?? s.id ?? s.name ?? "", label: s.label ?? s.name ?? s.value ?? s.id ?? "" });
+  const previewKey = `${connectionId}|${mode}|${qualified}|${unqualified}`;
+  const [previewed, setPreviewed] = useState("");
+  const preview = useG8Query((signal) => g8Get("/integrations/crm-sync/leads/push-preview", { connection_id: connectionId, source_mode: mode, status_qualified: qualified || undefined, status_unqualified: unqualified || undefined }, { signal }), [previewKey], { enabled: false });
+
+  const n = Number(limit);
+  const limitOk = limit.trim() === "" || (Number.isInteger(n) && n > 0);
+  const cap = limit.trim() ? { limit: n } : {};
+  const scope = limit.trim() ? `up to ${n.toLocaleString()}` : "all";
+  const run = useG8Mutation(async (p: Plan) => {
+    const res = await g8Post<{ job_id?: string | null }>(p.path, p.body);
+    return { id: res.data?.job_id ?? null, label: p.label };
+  }, { onSuccess: (r) => { setPlan(null); if (r.id) setJobs((j) => [{ id: r.id as string, label: r.label }, ...j]); }, onError: () => setPlan(null) });
+
+  const plans = (kind: "contacts" | "deals"): Plan[] => [
+    { path: `/integrations/crm-sync/${kind}/push`, label: `Send ${kind} to ${label}`, scope: `${scope} ${brand.name} ${kind}, created or updated in ${label}`, body: { connection_id: connectionId, ...cap } },
+    { path: `/integrations/crm-sync/${kind}/pull`, label: `Bring ${kind} in from ${label}`, scope: `${scope} ${label} ${kind}, created or updated in ${brand.name}`, body: { connection_id: connectionId, ...cap } },
+  ];
+  const leadPush: Plan = { path: "/integrations/crm-sync/leads/push", label: `Send leads to ${label}`, scope: `${mode === "all_qualified" ? "qualified" : "all"} contacts as leads in ${label}`,
+    body: { connection_id: connectionId, source_mode: mode, ...(qualified ? { status_qualified: qualified } : {}), ...(unqualified ? { status_unqualified: unqualified } : {}), ...(bigOk ? { large_population_confirmed: true } : {}), ...cap } };
+  const leadPull: Plan = { path: "/integrations/crm-sync/leads/pull", label: `Bring leads in from ${label}`, scope: `${scope} ${label} leads (the saved lead pull settings), created or updated in ${brand.name}`, body: { connection_id: connectionId, ...cap } };
+  const pv = ((preview.data as { data?: Record<string, unknown> } | undefined)?.data ?? {}) as Record<string, unknown>;
+  const shown = previewed === previewKey && preview.data !== undefined;
+  const row = (p: Plan) => <Button key={p.path} size="sm" variant="outline" disabled={!limitOk} onClick={() => setPlan(p)}>{p.label}</Button>;
+  return (
+    <div className={`flex flex-col gap-4 ${className ?? ""}`}>
+      <div className="flex flex-col gap-1 sm:max-w-xs">
+        <Label htmlFor="sync-limit">Only the first N records (optional)</Label>
+        <Input id="sync-limit" inputMode="numeric" placeholder="All" value={limit} onChange={(e) => setLimit(e.target.value)} />
+        {!limitOk ? <p role="alert" className="text-xs text-error-foreground">Enter a whole number above zero, or leave it empty.</p> : null}
+      </div>
+      <SectionCard title="Contacts" description={`Between ${brand.name} and ${label}`}><div className="flex flex-wrap gap-2">{plans("contacts").map(row)}</div></SectionCard>
+      <SectionCard title="Deals" description={`Between ${brand.name} and ${label}`}><div className="flex flex-wrap gap-2">{plans("deals").map(row)}</div></SectionCard>
+      {provider === "salesforce" ? <SectionCard title="Leads" description="Check what would be sent first, then send">
+        <div className="flex flex-col gap-3">
+          <div className="grid gap-3 sm:grid-cols-3">
+            <div className="flex flex-col gap-1"><Label htmlFor="lead-mode">Send</Label><select id="lead-mode" className="h-9 rounded-md border bg-background px-2 text-sm" value={mode} onChange={(e) => setMode(e.target.value as typeof mode)}><option value="all_qualified">Qualified contacts</option><option value="all_contacts">All contacts</option></select></div>
+            <div className="flex flex-col gap-1"><Label htmlFor="lead-q">Status for qualified</Label><select id="lead-q" className="h-9 rounded-md border bg-background px-2 text-sm" value={qualified} onChange={(e) => setQualified(e.target.value)}><option value="">CRM default</option>{statusRows.map((s) => <option key={s.value} value={s.value}>{s.label}</option>)}</select></div>
+            <div className="flex flex-col gap-1"><Label htmlFor="lead-u">Status for others</Label><select id="lead-u" className="h-9 rounded-md border bg-background px-2 text-sm" value={unqualified} onChange={(e) => setUnqualified(e.target.value)}><option value="">CRM default</option>{statusRows.map((s) => <option key={s.value} value={s.value}>{s.label}</option>)}</select></div>
+          </div>
+          {statuses.error ? <ApiError compact error={statuses.error} title="Could not load the lead statuses" onRetry={() => void statuses.refetch()} /> : null}
+          <div className="flex flex-wrap items-center gap-2">
+            <Button size="sm" variant="outline" loading={preview.loading} onClick={() => { setPreviewed(previewKey); void preview.refetch(); }}>Preview the push</Button>
+            {shown ? <span role="status" className="text-sm" data-testid="lead-preview">{Object.keys(pv).length ? Object.entries(pv).filter(([, v]) => typeof v === "number" || typeof v === "string").slice(0, 4).map(([k, v]) => `${k.replace(/_/g, " ")}: ${String(v)}`).join(", ") : "Nothing would be sent."}</span> : null}
+          </div>
+          {preview.error && previewed === previewKey ? <ApiError compact error={preview.error} title="Could not preview the push" /> : null}
+          <label className="flex items-start gap-2 text-sm"><input type="checkbox" className="mt-1" checked={bigOk} onChange={(e) => setBigOk(e.target.checked)} /><span>I have checked the previewed count and accept a large push (needed only above the app's population limit).</span></label>
+          <div className="flex flex-wrap gap-2">{row(leadPush)}{row(leadPull)}</div>
+        </div>
+      </SectionCard> : null}
+      {run.error ? <ApiError error={run.error} title="The sync did not start" /> : null}
+      <SectionCard title={`Jobs (${jobs.length})`} description="Started in this session" flush>
+        {run.loading ? <Skeleton className="m-3 h-8" /> : null}
+        {jobs.length === 0 ? <p className="px-4 py-3 text-sm text-muted-foreground">No sync started yet. Pick one above.</p> : <ul className="divide-y">{jobs.map((j) => <JobRow key={j.id} job={j} />)}</ul>}
+      </SectionCard>
+      <ConfirmSpendDialog open={plan != null} tier="external" title={plan?.label ?? "Run a sync"} description={`This changes real data: ${plan?.scope ?? ""}. It runs in the background and cannot be recalled.`}
+        confirmLabel="Start sync" confirming={run.loading} onConfirm={() => plan && void run.mutate(plan)} onCancel={() => setPlan(null)} />
+    </div>
+  );
+}

package/blocks/integrations/components/webhook-detail.tsx

@@ -0,0 +1,179 @@
+"use client";
+
+/**
+ * WebhookDetail: the complete screen for one webhook. Finds it by id (so `?id=` deep links work), shows every field (endpoint, name,
+ * events, active state, field filters, created and updated times), its delivery log, and every action: rename, change the endpoint or
+ * the events, pause or resume, rotate the signing secret (shown once), delete.
+ *
+ * SDK operations, in order:
+ *   1. listWebhooks          GET    /webhooks                          (read)
+ *      getWebhook            GET    /webhooks/{id}                     (read; only when the id is not in the list, e.g. a deep link to a webhook beyond the list's page)
+ *   2. listWebhookEvents     GET    /webhooks/events                   (read; the event names to pick from)
+ *   3. listWebhookDeliveries GET    /webhooks/{id}/deliveries          (read)
+ *   4. updateWebhook         PATCH  /webhooks/{id}                     (external, confirmed; edit, pause, resume)
+ *   5. rotateWebhookSecret   POST   /webhooks/{id}/rotate-secret       (external, confirmed; new secret shown once)
+ *   6. deleteWebhook         DELETE /webhooks/{id}                     (destructive, confirmed; 404 counts as done)
+ * Verify deliveries on the server with g8.webhooks.constructEvent; the secret never belongs in browser code.
+ */
+import { useEffect, useState, type ReactNode } from "react";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { useLoadMoreList } from "@/g8/hooks/use-load-more-list";
+import { byPage, hasNextOf } from "@/g8/lib/paging";
+import { LoadMore } from "@/g8/components/paging-notices";
+import { EmptyState } from "@/g8/components/empty-state";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { arrayOf, formatWhen } from "../lib/integrations-utils";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { AskButton, useConfirmAction } from "@/g8/components/confirmed-action";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface WebhookDetailProps {
+  webhookId: string;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  onChanged?: () => void;
+  /** Extra header actions from the screen's `renderDetailActions` slot. */
+  extraActions?: ReactNode;
+  /** Extra tabs from the screen's `extraDetailTabs` slot, after the built-in ones. */
+  extraTabs?: { id: string; label: string; content: ReactNode }[];
+}
+
+interface Hook { id: string; url: string; name?: string | null; events?: string[]; is_active?: boolean; created_at?: string | null; updated_at?: string | null; field_filters?: Record<string, string[]> | null; secret?: string | null }
+interface EventType { event: string; category?: string | null; description?: string | null }
+interface Delivery { id: string; event: string; status: string; attempts?: number; max_attempts?: number; response_code?: number | null; error_message?: string | null; created_at?: string | null; completed_at?: string | null }
+
+/** Deliveries per read; "Load more" appends the next page. */
+const DELIVERY_PAGE = 20;
+
+export function WebhookDetail({ webhookId, onClose, onExpand, onCollapse, onChanged, extraActions, extraTabs }: WebhookDetailProps) {
+  const brand = useBrand();
+  const { ask, dialog, failure } = useConfirmAction();
+  const hooks = useG8Query((signal) => g8Get("/webhooks", undefined, { signal }), []);
+  const events = useG8Query((signal) => g8Get("/webhooks/events", undefined, { signal }), []);
+  const deliveries = useLoadMoreList(byPage<Delivery>(DELIVERY_PAGE, async (page, signal) => {
+    const env = await g8Get(`/webhooks/${webhookId}/deliveries`, { page, limit: DELIVERY_PAGE }, { signal });
+    const rows = arrayOf<Delivery>(env);
+    return { rows, hasNext: hasNextOf(env, DELIVERY_PAGE, rows.length) };
+  }), [webhookId]);
+  const listed = arrayOf<Hook>(hooks.data).find((h) => h.id === webhookId);
+  const single = useG8Query((signal) => g8Get<Hook>(`/webhooks/${webhookId}`, undefined, { signal }), [webhookId], { enabled: Boolean(hooks.data) && !listed });
+  const fetched = (single.data as { data?: Hook } | undefined)?.data;
+  // Only the record fetched for THIS id counts: useG8Query keeps the previous webhook's data while the next one loads.
+  const hook = listed ?? (fetched?.id === webhookId ? fetched : undefined);
+  const [form, setForm] = useState({ url: "", name: "", events: [] as string[] });
+  const [secret, setSecret] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (hook) setForm({ url: hook.url, name: hook.name ?? "", events: hook.events ?? [] });
+  }, [hook?.id, hook?.url, hook?.name, hook?.events?.join(",")]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  if (hooks.error) return <ApiError error={hooks.error} title="Could not load the webhook" onRetry={() => void hooks.refetch()} />;
+  if (!hook && single.error) return <ApiError error={single.error} title="Could not load the webhook" onRetry={() => void single.refetch()} />;
+  if (!hooks.data || (!hook && single.loading)) return <Skeleton className="h-40 w-full" />;
+  if (!hook) return <EmptyState title="Webhook not found" description="It may have been deleted." />;
+  const changed = () => { void hooks.refetch(); if (!listed) void single.refetch(); onChanged?.(); };
+  const active = hook.is_active !== false;
+  const byCategory = arrayOf<EventType>(events.data).reduce<Record<string, EventType[]>>((acc, e) => ({ ...acc, [e.category ?? "other"]: [...(acc[e.category ?? "other"] ?? []), e] }), {});
+  const toggle = (event: string) => setForm((f) => ({ ...f, events: f.events.includes(event) ? f.events.filter((x) => x !== event) : [...f.events, event] }));
+  const urlOk = /^https:\/\/\S+$/.test(form.url.trim());
+  const rows = deliveries.data ?? [];
+
+  const actions = (
+    <div className="flex flex-wrap gap-1">
+      <AskButton ask={ask} label={active ? "Pause" : "Resume"} tier="external" title={`${active ? "Pause" : "Resume"} deliveries to ${hook.url}`} confirmLabel={active ? "Pause" : "Resume"}
+        description={active ? "Events stop being sent to this endpoint until you resume." : "Events are sent to this endpoint again."} run={() => g8Patch(`/webhooks/${hook.id}`, { is_active: !active })} onDone={changed} />
+      <AskButton ask={ask} label="Rotate secret" tier="external" title={`Rotate the signing secret for ${hook.url}`} confirmLabel="Rotate"
+        description="The old secret stops verifying deliveries as soon as you rotate. Update your server before or right after."
+        run={async () => { const res = await g8Post<Hook>(`/webhooks/${hook.id}/rotate-secret`); if (res.data?.secret) setSecret(res.data.secret); }} onDone={changed} />
+      <AskButton ask={ask} label="Delete" variant="ghost" tier="destructive" title={`Delete the webhook for ${hook.url}`} confirmLabel="Delete" tolerateStatus={[404]}
+        description={`${brand.linkLabel} stops sending events to this endpoint and removes its delivery log.`} run={() => g8Delete(`/webhooks/${hook.id}`)} onDone={() => { changed(); onClose?.(); }} />
+    </div>
+  );
+
+  const tabs = [
+    {
+      id: "overview",
+      label: "Overview",
+      content: (
+        <div className="space-y-4">
+          {secret ? (
+            <div role="alert" className="rounded border border-warning-foreground/30 bg-warning p-3 text-sm">
+              <p className="font-medium">New signing secret. It is shown once.</p>
+              <code className="mt-1 block break-all rounded bg-background p-2">{secret}</code>
+              <p className="mt-1 text-xs">Store it as G8_WEBHOOK_SECRET on your server. Never put it in browser code.</p>
+              <Button size="sm" variant="outline" className="mt-2" onClick={() => setSecret(null)}>I saved it</Button>
+            </div>
+          ) : null}
+          <KeyValueList columns={2} items={[
+            { label: "Endpoint", value: hook.url },
+            { label: "Name", value: hook.name ?? "-" },
+            { label: "Status", value: active ? "active" : "paused" },
+            { label: "Created", value: formatWhen(hook.created_at) },
+            { label: "Updated", value: formatWhen(hook.updated_at) },
+            { label: "Events", value: (hook.events ?? []).length },
+          ]} />
+          <SectionCard title="Subscribed events"><ul className="flex flex-wrap gap-1 text-xs">{(hook.events ?? []).map((e) => <li key={e}><StatusPill tone="neutral">{e}</StatusPill></li>)}</ul></SectionCard>
+          {hook.field_filters && Object.keys(hook.field_filters).length > 0 ? (
+            <SectionCard title="Field filters" description="crm.record.updated fires only when a watched field changed."><pre className="overflow-x-auto text-xs">{JSON.stringify(hook.field_filters, null, 2)}</pre></SectionCard>
+          ) : null}
+        </div>
+      ),
+    },
+    {
+      id: "edit",
+      label: "Edit",
+      content: (
+        <SectionCard title="Edit webhook" description="Changing where events go is confirmed first.">
+          <div className="space-y-3">
+            <div className="flex flex-col gap-1"><Label htmlFor="wd-url">Endpoint URL</Label><Input id="wd-url" value={form.url} onChange={(e) => setForm({ ...form, url: e.target.value })} /></div>
+            {form.url && !urlOk ? <p className="text-xs text-error-foreground">The endpoint must be an https:// URL.</p> : null}
+            <div className="flex flex-col gap-1"><Label htmlFor="wd-name">Name</Label><Input id="wd-name" value={form.name} onChange={(e) => setForm({ ...form, name: e.target.value })} /></div>
+            {Object.entries(byCategory).map(([category, items]) => (
+              <fieldset key={category}>
+                <legend className="text-xs font-medium uppercase text-muted-foreground">{category}</legend>
+                <div className="flex flex-wrap gap-x-4 gap-y-1">
+                  {items.map((e) => <label key={e.event} className="flex items-center gap-1 text-sm" title={e.description ?? undefined}><input type="checkbox" checked={form.events.includes(e.event)} onChange={() => toggle(e.event)} />{e.event}</label>)}
+                </div>
+              </fieldset>
+            ))}
+            <AskButton ask={ask} label="Save changes" variant="default" tier="external" title={`Update the webhook for ${hook.url}`} confirmLabel="Save" disabled={!urlOk || form.events.length === 0}
+              description={`Changes where ${brand.linkLabel} sends your data.`} run={() => g8Patch(`/webhooks/${hook.id}`, { url: form.url.trim(), name: form.name.trim() || null, events: form.events })} onDone={changed} />
+          </div>
+        </SectionCard>
+      ),
+    },
+    {
+      id: "deliveries",
+      label: "Deliveries",
+      content: deliveries.loading && !deliveries.data ? <Skeleton className="h-16 w-full" /> : deliveries.error ? <ApiError error={deliveries.error} onRetry={() => void deliveries.refetch()} /> : rows.length === 0 ? <p className="text-sm text-muted-foreground">No deliveries yet.</p> : (
+        <>
+        <table className="w-full text-sm" aria-label="Deliveries">
+          <thead><tr className="text-left text-muted-foreground"><th>Event</th><th>Status</th><th>Code</th><th>Attempts</th><th>When</th></tr></thead>
+          <tbody>
+            {rows.map((d) => (
+              <tr key={d.id} className="border-t" title={d.error_message ?? undefined}>
+                <td>{d.event}</td><td>{d.status}</td><td>{d.response_code ?? "-"}</td><td>{d.attempts ?? 1}{d.max_attempts ? ` of ${d.max_attempts}` : ""}</td><td>{formatWhen(d.created_at)}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+        <LoadMore shown={rows.length} noun="deliveries" hasMore={deliveries.hasMore} loading={deliveries.loadingMore} onLoadMore={deliveries.loadMore} />
+        </>
+      ),
+    },
+  ];
+  return (
+    <>
+      <DetailPanel title={hook.name || hook.url} subtitle={hook.name ? hook.url : undefined} badges={<StatusPill tone={active ? "positive" : "neutral"}>{active ? "active" : "paused"}</StatusPill>} actions={extraActions ? <>{actions}{extraActions}</> : actions} tabs={extraTabs?.length ? [...tabs, ...extraTabs] : tabs} onClose={onClose} onExpand={onExpand} onCollapse={onCollapse} />
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </>
+  );
+}