@graph8/sdk 0.308.1 → 0.357.0

package/blocks/lists/components/suppression-manager.tsx

@@ -0,0 +1,153 @@
+"use client";
+
+/**
+ * SuppressionManager: the do-not-contact ledger. See who is suppressed (filter by channel and
+ * reason category), suppress contacts by id, check one contact, and reinstate contacts.
+ *
+ * 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)
+ *   3. checkContactSuppression GET  /contacts/{contact_id}/suppression                     (read)
+ *   4. reinstateSuppressions   POST /contacts/suppressions/reinstate  { contact_ids, reason }   (write, but it lets
+ *                              sequences and campaigns contact people again, so it goes through ConfirmSpendDialog as "external")
+ *
+ * The ledger holds ids, not names or emails (no personal data): resolve a name with ContactDetail.
+ * Suppressing only ever REDUCES outreach, so it runs without a confirmation.
+ */
+
+import { useState } from "react";
+import { Button, Input, Label, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, 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 { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+
+export interface SuppressionRecord {
+  id: string;
+  contact_id: number;
+  channel: string;
+  category: string;
+  source?: string | null;
+  reason?: string | null;
+  created_at?: string | null;
+}
+
+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[] }
+
+export interface SuppressionManagerProps {
+  pageSize?: number;
+  /** Open the contact behind a ledger row in your ContactDetail. */
+  onOpenContact?: (contactId: number) => void;
+  className?: string;
+}
+
+/** "12, 15 16\n17" -> [12, 15, 16, 17]. Anything that is not a positive whole number is dropped. */
+export function parseIds(text: string): number[] {
+  return [...new Set(text.split(/[\s,;]+/).map(Number).filter((n) => Number.isInteger(n) && n > 0))];
+}
+
+export function SuppressionManager({ pageSize = 50, onOpenContact, className }: SuppressionManagerProps) {
+  const [channel, setChannel] = useState("");
+  const [category, setCategory] = useState("");
+  const [offset, setOffset] = useState(0);
+  const [idsText, setIdsText] = useState("");
+  const [addChannel, setAddChannel] = useState("all");
+  const [reason, setReason] = useState("");
+  const [picked, setPicked] = useState<Set<number>>(new Set());
+  const [confirmReinstate, setConfirmReinstate] = useState(false);
+  const [checkId, setCheckId] = useState("");
+  const [reinstateReason, setReinstateReason] = useState("");
+
+  const ledger = useG8Query((signal) => g8Get<SuppressionRecord[]>("/contacts/suppressions", { channel: channel || undefined, category: category || undefined, limit: pageSize, offset }, { signal }), [channel, category, offset, pageSize]);
+  const add = useG8Mutation((ids: number[]) => g8Post<BulkAdd>("/contacts/suppressions/bulk-add", { contact_ids: ids, channel: addChannel, reason: reason.trim() || undefined }), {
+    onSuccess: () => { setIdsText(""); 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(""); setPicked(new Set()); void ledger.refetch(); },
+  });
+  const check = useG8Mutation((id: number) => g8Get<ContactStatus>(`/contacts/${id}/suppression`));
+
+  const rows = (ledger.data?.data ?? []) as SuppressionRecord[];
+  const ids = parseIds(idsText);
+  const selectedContacts = [...picked];
+  const togglePick = (contactId: number) => setPicked((p) => { const n = new Set(p); if (!n.delete(contactId)) n.add(contactId); return n; });
+
+  return (
+    <div className={`flex flex-col gap-5 ${className ?? ""}`}>
+      <section className="flex flex-col gap-2" aria-label="Suppress contacts">
+        <Label htmlFor="suppress-ids">Suppress contacts by id</Label>
+        <Textarea id="suppress-ids" rows={2} placeholder="101, 102, 103" value={idsText} onChange={(e) => setIdsText(e.target.value)} />
+        <div className="flex flex-wrap items-center gap-2">
+          <select aria-label="Channel to suppress" className="h-9 rounded-md border bg-background px-2 text-sm" value={addChannel} onChange={(e) => setAddChannel(e.target.value)}>
+            <option value="all">All channels</option><option value="email">Email</option><option value="phone">Phone</option><option value="linkedin">LinkedIn</option>
+          </select>
+          <Input aria-label="Reason" placeholder="Reason (optional)" className="w-64" value={reason} onChange={(e) => setReason(e.target.value)} />
+          <Button size="sm" loading={add.loading} disabled={ids.length === 0} onClick={() => void add.mutate(ids)}>Suppress {ids.length || ""} contact{ids.length === 1 ? "" : "s"}</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}
+      </section>
+
+      <section className="flex items-end gap-2" aria-label="Check a contact">
+        <div className="flex flex-col gap-1"><Label htmlFor="check-id">Check one contact</Label><Input id="check-id" inputMode="numeric" placeholder="Contact id" className="w-40" value={checkId} onChange={(e) => setCheckId(e.target.value)} /></div>
+        <Button variant="outline" size="sm" loading={check.loading} disabled={!Number(checkId)} onClick={() => void check.mutate(Number(checkId))}>Check</Button>
+        {check.data ? <p role="status" className="text-sm">{check.data.data.is_suppressed ? `Suppressed on: ${check.data.data.active_channels.join(", ")}` : "Not suppressed"}</p> : null}
+        {check.error ? <ApiError error={check.error} title="Could not check that contact" /> : null}
+      </section>
+
+      <section className="flex flex-col gap-2" aria-label="Suppression ledger">
+        <div className="flex flex-wrap items-center gap-2">
+          <select aria-label="Filter by channel" className="h-9 rounded-md border bg-background px-2 text-sm" value={channel} onChange={(e) => { setChannel(e.target.value); setOffset(0); }}>
+            <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="h-9 rounded-md border bg-background px-2 text-sm" value={category} onChange={(e) => { setCategory(e.target.value); setOffset(0); }}>
+            <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>
+          <Button className="ml-auto" variant="outline" size="sm" disabled={selectedContacts.length === 0} onClick={() => setConfirmReinstate(true)}>Reinstate {selectedContacts.length || ""}</Button>
+        </div>
+        {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="rounded-md border">
+          <Table>
+            <TableHeader><TableRow><TableHead className="w-8" /><TableHead>Contact</TableHead><TableHead>Channel</TableHead><TableHead>Reason</TableHead><TableHead>Note</TableHead><TableHead>Since</TableHead></TableRow></TableHeader>
+            <TableBody>
+              {ledger.loading && rows.length === 0
+                ? Array.from({ length: 4 }, (_, i) => <TableRow key={`sk${i}`}><TableCell colSpan={6}><Skeleton className="h-5 w-full" /></TableCell></TableRow>)
+                : rows.map((r) => (
+                    <TableRow key={r.id} data-testid="suppression-row">
+                      <TableCell><input type="checkbox" aria-label={`Select contact ${r.contact_id}`} checked={picked.has(r.contact_id)} onChange={() => togglePick(r.contact_id)} /></TableCell>
+                      <TableCell>{onOpenContact ? <Button variant="link" size="sm" onClick={() => onOpenContact(r.contact_id)}>#{r.contact_id}</Button> : `#${r.contact_id}`}</TableCell>
+                      <TableCell className="capitalize">{r.channel}</TableCell>
+                      <TableCell>{r.category.replace(/_/g, " ")}</TableCell>
+                      <TableCell>{r.reason ?? "-"}</TableCell>
+                      <TableCell>{r.created_at ? new Date(r.created_at).toLocaleDateString() : "-"}</TableCell>
+                    </TableRow>
+                  ))}
+            </TableBody>
+          </Table>
+          {!ledger.loading && !ledger.error && rows.length === 0 ? <EmptyState title="Nobody is suppressed" description="Suppressed contacts are skipped by every sequence, campaign and newsletter." /> : 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))}>Previous</Button>
+          <Button variant="outline" size="sm" disabled={rows.length < pageSize || ledger.loading} onClick={() => setOffset(offset + pageSize)}>Next</Button>
+        </div>
+      </section>
+
+      <ConfirmSpendDialog open={confirmReinstate} tier="external" title={`Reinstate ${selectedContacts.length} contact${selectedContacts.length === 1 ? "" : "s"}`}
+        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={selectedContacts.length} confirmLabel="Reinstate" confirming={reinstate.loading}
+        onConfirm={() => void reinstate.mutate(selectedContacts)} onCancel={() => setConfirmReinstate(false)} />
+    </div>
+  );
+}

