@graph8/sdk 0.370.0 → 0.374.0

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

@@ -5,10 +5,13 @@
  *
  * Composes: ScreenLayout (title, tabs, stats), Toolbar, SplitView + DetailPanel (selected issue, deep link
  * `?id=`), FormSheet (new newsletter), IssueForm (write, AI, test, delete), IssueScheduler (send, schedule,
- * pause, resume, cancel), SubscriberTable (add, import a list, verify, unsubscribe, erase), NewsletterStats.
+ * pause, resume, cancel), SubscriberTable (add, import a list, verify, unsubscribe, erase), NewsletterStats,
+ * NewsletterSettings (name, sender, opt-in, sending domain, running state), NewsletterListSyncs, NewsletterTemplates,
+ * IssueVersions (history, restore, duplicate) and SubscriberTimeline.
  *
  * Every record has a full detail view: `?tab=` picks Issues, Subscribers, Performance or Details (the newsletter itself);
- * `?id=` opens an issue (Write, Send, Results, Details) or a subscriber (all fields, unsubscribe, erase);
+ * `?id=` opens an issue (Write, Send, Results, History, Details) or a subscriber (all fields, activity, unsubscribe, erase);
+ * the Settings, Lists and Templates tabs manage the newsletter itself, its synced lists and its saved templates;
  * `&view=full` shows the open record as a full page.
  *
  * User flows: pick or create a newsletter (`?newsletter=`), activate or pause it, read the headline numbers,
@@ -39,12 +42,18 @@ import { Toolbar } from "@/g8/components/screen/toolbar";
 import { useUrlState } from "@/g8/hooks/use-url-state";
 import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useAllPages } from "@/g8/hooks/use-all-pages";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { isDraft, issueTitle, percent } from "../lib/newsletter-types";
 import type { Issue, IssueKpis, Newsletter, Subscriber } from "../lib/newsletter-types";
 import { IssueForm } from "./issue-form";
 import { IssueScheduler } from "./issue-scheduler";
+import { IssueVersions } from "./issue-versions";
+import { NewsletterListSyncs } from "./newsletter-list-syncs";
+import { NewsletterSettings } from "./newsletter-settings";
 import { NewsletterStats } from "./newsletter-stats";
+import { NewsletterTemplates } from "./newsletter-templates";
+import { SubscriberTimeline } from "./subscriber-timeline";
 import { SubscriberTable } from "./subscriber-table";
 import { useBrand } from "@/g8/hooks/use-brand";
 
@@ -58,7 +67,9 @@ export interface NewsletterScreenProps {
   className?: string;
 }
 
-type Tab = "issues" | "subscribers" | "performance" | "details";
+type Tab = "issues" | "subscribers" | "performance" | "details" | "settings" | "lists" | "templates";
+/** Subscribers per read when looking one up for a deep link; every page is read. */
+const SUBSCRIBER_PAGE = 100; // the API caps page_size at 100 (a larger value is a 422)
 const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
 
 function tone(status: string | undefined): Tone {
@@ -119,7 +130,7 @@ function IssueDetails({ issue }: { issue: Issue }) {
   );
 }
 
