@graph8/sdk 0.303.0 → 0.357.0

package/blocks/newsletter/components/newsletter-editor.tsx

@@ -0,0 +1,131 @@
+"use client";
+
+/**
+ * NewsletterEditor: pick or create a newsletter, see its issues, write one, and take the newsletter live.
+ *
+ * SDK operations, in order:
+ *   1. listNewsletters (GET /newsletters)                              read
+ *   2. createNewsletter (POST /newsletters)                            external -> ConfirmSpendDialog (creates the container; sends nothing)
+ *   3. listIssues (GET /newsletters/{id}/issues)                       read      (each row carries inline KPIs once sent)
+ *   4. IssueForm: getIssue, createIssue/updateIssue, generateNewsletterIssue, sendTestEmail, deleteIssue
+ *   5. activateNewsletter (POST /newsletters/{id}/activate)            external -> ConfirmSpendDialog (LAUNCH-CLASS: the scheduler may now mail due issues)
+ *   6. pauseNewsletter (POST /newsletters/{id}/pause)                  write     (stops further sends)
+ * Sending an issue is NOT here: use IssueScheduler, which confirms with the subscriber count.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label, Skeleton } 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 { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { issueTitle } from "../lib/newsletter-types";
+import type { Issue, Newsletter } from "../lib/newsletter-types";
+import { IssueForm } from "./issue-form";
+
+export interface NewsletterEditorProps {
+  initialNewsletterId?: string;
+  /** Called when a sent-ready draft is chosen, so the page can show IssueScheduler. */
+  onSelectIssue?: (newsletterId: string, issue: Issue) => void;
+}
+
+type Pending = { kind: "create" } | { kind: "activate" } | null;
+
+export function NewsletterEditor({ initialNewsletterId, onSelectIssue }: NewsletterEditorProps) {
+  const [newsletterId, setNewsletterId] = useState<string | undefined>(initialNewsletterId);
+  const [issueId, setIssueId] = useState<number | "new" | undefined>(undefined);
+  const [name, setName] = useState("");
+  const [goal, setGoal] = useState("");
+  const [pending, setPending] = useState<Pending>(null);
+  const newsletters = useG8Query((signal) => g8Get<Newsletter[]>("/newsletters", {}, { signal }).then((r) => r.data ?? []), []);
+  const issues = useG8Query((signal) => g8Get<Issue[]>(`/newsletters/${encodeURIComponent(newsletterId ?? "")}/issues`, {}, { signal }).then((r) => r.data ?? []), [newsletterId], { enabled: Boolean(newsletterId) });
+  const current = (newsletters.data ?? []).find((n) => n.id === newsletterId);
+
+  const create = useG8Mutation(async () => (await g8Post<Newsletter>("/newsletters", { name: name.trim(), goal: goal.trim() || undefined })).data, {
+    onSuccess: (created) => { setPending(null); setName(""); setGoal(""); setNewsletterId(created.id); void newsletters.refetch(); },
+  });
+  const activate = useG8Mutation(() => g8Post(`/newsletters/${encodeURIComponent(newsletterId ?? "")}/activate`), { onSuccess: () => { setPending(null); void newsletters.refetch(); } });
+  const pause = useG8Mutation(() => g8Post(`/newsletters/${encodeURIComponent(newsletterId ?? "")}/pause`), { onSuccess: () => void newsletters.refetch() });
+
+  if (newsletters.error) return <ApiError error={newsletters.error} title="Could not load newsletters" onRetry={() => void newsletters.refetch()} />;
+  if (newsletters.loading && !newsletters.data) return <div aria-busy="true" className="grid gap-2"><Skeleton className="h-9 w-64" /><Skeleton className="h-40 w-full" /></div>;
+  const list = newsletters.data ?? [];
+  const live = current?.status === "active";
+  return (
+    <div className="grid gap-4 md:grid-cols-[18rem_1fr]">
+      <Card>
+        <CardHeader><CardTitle>Newsletters</CardTitle></CardHeader>
+        <CardContent className="grid gap-3">
+          {list.length === 0 ? <p className="text-muted-foreground text-sm">No newsletters yet.</p> : (
+            <ul className="grid gap-1">
+              {list.map((n) => (
+                <li key={n.id}>
+                  <Button variant={n.id === newsletterId ? "secondary" : "ghost"} size="sm" className="w-full justify-between" onClick={() => { setNewsletterId(n.id); setIssueId(undefined); }}>
+                    <span>{n.name}</span><span className="text-muted-foreground text-xs">{n.status}</span>
+                  </Button>
+                </li>
+              ))}
+            </ul>
+          )}
+          <form className="grid gap-2" onSubmit={(e) => { e.preventDefault(); if (name.trim()) setPending({ kind: "create" }); }}>
+            <Label htmlFor="g8-nl-name">New newsletter</Label>
+            <Input id="g8-nl-name" placeholder="Name" value={name} onChange={(e) => setName(e.target.value)} />
+            <Input aria-label="Goal" placeholder="Goal (optional)" value={goal} onChange={(e) => setGoal(e.target.value)} />
+            <Button type="submit" size="sm" disabled={!name.trim()}>Create newsletter</Button>
+          </form>
+        </CardContent>
+      </Card>
+      <div className="grid content-start gap-4">
+        {!current ? <EmptyState title="Pick a newsletter" description="Choose a newsletter to see its issues, or create one." /> : (
+          <>
+            <div className="flex items-center justify-between">
+              <h2 className="text-lg font-semibold">{current.name} <span className="text-muted-foreground text-sm font-normal">{current.status}</span></h2>
+              {live ? <Button variant="outline" size="sm" loading={pause.loading} onClick={() => void pause.mutate(undefined)}>Pause newsletter</Button> : <Button size="sm" onClick={() => setPending({ kind: "activate" })}>Activate newsletter</Button>}
+            </div>
+            {pause.error ? <ApiError error={pause.error} title="Could not pause" /> : null}
+            <Card>
+              <CardHeader><CardTitle>Issues</CardTitle></CardHeader>
+              <CardContent className="grid gap-2">
+                {issues.error ? <ApiError error={issues.error} title="Could not load issues" onRetry={() => void issues.refetch()} /> : issues.loading && !issues.data ? <Skeleton className="h-16 w-full" /> : (issues.data ?? []).length === 0 ? (
+                  <p className="text-muted-foreground text-sm">No issues yet.</p>
+                ) : (
+                  <ul className="grid gap-1">
+                    {(issues.data ?? []).map((i) => (
+                      <li key={i.id}>
+                        <Button variant={i.id === issueId ? "secondary" : "ghost"} size="sm" className="w-full justify-between" onClick={() => { setIssueId(i.id); onSelectIssue?.(current.id, i); }}>
+                          <span>{issueTitle(i)}</span><span className="text-muted-foreground text-xs">{i.status}</span>
+                        </Button>
+                      </li>
+                    ))}
+                  </ul>
+                )}
+                <div><Button size="sm" onClick={() => setIssueId("new")}>New issue</Button></div>
+              </CardContent>
+            </Card>
+            {issueId !== undefined ? (
+              <Card>
+                <CardHeader><CardTitle>{issueId === "new" ? "New issue" : "Edit issue"}</CardTitle></CardHeader>
+                <CardContent>
+                  <IssueForm key={String(issueId)} newsletterId={current.id} issueId={issueId === "new" ? undefined : issueId}
+                    onSaved={(saved) => { void issues.refetch(); setIssueId(saved.id); }} onDeleted={() => { setIssueId(undefined); void issues.refetch(); }} />
+                </CardContent>
+              </Card>
+            ) : null}
+          </>
+        )}
+      </div>
+      <ConfirmSpendDialog
+        open={pending !== null}
+        tier="external"
+        title={pending?.kind === "activate" ? `Activate ${current?.name ?? "this newsletter"}?` : `Create the newsletter "${name.trim()}"?`}
+        description={<><p>{pending?.kind === "activate" ? "Once active, the scheduler sends any issue whose scheduled time has passed to real subscribers." : "This creates the newsletter container. Nothing is sent until you activate it and schedule an issue."}</p>{(create.error ?? activate.error) ? <ApiError error={create.error ?? activate.error} title="That did not work" /> : null}</>}
+        confirmLabel={pending?.kind === "activate" ? "Activate" : "Create"}
+        confirming={create.loading || activate.loading}
+        onCancel={() => setPending(null)}
+        onConfirm={() => void (pending?.kind === "activate" ? activate.mutate(undefined) : create.mutate(undefined))}
+      />
+    </div>
+  );
+}