package/blocks/lists/recipes/create-list-and-add-contacts.ts

@@ -0,0 +1,35 @@
+/**
+ * @title Create a list, add contacts to it and read the members
+ * @when Grouping people for a sequence, campaign or export. A list's `type` is `contacts` or `companies`.
+ * The list id comes from the create response; contact ids come from a contact read or search, never a guess.
+ * Adding is idempotent: contacts already in the list are reported in `already_member`, ids that do not
+ * exist in `not_found`. Contacts owned by other reps can answer 409 CONFLICT_REVIEW_REQUIRED: repeat the
+ * call with `conflict_resolution` once a person decided.
+ */
+import { g8, G8Error } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function buildList(title: string, contactIds: number[]) {
+  const list = await g8.lists.create(title, "contacts");
+  try {
+    const res = await g8.api.lists.addContactsToList({ path: { list_id: list.id }, body: { contact_ids: contactIds } });
+    return { listId: list.id, result: res.data };
+  } catch (err) {
+    if (err instanceof G8Error && err.status === 409) {
+      // detail = { code: "CONFLICT_REVIEW_REQUIRED", ready_count, warned: [...], blocked: [...] }: show it to a person.
+      return { listId: list.id, conflict: err.detail };
+    }
+    throw err;
+  }
+}
+
+export async function members(listId: number) {
+  const { data, total } = await g8.lists.contacts(listId, 1, 100);
+  return { total, ids: data.map((c) => c.id) };
+}
+
+/** Removing members does not delete the contacts. */
+export async function removeMembers(listId: number, contactIds: number[]) {
+  return g8.lists.removeContacts(listId, contactIds);
+}

