@graph8/sdk 0.362.0 → 0.373.0

package/blocks/lists/components/suppressions-screen.tsx

@@ -0,0 +1,264 @@
+"use client";
+
+/**
+ * SuppressionsScreen: the finished do-not-contact page. A filterable ledger with a detail panel for the contact behind
+ * a row, a "Suppress contacts" sheet (paste ids or tick people from the CRM) and a confirmed Reinstate.
+ *
+ * Composes: ScreenLayout, StatStrip, Toolbar, SplitView, DetailPanel, FormSheet (screen kit), ContactTable and
+ * ContactDetail (crm), ConfirmSpendDialog.
+ *
+ * User flows:
+ *   - filter the ledger by channel and reason, page through it, see how many are suppressed on each channel
+ *   - Suppress contacts: search and tick people (ContactPicker), or pick them from the CRM table, or paste ids under
+ *     "Paste ids instead"; choose the channel (default all) and a reason
+ *   - open a ledger row: the contact's record plus its live suppression status (read-only check)
+ *   - check any contact without opening it (pick them by name; no ids to type)
+ *   - tick rows and Reinstate (confirmed: it lets sequences, campaigns and newsletters contact them again)
+ *
+ * SDK operations, in order:
+ *   1. listSuppressions        GET  /contacts/suppressions?channel&category&limit&offset         (read)
+ *   2. bulkAddSuppressions     POST /contacts/suppressions/bulk-add { contact_ids, channel, reason }   (write; only reduces outreach, no confirm)
+ *   3. checkContactSuppression GET  /contacts/{contact_id}/suppression                            (read)
+ *   4. reinstateSuppressions   POST /contacts/suppressions/reinstate { contact_ids, reason }      (write, ConfirmSpendDialog "external")
+ *   5. listContacts / getContact via ContactTable / ContactDetail                                  (read)
+ */
+
+import { useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import { BadgeCheck, Ban, ShieldOff, Undo2 } from "lucide-react";
+import { Button, Input, Label, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { ContactPicker } from "@/g8/pickers/components/contact-picker";
+import type { ContactOption } from "@/g8/pickers/components/contact-picker";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { ContactDetail } from "@/g8/crm/components/contact-detail";
+import { ContactTable } from "@/g8/crm/components/contact-table";
+import { plural } from "@/g8/lib/plural";
+import { parseIds } from "./suppression-manager";
+import type { SuppressionRecord } from "./suppression-manager";
+
+export interface SuppressionsScreenProps {
+  pageSize?: number;
+  toolbarActions?: ReactNode;
+  renderRowActions?: (row: SuppressionRecord) => ReactNode;
+  renderDetailActions?: (contactId: number) => ReactNode;
+  extraDetailTabs?: { id: string; label: string; render: (contactId: number) => ReactNode }[];
+  className?: string;
+}
+
+interface ContactStatus { contact_id: number; is_suppressed: boolean; active_channels: string[]; suppressions: SuppressionRecord[] }
+interface BulkAdd { suppressed: number; total_requested: number; channel: string; not_found: number[] }
+interface Reinstate { reinstated: number[]; skipped: Array<{ contact_id: number; reason: string }>; not_found: number[] }
+
+const CHANNELS = [["all", "All channels"], ["email", "Email"], ["phone", "Phone"], ["linkedin", "LinkedIn"]] as const;
+const SELECT = "h-9 rounded-md border bg-background px-2 text-sm";
+
+function ContactStatusPanel({ contactId }: { contactId: number }) {
+  const status = useG8Query((signal) => g8Get<ContactStatus>(`/contacts/${contactId}/suppression`, undefined, { signal }), [contactId]);
+  if (status.error) return <ApiError error={status.error} title="Could not check that contact" onRetry={() => void status.refetch()} />;
+  if (!status.data) return <Skeleton className="h-6 w-48" />;
+  const s = status.data.data;
+  return (
+    <p role="status" className="flex items-center gap-2 text-sm">
+      {s.is_suppressed ? <StatusPill tone="negative" dot>Suppressed</StatusPill> : <StatusPill tone="positive" dot>Can be contacted</StatusPill>}
+      {s.is_suppressed ? <span className="text-muted-foreground">on {s.active_channels.join(", ")}</span> : null}
+    </p>
+  );
+}
+
+export function SuppressionsScreen({ pageSize = 50, toolbarActions, renderRowActions, renderDetailActions, extraDetailTabs, className }: SuppressionsScreenProps) {
+  const [channel, setChannel] = useState("");
+  const [category, setCategory] = useState("");
+  const [offset, setOffset] = useState(0);
+  const [openId, setOpenId] = useUrlState("id");
+  const [view, setView] = useUrlState("view");
+  const full = view === "full";
+  const [adding, setAdding] = useState(false);
+  const [idsText, setIdsText] = useState("");
+  const [pickedContacts, setPickedContacts] = useState<ContactOption[]>([]);
+  const [addChannel, setAddChannel] = useState("all");
+  const [reason, setReason] = useState("");
+  const [picked, setPicked] = useState<Set<number>>(new Set());
+  const [confirmReinstate, setConfirmReinstate] = useState(false);
+  /** Set when Reinstate is started from a row's panel: the confirm acts on that contact only and leaves the ticked rows alone. */
+  const [panelTarget, setPanelTarget] = useState<number | null>(null);
+  const [reinstateReason, setReinstateReason] = useState("");
+  const [checked, setChecked] = useState<ContactOption | null>(null);
+
+  const ledger = useG8Query((signal) => g8Get<SuppressionRecord[]>("/contacts/suppressions", { channel: channel || undefined, category: category || undefined, limit: pageSize, offset }, { signal }), [channel, category, offset, pageSize]);
+  const rows = (ledger.data?.data ?? []) as SuppressionRecord[];
+  // Selection belongs to the rows on screen: prune it when the page or a filter changes.
+  useEffect(() => { setPicked((p) => new Set([...p].filter((id) => rows.some((r) => r.contact_id === id)))); }, [ledger.data]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const add = useG8Mutation((v: { ids: number[] }) => g8Post<BulkAdd>("/contacts/suppressions/bulk-add", { contact_ids: v.ids, channel: addChannel, reason: reason.trim() || undefined }), {
+    onSuccess: () => { setIdsText(""); setPickedContacts([]); setReason(""); void ledger.refetch(); },
+  });
+  const reinstate = useG8Mutation((ids: number[]) => g8Post<Reinstate>("/contacts/suppressions/reinstate", { contact_ids: ids, reason: reinstateReason.trim() || undefined }), {
+    onSuccess: () => { setConfirmReinstate(false); setReinstateReason(""); if (panelTarget != null) { const done = panelTarget; setPicked((p) => { const n = new Set(p); n.delete(done); return n; }); } else setPicked(new Set()); setPanelTarget(null); void ledger.refetch(); },
+  });
+
+  const ids = [...new Set([...pickedContacts.map((c) => c.id), ...parseIds(idsText)])];
+  const chosen = panelTarget != null ? [panelTarget] : [...picked];
+  const togglePick = (id: number) => setPicked((p) => { const n = new Set(p); if (!n.delete(id)) n.add(id); return n; });
+  const byChannel = (c: string) => rows.filter((r) => r.channel === c).length;
+  const resetPage = () => { setOffset(0); setPicked(new Set()); };
+
+  const list = (
+    <div className="flex flex-col gap-3">
+      {ledger.error ? <ApiError error={ledger.error} title="Could not load the ledger" onRetry={() => void ledger.refetch()} /> : null}
+      {reinstate.error ? <ApiError error={reinstate.error} title="Could not reinstate" /> : null}
+      {reinstate.data ? <p role="status" className="text-sm">Reinstated {reinstate.data.data.reinstated.length}.{reinstate.data.data.skipped.length ? ` Skipped ${reinstate.data.data.skipped.length}: ${reinstate.data.data.skipped.map((s) => `${s.contact_id} (${s.reason})`).join(", ")}.` : ""}</p> : null}
+      <div className="divide-y rounded-md border">
+        {ledger.loading && rows.length === 0
+          ? Array.from({ length: 5 }, (_, i) => <div key={`sk${i}`} className="p-3"><Skeleton className="h-6 w-full" /></div>)
+          : rows.map((r) => (
+              <div key={r.id} data-testid="suppression-row" className={`flex items-center gap-3 p-3 ${String(r.contact_id) === openId ? "bg-muted/50" : ""}`}>
+                <input type="checkbox" aria-label={`Select contact ${r.contact_id}`} checked={picked.has(r.contact_id)} onChange={() => togglePick(r.contact_id)} />
+                <button type="button" className="flex min-w-0 flex-1 items-center gap-3 text-left" onClick={() => setOpenId(String(r.contact_id))}>
+                  <span className="text-sm font-medium tabular-nums">#{r.contact_id}</span>
+                  <StatusPill tone="negative">{r.channel === "all" ? "All channels" : r.channel}</StatusPill>
+                  <span className="min-w-0 flex-1 truncate text-sm text-muted-foreground">{r.category.replace(/_/g, " ")}{r.reason ? `: ${r.reason}` : ""}</span>
+                  <span className="text-xs text-muted-foreground">{r.created_at ? new Date(r.created_at).toLocaleDateString() : ""}</span>
+                </button>
+                {renderRowActions?.(r)}
+              </div>
+            ))}
+        {!ledger.loading && !ledger.error && rows.length === 0 ? (
+          <EmptyState icon={<ShieldOff className="size-6" aria-hidden />} title="Nobody is suppressed" description="Suppressed contacts are skipped by every sequence, campaign and newsletter."
+            action={<Button size="sm" onClick={() => setAdding(true)}>Suppress contacts</Button>} />
+        ) : null}
+      </div>
+      <div className="flex items-center justify-end gap-2 text-sm">
+        <Button variant="outline" size="sm" disabled={offset === 0 || ledger.loading} onClick={() => { setOffset(Math.max(0, offset - pageSize)); setPicked(new Set()); }}>Previous</Button>
+        <Button variant="outline" size="sm" disabled={rows.length < pageSize || ledger.loading} onClick={() => { setOffset(offset + pageSize); setPicked(new Set()); }}>Next</Button>
+      </div>
+    </div>
+  );
+
+  const contactId = openId ? Number(openId) : null;
+  const detail = contactId ? (
+    <DetailPanel
+      key={contactId}
+      onExpand={full ? undefined : () => setView("full")}
+      onCollapse={full ? () => setView(null) : undefined}
+      title={`Contact #${contactId}`}
+      subtitle="Suppression status and record"
+      onClose={() => setOpenId(null)}
+      actions={(<>
+        <Button size="sm" variant="outline" onClick={() => { setPanelTarget(contactId); setConfirmReinstate(true); }}><Undo2 className="mr-1 size-4" aria-hidden />Reinstate</Button>
+        {renderDetailActions?.(contactId)}
+      </>)}
+      tabs={[
+        { id: "status", label: "Status", content: (
+          <div className="flex flex-col gap-3">
+            <ContactStatusPanel contactId={contactId} />
+            {rows.filter((r) => r.contact_id === contactId).map((r) => (
+              <SectionCard key={r.id} title={r.channel === "all" ? "All channels" : `${r.channel} suppression`} description={r.category.replace(/_/g, " ")}>
+                <KeyValueList columns={2} items={[
+                  { label: "Reason", value: r.reason ?? "", wide: true },
+                  { label: "Source", value: r.source ?? "" },
+                  { label: "Source reference", value: r.source_ref ?? "", mono: true },
+                  { label: "Added by", value: r.created_by ?? "" },
+                  { label: "Since", value: r.created_at ? new Date(r.created_at).toLocaleString() : "" },
+                  { label: "Revision", value: r.revision != null ? String(r.revision) : "" },
+                  { label: "Entry id", value: r.id, mono: true },
+                ]} />
+              </SectionCard>
+            ))}
+          </div>
+        ) },
+        { id: "contact", label: "Contact", content: <ContactDetail contactId={contactId} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(contactId) })),
+      ]}
+    />
+  ) : null;
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Suppressions"
+      description="Everyone on this list is skipped by every sequence, campaign and newsletter."
+      icon={<Ban className="size-5" aria-hidden />}
+      actions={<>{toolbarActions}<Button size="sm" onClick={() => setAdding(true)}><Ban className="mr-1 size-4" aria-hidden />Suppress contacts</Button></>}
+      stats={[
+        { label: "On this page", value: rows.length.toLocaleString() },
+        { label: "All channels", value: byChannel("all") },
+        { label: "Email", value: byChannel("email") },
+        { label: "Phone and LinkedIn", value: byChannel("phone") + byChannel("linkedin") },
+      ]}
+      toolbar={(
+        <Toolbar
+          filters={(<>
+            <select aria-label="Filter by channel" className={SELECT} value={channel} onChange={(e) => { setChannel(e.target.value); resetPage(); }}>
+              <option value="">Any channel</option><option value="all">All</option><option value="email">Email</option><option value="phone">Phone</option><option value="linkedin">LinkedIn</option>
+            </select>
+            <select aria-label="Filter by reason" className={SELECT} value={category} onChange={(e) => { setCategory(e.target.value); resetPage(); }}>
+              <option value="">Any reason</option><option value="contact_initiated">Contact asked</option><option value="org_initiated">Our team</option><option value="system">System</option>
+            </select>
+            <ContactPicker label="Contact to check" placeholder="Check a contact" value={checked} onChange={setChecked} />
+            {checked ? <span className="flex items-center gap-1"><ContactStatusPanel key={checked.id} contactId={checked.id} /><span className="text-xs text-muted-foreground">{checked.name}</span></span> : null}
+          </>)}
+          actions={<Button variant="outline" size="sm" disabled={chosen.length === 0} onClick={() => { setPanelTarget(null); setConfirmReinstate(true); }}><BadgeCheck className="mr-1 size-4" aria-hidden />Reinstate {chosen.length || ""}</Button>}
+        />
+      )}
+    >
+      <SplitView expanded={full} onExpandedChange={(e) => setView(e ? "full" : null)} list={list} detail={detail} detailOpen={contactId != null} onCloseDetail={() => setOpenId(null)} />
+
+      <FormSheet open={adding} onOpenChange={setAdding} title="Suppress contacts" description="They will be skipped by every sequence, campaign and newsletter on the chosen channels.">
+        <div className="flex flex-col gap-4">
+          <div className="flex flex-wrap items-end gap-2">
+            <div className="flex flex-col gap-1"><Label htmlFor="suppress-channel">Channel</Label>
+              <select id="suppress-channel" className={SELECT} value={addChannel} onChange={(e) => setAddChannel(e.target.value)}>{CHANNELS.map(([v, l]) => <option key={v} value={v}>{l}</option>)}</select>
+            </div>
+            <div className="flex min-w-40 flex-1 flex-col gap-1"><Label htmlFor="suppress-reason">Reason (optional)</Label><Input id="suppress-reason" value={reason} onChange={(e) => setReason(e.target.value)} /></div>
+          </div>
+          <div className="flex flex-col gap-2">
+            <span className="text-sm font-medium leading-none">Search and add people</span>
+            <ContactPicker multiple label="Contacts to suppress" selected={pickedContacts} onSelectedChange={setPickedContacts} />
+            <details className="text-sm">
+              <summary className="cursor-pointer text-muted-foreground">Paste ids instead</summary>
+              <div className="mt-1 flex flex-col gap-1">
+                <Label htmlFor="suppress-ids">Contact ids</Label>
+                <Textarea id="suppress-ids" rows={3} placeholder="101, 102, 103" value={idsText} onChange={(e) => setIdsText(e.target.value)} />
+              </div>
+            </details>
+            <Button size="sm" loading={add.loading} disabled={ids.length === 0} onClick={() => void add.mutate({ ids })}>{ids.length ? `Suppress ${plural(ids.length, "contact")}` : "Suppress contacts"}</Button>
+          </div>
+          <div className="flex flex-col gap-2">
+            <Label>Or pick people from your CRM</Label>
+            <ContactTable selectable allowDelete={false} pageSize={8}
+              renderBulkActions={({ ids: sel, clear }) => (
+                <Button size="sm" variant="outline" loading={add.loading} onClick={async () => { if (await add.mutate({ ids: sel })) clear(); }}>Suppress {sel.length} selected</Button>
+              )} />
+          </div>
+          {add.data ? <p role="status" className="text-sm">Suppressed {add.data.data.suppressed} of {add.data.data.total_requested}.{add.data.data.not_found.length ? ` ${add.data.data.not_found.length} ids do not exist.` : ""}</p> : null}
+          {add.error ? <ApiError error={add.error} title="Could not suppress" /> : null}
+        </div>
+      </FormSheet>
+
+      <ConfirmSpendDialog open={confirmReinstate} tier="external" title={`Reinstate ${plural(chosen.length, "contact")}`}
+        description={(
+          <div className="flex flex-col gap-2">
+            <p>Reinstating a contact lifts EVERY suppression on it (all channels), not only the row you ticked. They can be messaged again by sequences, campaigns and newsletters. Contacts who unsubscribed themselves may be refused.</p>
+            <Label htmlFor="reinstate-reason">Reason (kept in the audit trail)</Label>
+            <Input id="reinstate-reason" value={reinstateReason} onChange={(e) => setReinstateReason(e.target.value)} />
+          </div>
+        )}
+        recipients={chosen.length} confirmLabel="Reinstate" confirming={reinstate.loading}
+        onConfirm={() => void reinstate.mutate(chosen)} onCancel={() => { setConfirmReinstate(false); setPanelTarget(null); }} />
+    </ScreenLayout>
+  );
+}

