@graph8/sdk 0.308.1 → 0.357.0

package/blocks/newsletter/README.md

@@ -0,0 +1,122 @@
+# newsletter
+
+Write, test, schedule and send newsletter issues, manage subscribers, and read open and click numbers.
+**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.
+
+## Install
+
+```
+npx @graph8/sdk add newsletter
+```
+
+Installs `foundation`, `crm` and `lists` first if missing. Everything lands under `g8/newsletter/`.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| graph8 workspace | A verified **sending domain** and default sender for the newsletter (settings: `default_sender_email`, `sending_domain`; DNS records are verified in the graph8 app). | `GET /api/v1/newsletters/{id}/settings` has a `sending_domain`; `.../settings/domain-status?domain=` is verified. |
+| The business | **Consent**: only people who agreed to be mailed may be added or imported. The block never imports anyone by itself. | The owner confirmed the source of every imported list. |
+| graph8 key | `campaigns:launch` permission behind the key for activate, resume and send. | Activating a test newsletter is not a 403. |
+| Your app | `allowedPrefixes` in `app/api/g8/[...path]/route.ts` must include `newsletters` and `lists`. | The route file lists both. |
+
+## The flow, in order (IDs passed between steps)
+
+1. `createNewsletter({ name, goal })` -> **`newsletter.id`** (a UUID string). `NewsletterEditor` does this behind a confirm.
+2. `createIssue(newsletter.id, { subject, html_body, ... })` -> **`issue.id`** (a NUMBER, not a string). The issue is a **draft**.
+   Optional: `generateNewsletterIssue(issue.id)` (billable, runs a model) then poll `getIssueGenerationStatus` until it is no longer running.
+   **Never send an issue whose generation has not finished**: it mails the partial HTML (`IssueScheduler` blocks it).
+3. `sendTestEmail(issue.id, { test_email })`: one email to one address you own.
+4. Subscribers: `addSubscriber` (one person) or `importSubscribersFromAudience({ audience_id: list.id })` (a list; asynchronous, billable when
+   `auto_verify_on_import` is on). Optional: `previewNewsletterSubscriberVerification` (free, shows the cost) then `verifyNewsletterSubscribers` (billable).
+5. `activateNewsletter(newsletter.id)`: launch-class. Once active the scheduler mails any issue whose scheduled time has passed.
+6. `IssueScheduler`: reads `listSubscribers?status=subscribed&page_size=1` for the **recipient count**, then `sendIssue(issue.id, { scheduled_at? })`.
+   `202` means queued, not delivered. Follow with `getSendStatus` (polled until `active` is false). `pauseSend` is immediate;
+   `resumeSend` is external (confirmed); `cancelSend` is permanent.
+7. `NewsletterStats`: `listIssues` (sent rows carry inline KPIs) and `getIssueAnalyticsKpis` for one issue.
+
+```tsx
+// app/newsletter/page.tsx
+"use client";
+import { useState } from "react";
+import { NewsletterEditor } from "@/g8/newsletter/components/newsletter-editor";
+import { IssueScheduler } from "@/g8/newsletter/components/issue-scheduler";
+
+export default function Page() {
+  const [sel, setSel] = useState<{ newsletterId: string; issueId: number } | null>(null);
+  return (
+    <>
+      <NewsletterEditor onSelectIssue={(newsletterId, issue) => setSel({ newsletterId, issueId: issue.id })} />
+      {sel ? <IssueScheduler newsletterId={sel.newsletterId} issueId={sel.issueId} /> : null}
+    </>
+  );
+}
+```
+
+## Default decisions (do not ask the human unless marked)
+
+| Decision | Default | Ask? |
+|---|---|---|
+| Send now vs scheduled | Send now, with Schedule as a second option | no |
+| Who receives an issue | Every `subscribed` person; the count is in the confirm dialog | no |
+| Confirming a send | Always, never auto-send | no |
+| Auto-verify imported addresses | Off; run the preview first and confirm the cost | **yes** |
+| Removing a subscriber | Unsubscribe (keeps the opt-out). Erase only for an erasure request | no |
+
+## Things that surprise people
+
+- **Saving a draft is tier `external` in the contract.** `createNewsletter`, `createIssue` and `updateIssue` are classified conservatively, so the block confirms them too (the dialog says nothing is sent).
+- **Only drafts can be edited or deleted.** A sent issue is a record of mail real people received.
+- **The hand-written `g8.newsletter` client has stale types.** `issueKpis` is typed with `opens/clicks` and `listSubscribers` as a bare array, but the API returns `opened/clicked/delivered/...` and `{ items, total, page, page_size }`. The block and recipes use `g8.api.newsletter.*` for those.
+- **KPIs can be `stale: true`**: the read failed, which is not "zero engagement". `NewsletterStats` says so.
+- **Unsubscribe vs delete**: deleting a subscriber loses the opt-out record, so the same address can be re-imported and mailed again.
+
+## Recipes (server-side, `recipes/`)
+
+- `create-newsletter-and-draft-issue.ts`: set up and test, nothing reaches a subscriber.
+- `import-audience-and-send.ts`: import, count, guard against partial AI content, send with an idempotency key, follow to the end.
+- `issue-performance-report.ts`: per-issue rates, skipping stale reads.
+
+## What is in the block
+
+| Component | File | What it is |
+|---|---|---|
+| `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. |
+| `SubscriberTable` | `components/subscriber-table.tsx` | Subscribers with search, status filter, add, import a list, verify addresses, unsubscribe and erase. |
+| `NewsletterStats` | `components/newsletter-stats.tsx` | Per-issue delivered, opened, clicked, bounced and unsubscribed numbers, with a stale-data warning. |
+
+## Operations
+
+Tiers: `read` and `write` need no confirmation; `billable`, `external` and `destructive` always open `ConfirmSpendDialog` first.
+
+| Operation | Method and path | Tier | Scope | Used by |
+|---|---|---|---|---|
+| `newsletter.listNewsletters` | `GET /api/v1/newsletters` | read | `newsletter:read` | NewsletterEditor |
+| `newsletter.createNewsletter` | `POST /api/v1/newsletters` | external | `newsletter:run` | NewsletterEditor |
+| `newsletter.listIssues` | `GET /api/v1/newsletters/{newsletter_id}/issues` | read | `newsletter:read` | NewsletterEditor, NewsletterStats |
+| `newsletter.activateNewsletter` | `POST /api/v1/newsletters/{newsletter_id}/activate` | external | `newsletter:run` | NewsletterEditor |
+| `newsletter.pauseNewsletter` | `POST /api/v1/newsletters/{newsletter_id}/pause` | write | `newsletter:write` | NewsletterEditor |
+| `newsletter.getIssue` | `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}` | read | `newsletter:read` | IssueForm, IssueScheduler |
+| `newsletter.createIssue` | `POST /api/v1/newsletters/{newsletter_id}/issues` | external | `newsletter:run` | IssueForm |
+| `newsletter.updateIssue` | `PUT /api/v1/newsletters/{newsletter_id}/issues/{issue_id}` | external | `newsletter:run` | IssueForm |
+| `newsletter.generateNewsletterIssue` | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/generate` | billable | `newsletter:run` | IssueForm |
+| `newsletter.getIssueGenerationStatus` | `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/generation-status` | read | `newsletter:read` | IssueForm, IssueScheduler |
+| `newsletter.sendTestEmail` | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send-test` | external | `newsletter:run` | IssueForm |
+| `newsletter.deleteIssue` | `DELETE /api/v1/newsletters/{newsletter_id}/issues/{issue_id}` | destructive | `newsletter:delete` | IssueForm |
+| `newsletter.listSubscribers` | `GET /api/v1/newsletters/{newsletter_id}/subscribers` | read | `newsletter:read` | IssueScheduler, SubscriberTable |
+| `newsletter.sendIssue` | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send` | external | `newsletter:run` | IssueScheduler |
+| `newsletter.getSendStatus` | `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send` | read | `newsletter:read` | IssueScheduler |
+| `newsletter.pauseSend` | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send/pause` | write | `newsletter:write` | IssueScheduler |
+| `newsletter.resumeSend` | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send/resume` | external | `newsletter:run` | IssueScheduler |
+| `newsletter.cancelSend` | `POST /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/send/cancel` | write | `newsletter:write` | IssueScheduler |
+| `newsletter.addSubscriber` | `POST /api/v1/newsletters/{newsletter_id}/subscribers` | external | `newsletter:run` | SubscriberTable |
+| `lists.listLists` | `GET /api/v1/lists` | read | `lists:read` | SubscriberTable |
+| `newsletter.importSubscribersFromAudience` | `POST /api/v1/newsletters/{newsletter_id}/subscribers/import-audience` | billable | `newsletter:run` | SubscriberTable |
+| `newsletter.previewNewsletterSubscriberVerification` | `POST /api/v1/newsletters/{newsletter_id}/subscribers/verify/preview` | read | `newsletter:read` | SubscriberTable |
+| `newsletter.verifyNewsletterSubscribers` | `POST /api/v1/newsletters/{newsletter_id}/subscribers/verify` | billable | `newsletter:run` | SubscriberTable |
+| `newsletter.unsubscribeSubscriber` | `PATCH /api/v1/newsletters/{newsletter_id}/subscribers/{subscriber_id}/unsubscribe` | external | `newsletter:run` | SubscriberTable |
+| `newsletter.deleteSubscriber` | `DELETE /api/v1/newsletters/{newsletter_id}/subscribers/{subscriber_id}` | destructive | `newsletter:delete` | SubscriberTable |
+| `newsletter.getIssueAnalyticsKpis` | `GET /api/v1/newsletters/{newsletter_id}/issues/{issue_id}/analytics/kpis` | read | `newsletter:read` | NewsletterStats |