package/blocks/lists/recipes/refresh-and-check-lists.ts

@@ -0,0 +1,21 @@
+/**
+ * @title Refresh a dynamic list and check a list's health
+ * @when A list is built from filters (dynamic) and must be re-evaluated, or a list looks wrong
+ * (stuck importing, member count off). `refresh` re-runs the filters; the integrity check is read-only and
+ * reports problems without changing anything.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function refreshDynamic(listId: number) {
+  const res = await g8.api.lists.refreshDynamicList({ path: { audience_id: listId } });
+  return res.data;
+}
+
+export async function checkHealth(listId: number) {
+  const check = await g8.api.lists.checkListIntegrity({ path: { list_id: listId } });
+  const all = await g8.lists.list(1, 50);
+  const list = all.data.find((l) => l.id === listId);
+  return { integrity: check.data, memberCount: list?.contact_count ?? null };
+}

package/blocks/lists/recipes/suppress-and-reinstate.ts

@@ -0,0 +1,30 @@
+/**
+ * @title Suppress contacts and reinstate them later
+ * @when Honouring an opt-out, a bounce or a "do not call" request. Suppression is respected by every
+ * sequence, campaign and newsletter. Reinstating lets outreach resume, so ask a human first. The ledger
+ * holds contact ids only; resolve names with `g8.contacts.get`.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function suppress(contactIds: number[], channel: "all" | "email" | "phone" | "linkedin" = "all", reason?: string) {
+  const res = await g8.api.suppressions.bulkAddSuppressions({ body: { contact_ids: contactIds, channel, reason } });
+  return res.data; // { suppressed, total_requested, channel, not_found }
+}
+
+export async function isSuppressed(contactId: number) {
+  const res = await g8.api.suppressions.checkContactSuppression({ path: { contact_id: contactId } });
+  return res.data; // { is_suppressed, active_channels, suppressions }
+}
+
+export async function listEmailSuppressions() {
+  const res = await g8.api.suppressions.listSuppressions({ query: { channel: "email", limit: 200 } });
+  return res.data;
+}
+
+/** Only after a person approved: contacts who unsubscribed themselves may be refused. */
+export async function reinstate(contactIds: number[], reason: string) {
+  const res = await g8.api.suppressions.reinstateSuppressions({ body: { contact_ids: contactIds, reason } });
+  return res.data; // { reinstated, skipped: [{ contact_id, reason }], not_found }
+}