package/blocks/mailboxes/README.md

@@ -5,6 +5,23 @@ and check deliverability and warmup before a send. The Apollo / Outreach "mailbo
 
 Depends on: `foundation`. Install: `npx @graph8/sdk add mailboxes`.
 
+## Screens
+
+`MailboxesScreen` is the finished page: mount it as the route. Every record type has a complete detail view,
+deep-linkable with `?id=` (plus `?tab=` for the section and `?dtab=` for the detail tab).
+
+- **Mailboxes tab**: fleet stat strip and the mailbox list (show archived). `MailboxDetail` opens beside it: every
+  field, its domain, warmup analytics, start/stop warmup, placement test (confirmed), test connection, archive,
+  restore and delete (confirmed).
+- **Domains tab**: your domains plus `DomainPurchase` (suggest, check, buy). `DomainDetail` (`?tab=domains&id=`):
+  every field, the mailboxes on it, connect and check DNS (confirmed), buy mailboxes on it.
+- **Add mailbox** (header button): IMAP/SMTP connect, the Google/Microsoft link-out to the graph8 app (OAuth cannot
+  run through the API), and buy-mailboxes on a connected domain.
+- **Deliverability tab**: safe-to-send verdict, fleet counts, degraded mailboxes.
+
+Slot props: `toolbarActions`, `renderDetailActions(mailbox)`, `extraDetailTabs`, `appUrl`. `WarmupHealth` gained an
+optional `showFleet` prop and `ConnectMailbox` optional `initialMode` and `domainId`.
+
 ## Components
 
 | Component | What it does | Tiers |

