@graph8/sdk 0.361.0 → 0.370.0

package/blocks/mailboxes/components/domain-detail.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+/**
+ * DomainDetail: one sending domain, complete. Every field, the mailboxes on it, and every action: connect it
+ * to mailbox provisioning, check DNS propagation, buy mailboxes on it.
+ *
+ * SDK operations, in order:
+ *   1. listProviderDomains   GET  /provider-domains                        (read; the row for this domain)
+ *   2. listMailboxes         GET  /mailboxes                               (read; mailboxes whose address ends with the domain)
+ *   3. connectProvider       POST /provider-domains/{domain_id}/connect-provider    (billable tier: confirmed)
+ *   4. checkDomainPropagation POST /provider-domains/{domain_id}/check-propagation  (billable tier: confirmed)
+ *   Buying mailboxes is the ConnectMailbox "Buy" tab, opened by `onBuyMailboxes` (confirmed with a credit estimate there).
+ *
+ * Tiers: 3 and 4 are billable in the contract (no credit estimate is known), so each opens ConfirmSpendDialog.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { 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 { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { fieldItems, listOf, objectOf } from "../lib/mailboxes-utils";
+import type { DomainRow, MailboxRow } from "../lib/mailboxes-utils";
+
+export interface DomainDetailProps {
+  domainId: string | number;
+  onClose?: () => void;
+  /** Full-page mode: show an "Open full page" (onExpand) or "Back to split view" (onCollapse) button. */
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  /** Called after a connect so a list can refresh. */
+  onChanged?: () => void;
+  /** Open the Buy tab of ConnectMailbox for this domain (a screen shows it in a sheet). */
+  onBuyMailboxes?: (domain: DomainRow) => void;
+  onOpenMailbox?: (mailbox: MailboxRow) => void;
+  renderActions?: (domain: DomainRow) => ReactNode;
+  className?: string;
+}
+
+type Pending = "connect" | "propagation";
+
+export function DomainDetail({ domainId, onClose, onExpand, onCollapse, onChanged, onBuyMailboxes, onOpenMailbox, renderActions, className }: DomainDetailProps) {
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [note, setNote] = useState<string | null>(null);
+  const domains = useG8Query((signal) => g8Get("/provider-domains", { page: 1, limit: 100 }, { signal }), [domainId]);
+  const mailboxes = useG8Query((signal) => g8Get("/mailboxes", { limit: 200 }, { signal }), [domainId]);
+
+  const row = listOf<DomainRow>(domains.data).find((d) => String(d.id) === String(domainId));
+  const run = useG8Mutation(async (p: Pending) => {
+    if (p === "connect") {
+      await g8Post(`/provider-domains/${domainId}/connect-provider`, {});
+      setNote(`${row?.domain ?? "The domain"} is connecting. Check propagation in a few minutes.`);
+      await domains.refetch();
+      onChanged?.();
+    } else {
+      const status = objectOf(await g8Post(`/provider-domains/${domainId}/check-propagation`, {}));
+      setNote(status.propagated ? `${row?.domain} has propagated.` : `${row?.domain} has not propagated yet.`);
+    }
+    setPending(null);
+  }, { onError: () => setPending(null) });
+
+  if (domains.error) return <ApiError error={domains.error} title="Could not load the domain" onRetry={() => void domains.refetch()} className={className} />;
+  if (domains.loading && !domains.data) return <Skeleton className={`h-48 w-full ${className ?? ""}`} />;
+  if (!row) return <p className={`p-4 text-sm ${className ?? ""}`}>This domain no longer exists.</p>;
+
+  const onDomain = listOf<MailboxRow>(mailboxes.data).filter((m) => (m.email ?? "").toLowerCase().endsWith(`@${row.domain.toLowerCase()}`));
+  return (
+    <DetailPanel
+      className={className}
+      title={row.domain}
+      subtitle={row.source ?? undefined}
+      badges={
+        <>
+          <StatusPill tone={row.provider_connected ? "positive" : "warning"} dot>{row.provider_connected ? "Connected" : "Not connected"}</StatusPill>
+          {row.status ? <StatusPill tone="neutral">{row.status}</StatusPill> : null}
+        </>
+      }
+      actions={
+        <>
+          {!row.provider_connected ? <Button size="sm" variant="outline" onClick={() => setPending("connect")}>Connect domain</Button> : null}
+          <Button size="sm" variant="outline" onClick={() => setPending("propagation")}>Check DNS</Button>
+          <Button size="sm" disabled={!row.provider_connected || !onBuyMailboxes} onClick={() => onBuyMailboxes?.(row)}>Buy mailboxes</Button>
+          {renderActions?.(row)}
+          <ConfirmSpendDialog
+            open={pending !== null}
+            tier="billable"
+            title={pending === "connect" ? `Connect ${row.domain}` : `Check DNS propagation for ${row.domain}`}
+            description={pending === "connect" ? "Connects the domain to mailbox provisioning. Required before buying mailboxes on it." : "Asks the provider whether the nameservers have propagated."}
+            confirmLabel={pending === "connect" ? "Connect domain" : "Check propagation"}
+            confirming={run.loading}
+            onCancel={() => setPending(null)}
+            onConfirm={() => pending && void run.mutate(pending)}
+          />
+        </>
+      }
+      summary={note ? <p role="status" className="text-sm">{note}</p> : undefined}
+      onClose={onClose}
+      onExpand={onExpand}
+      onCollapse={onCollapse}
+      tabs={[
+        {
+          id: "details",
+          label: "Details",
+          content: (
+            <div className="space-y-4">
+              {run.error ? <ApiError error={run.error} onRetry={run.reset} /> : null}
+              <KeyValueList columns={2} items={fieldItems(row as unknown as Record<string, unknown>)} />
+            </div>
+          ),
+        },
+        {
+          id: "mailboxes",
+          label: "Mailboxes",
+          count: onDomain.length,
+          content: (
+            <SectionCard title="Mailboxes on this domain" description="Open one for warmup and health.">
+              {onDomain.length === 0 ? (
+                <p className="text-sm text-muted-foreground">{row.provider_connected ? "No mailboxes yet. Buy some with the button above." : "Connect the domain first, then buy mailboxes on it."}</p>
+              ) : (
+                <ul className="divide-y">
+                  {onDomain.map((m) => (
+                    <li key={m.id} className="flex items-center justify-between py-2 text-sm">
+                      <Button variant="ghost" size="sm" onClick={() => onOpenMailbox?.(m)}>{m.email}</Button>
+                      <StatusPill tone={m.connection_status === "active" ? "positive" : "warning"} dot>{m.connection_status ?? "unknown"}</StatusPill>
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </SectionCard>
+          ),
+        },
+      ]}
+    />
+  );
+}

package/blocks/mailboxes/components/domain-purchase.tsx

@@ -28,6 +28,8 @@ import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { DEFAULT_DOMAIN_CREDITS, listOf, newIdempotencyKey, objectOf, statusClass } from "../lib/mailboxes-utils";
 import type { DomainRow } from "../lib/mailboxes-utils";
+import { plural } from "@/g8/lib/plural";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface DomainPurchaseProps {
   /** Called after a purchase was accepted (provisioning continues in the background). */
@@ -54,6 +56,7 @@ function suggestionsOf(envelope: unknown): string[] {
 }
 
 export function DomainPurchase({ onPurchased, className }: DomainPurchaseProps) {
+  const brand = useBrand();
   const [keyword, setKeyword] = useState("");
   const [names, setNames] = useState<string[]>([]);
   const [selected, setSelected] = useState<string[]>([]);
@@ -109,7 +112,7 @@ export function DomainPurchase({ onPurchased, className }: DomainPurchaseProps)
     if (!pending) return null;
     if (pending.kind === "check")
       return {
-        title: `Check ${pending.domains.length} domain${pending.domains.length === 1 ? "" : "s"}`,
+        title: `Check ${plural(pending.domains.length, "domain")}`,
         description: "Looks up availability and price. The API documents no charge for this check.",
         credits: 0,
         label: "Check availability",
@@ -209,7 +212,7 @@ export function DomainPurchase({ onPurchased, className }: DomainPurchaseProps)
           />
         </div>
         <Button disabled={buyable.length === 0 || !contactOk} onClick={() => setPending({ kind: "buy", domains: buyable })}>
-          Buy {buyable.length} domain{buyable.length === 1 ? "" : "s"}
+          Buy {plural(buyable.length, "domain")}
         </Button>
       </section>
 
@@ -226,7 +229,7 @@ export function DomainPurchase({ onPurchased, className }: DomainPurchaseProps)
         ) : domains.loading && !domains.data ? (
           <Skeleton className="h-16 w-full" />
         ) : rows.length === 0 ? (
-          <EmptyState title="No sending domains yet" description="Buy one above, or add a domain you already own in the graph8 app." />
+          <EmptyState title="No sending domains yet" description={`Buy one above, or add a domain you already own in the ${brand.linkLabel} app.`} />
         ) : (
           <ul className="divide-y rounded border border-gray-200">
             {rows.map((d) => (

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

@@ -0,0 +1,156 @@
+"use client";
+
+/**
+ * MailboxDetail: one mailbox, complete. Every field the API returns, the domain it sits on, its warmup and
+ * deliverability, and every action: test the connection, archive or restore, delete.
+ *
+ * SDK operations, in order:
+ *   1. getMailbox             GET    /mailboxes/{mailbox_id}                (read; all fields)
+ *   2. listProviderDomains    GET    /provider-domains                      (read; finds the domain this address sits on)
+ *   3. testMailboxConnection  POST   /mailboxes/{mailbox_id}/test-connection (write; SMTP and IMAP, no spend)
+ *   4. archiveMailbox         POST   /mailboxes/{mailbox_id}/archive        (destructive: confirmed; `is_archived: false` restores)
+ *   5. deleteMailbox          DELETE /mailboxes/{mailbox_id}                (destructive: confirmed)
+ *   Warmup tab: WarmupHealth (analytics, start/stop warmup, confirmed placement test).
+ *
+ * Tiers: 4 and 5 are destructive, so each opens ConfirmSpendDialog. Credentials are write-only and never shown.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+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 { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { fieldItems, listOf, objectOf } from "../lib/mailboxes-utils";
+import type { DomainRow, MailboxRow } from "../lib/mailboxes-utils";
+import { WarmupHealth } from "./warmup-health";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface MailboxDetailProps {
+  mailboxId: string | number;
+  /** Controlled tab ("details" | "warmup" | an extra tab id) and its change handler, for deep links. */
+  tab?: string;
+  onTabChange?: (tab: string) => void;
+  onClose?: () => void;
+  /** Full-page mode: show an "Open full page" (onExpand) or "Back to split view" (onCollapse) button. */
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  /** Called after archive, restore or delete so a list can refresh. */
+  onChanged?: () => void;
+  /** Open the domain this mailbox sits on. */
+  onOpenDomain?: (domain: DomainRow) => void;
+  renderActions?: (mailbox: MailboxRow) => ReactNode;
+  extraTabs?: { id: string; label: string; render: (mailbox: MailboxRow) => ReactNode }[];
+  className?: string;
+}
+
+type Pending = "archive" | "restore" | "delete";
+interface TestResult { success?: boolean; smtp?: { success?: boolean; error?: string }; imap?: { success?: boolean; error?: string } }
+
+export function MailboxDetail({ mailboxId, tab, onTabChange, onClose, onExpand, onCollapse, onChanged, onOpenDomain, renderActions, extraTabs, className }: MailboxDetailProps) {
+  const brand = useBrand();
+  const [pending, setPending] = useState<Pending | null>(null);
+  const [testNote, setTestNote] = useState<string | null>(null);
+  const q = useG8Query((signal) => g8Get(`/mailboxes/${mailboxId}`, undefined, { signal }), [mailboxId]);
+  const domains = useG8Query((signal) => g8Get("/provider-domains", { page: 1, limit: 100 }, { signal }), []);
+
+  const test = useG8Mutation(async () => {
+    const r = objectOf(await g8Post(`/mailboxes/${mailboxId}/test-connection`, {})) as TestResult;
+    setTestNote(
+      r.success
+        ? "SMTP and IMAP both work"
+        : [r.smtp?.success === false && `SMTP: ${r.smtp.error ?? "failed"}`, r.imap?.success === false && `IMAP: ${r.imap.error ?? "failed"}`].filter(Boolean).join("; ") || "Connection failed",
+    );
+    await q.refetch();
+  });
+  const act = useG8Mutation(async (p: Pending) => {
+    if (p === "delete") await g8Delete(`/mailboxes/${mailboxId}`);
+    else await g8Post(`/mailboxes/${mailboxId}/archive`, { is_archived: p === "archive" });
+    setPending(null);
+    if (p === "delete") onClose?.();
+    else await q.refetch();
+    onChanged?.();
+  }, { onError: () => setPending(null) });
+
+  if (q.error) return <ApiError error={q.error} title="Could not load the mailbox" onRetry={() => void q.refetch()} className={className} />;
+  if (q.loading && !q.data) return <Skeleton className={`h-48 w-full ${className ?? ""}`} />;
+  const raw = objectOf(q.data);
+  const m = { id: String(mailboxId), email: null, ...raw } as MailboxRow;
+  const domain = (m.email ?? "").split("@")[1]?.toLowerCase();
+  const domainRow = listOf<DomainRow>(domains.data).find((d) => d.domain?.toLowerCase() === domain);
+  const status = m.connection_status ?? "unknown";
+  const name = m.email ?? `Mailbox ${mailboxId}`;
+
+  return (
+    <DetailPanel
+      className={className}
+      title={name}
+      subtitle={[m.display_name, m.provider].filter(Boolean).join(" - ") || undefined}
+      avatar={<EntityAvatar name={m.display_name || name} size="lg" />}
+      badges={
+        <>
+          <StatusPill tone={status === "active" ? "positive" : status === "unknown" ? "neutral" : "warning"} dot>{status}</StatusPill>
+          {m.is_archived ? <StatusPill tone="neutral">archived</StatusPill> : null}
+        </>
+      }
+      actions={
+        <>
+          <Button size="sm" variant="outline" loading={test.loading} onClick={() => void test.mutate(undefined)}>Test connection</Button>
+          <Button size="sm" variant="outline" onClick={() => setPending(m.is_archived ? "restore" : "archive")}>{m.is_archived ? "Restore mailbox" : "Archive mailbox"}</Button>
+          <Button size="sm" variant="outline" onClick={() => setPending("delete")}>Delete mailbox</Button>
+          {renderActions?.(m)}
+          <ConfirmSpendDialog
+            open={pending !== null}
+            tier="destructive"
+            title={`${pending === "delete" ? "Delete" : pending === "restore" ? "Restore" : "Archive"} ${name}`}
+            description={
+              pending === "delete" ? "Sequences that send from it can no longer send. This cannot be undone."
+                : pending === "restore" ? "It comes back into pickers. Nothing is deleted."
+                  : "It disappears from pickers. History is kept and you can restore it."
+            }
+            confirmLabel={pending === "delete" ? "Delete mailbox" : pending === "restore" ? "Restore mailbox" : "Archive mailbox"}
+            affected={1}
+            confirming={act.loading}
+            onCancel={() => setPending(null)}
+            onConfirm={() => pending && void act.mutate(pending)}
+          />
+        </>
+      }
+      summary={testNote ? <p role="status" className="px-5 py-2 text-sm">{testNote}</p> : undefined}
+      onClose={onClose}
+      onExpand={onExpand}
+      onCollapse={onCollapse}
+      activeTab={tab}
+      onTabChange={onTabChange}
+      tabs={[
+        {
+          id: "details",
+          label: "Details",
+          content: (
+            <div className="space-y-4">
+              {test.error ? <ApiError error={test.error} onRetry={test.reset} /> : null}
+              {act.error ? <ApiError error={act.error} onRetry={act.reset} /> : null}
+              <KeyValueList columns={2} items={fieldItems(raw)} />
+              <SectionCard title="Domain" description="The sending domain this address belongs to.">
+                {domainRow ? (
+                  <Button size="sm" variant="outline" disabled={!onOpenDomain} onClick={() => onOpenDomain?.(domainRow)}>{domainRow.domain}</Button>
+                ) : (
+                  <p className="text-sm text-muted-foreground">{domain ? `${domain} is not a domain bought or connected through ${brand.linkLabel}.` : "No domain."}</p>
+                )}
+              </SectionCard>
+            </div>
+          ),
+        },
+        { id: "warmup", label: "Warmup and health", content: <WarmupHealth mailboxId={mailboxId} showFleet={false} /> },
+        ...(extraTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(m) })),
+      ]}
+    />
+  );
+}

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

@@ -0,0 +1,223 @@
+"use client";
+
+/**
+ * MailboxesScreen: the finished "Mailboxes" settings page. Everything about the inboxes you send from.
+ *
+ * Composes: MailboxList, MailboxDetail (every field, warmup, test, archive, restore, delete), DomainDetail, WarmupHealth (fleet verdict, per-mailbox warmup and
+ * placement test), ConnectMailbox (IMAP/SMTP, Google/Microsoft link-out, buy mailboxes), DomainPurchase
+ * (suggest, check, buy, connect, DNS).
+ *
+ * User flows:
+ *   - See fleet health at a glance (stat strip from the deliverability summary).
+ *   - Every record opens a complete detail (MailboxDetail, DomainDetail) beside the list or as a full page
+ *     (`?view=full`), deep-linked with `?id=`, `?tab=`, `?dtab=`.
+ *   - Mailboxes tab: browse mailboxes, show archived (an archived one can be restored, confirmed), test a connection, archive or delete (confirmed),
+ *     open one (deep link `?id=`) for warmup analytics, start/stop warmup and a confirmed placement test.
+ *   - "Add mailbox" opens a sheet: connect over IMAP/SMTP, open the graph8 app for Google/Microsoft, or buy
+ *     mailboxes on a connected domain (confirmed with a credit estimate).
+ *   - Deliverability tab: the safe-to-send verdict, fleet counts and degraded mailboxes.
+ *   - Domains tab: suggest, check availability, buy (confirmed), connect and check DNS propagation.
+ *
+ * SDK operations: none of its own, plus one read for the stat strip:
+ *   getFleetSummary  GET /deliverability/fleet-summary  (read)
+ * Billable and destructive calls live in the composed parts and open ConfirmSpendDialog there.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Mail, Plus } from "lucide-react";
+import { Button } from "@graph8/sdk/ui";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import type { StatItem } from "@/g8/components/screen/stat-strip";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Skeleton } from "@graph8/sdk/ui";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { listOf, objectOf } from "../lib/mailboxes-utils";
+import type { DomainRow, MailboxRow } from "../lib/mailboxes-utils";
+import { ConnectMailbox } from "./connect-mailbox";
+import { DomainPurchase } from "./domain-purchase";
+import { DomainDetail } from "./domain-detail";
+import { MailboxDetail } from "./mailbox-detail";
+import { MailboxList } from "./mailbox-list";
+import { WarmupHealth } from "./warmup-health";
+
+export interface MailboxesScreenProps {
+  /** Where the person connects Google or Microsoft. Default: graph8 Settings > Purchase > Mailboxes. */
+  appUrl?: string;
+  /** Extra buttons in the toolbar. */
+  toolbarActions?: ReactNode;
+  /** Extra buttons in the open mailbox's header. */
+  renderDetailActions?: (mailbox: MailboxRow) => ReactNode;
+  /** Extra tabs in the open mailbox's panel. */
+  extraDetailTabs?: { id: string; label: string; render: (mailbox: MailboxRow) => ReactNode }[];
+  className?: string;
+}
+
+const TABS = [
+  { id: "mailboxes", label: "Mailboxes" },
+  { id: "deliverability", label: "Deliverability" },
+  { id: "domains", label: "Domains" },
+];
+
+const STAT_ORDER = ["total", "healthy", "watch", "paused", "inbox_rate"];
+
+function label(key: string): string {
+  const s = key.replace(/_/g, " ");
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/** Up to four numeric fleet fields; a 0..1 rate reads as a percent. Unknown shapes just show what is there. */
+export function fleetStats(summary: Record<string, unknown>): StatItem[] {
+  const nums = Object.entries(summary).filter(([, v]) => typeof v === "number") as Array<[string, number]>;
+  nums.sort((a, b) => (STAT_ORDER.indexOf(a[0]) + 1 || 99) - (STAT_ORDER.indexOf(b[0]) + 1 || 99));
+  return nums.slice(0, 4).map(([k, v]) => ({
+    label: label(k),
+    value: k.includes("rate") && v <= 1 ? `${Math.round(v * 100)}%` : v.toLocaleString(),
+    tone: k === "healthy" ? "positive" : k === "watch" ? "warning" : undefined,
+  }));
+}
+
+function DomainList({ version, selectedId, onOpen }: { version: number; selectedId: string; onOpen: (d: DomainRow) => void }) {
+  const q = useG8Query((signal) => g8Get("/provider-domains", { page: 1, limit: 100 }, { signal }), [version]);
+  const rows = listOf<DomainRow>(q.data);
+  if (q.loading && !q.data) return <Skeleton className="h-24 w-full" />;
+  if (rows.length === 0) return null;
+  return (
+    <ul aria-label="Your domains" className="divide-y rounded-md border">
+      {rows.map((d) => (
+        <li key={d.id} className={`flex items-center justify-between px-3 py-2 text-sm ${String(d.id) === selectedId ? "bg-muted" : ""}`}>
+          <button type="button" className="font-medium hover:underline" onClick={() => onOpen(d)}>{d.domain}</button>
+          <span className="flex items-center gap-2">
+            {d.mailbox_count != null ? <span className="text-xs text-muted-foreground">{d.mailbox_count} mailboxes</span> : null}
+            <StatusPill tone={d.provider_connected ? "positive" : "warning"} dot>{d.provider_connected ? "Connected" : "Not connected"}</StatusPill>
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export function MailboxesScreen({ appUrl, toolbarActions, renderDetailActions, extraDetailTabs, className }: MailboxesScreenProps) {
+  const [tab, setTab] = useUrlState("tab", "mailboxes");
+  const [selectedId, setSelectedId] = useUrlState("id", "");
+  const [detailTab, setDetailTab] = useUrlState("dtab", "");
+  const [view, setView] = useUrlState("view", "");
+  const [archived, setArchived] = useState(false);
+  const [adding, setAdding] = useState<{ domainId?: number | string } | null>(null);
+  const [version, setVersion] = useState(0);
+  const summary = useG8Query((signal) => g8Get("/deliverability/fleet-summary", undefined, { signal }), [version]);
+  const stats = fleetStats(objectOf(summary.data));
+  const bump = () => setVersion((v) => v + 1);
+
+  const go = (nextTab: string, id: string) => {
+    setTab(nextTab === "mailboxes" ? null : nextTab);
+    setSelectedId(id || null);
+    setDetailTab(null);
+    setView(null);
+  };
+  const close = () => { setSelectedId(null); setDetailTab(null); setView(null); };
+  const add = (
+    <Button onClick={() => setAdding({})}>
+      <Plus className="mr-1 h-4 w-4" aria-hidden /> Add mailbox
+    </Button>
+  );
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Mailboxes"
+      description="The inboxes you send from: connect, warm up and keep them healthy."
+      icon={<Mail className="h-5 w-5" aria-hidden />}
+      actions={add}
+      tabs={TABS}
+      activeTab={TABS.some((t) => t.id === tab) ? tab : "mailboxes"}
+      onTabChange={(id) => go(id, "")}
+      stats={stats.length > 0 ? stats : undefined}
+    >
+      {tab === "deliverability" ? (
+        <WarmupHealth />
+      ) : tab === "domains" ? (
+        <SplitView
+          expanded={view === "full"} onExpandedChange={(e) => setView(e ? "full" : null)}
+          detailOpen={Boolean(selectedId)}
+          onCloseDetail={close}
+          list={
+            <div className="space-y-4">
+              <DomainList version={version} selectedId={selectedId} onOpen={(d) => go("domains", String(d.id))} />
+              <DomainPurchase onPurchased={bump} />
+            </div>
+          }
+          detail={
+            selectedId ? (
+              <DomainDetail
+                key={selectedId}
+                domainId={selectedId}
+                onExpand={view === "full" ? undefined : () => setView("full")} onCollapse={view === "full" ? () => setView(null) : undefined}
+                onClose={close}
+                onChanged={bump}
+                onBuyMailboxes={(d) => setAdding({ domainId: d.id })}
+                onOpenMailbox={(m) => go("mailboxes", m.id)}
+              />
+            ) : null
+          }
+        />
+      ) : (
+        <div className="space-y-3">
+          <Toolbar
+            actions={toolbarActions}
+            filters={
+              <label className="flex items-center gap-2 text-sm text-muted-foreground">
+                <input type="checkbox" checked={archived} onChange={(e) => setArchived(e.target.checked)} />
+                Show archived
+              </label>
+            }
+          />
+          <SplitView
+            expanded={view === "full"} onExpandedChange={(e) => setView(e ? "full" : null)}
+            detailOpen={Boolean(selectedId)}
+            onCloseDetail={close}
+            list={<MailboxList key={`${version}:${archived}`} includeArchived={archived} onSelect={(m) => go("mailboxes", m.id)} emptyAction={add} />}
+            detail={
+              selectedId ? (
+                <MailboxDetail
+                  key={selectedId}
+                  mailboxId={selectedId}
+                  onExpand={view === "full" ? undefined : () => setView("full")} onCollapse={view === "full" ? () => setView(null) : undefined}
+                  tab={detailTab || undefined}
+                  onTabChange={(t) => setDetailTab(t === "details" ? null : t)}
+                  onClose={close}
+                  onChanged={bump}
+                  onOpenDomain={(d) => go("domains", String(d.id))}
+                  renderActions={renderDetailActions}
+                  extraTabs={extraDetailTabs}
+                />
+              ) : null
+            }
+          />
+        </div>
+      )}
+      <FormSheet
+        width="lg"
+        open={adding !== null}
+        onOpenChange={(o) => !o && setAdding(null)}
+        title={adding?.domainId != null ? "Buy mailboxes" : "Add a mailbox"}
+        description="Connect one you own, use Google or Microsoft, or buy new ones."
+      >
+        {adding ? (
+          <ConnectMailbox
+            appUrl={appUrl}
+            initialMode={adding.domainId != null ? "buy" : "imap"}
+            domainId={adding.domainId}
+            onConnected={() => { setAdding(null); bump(); }}
+            onPurchased={bump}
+          />
+        ) : null}
+      </FormSheet>
+    </ScreenLayout>
+  );
+}

package/blocks/mailboxes/components/warmup-health.tsx

@@ -29,6 +29,8 @@ import { listOf, objectOf, PLACEMENT_TEST_CREDITS, scalars, statusClass } from "
 export interface WarmupHealthProps {
   /** Show warmup analytics and controls for this mailbox (an id from MailboxList). */
   mailboxId?: string | number;
+  /** Show the fleet verdict and counts above the mailbox section. Default true; screens that already show them pass false. */
+  showFleet?: boolean;
   className?: string;
 }
 
@@ -222,10 +224,10 @@ function MailboxWarmup({ mailboxId }: { mailboxId: string | number }) {
   );
 }
 
-export function WarmupHealth({ mailboxId, className }: WarmupHealthProps) {
+export function WarmupHealth({ mailboxId, showFleet = true, className }: WarmupHealthProps) {
   return (
     <div className={`space-y-4 ${className ?? ""}`}>
-      <Fleet />
+      {showFleet || mailboxId == null ? <Fleet /> : null}
       {mailboxId != null ? <MailboxWarmup mailboxId={mailboxId} /> : null}
     </div>
   );

package/blocks/mailboxes/lib/mailboxes-utils.ts

@@ -2,8 +2,13 @@
 
 /** Types and helpers shared by the mailbox components. Open-shaped payloads: every field is optional. */
 
+import { DEFAULT_BRAND } from "@/g8/hooks/use-brand";
+
 /** Where the person connects a Google or Microsoft mailbox. OAuth consent can only run in the graph8 app. */
-export const GRAPH8_APP_MAILBOXES_URL = "https://app.graph8.com/studio/settings?tab=purchase&view=mailboxes";
+/** The path on the platform's web app; components resolve it against the brand (`brandUrl(useBrand(), ...)`). */
+export const GRAPH8_APP_MAILBOXES_PATH = "/studio/settings?tab=purchase&view=mailboxes";
+/** The default (graph8) URL. Kept for existing imports; prefer GRAPH8_APP_MAILBOXES_PATH with useBrand. */
+export const GRAPH8_APP_MAILBOXES_URL = `${DEFAULT_BRAND.appUrl}${GRAPH8_APP_MAILBOXES_PATH}`;
 
 /** The API holds these when you buy (docs/developer-api-reference.md, Channel Purchase); the real rate can change. */
 export const DEFAULT_DOMAIN_CREDITS = 2500;
@@ -67,3 +72,19 @@ export function newIdempotencyKey(): string {
     ? crypto.randomUUID()
     : `g8-${Date.now()}-${Math.random().toString(36).slice(2)}`;
 }
+
+const HIDDEN_FIELDS = /password|secret|token|credential/i;
+
+/** Every readable field of an open-shaped record as label/value pairs (secrets are never shown). */
+export function fieldItems(obj: Record<string, unknown>): Array<{ label: string; value: string }> {
+  return Object.entries(obj)
+    .filter(([k, v]) => !HIDDEN_FIELDS.test(k) && v !== null && v !== undefined && v !== "")
+    .map(([k, v]) => {
+      const label = k.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+      if (typeof v === "string" && /_at$|date$/.test(k) && !Number.isNaN(new Date(v).getTime()))
+        return { label, value: new Date(v).toLocaleString("en-US", { dateStyle: "medium", timeStyle: "short", timeZone: "UTC" }) + " UTC" };
+      if (typeof v === "boolean") return { label, value: v ? "Yes" : "No" };
+      if (typeof v === "object") return { label, value: JSON.stringify(v) };
+      return { label, value: String(v) };
+    });
+}

package/blocks/newsletter/README.md

@@ -4,6 +4,18 @@ Write, test, schedule and send newsletter issues, manage subscribers, and read o
 **Sending reaches real inboxes and cannot be recalled**, so every call that can mail a person is tier `external`
 and goes through `ConfirmSpendDialog` with the recipient count.
 
+## Screens
+
+`NewsletterScreen` (`components/newsletter-screen.tsx`) is the finished page: mount it and a person can run a newsletter end to end, no extra code.
+
+```tsx
+import { NewsletterScreen } from "@/g8/newsletter/components/newsletter-screen";
+export default function Page() { return <NewsletterScreen />; }
+```
+
+Flows: pick or create a newsletter (deep link `?newsletter=`), activate or pause it, read subscribers and open and click rates, search and filter issues, write an issue (deep link `?id=`), generate it with AI, send a test, send now or schedule, follow the send and pause, resume or cancel it, read per-issue results, manage subscribers (add, import a list, verify, unsubscribe, erase), compare sent issues. Every send, import, verify, unsubscribe and erase is confirmed.
+Prerequisites are the ones below (verified sending domain, consent, `campaigns:launch`). Optional props: `renderRowActions`, `renderDetailActions`, `extraDetailTabs`, `toolbarActions`.
+
 ## Install
 
 ```
@@ -82,6 +94,7 @@ export default function Page() {
 
 | Component | File | What it is |
 |---|---|---|
+| `NewsletterScreen` | `components/newsletter-screen.tsx` | The finished page: issues with write, send and results, subscribers and performance. |
 | `NewsletterEditor` | `components/newsletter-editor.tsx` | Pick or create a newsletter, list its issues, write issues and activate or pause the newsletter. |
 | `IssueForm` | `components/issue-form.tsx` | Draft one issue: subject, preview text, HTML, AI generation, test send and delete of drafts. |
 | `IssueScheduler` | `components/issue-scheduler.tsx` | Send an issue now or schedule it, confirmed with the subscriber count, then follow, pause, resume or cancel the send. |