package/blocks/mailboxes/README.md

@@ -0,0 +1,71 @@
+# mailboxes
+
+Everything about the inboxes you send from: list them, connect or buy new ones, buy the domains behind them,
+and check deliverability and warmup before a send. The Apollo / Outreach "mailboxes" settings screen.
+
+Depends on: `foundation`. Install: `npx @graph8/sdk add mailboxes`.
+
+## Components
+
+| Component | What it does | Tiers |
+|---|---|---|
+| `MailboxList` | Mailboxes with connection status, warmup and daily limit. Test connection; archive and delete are confirmed. | read, write, destructive |
+| `ConnectMailbox` | Three modes: IMAP/SMTP form (create then test), Google/Microsoft (a link to the app, no API call), and buy mailboxes on a connected domain. | read, write, billable |
+| `DomainPurchase` | Suggest names, check availability, buy domains, connect them, check DNS propagation. | read, billable |
+| `WarmupHealth` | "Safe to send?" verdict, fleet counts, degraded mailboxes; for one mailbox, warmup analytics, start/stop and a placement test. | read, write, billable |
+
+Every billable or destructive action opens `ConfirmSpendDialog` first, with a credit estimate where one
+exists. There is no credit-balance read, so the numbers are estimates (about 2,500 credits held per domain,
+750 per mailbox, 20 per placement test).
+
+## The flow, in order
+
+1. **Connect what you own.** `ConnectMailbox` IMAP tab -> `createMailbox` (returns `id`) -> `testMailboxConnection`
+   with that `id`. Credentials are write-only.
+2. **Google or Microsoft (the human).** OAuth consent only runs in the graph8 app. `ConnectMailbox` shows a button
+   to `appUrl`; the mailbox then appears in `MailboxList`.
+3. **Buy infrastructure** (needs approval): `DomainPurchase` -> `generateDomainNames` -> `checkDomainAvailability`
+   -> `checkoutPurchaseDomains` (sent with an Idempotency-Key) -> `listProviderDomains` until the domain
+   shows -> `connectProvider` -> `checkDomainPropagation`. Then `ConnectMailbox` Buy tab ->
+   `getSendingPricing` -> `checkoutPurchaseMailboxes` for that domain's `id`.
+4. **Warm up.** `WarmupHealth mailboxId={id}` -> `getMailboxWarmupAnalytics`, `enableWarmup` / `disableWarmup`.
+5. **Gate every launch.** `WarmupHealth` (no `mailboxId`) shows `getSafeToSend`, `getFleetSummary` and
+   `listDegradedMailboxes`. A `false` verdict means pause instead of pushing more volume.
+
+## Prerequisites
+
+- Google/Microsoft mailboxes connected by the person in the graph8 app (`where: "app"`).
+- A plan with credits if buying (`where: "api"`). A 402 on purchase means the credit hold could not clear;
+  a 422 means the plan cannot fund purchases.
+
+## Defaults (do not ask the human)
+
+- Daily limit 40 for a new IMAP mailbox; warmup on for bought mailboxes; domains via `registrar`, mailboxes via `managed`.
+- **Ask the human**: which domains and usernames to buy, and the registrant contact. Never buy without approval.
+
+## Operations
+
+| Operation | Method and path | Tier | Used by |
+|---|---|---|---|
+| `list_mailboxes_mailboxes_get` | GET /mailboxes | read | MailboxList |
+| `test_mailbox_connection_mailboxes__mailbox_id__test_connection_post` | POST /mailboxes/{mailbox_id}/test-connection | write | MailboxList, ConnectMailbox |
+| `archive_mailbox_mailboxes__mailbox_id__archive_post` | POST /mailboxes/{mailbox_id}/archive | destructive | MailboxList |
+| `delete_mailbox_mailboxes__mailbox_id__delete` | DELETE /mailboxes/{mailbox_id} | destructive | MailboxList |
+| `create_mailbox_mailboxes_post` | POST /mailboxes | write | ConnectMailbox |
+| `list_provider_domains_provider_domains_get` | GET /provider-domains | read | ConnectMailbox, DomainPurchase |
+| `get_sending_pricing_provider_domains_pricing_get` | GET /provider-domains/pricing | read | ConnectMailbox |
+| `checkout_purchase_mailboxes_provider_domains__domain_id__checkout_mailboxes_post` | POST /provider-domains/{domain_id}/checkout-mailboxes | billable | ConnectMailbox |
+| `generate_domain_names_provider_domains_generate_domains_post` | POST /provider-domains/generate-domains | read | DomainPurchase |
+| `check_domain_availability_provider_domains_check_availability_post` | POST /provider-domains/check-availability | billable | DomainPurchase |
+| `checkout_purchase_domains_provider_domains_checkout_purchase_post` | POST /provider-domains/checkout-purchase | billable | DomainPurchase |
+| `connect_provider_provider_domains__domain_id__connect_provider_post` | POST /provider-domains/{domain_id}/connect-provider | billable | DomainPurchase |
+| `check_domain_propagation_provider_domains__domain_id__check_propagation_post` | POST /provider-domains/{domain_id}/check-propagation | billable | DomainPurchase |
+| `get_fleet_summary_deliverability_fleet_summary_get` | GET /deliverability/fleet-summary | read | WarmupHealth |
+| `get_safe_to_send_deliverability_safe_to_send_get` | GET /deliverability/safe-to-send | read | WarmupHealth |
+| `list_degraded_mailboxes_deliverability_degraded_get` | GET /deliverability/degraded | read | WarmupHealth |
+| `get_mailbox_warmup_analytics_mailboxes__mailbox_id__warmup_get` | GET /mailboxes/{mailbox_id}/warmup | read | WarmupHealth |
+| `enable_warmup_warmup__mailbox_id__enable_post` | POST /warmup/{mailbox_id}/enable | write | WarmupHealth |
+| `disable_warmup_warmup__mailbox_id__disable_post` | POST /warmup/{mailbox_id}/disable | write | WarmupHealth |
+| `run_mailbox_placement_test_mailboxes__mailbox_id__health_placement_test_post` | POST /mailboxes/{mailbox_id}/health/placement-test | billable | WarmupHealth |
+
+Recipes (`recipes/`): `connect-imap-mailbox.ts`, `buy-domain-and-mailboxes.ts`, `is-it-safe-to-send.ts`, `warmup-report.ts`.