package/blocks/mailboxes/block.json

@@ -13,26 +13,28 @@
     "foundation"
   ],
   "operations": [
-    "list_mailboxes_mailboxes_get",
-    "test_mailbox_connection_mailboxes__mailbox_id__test_connection_post",
     "archive_mailbox_mailboxes__mailbox_id__archive_post",
-    "delete_mailbox_mailboxes__mailbox_id__delete",
-    "create_mailbox_mailboxes_post",
-    "list_provider_domains_provider_domains_get",
-    "get_sending_pricing_provider_domains_pricing_get",
-    "checkout_purchase_mailboxes_provider_domains__domain_id__checkout_mailboxes_post",
-    "generate_domain_names_provider_domains_generate_domains_post",
     "check_domain_availability_provider_domains_check_availability_post",
+    "check_domain_propagation_provider_domains__domain_id__check_propagation_post",
     "checkout_purchase_domains_provider_domains_checkout_purchase_post",
+    "checkout_purchase_mailboxes_provider_domains__domain_id__checkout_mailboxes_post",
     "connect_provider_provider_domains__domain_id__connect_provider_post",
-    "check_domain_propagation_provider_domains__domain_id__check_propagation_post",
+    "create_mailbox_mailboxes_post",
+    "delete_mailbox_mailboxes__mailbox_id__delete",
+    "disable_warmup_warmup__mailbox_id__disable_post",
+    "enable_warmup_warmup__mailbox_id__enable_post",
+    "generate_domain_names_provider_domains_generate_domains_post",
     "get_fleet_summary_deliverability_fleet_summary_get",
+    "get_mailbox_mailboxes__mailbox_id__get",
+    "get_mailbox_warmup_analytics_mailboxes__mailbox_id__warmup_get",
     "get_safe_to_send_deliverability_safe_to_send_get",
+    "get_sending_pricing_provider_domains_pricing_get",
     "list_degraded_mailboxes_deliverability_degraded_get",
-    "get_mailbox_warmup_analytics_mailboxes__mailbox_id__warmup_get",
-    "enable_warmup_warmup__mailbox_id__enable_post",
-    "disable_warmup_warmup__mailbox_id__disable_post",
-    "run_mailbox_placement_test_mailboxes__mailbox_id__health_placement_test_post"
+    "list_mailboxes_mailboxes_get",
+    "list_provider_domains_provider_domains_get",
+    "run_mailbox_placement_test_mailboxes__mailbox_id__health_placement_test_post",
+    "test_mailbox_connection_mailboxes__mailbox_id__test_connection_post",
+    "update_mailbox_mailboxes__mailbox_id__patch"
   ],
   "components": [
     {
@@ -56,11 +58,12 @@
       "file": "components/connect-mailbox.tsx",
       "purpose": "Connect over IMAP/SMTP and test, link to the app for Google/Microsoft, or buy mailboxes on a connected domain (confirmed).",
       "operations": [
+        "checkout_purchase_mailboxes_provider_domains__domain_id__checkout_mailboxes_post",
         "create_mailbox_mailboxes_post",
-        "test_mailbox_connection_mailboxes__mailbox_id__test_connection_post",
-        "list_provider_domains_provider_domains_get",
         "get_sending_pricing_provider_domains_pricing_get",
-        "checkout_purchase_mailboxes_provider_domains__domain_id__checkout_mailboxes_post"
+        "list_provider_domains_provider_domains_get",
+        "test_mailbox_connection_mailboxes__mailbox_id__test_connection_post",
+        "update_mailbox_mailboxes__mailbox_id__patch"
       ],
       "tiers": [
         "read",
@@ -103,6 +106,50 @@
         "write",
         "billable"
       ]
+    },
+    {
+      "name": "MailboxesScreen",
+      "file": "components/mailboxes-screen.tsx",
+      "purpose": "Finished mailboxes page: fleet stats, mailbox list with warmup detail panel, add-mailbox sheet, deliverability and domains tabs.",
+      "operations": [
+        "get_fleet_summary_deliverability_fleet_summary_get",
+        "list_provider_domains_provider_domains_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "MailboxDetail",
+      "file": "components/mailbox-detail.tsx",
+      "purpose": "One mailbox, complete: every field, its domain, warmup and health; test, archive, restore and delete (confirmed).",
+      "operations": [
+        "get_mailbox_mailboxes__mailbox_id__get",
+        "list_provider_domains_provider_domains_get",
+        "test_mailbox_connection_mailboxes__mailbox_id__test_connection_post",
+        "archive_mailbox_mailboxes__mailbox_id__archive_post",
+        "delete_mailbox_mailboxes__mailbox_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "DomainDetail",
+      "file": "components/domain-detail.tsx",
+      "purpose": "One sending domain, complete: every field, the mailboxes on it; connect and check DNS (confirmed), buy mailboxes.",
+      "operations": [
+        "list_provider_domains_provider_domains_get",
+        "list_mailboxes_mailboxes_get",
+        "connect_provider_provider_domains__domain_id__connect_provider_post",
+        "check_domain_propagation_provider_domains__domain_id__check_propagation_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
     }
   ],
   "hooks": [],
@@ -110,6 +157,10 @@
     {
       "file": "lib/mailboxes-utils.ts",
       "purpose": "Mailbox and domain row types, credit estimate constants, status colors and idempotency-key helper."
+    },
+    {
+      "file": "lib/use-provider-domains.ts",
+      "purpose": "Every sending domain, read page after page (the domains API pages) instead of one capped call."
     }
   ],
   "recipes": [
@@ -182,6 +233,7 @@
     }
   ],
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
   }
 }