package/blocks/newsletter/components/newsletter-stats.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+/**
+ * NewsletterStats: how sent issues performed (delivered, opened, clicked, bounced, unsubscribed).
+ *
+ * SDK operations, in order:
+ *   1. listIssues (GET /newsletters/{id}/issues)                                 read   (sent rows carry inline KPIs)
+ *   2. getIssueAnalyticsKpis (GET .../issues/{issue_id}/analytics/kpis)          read   (fresh numbers for the selected issue)
+ * KPIs can lag: the API answers 200 with `stale: true` and an empty bucket when its read failed, which is different
+ * from "zero engagement yet". The panel says so instead of showing zeros. Open rates are approximate (image-blocking
+ * and privacy proxies) and are shown as a share of delivered mail.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { issueTitle, percent } from "../lib/newsletter-types";
+import type { Issue, IssueKpis } from "../lib/newsletter-types";
+
+export interface NewsletterStatsProps {
+  newsletterId: string;
+}
+
+interface Kpis { stale?: boolean; last_updated_at?: string | null; kpis?: IssueKpis }
+
+function Tile({ label, value, sub }: { label: string; value: number | undefined; sub?: string }) {
+  return (
+    <div className="rounded-md border p-3">
+      <p className="text-muted-foreground text-xs">{label}</p>
+      <p className="text-xl font-semibold">{(value ?? 0).toLocaleString()}</p>
+      {sub ? <p className="text-muted-foreground text-xs">{sub}</p> : null}
+    </div>
+  );
+}
+
+export function NewsletterStats({ newsletterId }: NewsletterStatsProps) {
+  const base = `/newsletters/${encodeURIComponent(newsletterId)}/issues`;
+  const issues = useG8Query((signal) => g8Get<Issue[]>(base, {}, { signal }).then((r) => r.data ?? []), [base]);
+  const [selected, setSelected] = useState<number | undefined>(undefined);
+  const detail = useG8Query((signal) => g8Get<Kpis>(`${base}/${selected}/analytics/kpis`, {}, { signal }).then((r) => r.data), [base, selected], { enabled: selected !== undefined });
+
+  if (issues.error) return <ApiError error={issues.error} title="Could not load issues" onRetry={() => void issues.refetch()} />;
+  if (issues.loading && !issues.data) return <Skeleton className="h-40 w-full" aria-busy="true" />;
+  const sent = (issues.data ?? []).filter((i) => i.status === "sent" || i.sent_at);
+  if (sent.length === 0) return <EmptyState title="Nothing sent yet" description="Statistics appear here after the first issue goes out." />;
+  const k = detail.data?.kpis;
+  return (
+    <div className="grid gap-4">
+      <Table>
+        <TableHeader><TableRow><TableHead>Issue</TableHead><TableHead>Sent</TableHead><TableHead>Delivered</TableHead><TableHead>Opened</TableHead><TableHead>Clicked</TableHead><TableHead /></TableRow></TableHeader>
+        <TableBody>
+          {sent.map((i) => (
+            <TableRow key={i.id}>
+              <TableCell>{issueTitle(i)}</TableCell>
+              <TableCell>{i.sent_at ? new Date(i.sent_at).toLocaleDateString() : ""}</TableCell>
+              <TableCell>{(i.kpis?.delivered ?? 0).toLocaleString()}</TableCell>
+              <TableCell>{percent(i.kpis?.opened, i.kpis?.delivered)}</TableCell>
+              <TableCell>{percent(i.kpis?.clicked, i.kpis?.delivered)}</TableCell>
+              <TableCell className="text-right"><Button size="sm" variant="ghost" onClick={() => setSelected(i.id)}>Details</Button></TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      {selected !== undefined ? (
+        <Card>
+          <CardHeader><CardTitle>Issue details</CardTitle></CardHeader>
+          <CardContent className="grid gap-3">
+            {detail.error ? <ApiError error={detail.error} title="Could not load the numbers" onRetry={() => void detail.refetch()} /> : detail.loading && !detail.data ? <Skeleton className="h-20 w-full" /> : detail.data?.stale ? (
+              <p role="alert" className="text-sm text-amber-700">The numbers could not be read just now. This is not zero engagement: try again in a minute.</p>
+            ) : (
+              <>
+                <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
+                  <Tile label="Delivered" value={k?.delivered} sub={`of ${(k?.total ?? 0).toLocaleString()} queued`} />
+                  <Tile label="Opened" value={k?.opened} sub={percent(k?.opened, k?.delivered)} />
+                  <Tile label="Clicked" value={k?.clicked} sub={percent(k?.clicked, k?.delivered)} />
+                  <Tile label="Bounced" value={k?.bounced} sub={percent(k?.bounced, k?.total)} />
+                  <Tile label="Unsubscribed" value={k?.unsubscribed_attributed} />
+                  <Tile label="Complaints" value={k?.complained} />
+                  <Tile label="Skipped" value={k?.skipped} />
+                  <Tile label="No activity" value={k?.no_activity} />
+                </div>
+                {detail.data?.last_updated_at ? <p className="text-muted-foreground text-xs">Updated {new Date(detail.data.last_updated_at).toLocaleString()}</p> : null}
+              </>
+            )}
+          </CardContent>
+        </Card>
+      ) : null}
+    </div>
+  );
+}

package/blocks/newsletter/components/subscriber-table.tsx

@@ -0,0 +1,173 @@
+"use client";
+
+/**
+ * SubscriberTable: who is on the newsletter, plus add, import from a list, verify, unsubscribe and erase.
+ *
+ * SDK operations, in order:
+ *   1. listSubscribers (GET /newsletters/{id}/subscribers?page&page_size&search&status)   read
+ *   2. addSubscriber (POST .../subscribers)                                      external  -> ConfirmSpendDialog (they will receive future issues)
+ *   3. listLists (GET /lists) + importSubscribersFromAudience (POST .../subscribers/import-audience)   billable -> ConfirmSpendDialog (async; may verify addresses)
+ *   4. previewNewsletterSubscriberVerification (POST .../subscribers/verify/preview)  read   (free: how many, what it costs)
+ *   5. verifyNewsletterSubscribers (POST .../subscribers/verify)                 billable  -> ConfirmSpendDialog with the previewed cost
+ *   6. unsubscribeSubscriber (PATCH .../subscribers/{id}/unsubscribe)            external  -> ConfirmSpendDialog (keeps the row and the opt-out)
+ *   7. deleteSubscriber (DELETE .../subscribers/{id})                            destructive -> ConfirmSpendDialog (erases the opt-out record too)
+ * Prefer Unsubscribe over Delete: deleting loses the record that someone opted out, so a re-import could mail them again.
+ */
+
+import { useState } from "react";
+import { Button, Input, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } 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 { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import type { Subscriber } from "../lib/newsletter-types";
+
+export interface SubscriberTableProps {
+  /** The newsletter to show. Omit it (for example as a stack nav page) and a newsletter picker is shown instead. */
+  newsletterId?: string;
+  pageSize?: number;
+}
+
+type Action =
+  | { kind: "add" }
+  | { kind: "import"; listId: number; contacts?: number }
+  | { kind: "verify" }
+  | { kind: "unsubscribe"; subscriber: Subscriber }
+  | { kind: "delete"; subscriber: Subscriber };
+
+interface Page { items: Subscriber[]; total: number }
+interface ListOption { id: number; title: string; contact_count?: number }
+
+function creditsOf(preview: unknown): number | undefined {
+  const p = (preview ?? {}) as Record<string, unknown>;
+  const value = p.estimated_credits ?? p.credits ?? p.cost ?? p.estimated_cost;
+  return typeof value === "number" ? value : undefined;
+}
+
+export function SubscriberTable({ newsletterId: given, pageSize = 25 }: SubscriberTableProps) {
+  const [picked, setPicked] = useState("");
+  const all = useG8Query((signal) => g8Get<Array<{ id: string; name: string }>>("/newsletters", {}, { signal }).then((r) => r.data ?? []), [], { enabled: !given });
+  const newsletterId = given ?? picked;
+  if (!newsletterId) {
+    if (all.error) return <ApiError error={all.error} title="Could not load newsletters" onRetry={() => void all.refetch()} />;
+    if (all.loading && !all.data) return <Skeleton className="h-9 w-64" aria-busy="true" />;
+    if ((all.data ?? []).length === 0) return <EmptyState title="No newsletters yet" description="Create a newsletter first (NewsletterEditor)." />;
+    return (
+      <select aria-label="Choose a newsletter" className="border-input bg-background h-9 max-w-sm rounded-md border px-2 text-sm" value="" onChange={(e) => setPicked(e.target.value)}>
+        <option value="" disabled>Choose a newsletter</option>
+        {(all.data ?? []).map((n) => <option key={n.id} value={n.id}>{n.name}</option>)}
+      </select>
+    );
+  }
+  return <SubscribersOf newsletterId={newsletterId} pageSize={pageSize} />;
+}
+
+function SubscribersOf({ newsletterId, pageSize }: { newsletterId: string; pageSize: number }) {
+  const base = `/newsletters/${encodeURIComponent(newsletterId)}/subscribers`;
+  const [page, setPage] = useState(1);
+  const [search, setSearch] = useState("");
+  const [query, setQuery] = useState("");
+  const [status, setStatus] = useState("");
+  const [draft, setDraft] = useState({ email: "", first_name: "", last_name: "" });
+  const [listId, setListId] = useState("");
+  const [action, setAction] = useState<Action | null>(null);
+  const subscribers = useG8Query<Page>(
+    (signal) => g8Get<Page>(base, { page, page_size: pageSize, search: query || undefined, status: status || undefined }, { signal }).then((r) => ({ items: r.data?.items ?? [], total: r.data?.total ?? 0 })),
+    [base, page, pageSize, query, status],
+  );
+  const lists = useG8Query((signal) => g8Get<ListOption[]>("/lists", { limit: 200 }, { signal }).then((r) => r.data ?? []), []);
+  const preview = useG8Mutation(async () => (await g8Post(`${base}/verify/preview`, {})).data);
+
+  const run = useG8Mutation(async (a: Action) => {
+    if (a.kind === "add") return g8Post(base, { email: draft.email.trim(), first_name: draft.first_name.trim() || undefined, last_name: draft.last_name.trim() || undefined });
+    if (a.kind === "import") return g8Post(`${base}/import-audience`, { audience_id: a.listId });
+    if (a.kind === "verify") return g8Post(`${base}/verify`, {});
+    if (a.kind === "unsubscribe") return g8Patch(`${base}/${a.subscriber.id}/unsubscribe`, {});
+    return g8Delete(`${base}/${a.subscriber.id}`);
+  }, { onSuccess: (_r, a) => { setAction(null); if (a.kind === "add") setDraft({ email: "", first_name: "", last_name: "" }); void subscribers.refetch(); } });
+
+  const copy = (a: Action | null): { tier: "external" | "billable" | "destructive"; title: string; note: string; label: string; credits?: number; affected?: number; recipients?: number } => {
+    switch (a?.kind) {
+      case "import": return { tier: "billable", title: "Import this list as subscribers?", note: "The import runs in the background. Only import people who agreed to hear from you; addresses may be verified, which spends credits.", label: "Import", recipients: a.contacts };
+      case "verify": return { tier: "billable", title: "Verify unverified addresses?", note: "Every unverified subscriber address is checked and charged per address.", label: "Verify", credits: creditsOf(preview.data) };
+      case "unsubscribe": return { tier: "external", title: `Unsubscribe ${a.subscriber.email}?`, note: "They stay in the list as unsubscribed and will not be mailed.", label: "Unsubscribe" };
+      case "delete": return { tier: "destructive", title: `Erase ${a.subscriber.email}?`, note: "This removes the person and the record that they opted out. Use only for an erasure request.", label: "Erase", affected: 1 };
+      default: return { tier: "external", title: `Add ${draft.email.trim()}?`, note: "They will receive future issues. Only add people who agreed to be mailed.", label: "Add subscriber", recipients: 1 };
+    }
+  };
+  const c = copy(action);
+  const items = subscribers.data?.items ?? [];
+  const total = subscribers.data?.total ?? 0;
+
+  return (
+    <div className="grid gap-4">
+      <form className="grid gap-2 sm:grid-cols-[1fr_8rem_8rem_auto]" onSubmit={(e) => { e.preventDefault(); if (draft.email.includes("@")) setAction({ kind: "add" }); }}>
+        <Input aria-label="Email" type="email" placeholder="Email" value={draft.email} onChange={(e) => setDraft({ ...draft, email: e.target.value })} />
+        <Input aria-label="First name" placeholder="First name" value={draft.first_name} onChange={(e) => setDraft({ ...draft, first_name: e.target.value })} />
+        <Input aria-label="Last name" placeholder="Last name" value={draft.last_name} onChange={(e) => setDraft({ ...draft, last_name: e.target.value })} />
+        <Button type="submit" disabled={!draft.email.includes("@")}>Add subscriber</Button>
+      </form>
+      <div className="flex flex-wrap items-end gap-2">
+        <select aria-label="Import from list" value={listId} onChange={(e) => setListId(e.target.value)} className="border-input bg-background h-9 rounded-md border px-2 text-sm">
+          <option value="">Import from a list...</option>
+          {(lists.data ?? []).map((l) => <option key={l.id} value={l.id}>{l.title}</option>)}
+        </select>
+        <Button variant="outline" disabled={!listId} onClick={() => setAction({ kind: "import", listId: Number(listId), contacts: lists.data?.find((l) => l.id === Number(listId))?.contact_count })}>Import list</Button>
+        <Button variant="outline" loading={preview.loading} onClick={() => void preview.mutate(undefined)}>Check verification cost</Button>
+        {preview.data ? <Button variant="outline" onClick={() => setAction({ kind: "verify" })}>Verify addresses</Button> : null}
+      </div>
+      {preview.data ? <pre role="status" className="rounded border p-2 text-xs">{JSON.stringify(preview.data)}</pre> : null}
+      {preview.error ? <ApiError error={preview.error} title="Could not estimate verification" /> : null}
+      <form className="flex gap-2" onSubmit={(e) => { e.preventDefault(); setPage(1); setQuery(search.trim()); }}>
+        <Input aria-label="Search subscribers" placeholder="Search by email or name" value={search} onChange={(e) => setSearch(e.target.value)} />
+        <select aria-label="Status" value={status} onChange={(e) => { setPage(1); setStatus(e.target.value); }} className="border-input bg-background h-9 rounded-md border px-2 text-sm">
+          <option value="">All</option><option value="subscribed">Subscribed</option><option value="unsubscribed">Unsubscribed</option>
+        </select>
+        <Button type="submit" variant="outline">Search</Button>
+      </form>
+      {subscribers.error ? <ApiError error={subscribers.error} title="Could not load subscribers" onRetry={() => void subscribers.refetch()} /> : subscribers.loading && !subscribers.data ? (
+        <div aria-busy="true" className="grid gap-2"><Skeleton className="h-9 w-full" /><Skeleton className="h-9 w-full" /></div>
+      ) : items.length === 0 ? <EmptyState title="No subscribers" description="Add someone above, or import one of your lists." /> : (
+        <Table>
+          <TableHeader><TableRow><TableHead>Email</TableHead><TableHead>Name</TableHead><TableHead>Status</TableHead><TableHead>Verification</TableHead><TableHead /></TableRow></TableHeader>
+          <TableBody>
+            {items.map((s) => (
+              <TableRow key={s.id}>
+                <TableCell>{s.email}</TableCell>
+                <TableCell>{[s.first_name, s.last_name].filter(Boolean).join(" ")}</TableCell>
+                <TableCell>{s.status}</TableCell>
+                <TableCell>{s.verification_status ?? ""}</TableCell>
+                <TableCell className="text-right">
+                  {s.status !== "unsubscribed" ? <Button size="sm" variant="ghost" onClick={() => setAction({ kind: "unsubscribe", subscriber: s })}>Unsubscribe</Button> : null}
+                  <Button size="sm" variant="ghost" onClick={() => setAction({ kind: "delete", subscriber: s })}>Erase</Button>
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
+      <div className="flex items-center justify-between text-sm">
+        <span className="text-muted-foreground">{total.toLocaleString()} subscribers</span>
+        <span>
+          <Button size="sm" variant="ghost" disabled={page <= 1} onClick={() => setPage(page - 1)}>Previous</Button>
+          <Button size="sm" variant="ghost" disabled={page * pageSize >= total} onClick={() => setPage(page + 1)}>Next</Button>
+        </span>
+      </div>
+      <ConfirmSpendDialog
+        open={action !== null}
+        tier={c.tier}
+        title={c.title}
+        estimatedCredits={c.credits}
+        recipients={c.recipients}
+        affected={c.affected}
+        description={<><p>{c.note}</p>{run.error ? <ApiError error={run.error} title="That did not work" /> : null}</>}
+        confirmLabel={c.label}
+        confirming={run.loading}
+        onCancel={() => setAction(null)}
+        onConfirm={() => { if (action) void run.mutate(action); }}
+      />
+    </div>
+  );
+}

package/blocks/newsletter/lib/newsletter-types.ts

@@ -0,0 +1,97 @@
+"use client";
+
+/**
+ * Types and helpers for the newsletter block.
+ *
+ * Responses are open dicts in the contract (the app adds columns freely), so every field here is optional and the
+ * components render what is present. SENDING IS EXTERNAL: every call that can reach a subscriber's inbox is tier
+ * `external` and must be confirmed with the subscriber count (see IssueScheduler).
+ */
+
+export interface Newsletter {
+  id: string;
+  name: string;
+  slug?: string;
+  status?: string;
+  goal?: string | null;
+  audience_list_id?: string | number | null;
+}
+
+export interface IssueKpis {
+  total?: number;
+  delivered?: number;
+  opened?: number;
+  clicked?: number;
+  bounced?: number;
+  complained?: number;
+  unsubscribed_attributed?: number;
+  skipped?: number;
+  no_activity?: number;
+}
+
+export interface Issue {
+  id: number;
+  newsletter_id?: string;
+  subject?: string | null;
+  status?: string;
+  sent_at?: string | null;
+  scheduled_at?: string | null;
+  html_body?: string | null;
+  plain_text?: string | null;
+  preview_text?: string | null;
+  sender_name?: string | null;
+  sender_email?: string | null;
+  reply_to?: string | null;
+  kpis?: IssueKpis | null;
+}
+
+export interface Subscriber {
+  id: number;
+  email: string;
+  first_name?: string | null;
+  last_name?: string | null;
+  status?: string;
+  verification_status?: string | null;
+  created_at?: string;
+}
+
+export interface SendState {
+  active?: boolean;
+  send?: { status?: string; sent_count?: number; total_recipients?: number; eligible_recipients?: number; failed_count?: number } | null;
+}
+
+/** Only drafts can be edited or deleted; a sent issue is a record of mail real people received. */
+export function isDraft(issue: Pick<Issue, "status"> | undefined): boolean {
+  return !issue?.status || issue.status === "draft";
+}
+
+export function percent(part: number | undefined, whole: number | undefined): string {
+  if (!whole) return "0%";
+  return `${Math.round(((part ?? 0) / whole) * 1000) / 10}%`;
+}
+
+/** `datetime-local` text ("2026-11-01T09:00") to the ISO instant the API wants. Returns undefined when empty or invalid. */
+export function toIsoInstant(local: string): string | undefined {
+  if (!local) return undefined;
+  const d = new Date(local);
+  return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+}
+
+/** A generation that has not finished has PARTIAL html: never send it. */
+export function generationInProgress(status: unknown): boolean {
+  const word = typeof status === "string" ? status : ((status as { status?: string } | null | undefined)?.status ?? "");
+  return /pending|queued|running|generating|in_progress|processing/i.test(word);
+}
+
+export function issueTitle(issue: Pick<Issue, "subject" | "id">): string {
+  return issue.subject?.trim() || `Untitled issue ${issue.id}`;
+}
+
+/** Pause is offered while a send is moving; Resume while it is paused (or pausing). */
+export function sendIsMoving(status: string | undefined): boolean {
+  return /running|queued|resuming|sending|in_progress/i.test(status ?? "");
+}
+
+export function sendIsPaused(status: string | undefined): boolean {
+  return /paus/i.test(status ?? "");
+}

package/blocks/newsletter/recipes/create-newsletter-and-draft-issue.ts

@@ -0,0 +1,27 @@
+/**
+ * @title Create a newsletter, draft its first issue, and send yourself a test
+ * @when Setting up a newsletter before any subscriber exists. Nothing here reaches a subscriber: creating,
+ * drafting and testing are safe; activating the newsletter (last step) is what lets the scheduler mail due issues,
+ * so it is left to a person.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const newsletter = await g8.newsletter.create({ name: "Product updates", goal: "Tell customers what shipped each month" });
+console.log("newsletter", newsletter.id);
+
+// The issue id is a NUMBER in the API, the hand-written client takes it as a string.
+const issue = await g8.newsletter.createIssue(newsletter.id, {
+  subject: "What shipped in October",
+  preview_text: "Three things you asked for",
+  html_body: "<h1>October</h1><p>Here is what shipped.</p>",
+  sender_name: "The graph8 team",
+});
+console.log("draft issue", issue.id, issue.status);
+
+// ONE email to ONE address you own.
+await g8.newsletter.sendTestEmail(newsletter.id, String(issue.id), "you@example.com");
+
+// Do not call activate from an agent without the owner's say-so: it is launch-class.
+// await g8.api.newsletter.activateNewsletter({ path: { newsletter_id: newsletter.id } });

package/blocks/newsletter/recipes/import-audience-and-send.ts

@@ -0,0 +1,43 @@
+/**
+ * @title Import a list as subscribers, then send an issue and follow it to the end
+ * @when A one-off broadcast to an existing audience. Import is BILLABLE if auto_verify_on_import is on and the
+ * send is EXTERNAL (real inboxes): count first, confirm the number with the owner, send once with an idempotency
+ * key so a retry cannot double-send.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function broadcast(newsletterId: string, issueId: number, audienceListId: number): Promise<void> {
+  const path = { newsletter_id: newsletterId };
+
+  // 1. Import the list. The response only acknowledges the job (asynchronous).
+  await g8.api.newsletter.importSubscribersFromAudience({ path, body: { audience_id: audienceListId } });
+
+  // 2. Wait until the subscriber count stops growing, then read the number you are about to mail.
+  let last = -1;
+  let total = 0;
+  for (let i = 0; i < 20 && total !== last; i += 1) {
+    last = total;
+    await new Promise((r) => setTimeout(r, 3000));
+    const page = await g8.api.newsletter.listSubscribers({ path, query: { status: "subscribed", page_size: 1 } });
+    total = (page.data as { total?: number }).total ?? 0;
+  }
+  console.log(`About to mail ${total} subscribers. Stop here unless the owner approved that number.`);
+
+  // 3. Do not send an AI issue that is still generating: it would mail the partial version.
+  const gen = await g8.api.newsletter.getIssueGenerationStatus({ path: { ...path, issue_id: issueId } });
+  if (/pending|running|generating|queued/i.test(String((gen.data as { status?: string }).status ?? ""))) throw new Error("Issue is still being generated");
+
+  // 4. Send (202 = queued, not delivered). The idempotency key makes a retry safe.
+  await g8.api.newsletter.sendIssue({ path: { ...path, issue_id: issueId }, body: {} }, { idempotencyKey: `send-${newsletterId}-${issueId}` });
+
+  // 5. Follow it: `active` turns false when the worker is done.
+  for (let i = 0; i < 100; i += 1) {
+    const status = await g8.api.newsletter.getSendStatus({ path: { ...path, issue_id: issueId } });
+    const data = status.data as { active?: boolean; send?: { status?: string } };
+    console.log(data.send?.status ?? "idle");
+    if (data.active === false) break;
+    await new Promise((r) => setTimeout(r, 5000));
+  }
+}

package/blocks/newsletter/recipes/issue-performance-report.ts

@@ -0,0 +1,26 @@
+/**
+ * @title Report how every sent issue performed
+ * @when A weekly digest or a dashboard backend. Uses the API's field names (delivered, opened, clicked), which differ
+ * from the hand-written g8.newsletter.issueKpis types (opens, clicks). A response with stale=true means the read
+ * failed, NOT that nobody opened the mail.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function report(newsletterId: string): Promise<Array<{ issue: number; subject: string; delivered: number; openRate: number; clickRate: number }>> {
+  const issues = await g8.api.newsletter.listIssues({ path: { newsletter_id: newsletterId } });
+  const rows: Array<{ issue: number; subject: string; delivered: number; openRate: number; clickRate: number }> = [];
+  for (const issue of issues.data as Array<{ id: number; subject?: string; status?: string }>) {
+    if (issue.status !== "sent") continue;
+    const res = await g8.api.newsletter.getIssueAnalyticsKpis({ path: { newsletter_id: newsletterId, issue_id: issue.id } });
+    const data = res.data as { stale?: boolean; kpis: { delivered?: number; opened?: number; clicked?: number } };
+    if (data.stale) {
+      console.warn(`issue ${issue.id}: numbers unavailable right now, skipping (not zero)`);
+      continue;
+    }
+    const delivered = data.kpis.delivered ?? 0;
+    rows.push({ issue: issue.id, subject: issue.subject ?? "", delivered, openRate: delivered ? (data.kpis.opened ?? 0) / delivered : 0, clickRate: delivered ? (data.kpis.clicked ?? 0) / delivered : 0 });
+  }
+  return rows;
+}