package/blocks/mailboxes/block.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "mailboxes",
+  "title": "Mailboxes & deliverability",
+  "summary": "List, connect and buy sending mailboxes and domains, and watch warmup and deliverability before you send.",
+  "features": [
+    "mailbox list with connection test, archive and delete",
+    "connect over IMAP/SMTP, link out for Google/Microsoft, buy mailboxes",
+    "domain search, availability and purchase",
+    "fleet deliverability verdict, degraded mailboxes, warmup analytics, placement test"
+  ],
+  "dependsOn": [
+    "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",
+    "checkout_purchase_domains_provider_domains_checkout_purchase_post",
+    "connect_provider_provider_domains__domain_id__connect_provider_post",
+    "check_domain_propagation_provider_domains__domain_id__check_propagation_post",
+    "get_fleet_summary_deliverability_fleet_summary_get",
+    "get_safe_to_send_deliverability_safe_to_send_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"
+  ],
+  "components": [
+    {
+      "name": "MailboxList",
+      "file": "components/mailbox-list.tsx",
+      "purpose": "Sending mailboxes with status, warmup and daily limit; test, archive (confirmed) and delete (confirmed).",
+      "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"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "ConnectMailbox",
+      "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": [
+        "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"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable"
+      ]
+    },
+    {
+      "name": "DomainPurchase",
+      "file": "components/domain-purchase.tsx",
+      "purpose": "Suggest, check and buy sending domains (confirmed with a credit estimate), then connect them and check DNS.",
+      "operations": [
+        "generate_domain_names_provider_domains_generate_domains_post",
+        "check_domain_availability_provider_domains_check_availability_post",
+        "checkout_purchase_domains_provider_domains_checkout_purchase_post",
+        "list_provider_domains_provider_domains_get",
+        "connect_provider_provider_domains__domain_id__connect_provider_post",
+        "check_domain_propagation_provider_domains__domain_id__check_propagation_post"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "WarmupHealth",
+      "file": "components/warmup-health.tsx",
+      "purpose": "Safe-to-send verdict, fleet counts, degraded mailboxes, per-mailbox warmup analytics with start/stop and a confirmed placement test.",
+      "operations": [
+        "get_fleet_summary_deliverability_fleet_summary_get",
+        "get_safe_to_send_deliverability_safe_to_send_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"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/mailboxes-utils.ts",
+      "purpose": "Mailbox and domain row types, credit estimate constants, status colors and idempotency-key helper."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/connect-imap-mailbox.ts",
+      "title": "Connect a mailbox you own over IMAP/SMTP and prove it works",
+      "when": "Adding an existing mailbox (not Google or Microsoft)."
+    },
+    {
+      "file": "recipes/buy-domain-and-mailboxes.ts",
+      "title": "Buy a sending domain, connect it, then buy mailboxes on it",
+      "when": "Provisioning sending infrastructure; spends real credits, needs human approval."
+    },
+    {
+      "file": "recipes/is-it-safe-to-send.ts",
+      "title": "Check deliverability before a send",
+      "when": "Right before launching a sequence or campaign."
+    },
+    {
+      "file": "recipes/warmup-report.ts",
+      "title": "Report warmup progress for every mailbox",
+      "when": "A daily report or before moving a mailbox into a sequence."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "oauth-mailboxes-in-app",
+      "description": "Google and Microsoft mailboxes are connected by the person in the graph8 app. The API cannot run the OAuth consent screen.",
+      "where": "app",
+      "verify": "The mailbox appears in GET /mailboxes with connection_status active."
+    },
+    {
+      "id": "credits-for-purchases",
+      "description": "The workspace has an active plan with credits if you buy domains or mailboxes. There is no balance read, so the UI shows estimates.",
+      "where": "api",
+      "verify": "A purchase returns 202; a 402 means insufficient credits and a 422 means the plan cannot fund purchases."
+    }
+  ],
+  "scopes": [
+    "campaigns:delete",
+    "campaigns:read",
+    "campaigns:run",
+    "campaigns:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Daily send limit for a new IMAP mailbox",
+      "default": "40",
+      "askHuman": false
+    },
+    {
+      "decision": "Start warmup on newly bought mailboxes",
+      "default": "Yes",
+      "askHuman": false
+    },
+    {
+      "decision": "Which domain names and mailbox usernames to buy",
+      "default": "None: never buy without approval",
+      "askHuman": true
+    },
+    {
+      "decision": "Registrant contact for domain purchases",
+      "default": "None",
+      "askHuman": true
+    },
+    {
+      "decision": "Domain provider for purchases",
+      "default": "registrar (domains) and managed (mailboxes)",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}