-function SubscriberDetail({ newsletterId, subscriber, onChanged, onClose, expandProps }: { newsletterId: string; subscriber: Subscriber; onChanged: () => void; onClose: () => void; expandProps: { onExpand: () => void; onCollapse?: () => void } }) {
+function SubscriberDetail({ newsletterId, subscriber, issues, onChanged, onClose, expandProps }: { newsletterId: string; subscriber: Subscriber; issues?: Issue[]; onChanged: () => void; onClose: () => void; expandProps: { onExpand: () => void; onCollapse?: () => void } }) {
   const [confirm, setConfirm] = useState<"unsubscribe" | "erase" | null>(null);
   const base = `/newsletters/${encodeURIComponent(newsletterId)}/subscribers/${subscriber.id}`;
   const run = useG8Mutation((kind: "unsubscribe" | "erase") => (kind === "unsubscribe" ? g8Patch(`${base}/unsubscribe`, {}) : g8Delete(base)), {
@@ -155,6 +166,7 @@ function SubscriberDetail({ newsletterId, subscriber, onChanged, onClose, expand
           ...extra.map(([key, v]) => ({ label: key.replace(/_/g, " "), value: String(v) })),
         ]}
       />
+      {issues ? <SubscriberTimeline className="mt-4" newsletterId={newsletterId} subscriberId={subscriber.id} issues={issues} /> : null}
       <ConfirmSpendDialog
         open={confirm !== null}
         tier={confirm === "erase" ? "destructive" : "external"}
@@ -177,7 +189,7 @@ export function NewsletterScreen({ initialNewsletterId, renderRowActions, render
   const [view, setView] = useUrlState("view", "");
   const expandProps = { onExpand: () => setView("full"), onCollapse: view === "full" ? () => setView(null) : undefined };
   const [tabParam, setTabParam] = useUrlState("tab", "issues");
-  const tab = (["issues", "subscribers", "performance", "details"].includes(tabParam) ? tabParam : "issues") as Tab;
+  const tab = (["issues", "subscribers", "performance", "details", "settings", "lists", "templates"].includes(tabParam) ? tabParam : "issues") as Tab;
   const closeDetail = (): void => { setIssueParam(null); setView(null); };
   const [subRefresh, setSubRefresh] = useState(0);
   const [openedSubscriber, setOpenedSubscriber] = useState<Subscriber | null>(null);
@@ -187,6 +199,10 @@ export function NewsletterScreen({ initialNewsletterId, renderRowActions, render
   const [name, setName] = useState("");
   const [goal, setGoal] = useState("");
   const [pending, setPending] = useState<"create" | "activate" | null>(null);
+  // Bumped after a version restore so the editor reloads the draft instead of showing the old text.
+  // Bumped after a version restore so the Write tab remounts and reloads the draft. The History tab is NOT keyed on it:
+  // remounting it would drop a Duplicate confirm opened right after the restore (it refetches its own versions).
+  const [formRev, setFormRev] = useState(0);
 
   const newsletters = useG8Query((signal) => g8Get<Newsletter[]>("/newsletters", {}, { signal }).then((r) => r.data ?? []), []);
   const list = newsletters.data ?? [];
@@ -209,12 +225,17 @@ export function NewsletterScreen({ initialNewsletterId, renderRowActions, render
   const pause = useG8Mutation(() => g8Post(`${base}/pause`), { onSuccess: () => void newsletters.refetch() });
 
   const subscriberId = tab === "subscribers" && issueParam ? Number(issueParam) : undefined;
-  const lookup = useG8Query(
-    (signal) => g8Get<{ items?: Subscriber[] }>(`${base}/subscribers`, { page: 1, page_size: 200 }, { signal }).then((r) => r.data?.items ?? []),
+  // A deep link to a subscriber reads every page (100 per read), so no subscriber is out of reach.
+  const lookup = useAllPages<Subscriber>(
+    async (page, signal) => {
+      const r = await g8Get<{ items?: Subscriber[]; total?: number }>(`${base}/subscribers`, { page, page_size: SUBSCRIBER_PAGE }, { signal });
+      const rows = r.data?.items ?? [];
+      return { rows, hasNext: r.data?.total != null ? page * SUBSCRIBER_PAGE < r.data.total : rows.length >= SUBSCRIBER_PAGE };
+    },
     [base, subRefresh],
-    { enabled: subscriberId !== undefined && openedSubscriber?.id !== subscriberId },
+    { enabled: Boolean(newsletterId) && subscriberId !== undefined && openedSubscriber?.id !== subscriberId },
   );
-  const openSubscriber = subscriberId === undefined ? null : openedSubscriber?.id === subscriberId ? openedSubscriber : ((lookup.data ?? []).find((x) => x.id === subscriberId) ?? null);
+  const openSubscriber = subscriberId === undefined ? null : openedSubscriber?.id === subscriberId ? openedSubscriber : (lookup.items.find((x) => x.id === subscriberId) ?? null);
   const all = issues.data ?? [];
   const sent = all.filter((i) => i.status === "sent" || i.sent_at);
   const totals = sent.reduce((a, i) => ({ delivered: a.delivered + (i.kpis?.delivered ?? 0), opened: a.opened + (i.kpis?.opened ?? 0), clicked: a.clicked + (i.kpis?.clicked ?? 0) }), { delivered: 0, opened: 0, clicked: 0 });
@@ -227,9 +248,10 @@ export function NewsletterScreen({ initialNewsletterId, renderRowActions, render
   const pickNewsletter = (id: string): void => { setIssueParam(null); setUrlNewsletter(id); };
   const detailTabs = selected
     ? [
-        { id: "write", label: isDraft(selected) ? "Write" : "Content", content: <IssueForm key={`f${selected.id}`} newsletterId={newsletterId} issueId={selected.id} onSaved={() => void issues.refetch()} onDeleted={() => { setIssueParam(null); void issues.refetch(); }} /> },
+        { id: "write", label: isDraft(selected) ? "Write" : "Content", content: <IssueForm key={`f${selected.id}:${formRev}`} newsletterId={newsletterId} issueId={selected.id} onSaved={() => void issues.refetch()} onDeleted={() => { setIssueParam(null); void issues.refetch(); }} /> },
         { id: "send", label: "Send", content: <IssueScheduler key={`s${selected.id}`} newsletterId={newsletterId} issueId={selected.id} onSent={() => void issues.refetch()} /> },
         { id: "results", label: "Results", content: <IssueResults newsletterId={newsletterId} issue={selected} /> },
+        { id: "history", label: "History", content: <IssueVersions key={`v${selected.id}`} newsletterId={newsletterId} issue={selected} onRestored={() => { setFormRev((n) => n + 1); void issues.refetch(); }} onDuplicated={(id) => { void issues.refetch(); setIssueParam(String(id)); }} /> },
         { id: "details", label: "Issue details", content: <IssueDetails issue={selected} /> },
         ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selected) })),
       ]
@@ -287,9 +309,9 @@ export function NewsletterScreen({ initialNewsletterId, renderRowActions, render
       detailWidth="lg"
       list={<SubscriberTable key={newsletterId} newsletterId={newsletterId} refreshKey={subRefresh} selectedId={subscriberId} onOpen={(sub) => { setOpenedSubscriber(sub); setIssueParam(String(sub.id)); }} />}
       detail={openSubscriber ? (
-        <SubscriberDetail key={openSubscriber.id} newsletterId={newsletterId} subscriber={openSubscriber} onChanged={() => { setSubRefresh((n) => n + 1); setOpenedSubscriber(null); }} onClose={() => { closeDetail(); setOpenedSubscriber(null); }} expandProps={expandProps} />
+        <SubscriberDetail key={openSubscriber.id} newsletterId={newsletterId} subscriber={openSubscriber} issues={all} onChanged={() => { setSubRefresh((n) => n + 1); setOpenedSubscriber(null); }} onClose={() => { closeDetail(); setOpenedSubscriber(null); }} expandProps={expandProps} />
       ) : lookup.loading ? <Skeleton className="h-40 w-full" aria-busy="true" /> : (
-        <EmptyState title="Subscriber not found" description="Open a subscriber from the list. Direct links reach the first 200 subscribers." />
+        <EmptyState title="Subscriber not found" description="Open a subscriber from the list." />
       )}
     />
   )
@@ -320,6 +342,9 @@ export function NewsletterScreen({ initialNewsletterId, renderRowActions, render
       </DetailPanel>
     )
     : tab === "performance" ? <NewsletterStats key={newsletterId} newsletterId={newsletterId} />
+    : tab === "settings" ? <NewsletterSettings key={newsletterId} newsletterId={newsletterId} onChanged={() => void newsletters.refetch()} />
+    : tab === "lists" ? <NewsletterListSyncs key={newsletterId} newsletterId={newsletterId} onChanged={() => setSubRefresh((n) => n + 1)} />
+    : tab === "templates" ? <NewsletterTemplates key={newsletterId} newsletterId={newsletterId} onUsed={(id) => { void issues.refetch(); setTabParam(null); setIssueParam(String(id)); }} />
     : (
       <SplitView
         detailOpen={detailOpen}
@@ -364,7 +389,7 @@ export function NewsletterScreen({ initialNewsletterId, renderRowActions, render
           <Button size="sm" onClick={() => setSheet(true)}><Plus className="size-4" />New newsletter</Button>
         </>
       )}
-      tabs={current ? [{ id: "issues", label: "Issues", count: all.length }, { id: "subscribers", label: "Subscribers", count: audience.data }, { id: "performance", label: "Performance" }, { id: "details", label: "Details" }] : undefined}
+      tabs={current ? [{ id: "issues", label: "Issues", count: all.length }, { id: "subscribers", label: "Subscribers", count: audience.data }, { id: "performance", label: "Performance" }, { id: "templates", label: "Templates" }, { id: "lists", label: "Lists" }, { id: "settings", label: "Settings" }, { id: "details", label: "Details" }] : undefined}
       activeTab={tab}
       onTabChange={(id) => { setTabParam(id === "issues" ? null : id); closeDetail(); setOpenedSubscriber(null); }}
       stats={current ? [

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

@@ -0,0 +1,211 @@
+"use client";
+
+/**
+ * NewsletterSettings: everything about the newsletter itself. Its name and goal, who it sends as, double opt-in and
+ * address-check policy, the sending domain (start verification, read the DNS records, check status), and whether it is
+ * running (resume a paused newsletter, mark it completed).
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. getNewsletter                GET   /newsletters/{id}                             (read)
+ *   2. updateNewsletter             PATCH /newsletters/{id} { name?, goal? }            (write; ONLY changed fields are sent)
+ *   3. getNewsletterSettings        GET   /newsletters/{id}/settings                    (read)
+ *   4. updateNewsletterSettings     PUT   /newsletters/{id}/settings                    (write; ONLY changed fields are sent)
+ *   5. verifyNewsletterDomain       POST  /newsletters/{id}/settings/verify-domain { domain }   (EXTERNAL, confirmed: registers the domain with the email provider)
+ *   6. newsletterDomainStatus       GET   /newsletters/{id}/settings/domain-status?domain       (read; may mark the domain verified)
+ *   7. resumeNewsletter             POST  /newsletters/{id}/resume                      (EXTERNAL, confirmed: scheduled issues can send again)
+ *   8. completeNewsletter           POST  /newsletters/{id}/complete                    (write; two-step button, can be re-activated)
+ *
+ * Each form is seeded from the loaded record only and stays read-only until it has loaded, so a blank form can never be
+ * saved over real values. Pausing and activating stay on the screen header.
+ */
+import { useState } from "react";
+import { Button, Input, Label, Skeleton, Switch } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useConfirmAction } from "@/g8/components/confirmed-action";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Patch, g8Post, g8Put } from "@/g8/lib/g8-client";
+import type { Newsletter } from "../lib/newsletter-types";
+import { asRec, changedFields, dnsRecordsOf, isDomain, str } from "../lib/newsletter-extra";
+import type { Rec } from "../lib/newsletter-extra";
+
+export interface NewsletterSettingsProps {
+  newsletterId: string;
+  /** Called after the newsletter or its status changed, so the screen refreshes its header. */
+  onChanged?: () => void;
+  className?: string;
+}
+
+function Basics({ newsletter, onSaved }: { newsletter: Newsletter; onSaved: () => void }) {
+  // Only what the person typed is held as `edits`, shown over the saved copy: a reload never wipes typing.
+  const saved = { name: newsletter.name ?? "", goal: newsletter.goal ?? "" };
+  const [edits, setEdits] = useState<Partial<typeof saved>>({});
+  const draft = { ...saved, ...edits };
+  const setDraft = (next: typeof saved): void => setEdits(Object.fromEntries(Object.entries(next).filter(([k, v]) => v !== saved[k as keyof typeof saved])) as Partial<typeof saved>);
+  const changes = changedFields(saved, draft);
+  const save = useG8Mutation(() => g8Patch(`/newsletters/${encodeURIComponent(newsletter.id)}`, changes), { onSuccess: () => { setEdits({}); onSaved(); } });
+  const bad = "name" in changes && String(changes.name).trim() === "";
+  return (
+    <form className="grid gap-3 sm:grid-cols-2" onSubmit={(e) => { e.preventDefault(); if (Object.keys(changes).length && !bad) void save.mutate(undefined); }}>
+      <div><Label htmlFor="ns-name" className="mb-1">Name</Label><Input id="ns-name" value={draft.name} onChange={(e) => setDraft({ ...draft, name: e.target.value })} aria-invalid={bad} /></div>
+      <div><Label htmlFor="ns-goal" className="mb-1">Goal</Label><Input id="ns-goal" value={draft.goal} placeholder="What this newsletter is for" onChange={(e) => setDraft({ ...draft, goal: e.target.value })} /></div>
+      <div className="sm:col-span-2"><Button type="submit" loading={save.loading} disabled={Object.keys(changes).length === 0 || bad}>Save name and goal</Button></div>
+      {save.error ? <div className="sm:col-span-2"><ApiError error={save.error} title="Could not save" /></div> : null}
+    </form>
+  );
+}
+
+function SenderForm({ saved, newsletterId, onSaved }: { saved: Rec; newsletterId: string; onSaved: () => void }) {
+  const initial = {
+    default_sender_name: str(saved.default_sender_name),
+    default_sender_email: str(saved.default_sender_email),
+    default_reply_to: str(saved.default_reply_to),
+    double_opt_in_intent: Boolean(saved.double_opt_in_intent ?? saved.double_opt_in),
+    skip_unverified_subscribers: Boolean(saved.skip_unverified_subscribers),
+    auto_verify_on_import: Boolean(saved.auto_verify_on_import),
+  };
+  const [edits, setEdits] = useState<Partial<typeof initial>>({});
+  const draft = { ...initial, ...edits };
+  const setDraft = (next: typeof initial): void => setEdits(Object.fromEntries(Object.entries(next).filter(([k, v]) => v !== initial[k as keyof typeof initial])) as Partial<typeof initial>);
+  const changes = changedFields(initial, draft);
+  const emailBad = ["default_sender_email", "default_reply_to"].some((k) => draft[k as keyof typeof draft] !== "" && !/^\S+@\S+\.\S+$/.test(String(draft[k as keyof typeof draft])));
+  const save = useG8Mutation(() => g8Put(`/newsletters/${encodeURIComponent(newsletterId)}/settings`, Object.fromEntries(Object.entries(changes).map(([k, v]) => [k, v === "" ? null : v]))), { onSuccess: () => { setEdits({}); onSaved(); } });
+  const toggle = (key: "double_opt_in_intent" | "skip_unverified_subscribers" | "auto_verify_on_import", label: string, help: string) => (
+    <div className="flex items-start gap-2">
+      <Switch id={`ns-${key}`} checked={draft[key]} onCheckedChange={(v) => setDraft({ ...draft, [key]: v })} aria-label={label} />
+      <div><Label htmlFor={`ns-${key}`}>{label}</Label><p className="text-muted-foreground text-xs">{help}</p></div>
+    </div>
+  );
+  return (
+    <form className="grid gap-3 sm:grid-cols-2" onSubmit={(e) => { e.preventDefault(); if (Object.keys(changes).length && !emailBad) void save.mutate(undefined); }}>
+      <div><Label htmlFor="ns-sname" className="mb-1">Sender name</Label><Input id="ns-sname" value={draft.default_sender_name} onChange={(e) => setDraft({ ...draft, default_sender_name: e.target.value })} /></div>
+      <div><Label htmlFor="ns-semail" className="mb-1">Sender email</Label><Input id="ns-semail" type="email" value={draft.default_sender_email} onChange={(e) => setDraft({ ...draft, default_sender_email: e.target.value })} /></div>
+      <div><Label htmlFor="ns-reply" className="mb-1">Reply to</Label><Input id="ns-reply" type="email" value={draft.default_reply_to} onChange={(e) => setDraft({ ...draft, default_reply_to: e.target.value })} /></div>
+      <div className="grid gap-3 sm:col-span-2">
+        {toggle("double_opt_in_intent", "Ask new subscribers to confirm (double opt-in)", "Turns on once the sending domain is verified and a sender email is set.")}
+        {toggle("auto_verify_on_import", "Check addresses when a list is imported", "Verifying addresses uses credits.")}
+        {toggle("skip_unverified_subscribers", "Skip addresses that failed the check", "They stay subscribed but are not mailed.")}
+      </div>
+      {emailBad ? <p role="alert" className="text-error-foreground text-xs sm:col-span-2">Enter a full email address, for example news@updates.acme.com.</p> : null}
+      <div className="sm:col-span-2"><Button type="submit" loading={save.loading} disabled={Object.keys(changes).length === 0 || emailBad}>Save sender settings</Button></div>
+      {save.error ? <div className="sm:col-span-2"><ApiError error={save.error} title="Could not save the settings" /></div> : null}
+    </form>
+  );
+}
+
+function SendingDomain({ saved, newsletterId, onChanged }: { saved: Rec; newsletterId: string; onChanged: () => void }) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const base = `/newsletters/${encodeURIComponent(newsletterId)}/settings`;
+  const [domain, setDomain] = useState(str(saved.sending_domain));
+  const [records, setRecords] = useState<Rec[]>([]);
+  const [note, setNote] = useState("");
+  const verified = saved.domain_verified === true;
+  const status = useG8Mutation(async () => {
+    const d = asRec((await g8Get(`${base}/domain-status`, { domain: domain.trim() })).data);
+    setNote(d.verified === true ? "Verified. You can send from this domain." : "Not verified yet. DNS changes can take a while to spread; check again later.");
+    if (d.verified === true) onChanged();
+  });
+  const start = (): void => ask({
+    tier: "external",
+    title: `Start verifying ${domain.trim()}`,
+    confirmLabel: "Start verification",
+    description: "Registers this domain with the email provider and saves it as the sending domain. You then add the DNS records it returns at your DNS host. Nothing is sent.",
+    run: async () => {
+      const d = asRec((await g8Post(`${base}/verify-domain`, { domain: domain.trim() })).data);
+      setRecords(dnsRecordsOf(d));
+      setNote(str(d.instructions));
+    },
+    onDone: onChanged,
+  });
+  return (
+    <div className="grid gap-3">
+      <div className="flex flex-wrap items-end gap-2">
+        <div className="min-w-60 flex-1"><Label htmlFor="ns-domain" className="mb-1">Sending domain</Label><Input id="ns-domain" placeholder="updates.acme.com" value={domain} onChange={(e) => setDomain(e.target.value)} aria-invalid={domain !== "" && !isDomain(domain)} /></div>
+        <Button variant="outline" disabled={!isDomain(domain)} onClick={start}>Start verification</Button>
+        <Button variant="outline" loading={status.loading} disabled={!isDomain(domain)} onClick={() => void status.mutate(undefined)}>Check status</Button>
+        {verified ? <StatusPill tone="positive">Verified</StatusPill> : saved.sending_domain ? <StatusPill tone="warning">Not verified</StatusPill> : null}
+      </div>
+      {domain !== "" && !isDomain(domain) ? <p role="alert" className="text-error-foreground text-xs">Enter a domain such as updates.acme.com, without https://.</p> : null}
+      {note ? <p role="status" className="text-sm">{note}</p> : null}
+      {records.length > 0 ? (
+        <ul className="grid gap-2" aria-label="DNS records to add">
+          {records.map((r, i) => (
+            <li key={i} className="rounded-md border p-2 text-xs"><span className="font-medium">{str(r.type) || str(r.record_type)}</span> <span className="font-mono">{str(r.name)}</span> <span className="font-mono break-all">{str(r.value)}</span></li>
+          ))}
+        </ul>
+      ) : null}
+      {status.error ? <ApiError error={status.error} title="Could not check the domain" /> : null}
+      {failure ? <ApiError error={failure} title="Could not start verification" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </div>
+  );
+}
+
+function Lifecycle({ newsletter, onChanged }: { newsletter: Newsletter; onChanged: () => void }) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const [sure, setSure] = useState(false);
+  const base = `/newsletters/${encodeURIComponent(newsletter.id)}`;
+  const complete = useG8Mutation(() => g8Post(`${base}/complete`), { onSuccess: () => { setSure(false); onChanged(); } });
+  const status = newsletter.status ?? "draft";
+  return (
+    <div className="grid gap-3">
+      <p className="text-sm">Status: <StatusPill tone={status === "active" ? "positive" : "neutral"}>{status}</StatusPill></p>
+      <div className="flex flex-wrap gap-2">
+        {status === "paused" ? (
+          <Button variant="outline" onClick={() => ask({
+            tier: "external", title: `Resume ${newsletter.name}`, confirmLabel: "Resume newsletter",
+            description: "Issues scheduled for a time that has passed send to real subscribers again, and cannot be recalled.",
+            run: () => g8Post(`${base}/resume`), onDone: onChanged,
+          })}>Resume newsletter</Button>
+        ) : null}
+        {status !== "completed" ? (
+          sure ? (
+            <>
+              <Button variant="outline" loading={complete.loading} onClick={() => void complete.mutate(undefined)}>Yes, stop this newsletter</Button>
+              <Button variant="ghost" onClick={() => setSure(false)}>Keep it running</Button>
+            </>
+          ) : <Button variant="outline" onClick={() => setSure(true)}>Mark as completed</Button>
+        ) : <p className="text-muted-foreground text-sm">Completed newsletters send nothing. Activate it from the header to start again.</p>}
+      </div>
+      {sure ? <p className="text-muted-foreground text-xs">No more issues are sent. You can activate the newsletter again later.</p> : null}
+      {complete.error ? <ApiError error={complete.error} title="Could not complete the newsletter" /> : null}
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </div>
+  );
+}
+
+export function NewsletterSettings({ newsletterId, onChanged, className }: NewsletterSettingsProps) {
+  const base = `/newsletters/${encodeURIComponent(newsletterId)}`;
+  const nl = useG8Query((signal) => g8Get<Newsletter>(base, undefined, { signal }).then((r) => r.data), [newsletterId]);
+  const settings = useG8Query((signal) => g8Get(`${base}/settings`, undefined, { signal }), [newsletterId]);
+  const saved = asRec(settings.data?.data);
+  const changed = (): void => { void nl.refetch(); void settings.refetch(); onChanged?.(); };
+  return (
+    <div className={className}>
+      <div className="grid gap-4">
+        <SectionCard title="Name and goal">
+          {nl.error ? <ApiError error={nl.error} title="Could not load the newsletter" onRetry={() => void nl.refetch()} /> : !nl.data ? <Skeleton className="h-20 w-full" aria-busy="true" /> : (
+            <Basics key={nl.data.id} newsletter={nl.data} onSaved={changed} />
+          )}
+        </SectionCard>
+        <SectionCard title="Sender and opt-in" description="Who issues come from, and how people confirm.">
+          {settings.error ? <ApiError error={settings.error} title="Could not load the settings" onRetry={() => void settings.refetch()} /> : !settings.data ? <Skeleton className="h-32 w-full" aria-busy="true" /> : (
+            <SenderForm key={newsletterId} saved={saved} newsletterId={newsletterId} onSaved={changed} />
+          )}
+        </SectionCard>
+        <SectionCard title="Sending domain" description="Issues are only delivered from a verified domain.">
+          {settings.data ? <SendingDomain key={newsletterId} saved={saved} newsletterId={newsletterId} onChanged={changed} /> : <Skeleton className="h-16 w-full" aria-busy="true" />}
+        </SectionCard>
+        <SectionCard title="Running state">
+          {nl.data ? <Lifecycle newsletter={nl.data} onChanged={changed} /> : <Skeleton className="h-12 w-full" aria-busy="true" />}
+        </SectionCard>
+        {nl.data ? <KeyValueList columns={2} items={[{ label: "Newsletter id", value: nl.data.id, mono: true }, { label: "Slug", value: nl.data.slug }]} /> : null}
+      </div>
+    </div>
+  );
+}

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

@@ -30,7 +30,7 @@ function Tile({ label, value, sub }: { label: string; value: number | undefined;
   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>
+      <p className="text-xl font-medium">{(value ?? 0).toLocaleString()}</p>
       {sub ? <p className="text-muted-foreground text-xs">{sub}</p> : null}
     </div>
   );
@@ -69,7 +69,7 @@ export function NewsletterStats({ newsletterId }: NewsletterStatsProps) {
           <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>
+              <p role="alert" className="text-sm text-warning-foreground">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">

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

@@ -0,0 +1,133 @@
+"use client";
+
+/**
+ * NewsletterTemplates: your saved issue templates. Start a new draft issue from one, approve or archive it, rename it,
+ * delete it, or have AI write a new one from an idea.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. listTemplates (newsletter)  GET    /newsletters/templates                              (read; the whole list, no cap)
+ *   2. useTemplate                 POST   /newsletters/templates/{id}/use { newsletter_id }   (write; creates a DRAFT issue, sends nothing)
+ *   3. setTemplateApproval         POST   /newsletters/templates/{id}/approval { status }     (write)
+ *   4. updateNewsletterTemplate    PATCH  /newsletters/templates/{id} { name }                (write; only a changed name is sent)
+ *   5. deleteNewsletterTemplate    DELETE /newsletters/templates/{id}                         (destructive, confirmed)
+ *   6. createTemplateFromPrompt    POST   /newsletters/templates/custom { idea, tone?, length? }  (BILLABLE, confirmed; builds in the background)
+ *   7. templateGenerationStatus    GET    /newsletters/templates/{id}/generation-status       (read; polled every 3 s while a template is being written)
+ *
+ * The API quotes no price for AI templates in advance and the balance is not checked here, so the dialog says what runs.
+ */
+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 { useConfirmAction } from "@/g8/components/confirmed-action";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { asRec, num, rowsOf, str } from "../lib/newsletter-extra";
+import type { Rec } from "../lib/newsletter-extra";
+
+export interface NewsletterTemplatesProps {
+  /** The newsletter a template is used in. */
+  newsletterId: string;
+  /** Called with the new draft issue's id after "Use for a new issue". */
+  onUsed?: (issueId: number) => void;
+  className?: string;
+}
+
+const SELECT = "border-input bg-background h-8 rounded-md border px-2 text-sm";
+const APPROVAL = ["draft", "approved", "archived"] as const;
+const WORKING = /generating|pending|queued|running/i;
+
+/** The API stores "archived" as "rejected" and returns the raw value: show it as Archived. */
+export function approvalOf(t: Rec): string {
+  const v = str(t.approval_status, "draft");
+  return v === "rejected" ? "archived" : v;
+}
+
+function TemplateRow({ t, newsletterId, onChanged, onUsed }: { t: Rec; newsletterId: string; onChanged: () => void; onUsed?: (id: number) => void }) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const id = num(t.id) as number;
+  const base = `/newsletters/templates/${id}`;
+  const [name, setName] = useState(str(t.name));
+  const generating = WORKING.test(str(t.generation_status));
+  const rename = useG8Mutation(() => g8Patch(base, { name: name.trim() }), { onSuccess: onChanged });
+  const approve = useG8Mutation((status: string) => g8Post(`${base}/approval`, { status }), { onSuccess: onChanged });
+  const use = useG8Mutation(() => g8Post(`${base}/use`, { newsletter_id: newsletterId }), { onSuccess: (res) => { const n = num(asRec(res.data).id); if (n !== undefined) onUsed?.(n); } });
+  const status = useG8Query((signal) => g8Get(`${base}/generation-status`, undefined, { signal }), [id, str(t.generation_status)], { enabled: generating });
+  useEffect(() => {
+    if (!generating) return;
+    const state = str(asRec(status.data?.data).status);
+    if (status.data && state !== "" && !WORKING.test(state)) { onChanged(); return; }
+    // A failed poll is retried too (a blip must not stop the "Writing" state for good).
+    const timer = setTimeout(() => void status.refetch(), 3000);
+    return () => clearTimeout(timer);
+  }, [generating, status.data, status.error]); // eslint-disable-line react-hooks/exhaustive-deps
+  const dirty = name.trim() !== "" && name.trim() !== str(t.name);
+  return (
+    <li className="grid gap-2 rounded-md border p-3">
+      <div className="flex flex-wrap items-center gap-2">
+        <Input aria-label={`Template name ${str(t.name)}`} className="max-w-xs" value={name} onChange={(e) => setName(e.target.value)} />
+        <Button size="sm" variant="outline" loading={rename.loading} disabled={!dirty} onClick={() => void rename.mutate(undefined)}>Rename</Button>
+        {generating ? <StatusPill tone="info">Writing</StatusPill> : null}
+        <select aria-label={`Approval of ${str(t.name)}`} className={SELECT} value={approvalOf(t)} disabled={approve.loading} onChange={(e) => void approve.mutate(e.target.value)}>
+          {APPROVAL.map((a) => <option key={a} value={a}>{a[0].toUpperCase() + a.slice(1)}</option>)}
+        </select>
+        <div className="ml-auto flex gap-1">
+          <Button size="sm" loading={use.loading} disabled={generating} aria-label={`Use ${str(t.name)} for a new issue`} onClick={() => void use.mutate(undefined)}>Use for a new issue</Button>
+          <Button size="sm" variant="ghost" aria-label={`Delete ${str(t.name)}`} onClick={() => ask({
+            tier: "destructive", title: `Delete the template "${str(t.name)}"`, confirmLabel: "Delete template", affected: 1,
+            description: "The template is removed. Issues already made from it are not changed.", tolerateStatus: [404],
+            run: () => g8Delete(base), onDone: onChanged,
+          })}>Delete</Button>
+        </div>
+      </div>
+      {str(t.subject) ? <p className="text-muted-foreground text-xs">Subject: {str(t.subject)}</p> : null}
+      {[rename.error, approve.error, use.error].filter(Boolean).map((e, i) => <ApiError key={i} error={e} title="That did not work" />)}
+      {failure ? <ApiError error={failure} title="Could not delete the template" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </li>
+  );
+}
+
+export function NewsletterTemplates({ newsletterId, onUsed, className }: NewsletterTemplatesProps) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const list = useG8Query((signal) => g8Get("/newsletters/templates", undefined, { signal }), []);
+  const rows = rowsOf<Rec>(list.data?.data, "templates").filter((t) => num(t.id) !== undefined);
+  const [idea, setIdea] = useState("");
+  const [tone, setTone] = useState("");
+  const [length, setLength] = useState("");
+  const [note, setNote] = useState("");
+  const create = (): void => ask({
+    tier: "billable", title: "Write a template with AI", confirmLabel: "Write template",
+    description: "AI writes the copy for a new template from your idea. Uses credits; the API gives no price in advance and your balance is not checked here. It appears below while it is being written.",
+    run: async () => { await g8Post("/newsletters/templates/custom", { idea: idea.trim(), tone: tone.trim() || undefined, length: length.trim() || undefined }); setNote("The template is being written. It will finish by itself."); setIdea(""); },
+    onDone: () => void list.refetch(),
+  });
+  return (
+    <div className={className}>
+      <div className="grid gap-4">
+        <SectionCard title="Templates" description="Start a new draft issue from a saved layout.">
+          {list.error ? <ApiError error={list.error} title="Could not load templates" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? <Skeleton className="h-24 w-full" aria-busy="true" /> : rows.length === 0 ? (
+            <EmptyState compact title="No templates yet" description="Write one with AI below, or save an issue's layout in the web app." />
+          ) : (
+            <ul className="grid gap-2">{rows.map((t) => <TemplateRow key={String(t.id)} t={t} newsletterId={newsletterId} onChanged={() => void list.refetch()} onUsed={onUsed} />)}</ul>
+          )}
+        </SectionCard>
+        <SectionCard title="Write a template with AI" description="Describe the newsletter you want.">
+          <form className="grid gap-3 sm:grid-cols-2" onSubmit={(e) => { e.preventDefault(); if (idea.trim()) create(); }}>
+            <div className="sm:col-span-2"><Label htmlFor="nt-idea" className="mb-1">Idea</Label><Textarea id="nt-idea" rows={3} value={idea} onChange={(e) => setIdea(e.target.value)} placeholder="A monthly product digest with one big story and three quick links" /></div>
+            <div><Label htmlFor="nt-tone" className="mb-1">Tone (optional)</Label><Input id="nt-tone" value={tone} placeholder="Warm and direct" onChange={(e) => setTone(e.target.value)} /></div>
+            <div><Label htmlFor="nt-length" className="mb-1">Length (optional)</Label><Input id="nt-length" value={length} placeholder="Short" onChange={(e) => setLength(e.target.value)} /></div>
+            <div className="sm:col-span-2"><Button type="submit" disabled={!idea.trim()}>Write template with AI</Button></div>
+          </form>
+          {note ? <p role="status" className="mt-2 text-sm">{note}</p> : null}
+        </SectionCard>
+        {failure ? <ApiError error={failure} title="The template was not written" /> : null}
+      </div>
+      <ConfirmSpendDialog {...dialog} />
+    </div>
+  );
+}

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

@@ -17,6 +17,8 @@
 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 { useAllLists } from "@/g8/crm/hooks/use-all-lists";
+import { ListSelect } from "@/g8/crm/components/list-select";
 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";
@@ -44,7 +46,6 @@ type Action =
   | { 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>;
@@ -83,7 +84,7 @@ function SubscribersOf({ newsletterId, pageSize, onOpen, selectedId, refreshKey
     (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, refreshKey],
   );
-  const lists = useG8Query((signal) => g8Get<ListOption[]>("/lists", { limit: 200 }, { signal }).then((r) => r.data ?? []), []);
+  const lists = useAllLists([]);
   const preview = useG8Mutation(async () => (await g8Post(`${base}/verify/preview`, {})).data);
 
   const run = useG8Mutation(async (a: Action) => {
@@ -116,11 +117,8 @@ function SubscribersOf({ newsletterId, pageSize, onOpen, selectedId, refreshKey
         <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>
+        <ListSelect label="Import from list" emptyOption="Import from a list..." pageSize={200} value={listId} onChange={(l) => setListId(l ? String(l.id) : "")} />
+        <Button variant="outline" disabled={!listId} onClick={() => setAction({ kind: "import", listId: Number(listId), contacts: lists.items.find((l) => l.id === Number(listId))?.contact_count ?? undefined })}>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>

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

@@ -0,0 +1,65 @@
+"use client";
+
+/**
+ * SubscriberTimeline: what one subscriber did with one sent issue (delivered, opened, clicked...), in order.
+ * Pick the issue from the ones already sent.
+ *
+ * SDK operations:
+ *   1. getSubscriberTimeline  GET /newsletters/{id}/issues/{issue}/analytics/subscribers/{subscriber}/timeline  (read)
+ *
+ * The payload is open-shaped: events are read from `events` (or `timeline`, or a bare list) and shown with whatever
+ * of `type`, `event`, `occurred_at`, `url` is present.
+ */
+import { useEffect, useState } from "react";
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { issueTitle } from "../lib/newsletter-types";
+import type { Issue } from "../lib/newsletter-types";
+import { rowsOf, str } from "../lib/newsletter-extra";
+import type { Rec } from "../lib/newsletter-extra";
+
+export interface SubscriberTimelineProps {
+  newsletterId: string;
+  subscriberId: number;
+  /** The issues to choose from (only sent ones are offered). */
+  issues: Issue[];
+  className?: string;
+}
+
+const when = (v: unknown): string => {
+  const d = new Date(str(v));
+  return Number.isNaN(d.getTime()) ? "" : d.toLocaleString();
+};
+
+export function SubscriberTimeline({ newsletterId, subscriberId, issues, className }: SubscriberTimelineProps) {
+  const sent = issues.filter((i) => i.status === "sent" || i.sent_at);
+  const [issueId, setIssueId] = useState<string>(sent[0] ? String(sent[0].id) : "");
+  // On a deep link the issues arrive after the first render: pick the newest sent one once they do.
+  useEffect(() => { if (issueId === "" && sent[0]) setIssueId(String(sent[0].id)); }, [issueId, sent.length]); // eslint-disable-line react-hooks/exhaustive-deps
+  const res = useG8Query(
+    (signal) => g8Get(`/newsletters/${encodeURIComponent(newsletterId)}/issues/${issueId}/analytics/subscribers/${subscriberId}/timeline`, undefined, { signal }),
+    [newsletterId, issueId, subscriberId],
+    { enabled: issueId !== "" },
+  );
+  const events = rowsOf<Rec>(res.data?.data, "events", "timeline");
+  return (
+    <SectionCard className={className} title="Activity on an issue" description="What this person did with one sent issue."
+      actions={sent.length ? <select aria-label="Issue" className="border-input bg-background h-8 rounded-md border px-2 text-sm" value={issueId} onChange={(e) => setIssueId(e.target.value)}>{sent.map((i) => <option key={i.id} value={String(i.id)}>{issueTitle(i)}</option>)}</select> : undefined}>
+      {sent.length === 0 ? <EmptyState compact title="No sent issues yet" description="Activity appears after an issue is sent." />
+        : res.error ? <ApiError error={res.error} title="Could not load the activity" onRetry={() => void res.refetch()} />
+        : res.loading && !res.data ? <Skeleton className="h-16 w-full" aria-busy="true" />
+        : events.length === 0 ? <EmptyState compact title="No activity recorded" description="This person has not opened or clicked this issue." />
+        : (
+          <ol className="grid gap-2">
+            {events.map((e, i) => (
+              <li key={i} className="rounded-md border p-2 text-sm"><span className="font-medium">{str(e.type) || str(e.event) || "Event"}</span> <span className="text-muted-foreground text-xs">{when(e.occurred_at) || when(e.timestamp) || when(e.created_at)}</span>{str(e.url) ? <span className="text-muted-foreground block truncate text-xs">{str(e.url)}</span> : null}</li>
+            ))}
+          </ol>
+        )}
+    </SectionCard>
+  );
+}