package/blocks/newsletter/block.json

@@ -0,0 +1,224 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "newsletter",
+  "title": "Newsletter",
+  "summary": "Write, test, schedule and send newsletter issues to subscribers, manage the subscriber list, and read open and click statistics.",
+  "features": [
+    "newsletters and issue drafts with AI generation",
+    "test send to one address",
+    "send now or schedule with the subscriber count confirmed",
+    "send progress with pause, resume and cancel",
+    "subscriber table with add, import a list, verify, unsubscribe and erase",
+    "per-issue delivery, open and click statistics"
+  ],
+  "dependsOn": [
+    "lists"
+  ],
+  "operations": [
+    "list_newsletters_newsletters_get",
+    "create_newsletter_newsletters_post",
+    "list_issues_newsletters__newsletter_id__issues_get",
+    "activate_newsletter_newsletters__newsletter_id__activate_post",
+    "pause_newsletter_newsletters__newsletter_id__pause_post",
+    "get_issue_newsletters__newsletter_id__issues__issue_id__get",
+    "create_issue_newsletters__newsletter_id__issues_post",
+    "update_issue_newsletters__newsletter_id__issues__issue_id__put",
+    "generate_newsletter_issue_newsletters__newsletter_id__issues__issue_id__generate_post",
+    "get_issue_generation_status_newsletters__newsletter_id__issues__issue_id__generation_status_get",
+    "send_test_email_newsletters__newsletter_id__issues__issue_id__send_test_post",
+    "delete_issue_newsletters__newsletter_id__issues__issue_id__delete",
+    "list_subscribers_newsletters__newsletter_id__subscribers_get",
+    "send_issue_newsletters__newsletter_id__issues__issue_id__send_post",
+    "get_send_status_newsletters__newsletter_id__issues__issue_id__send_get",
+    "pause_send_newsletters__newsletter_id__issues__issue_id__send_pause_post",
+    "resume_send_newsletters__newsletter_id__issues__issue_id__send_resume_post",
+    "cancel_send_newsletters__newsletter_id__issues__issue_id__send_cancel_post",
+    "add_subscriber_newsletters__newsletter_id__subscribers_post",
+    "list_lists_lists_get",
+    "import_subscribers_from_audience_newsletters__newsletter_id__subscribers_import_audience_post",
+    "preview_newsletter_subscriber_verification_newsletters__newsletter_id__subscribers_verify_preview_post",
+    "verify_newsletter_subscribers_newsletters__newsletter_id__subscribers_verify_post",
+    "unsubscribe_subscriber_newsletters__newsletter_id__subscribers__subscriber_id__unsubscribe_patch",
+    "delete_subscriber_newsletters__newsletter_id__subscribers__subscriber_id__delete",
+    "get_issue_analytics_kpis_newsletters__newsletter_id__issues__issue_id__analytics_kpis_get"
+  ],
+  "components": [
+    {
+      "name": "NewsletterEditor",
+      "file": "components/newsletter-editor.tsx",
+      "purpose": "Pick or create a newsletter, list its issues, write issues and activate or pause the newsletter.",
+      "operations": [
+        "list_newsletters_newsletters_get",
+        "create_newsletter_newsletters_post",
+        "list_issues_newsletters__newsletter_id__issues_get",
+        "activate_newsletter_newsletters__newsletter_id__activate_post",
+        "pause_newsletter_newsletters__newsletter_id__pause_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external"
+      ]
+    },
+    {
+      "name": "IssueForm",
+      "file": "components/issue-form.tsx",
+      "purpose": "Draft one issue: subject, preview text, HTML, AI generation, test send and delete of drafts.",
+      "operations": [
+        "get_issue_newsletters__newsletter_id__issues__issue_id__get",
+        "create_issue_newsletters__newsletter_id__issues_post",
+        "update_issue_newsletters__newsletter_id__issues__issue_id__put",
+        "generate_newsletter_issue_newsletters__newsletter_id__issues__issue_id__generate_post",
+        "get_issue_generation_status_newsletters__newsletter_id__issues__issue_id__generation_status_get",
+        "send_test_email_newsletters__newsletter_id__issues__issue_id__send_test_post",
+        "delete_issue_newsletters__newsletter_id__issues__issue_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "IssueScheduler",
+      "file": "components/issue-scheduler.tsx",
+      "purpose": "Send an issue now or schedule it, confirmed with the subscriber count, then follow, pause, resume or cancel the send.",
+      "operations": [
+        "get_issue_newsletters__newsletter_id__issues__issue_id__get",
+        "list_subscribers_newsletters__newsletter_id__subscribers_get",
+        "get_issue_generation_status_newsletters__newsletter_id__issues__issue_id__generation_status_get",
+        "send_issue_newsletters__newsletter_id__issues__issue_id__send_post",
+        "get_send_status_newsletters__newsletter_id__issues__issue_id__send_get",
+        "pause_send_newsletters__newsletter_id__issues__issue_id__send_pause_post",
+        "resume_send_newsletters__newsletter_id__issues__issue_id__send_resume_post",
+        "cancel_send_newsletters__newsletter_id__issues__issue_id__send_cancel_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external"
+      ]
+    },
+    {
+      "name": "SubscriberTable",
+      "file": "components/subscriber-table.tsx",
+      "purpose": "Subscribers with search, status filter, add, import a list, verify addresses, unsubscribe and erase.",
+      "operations": [
+        "list_subscribers_newsletters__newsletter_id__subscribers_get",
+        "add_subscriber_newsletters__newsletter_id__subscribers_post",
+        "list_lists_lists_get",
+        "import_subscribers_from_audience_newsletters__newsletter_id__subscribers_import_audience_post",
+        "preview_newsletter_subscriber_verification_newsletters__newsletter_id__subscribers_verify_preview_post",
+        "verify_newsletter_subscribers_newsletters__newsletter_id__subscribers_verify_post",
+        "unsubscribe_subscriber_newsletters__newsletter_id__subscribers__subscriber_id__unsubscribe_patch",
+        "delete_subscriber_newsletters__newsletter_id__subscribers__subscriber_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "billable",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "NewsletterStats",
+      "file": "components/newsletter-stats.tsx",
+      "purpose": "Per-issue delivered, opened, clicked, bounced and unsubscribed numbers, with a stale-data warning.",
+      "operations": [
+        "list_issues_newsletters__newsletter_id__issues_get",
+        "get_issue_analytics_kpis_newsletters__newsletter_id__issues__issue_id__analytics_kpis_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [],
+  "lib": [
+    {
+      "file": "lib/newsletter-types.ts",
+      "purpose": "Newsletter/issue/subscriber types and helpers: draft check, percentages, scheduled-time conversion, generation-in-progress guard."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/create-newsletter-and-draft-issue.ts",
+      "title": "Create a newsletter, draft its first issue, send yourself a test",
+      "when": "Setting up a newsletter before any subscriber exists."
+    },
+    {
+      "file": "recipes/import-audience-and-send.ts",
+      "title": "Import a list as subscribers, send an issue and follow it to the end",
+      "when": "A one-off broadcast to an existing audience; count and confirm before sending."
+    },
+    {
+      "file": "recipes/issue-performance-report.ts",
+      "title": "Report how every sent issue performed",
+      "when": "A weekly digest or dashboard backend; handles stale analytics."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "sending-domain",
+      "description": "A verified sending domain/sender for the newsletter (newsletter settings: default_sender_email, sending_domain). Without it issues cannot be delivered. Verify the domain DNS records in the graph8 app.",
+      "where": "api",
+      "verify": "GET /api/v1/newsletters/{id}/settings shows a sending_domain, and GET .../settings/domain-status?domain= reports verified."
+    },
+    {
+      "id": "consent",
+      "description": "Only people who agreed to receive the newsletter may be added or imported. The block never imports contacts by itself: a person chooses the list and confirms the count.",
+      "where": "app",
+      "verify": "A human owner has confirmed the source and consent of every list that is imported."
+    },
+    {
+      "id": "launch-permission",
+      "description": "Activating, resuming and sending are launch-class and need the campaigns:launch permission behind the key.",
+      "where": "api",
+      "verify": "Activating a test newsletter does not return 403."
+    },
+    {
+      "id": "proxy-allowlist",
+      "description": "Add \"newsletters\" and \"lists\" to allowedPrefixes in app/api/g8/[...path]/route.ts.",
+      "where": "app",
+      "verify": "The route file's allowedPrefixes contains both."
+    }
+  ],
+  "scopes": [
+    "lists:read",
+    "newsletter:delete",
+    "newsletter:read",
+    "newsletter:run",
+    "newsletter:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Send now or scheduled",
+      "default": "Send now; offer Schedule as a second option with a datetime picker",
+      "askHuman": false
+    },
+    {
+      "decision": "Who gets an issue",
+      "default": "Every subscribed person of the newsletter; the count is shown in the confirm dialog",
+      "askHuman": false
+    },
+    {
+      "decision": "Confirming a send",
+      "default": "Always: external tier, with the subscriber count. Never auto-send",
+      "askHuman": false
+    },
+    {
+      "decision": "Whether to enable auto-verify of imported addresses",
+      "default": "Off; run the verification preview first and confirm the credit cost",
+      "askHuman": true
+    },
+    {
+      "decision": "Removing a subscriber",
+      "default": "Unsubscribe (keeps the opt-out record); Erase only for an erasure request",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/newsletter/components/issue-form.tsx

@@ -0,0 +1,124 @@
+"use client";
+
+/**
+ * IssueForm: write one newsletter issue (draft), generate it with AI, send yourself a test.
+ *
+ * SDK operations, in order:
+ *   1. getIssue (GET /newsletters/{id}/issues/{issue_id})                       read
+ *   2. createIssue (POST .../issues) or updateIssue (PUT .../issues/{issue_id})  external -> ConfirmSpendDialog (saves a DRAFT; nothing is sent)
+ *   3. generateNewsletterIssue (POST .../issues/{issue_id}/generate)            billable  -> ConfirmSpendDialog (runs a model)
+ *   4. getIssueGenerationStatus (GET .../generation-status), polled             read      (an unfinished generation is partial HTML)
+ *   5. sendTestEmail (POST .../issues/{issue_id}/send-test)                     external  -> ConfirmSpendDialog (ONE address)
+ *   6. deleteIssue (DELETE .../issues/{issue_id})                               destructive -> ConfirmSpendDialog (drafts only)
+ * Only drafts are editable; a sent issue opens read-only.
+ */
+
+import { useEffect, useState } from "react";
+import { Button, Input, Label, Skeleton, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { g8Delete, g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { generationInProgress, isDraft } from "../lib/newsletter-types";
+import type { Issue } from "../lib/newsletter-types";
+
+export interface IssueFormProps {
+  newsletterId: string;
+  /** Edit this issue; omit to write a new one. */
+  issueId?: number;
+  onSaved?: (issue: Issue) => void;
+  onDeleted?: () => void;
+}
+
+type Confirm = "save" | "generate" | "test" | "delete" | null;
+
+export function IssueForm({ newsletterId, issueId: given, onSaved, onDeleted }: IssueFormProps) {
+  // The id of a draft THIS form created: a second Save (or a retry after a failed follow-up) updates it, never creates a duplicate.
+  const [created, setCreated] = useState<number | undefined>(undefined);
+  const issueId = given ?? created;
+  const base = `/newsletters/${encodeURIComponent(newsletterId)}/issues`;
+  const loaded = useG8Query((signal) => g8Get<Issue>(`${base}/${issueId}`, {}, { signal }).then((r) => r.data), [base, issueId], { enabled: issueId !== undefined });
+  const [subject, setSubject] = useState("");
+  const [preview, setPreview] = useState("");
+  const [html, setHtml] = useState("");
+  const [prompt, setPrompt] = useState("");
+  const [testEmail, setTestEmail] = useState("");
+  const [confirm, setConfirm] = useState<Confirm>(null);
+
+  useEffect(() => {
+    if (!loaded.data) return;
+    setSubject(loaded.data.subject ?? "");
+    setPreview(loaded.data.preview_text ?? "");
+    setHtml(loaded.data.html_body ?? "");
+  }, [loaded.data]);
+
+  const generation = useJobPoll((signal) => g8Get<{ status?: string }>(`${base}/${issueId}/generation-status`, {}, { signal }).then((r) => r.data), {
+    enabled: false,
+    intervalMs: 2500,
+    isTerminal: (s) => !generationInProgress(s),
+    onDone: () => void loaded.refetch(),
+  });
+  const save = useG8Mutation(async () => {
+    const body = { subject: subject.trim(), preview_text: preview.trim() || undefined, html_body: html };
+    const res = issueId === undefined ? await g8Post<Issue>(base, body) : await g8Put<Issue>(`${base}/${issueId}`, body);
+    return res.data;
+  }, { onSuccess: (issue) => { setConfirm(null); if (given === undefined) setCreated(issue.id); onSaved?.(issue); } });
+  const generate = useG8Mutation(() => g8Post(`${base}/${issueId}/generate`, { prompt: prompt.trim() || undefined }), { onSuccess: () => { setConfirm(null); generation.start(); } });
+  const sendTest = useG8Mutation(() => g8Post(`${base}/${issueId}/send-test`, { test_email: testEmail.trim() }), { onSuccess: () => setConfirm(null) });
+  const remove = useG8Mutation(() => g8Delete(`${base}/${issueId}`), { onSuccess: () => { setConfirm(null); onDeleted?.(); } });
+
+  if (issueId !== undefined && loaded.loading && !loaded.data) return <div aria-busy="true" className="grid gap-2"><Skeleton className="h-9 w-full" /><Skeleton className="h-48 w-full" /></div>;
+  if (loaded.error) return <ApiError error={loaded.error} title="Could not load the issue" onRetry={() => void loaded.refetch()} />;
+  const editable = issueId === undefined || isDraft(loaded.data);
+  const busy = generation.polling;
+  const failure = { save: save.error, generate: generate.error, test: sendTest.error, delete: remove.error }[confirm ?? "save"];
+  const dialog = {
+    save: { tier: "external", title: issueId === undefined ? "Save this new draft?" : "Save changes to this draft?", note: "This saves a draft. Nothing is sent to subscribers.", label: "Save draft", go: () => void save.mutate(undefined), loading: save.loading },
+    generate: { tier: "billable", title: "Write this issue with AI?", note: "This runs a model and spends credits. It replaces the current content of the draft.", label: "Generate", go: () => void generate.mutate(undefined), loading: generate.loading },
+    test: { tier: "external", title: `Send a test to ${testEmail}?`, note: "One email goes to this address only. Subscribers are not contacted.", label: "Send test", go: () => void sendTest.mutate(undefined), loading: sendTest.loading },
+    delete: { tier: "destructive", title: "Delete this draft?", note: "The draft is removed for good.", label: "Delete", go: () => void remove.mutate(undefined), loading: remove.loading },
+  } as const;
+  const active = dialog[confirm ?? "save"];
+  return (
+    <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (subject.trim() && html.trim()) setConfirm("save"); }}>
+      {!editable ? <p className="text-muted-foreground text-sm">This issue has been {loaded.data?.status}. It cannot be edited.</p> : null}
+      <div><Label htmlFor="g8-issue-subject" className="mb-1">Subject</Label><Input id="g8-issue-subject" value={subject} disabled={!editable} maxLength={2000} onChange={(e) => setSubject(e.target.value)} /></div>
+      <div><Label htmlFor="g8-issue-preview" className="mb-1">Preview text</Label><Input id="g8-issue-preview" value={preview} disabled={!editable} maxLength={500} onChange={(e) => setPreview(e.target.value)} /></div>
+      <div><Label htmlFor="g8-issue-html" className="mb-1">Content (HTML)</Label><Textarea id="g8-issue-html" rows={10} value={html} disabled={!editable || busy} className="font-mono text-xs" onChange={(e) => setHtml(e.target.value)} /></div>
+      {html ? <iframe title="Issue preview" sandbox="" srcDoc={html} className="h-64 w-full rounded-md border" /> : null}
+      {busy ? <p role="status" className="text-sm">Writing the issue with AI. Do not send it until this finishes: an unfinished issue is partial.</p> : null}
+      {generation.error ? <ApiError error={generation.error} title="Could not read generation progress" /> : null}
+      {editable ? (
+        <div className="flex flex-wrap items-end gap-2">
+          <Button type="submit" disabled={!subject.trim() || !html.trim() || busy}>Save draft</Button>
+          {issueId !== undefined ? (
+            <>
+              <div className="min-w-48 flex-1"><Label htmlFor="g8-issue-prompt" className="mb-1">What should it say? (for AI)</Label><Input id="g8-issue-prompt" value={prompt} onChange={(e) => setPrompt(e.target.value)} /></div>
+              <Button type="button" variant="outline" disabled={busy} onClick={() => setConfirm("generate")}>Write with AI</Button>
+              <Button type="button" variant="ghost" disabled={busy} onClick={() => setConfirm("delete")}>Delete draft</Button>
+            </>
+          ) : null}
+        </div>
+      ) : null}
+      {issueId !== undefined ? (
+        <div className="flex items-end gap-2">
+          <div className="max-w-xs flex-1"><Label htmlFor="g8-issue-test" className="mb-1">Send a test to</Label><Input id="g8-issue-test" type="email" value={testEmail} onChange={(e) => setTestEmail(e.target.value)} /></div>
+          <Button type="button" variant="outline" disabled={!testEmail.includes("@") || busy} onClick={() => setConfirm("test")}>Send test</Button>
+        </div>
+      ) : null}
+      <ConfirmSpendDialog
+        open={confirm !== null}
+        tier={active.tier}
+        title={active.title}
+        description={<><p>{active.note}</p>{failure ? <ApiError error={failure} title="That did not work" /> : null}</>}
+        recipients={confirm === "test" ? 1 : undefined}
+        confirmLabel={active.label}
+        confirming={active.loading}
+        onCancel={() => setConfirm(null)}
+        onConfirm={active.go}
+      />
+    </form>
+  );
+}

package/blocks/newsletter/components/issue-scheduler.tsx

@@ -0,0 +1,152 @@
+"use client";
+
+/**
+ * IssueScheduler: send an issue now or schedule it, and follow the send. THIS MAILS REAL PEOPLE.
+ *
+ * SDK operations, in order:
+ *   1. getIssue (GET /newsletters/{id}/issues/{issue_id})                        read
+ *   2. listSubscribers (GET .../subscribers?status=subscribed&page_size=1)       read      (only for the recipient count in the confirm dialog)
+ *   3. getIssueGenerationStatus (GET .../generation-status), polled and re-read before the confirm   read   (an unfinished AI issue is partial HTML: sending is blocked)
+ *   4. sendIssue (POST .../issues/{issue_id}/send, optional scheduled_at)        external  -> ConfirmSpendDialog with the subscriber count
+ *   5. getSendStatus (GET .../issues/{issue_id}/send), polled                    read      (202 means queued, not delivered)
+ *   6. pauseSend (POST .../send/pause)                                           write
+ *   7. resumeSend (POST .../send/resume)                                         external  -> ConfirmSpendDialog (restarts delivery)
+ *   8. cancelSend (POST .../send/cancel)                                         write     -> confirmed anyway: there is no resuming a canceled send
+ * Delivery happens asynchronously in a worker, so progress comes from polling getSendStatus until `active` is false.
+ */
+
+import { useEffect, 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 { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { generationInProgress, isDraft, issueTitle, sendIsMoving, sendIsPaused, toIsoInstant } from "../lib/newsletter-types";
+import type { Issue, SendState } from "../lib/newsletter-types";
+
+export interface IssueSchedulerProps {
+  newsletterId: string;
+  issueId: number;
+  onSent?: () => void;
+}
+
+type Confirm = "send" | "resume" | "cancel" | null;
+
+export function IssueScheduler({ newsletterId, issueId, onSent }: IssueSchedulerProps) {
+  const base = `/newsletters/${encodeURIComponent(newsletterId)}`;
+  const issueBase = `${base}/issues/${issueId}`;
+  const issue = useG8Query((signal) => g8Get<Issue>(issueBase, {}, { signal }).then((r) => r.data), [issueBase]);
+  const audience = useG8Query((signal) => g8Get<{ total?: number }>(`${base}/subscribers`, { status: "subscribed", page_size: 1 }, { signal }).then((r) => r.data?.total ?? 0), [base]);
+  // Follow the AI generation until it is final: opening this screen mid-generation must unblock Send when it finishes.
+  const generation = useJobPoll((signal) => g8Get<{ status?: string }>(`${issueBase}/generation-status`, {}, { signal }).then((r) => r.data), { intervalMs: 3000, isTerminal: (s) => !generationInProgress(s?.status) });
+  const [lateGeneration, setLateGeneration] = useState(false);
+  // A paused send still reports active: stop polling while it is paused; Resume (or Pause) restarts the poll.
+  const send = useJobPoll((signal) => g8Get<SendState>(`${issueBase}/send`, {}, { signal }).then((r) => r.data), { enabled: false, intervalMs: 3000, isTerminal: (s) => s.active === false || (sendIsPaused(s.send?.status) && !/pausing/i.test(s.send?.status ?? "")) });
+  const [when, setWhen] = useState<"now" | "later">("now");
+  const [at, setAt] = useState("");
+  const [confirm, setConfirm] = useState<Confirm>(null);
+  const scheduledAt = when === "later" ? toIsoInstant(at) : undefined;
+  const inPast = scheduledAt !== undefined && new Date(scheduledAt).getTime() <= Date.now();
+  // Everything typed or opened here belongs to one issue: switching issues starts clean.
+  useEffect(() => {
+    setWhen("now");
+    setAt("");
+    setConfirm(null);
+    setLateGeneration(false);
+  }, [newsletterId, issueId]);
+
+  // The late-generation flag only lasts until the restarted poll sees a final status.
+  useEffect(() => {
+    if (generation.done && !generationInProgress(generation.status?.status)) setLateGeneration(false);
+  }, [generation.done, generation.status]);
+
+  // A generation can start after this screen opened: re-read it right before the confirm instead of trusting the last poll.
+  const openSend = async (): Promise<void> => {
+    try {
+      const fresh = (await g8Get<{ status?: string }>(`${issueBase}/generation-status`)).data;
+      if (generationInProgress(fresh?.status)) {
+        setLateGeneration(true);
+        generation.start();
+        return;
+      }
+    } catch {
+      // The poll above already surfaces a failing status read; do not block the send on a transient error here.
+    }
+    setConfirm("send");
+  };
+  const leftDraft = issue.data ? !isDraft(issue.data) : false;
+  // An issue that is already out: show where its send stands (progress, or "no send is running").
+  useEffect(() => {
+    if (leftDraft) send.start();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [leftDraft]);
+  const subscribers = audience.data ?? 0;
+
+  const start = useG8Mutation(() => g8Post(`${issueBase}/send`, scheduledAt ? { scheduled_at: scheduledAt } : {}), { onSuccess: () => { setConfirm(null); send.start(); void issue.refetch(); onSent?.(); } });
+  const pause = useG8Mutation(() => g8Post(`${issueBase}/send/pause`, {}), { onSuccess: () => send.start() });
+  const resume = useG8Mutation(() => g8Post(`${issueBase}/send/resume`), { onSuccess: () => { setConfirm(null); send.start(); } });
+  const cancel = useG8Mutation(() => g8Post(`${issueBase}/send/cancel`, {}), { onSuccess: () => { setConfirm(null); send.start(); } });
+
+  if (issue.error) return <ApiError error={issue.error} title="Could not load the issue" onRetry={() => void issue.refetch()} />;
+  if (!issue.data) return <Skeleton className="h-40 w-full" aria-busy="true" />;
+  const draft = isDraft(issue.data);
+  const partial = (generationInProgress(generation.status?.status) && !generation.done) || lateGeneration;
+  const invalidLater = when === "later" && (!scheduledAt || inPast);
+  const blocked = !draft || partial || subscribers === 0 || invalidLater;
+  const state = send.status?.send;
+  const moving = sendIsMoving(state?.status);
+  const paused = sendIsPaused(state?.status);
+  const dialogs = {
+    send: { title: scheduledAt ? `Schedule "${issueTitle(issue.data)}" for ${new Date(scheduledAt).toLocaleString()}?` : `Send "${issueTitle(issue.data)}" now?`, label: scheduledAt ? "Schedule" : "Send", go: () => void start.mutate(undefined), loading: start.loading, error: start.error, tier: "external" as const, note: "Real emails go to your subscribers and cannot be recalled." },
+    resume: { title: "Resume this send?", label: "Resume", go: () => void resume.mutate(undefined), loading: resume.loading, error: resume.error, tier: "external" as const, note: "Delivery restarts for the recipients who have not received this issue yet." },
+    cancel: { title: "Cancel this send for good?", label: "Cancel send", go: () => void cancel.mutate(undefined), loading: cancel.loading, error: cancel.error, tier: "destructive" as const, note: "Whoever already received the issue has it; nobody else will. A canceled send cannot be resumed." },
+  };
+  const active = dialogs[confirm ?? "send"];
+  return (
+    <Card>
+      <CardHeader><CardTitle>{issueTitle(issue.data)} <span className="text-muted-foreground text-sm font-normal">{issue.data.status}</span></CardTitle></CardHeader>
+      <CardContent className="grid gap-4">
+        {partial ? <p role="alert" className="text-sm text-amber-700">This issue is still being written by AI. Wait for it to finish: sending now would mail the partial version.</p> : null}
+        {draft ? (
+          <div className="grid gap-3">
+            <p className="text-sm">Audience: <strong>{audience.loading ? "..." : subscribers.toLocaleString()}</strong> subscribed {subscribers === 1 ? "person" : "people"}.</p>
+            <div className="flex gap-2" role="group" aria-label="When to send">
+              <Button size="sm" variant={when === "now" ? "secondary" : "ghost"} onClick={() => setWhen("now")}>Send now</Button>
+              <Button size="sm" variant={when === "later" ? "secondary" : "ghost"} onClick={() => setWhen("later")}>Schedule</Button>
+            </div>
+            {when === "later" ? <div className="max-w-xs"><Label htmlFor="g8-send-at" className="mb-1">Send at</Label><Input id="g8-send-at" type="datetime-local" value={at} onChange={(e) => setAt(e.target.value)} /></div> : null}
+            {inPast ? <p role="alert" className="text-sm text-red-700">Pick a time in the future.</p> : null}
+            <div><Button disabled={blocked} onClick={() => void openSend()}>{when === "later" ? "Schedule issue" : "Send issue"}</Button></div>
+            {subscribers === 0 && !audience.loading ? <p className="text-muted-foreground text-sm">Add subscribers first (SubscriberTable).</p> : null}
+          </div>
+        ) : <p className="text-sm">{issue.data.sent_at ? `Sent ${new Date(issue.data.sent_at).toLocaleString()}.` : issue.data.scheduled_at ? `Scheduled for ${new Date(issue.data.scheduled_at).toLocaleString()}.` : "This issue is not a draft."}</p>}
+        {send.status ? (
+          <div className="grid gap-2 text-sm" role="status">
+            <p>{send.status.active ? `Sending: ${state?.status ?? "in progress"}` : "No send is running."}{state?.sent_count != null ? ` ${state.sent_count}${state.total_recipients ? ` of ${state.total_recipients}` : ""} sent.${state.failed_count ? ` ${state.failed_count} failed.` : ""}` : ""}</p>
+            {send.status.active ? (
+              <div className="flex gap-2">
+                {moving ? <Button size="sm" variant="outline" loading={pause.loading} onClick={() => void pause.mutate(undefined)}>Pause send</Button> : null}
+                {paused ? <Button size="sm" variant="outline" onClick={() => setConfirm("resume")}>Resume send</Button> : null}
+                <Button size="sm" variant="ghost" onClick={() => setConfirm("cancel")}>Cancel send</Button>
+              </div>
+            ) : null}
+          </div>
+        ) : null}
+        {[send.error, pause.error].filter(Boolean).map((e, i) => <ApiError key={i} error={e} title="Could not follow the send" />)}
+        <ConfirmSpendDialog
+          open={confirm !== null}
+          tier={active.tier}
+          title={active.title}
+          recipients={confirm === "send" ? subscribers : undefined}
+          description={<><p>{active.note}</p>{active.error ? <ApiError error={active.error} title="That did not work" /> : null}</>}
+          confirmLabel={active.label}
+          confirming={active.loading}
+          onCancel={() => setConfirm(null)}
+          onConfirm={active.go}
+        />
+      </CardContent>
+    </Card>
+  );
+}