package/blocks/mailboxes/components/connect-mailbox.tsx

@@ -24,8 +24,11 @@ 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 { DEFAULT_MAILBOX_CREDITS, GRAPH8_APP_MAILBOXES_URL, listOf, newIdempotencyKey, objectOf } from "../lib/mailboxes-utils";
+import { DEFAULT_MAILBOX_CREDITS, GRAPH8_APP_MAILBOXES_PATH, listOf, newIdempotencyKey, objectOf } from "../lib/mailboxes-utils";
+import { useProviderDomains } from "../lib/use-provider-domains";
 import type { DomainRow } from "../lib/mailboxes-utils";
+import { plural, pluralWord } from "@/g8/lib/plural";
+import { brandUrl, useBrand } from "@/g8/hooks/use-brand";
 
 export interface ConnectMailboxProps {
   /** Where the person connects Google or Microsoft. Default: graph8 Settings > Purchase > Mailboxes. */
@@ -34,6 +37,10 @@ export interface ConnectMailboxProps {
   onConnected?: (mailboxId: number | string) => void;
   /** Called with the domain id after mailboxes were bought on it. */
   onPurchased?: (domainId: number | string) => void;
+  /** Open on this tab (default "imap"). */
+  initialMode?: "imap" | "oauth" | "buy";
+  /** Preselect this connected domain on the Buy tab. */
+  domainId?: number | string;
   className?: string;
 }
 
@@ -54,6 +61,7 @@ const EMPTY = {
 };
 
 function ImapForm({ onConnected }: { onConnected?: (id: number | string) => void }) {
+  const brand = useBrand();
   const [form, setForm] = useState(EMPTY);
   const [result, setResult] = useState<string | null>(null);
   // Step 1 (create) must not repeat when step 2 (test) fails, even if the person then fixes a password.
@@ -73,7 +81,7 @@ function ImapForm({ onConnected }: { onConnected?: (id: number | string) => void
     const known = created.current?.email === form.email.trim().toLowerCase() ? created.current : null;
     if (!known) {
       const res = await g8Post<{ id: number }>("/mailboxes", body);
-      if (res.data?.id == null) throw new Error("graph8 did not return the new mailbox id");
+      if (res.data?.id == null) throw new Error(`${brand.linkLabel} did not return the new mailbox id`);
       created.current = { email: form.email.trim().toLowerCase(), id: res.data.id, sig };
     } else if (known.sig !== sig) {
       const { email: _email, ...changes } = body;
@@ -128,7 +136,7 @@ function ImapForm({ onConnected }: { onConnected?: (id: number | string) => void
       </Button>
       {connect.error ? <ApiError error={connect.error} onRetry={connect.reset} /> : null}
       {result ? (
-        <p role="status" className="text-sm text-gray-700">
+        <p role="status" className="text-sm text-foreground">
           {result}
         </p>
       ) : null}
@@ -136,10 +144,11 @@ function ImapForm({ onConnected }: { onConnected?: (id: number | string) => void
   );
 }
 
-function BuyForm({ onPurchased }: { onPurchased?: (id: number | string) => void }) {
-  const domains = useG8Query((signal) => g8Get("/provider-domains", { page: 1, limit: 100 }, { signal }), []);
+function BuyForm({ onPurchased, domainId: initialDomainId }: { onPurchased?: (id: number | string) => void; domainId?: number | string }) {
+  const brand = useBrand();
+  const domains = useProviderDomains([]);
   const pricing = useG8Query((signal) => g8Get("/provider-domains/pricing", undefined, { signal }), []);
-  const [domainId, setDomainId] = useState("");
+  const [domainId, setDomainId] = useState(initialDomainId != null ? String(initialDomainId) : "");
   const [usernames, setUsernames] = useState("");
   const [person, setPerson] = useState({ first_name: "", last_name: "" });
   const [platform, setPlatform] = useState<"GOOGLE" | "MICROSOFT">("GOOGLE");
@@ -159,22 +168,22 @@ function BuyForm({ onPurchased }: { onPurchased?: (id: number | string) => void
     const sig = `${domainId}:${JSON.stringify(body)}`;
     if (key.current?.sig !== sig) key.current = { sig, value: newIdempotencyKey() };
     const res = objectOf(await g8Post(`/provider-domains/${domainId}/checkout-mailboxes`, body, { idempotencyKey: key.current.value }));
-    setDone(`Accepted ${res.count ?? names.length} mailbox${names.length === 1 ? "" : "es"}; provisioning continues in the background.`);
+    setDone(`Accepted ${plural(Number(res.count ?? names.length), "mailbox", "mailboxes")}; provisioning continues in the background.`);
     onPurchased?.(domainId);
   });
-  const connected = listOf<DomainRow>(domains.data).filter((d) => d.provider_connected);
+  const connected = domains.items.filter((d) => d.provider_connected);
   const ready = domainId && names.length > 0 && person.first_name.trim() && person.last_name.trim();
 
   return (
     <div className="space-y-3">
       {domains.error ? <ApiError error={domains.error} onRetry={() => void domains.refetch()} /> : null}
       {!domains.loading && connected.length === 0 ? (
-        <p className="text-sm text-gray-600">No connected domain yet. Buy and connect one with DomainPurchase first.</p>
+        <p className="text-sm text-muted-foreground">No connected domain yet. Buy and connect one with DomainPurchase first.</p>
       ) : (
         <div className="grid gap-2 sm:grid-cols-2">
           <select
             aria-label="Domain"
-            className="h-9 rounded-md border border-gray-300 px-2 text-sm"
+            className="h-9 rounded-md border border-input px-2 text-sm"
             value={domainId}
             onChange={(e) => setDomainId(e.target.value)}
           >
@@ -187,7 +196,7 @@ function BuyForm({ onPurchased }: { onPurchased?: (id: number | string) => void
           </select>
           <select
             aria-label="Platform"
-            className="h-9 rounded-md border border-gray-300 px-2 text-sm"
+            className="h-9 rounded-md border border-input px-2 text-sm"
             value={platform}
             onChange={(e) => setPlatform(e.target.value as "GOOGLE" | "MICROSOFT")}
           >
@@ -219,11 +228,11 @@ function BuyForm({ onPurchased }: { onPurchased?: (id: number | string) => void
         </div>
       )}
       <Button disabled={!ready} onClick={() => setConfirming(true)}>
-        Buy {names.length || ""} mailbox{names.length === 1 ? "" : "es"}
+        Buy {names.length || ""} {pluralWord(names.length, "mailbox", "mailboxes")}
       </Button>
       {buy.error ? <ApiError error={buy.error} onRetry={buy.reset} /> : null}
       {done ? (
-        <p role="status" className="text-sm text-green-700">
+        <p role="status" className="text-sm text-positive-foreground">
           {done}
         </p>
       ) : null}
@@ -231,8 +240,8 @@ function BuyForm({ onPurchased }: { onPurchased?: (id: number | string) => void
         <ConfirmSpendDialog
           open
           tier="billable"
-          title={`Buy ${names.length} mailbox${names.length === 1 ? "" : "es"}: ${names.join(", ")}`}
-          description="Mailboxes are billed monthly while they exist, plus warmup if enabled. This is an estimate: graph8 has no balance read."
+          title={`Buy ${plural(names.length, "mailbox", "mailboxes")}: ${names.join(", ")}`}
+          description={`Mailboxes are billed monthly while they exist, plus warmup if enabled. This is an estimate: ${brand.linkLabel} has no balance read.`}
           estimatedCredits={names.length * perMailbox}
           confirmLabel="Buy mailboxes"
           confirming={buy.loading}
@@ -244,8 +253,10 @@ function BuyForm({ onPurchased }: { onPurchased?: (id: number | string) => void
   );
 }
 
-export function ConnectMailbox({ appUrl = GRAPH8_APP_MAILBOXES_URL, onConnected, onPurchased, className }: ConnectMailboxProps) {
-  const [mode, setMode] = useState<Mode>("imap");
+export function ConnectMailbox({ appUrl: appUrlProp, onConnected, onPurchased, initialMode = "imap", domainId, className }: ConnectMailboxProps) {
+  const brand = useBrand();
+  const appUrl = appUrlProp ?? brandUrl(brand, GRAPH8_APP_MAILBOXES_PATH);
+  const [mode, setMode] = useState<Mode>(initialMode);
   return (
     <div className={`space-y-4 ${className ?? ""}`}>
       <div className="inline-flex gap-1" role="group" aria-label="How to add a mailbox">
@@ -266,19 +277,19 @@ export function ConnectMailbox({ appUrl = GRAPH8_APP_MAILBOXES_URL, onConnected,
       </div>
       {mode === "imap" ? <ImapForm onConnected={onConnected} /> : null}
       {mode === "oauth" ? (
-        <div className="space-y-2 rounded border border-gray-200 p-3 text-sm">
+        <div className="space-y-2 rounded border border-border p-3 text-sm">
           <p>
-            Google and Microsoft mailboxes connect through a sign-in screen that only runs inside the graph8 app. Connect it there, then
+            Google and Microsoft mailboxes connect through a sign-in screen that only runs inside the {brand.linkLabel} app. Connect it there, then
             come back: it appears in your mailbox list.
           </p>
           <Button asChild>
             <a href={appUrl} target="_blank" rel="noreferrer">
-              Open graph8 to connect
+              Open {brand.linkLabel} to connect
             </a>
           </Button>
         </div>
       ) : null}
-      {mode === "buy" ? <BuyForm onPurchased={onPurchased} /> : null}
+      {mode === "buy" ? <BuyForm onPurchased={onPurchased} domainId={domainId} /> : null}
     </div>
   );
 }