@startsimpli/integrations 0.2.46 → 0.2.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.46",
+  "version": "0.2.48",
   "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps, plus foundry customer email (subpath ./comms).",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/comms/__tests__/announcement-composer.test.tsx

@@ -41,7 +41,8 @@ const server = setupServer(
     if (hit.path === '/programs/') return HttpResponse.json([comeback(), productUpdate()]);
     if (hit.path === '/drafts/' && hit.method === 'POST') return createReply();
     if (hit.path === '/drafts/') {
-      const results = drafts.filter((d) => d.approval === 'pending');
+      const wanted = url.searchParams.get('status') ?? 'pending';
+      const results = drafts.filter((d) => d.approval === wanted);
       return HttpResponse.json({ count: results.length, next: null, previous: null, results });
     }
     const m = hit.path.match(/^\/drafts\/([^/]+)\/$/);

package/src/comms/__tests__/api.test.ts

@@ -235,6 +235,23 @@ describe('product updates', () => {
     expect(r.html).toBe('<p>Hi Quinn</p>');
   });
 
+  it('per-send audience: GET/PUT drafts/{id}/audience/, POST .../preview/, GET audience/segments/', async () => {
+    const result = { audience: { base: 'all' }, is_default: true, preview: { count: 3, eligible: 3, excluded: {}, excluded_total: 0, sample: [], excluded_sample: [] } };
+    reply = () => HttpResponse.json(result);
+    await api().getDraftAudience('d-1');
+    expect([last().method, last().path]).toEqual(['GET', pathOf(`${P}/drafts/d-1/audience/`)]);
+    await api().saveDraftAudience('d-1', { base: 'inactive', days: 30 });
+    expect([last().method, last().path]).toEqual(['PUT', pathOf(`${P}/drafts/d-1/audience/`)]);
+    expect(last().body).toEqual({ audience: { base: 'inactive', days: 30 } });
+    await api().previewDraftAudience('d-1', { segment: { key: 'paying' } });
+    expect([last().method, last().path]).toEqual(['POST', pathOf(`${P}/drafts/d-1/audience/preview/`)]);
+    expect(last().body).toEqual({ audience: { segment: { key: 'paying' } } });
+    reply = () => HttpResponse.json({ available: false, segments: [] });
+    const segs = await api().listAudienceSegments();
+    expect(last().path).toBe(pathOf(`${P}/audience/segments/`));
+    expect(segs.available).toBe(false);
+  });
+
   // Shipped contract (updates lane): 202 with a placeholder draft still generating.
   it('POST programs/product_update/send-now/ with notes', async () => {
     reply = () => HttpResponse.json({ draft: draft({ generating: true, subject: '' }), reason: null }, { status: 202 });

package/src/comms/__tests__/audience-panel.test.tsx

@@ -0,0 +1,155 @@
+/**
+ * Per-send audience on a pending draft (bd startsim-xkcnk): an "Audience"
+ * disclosure under each draft that shows who will receive it, lets the admin
+ * narrow it (activity, signup dates, a segment the foundry's backend defines,
+ * explicit exclusions), previews the count with an "excluded and why"
+ * breakdown, and saves it on the draft. Nothing is requested until it is opened.
+ */
+import * as React from 'react';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+
+import { DraftReview } from '../components/DraftReview';
+import { createCommsApi, setApiBase } from '../api/index';
+import type { AudiencePreview, AudienceSpec, DraftAudience } from '../types/index';
+import { BASE, P, SLUG, draft } from './fixtures';
+
+interface Hit { method: string; path: string; body: any }
+let hits: Hit[] = [];
+let audience: DraftAudience;
+let segmentsReply: () => Response;
+let previewReply: (spec: AudienceSpec) => Response;
+
+const rel = (p: string) => p.replace(new URL(P).pathname, '');
+const preview = (over: Partial<AudiencePreview> = {}): AudiencePreview => ({
+  count: 42, eligible: 50, excluded: { opted_out: 5, suppressed: 3 }, excluded_total: 8,
+  sample: ['a@x.com', 'b@x.com'], excluded_sample: [{ email: 'gone@x.com', reason: 'opted_out' }], ...over,
+});
+
+const server = setupServer(
+  http.all(`${P}/*`, async ({ request }) => {
+    const url = new URL(request.url);
+    const text = request.method === 'GET' ? '' : await request.text();
+    const hit: Hit = { method: request.method, path: rel(url.pathname), body: text ? JSON.parse(text) : undefined };
+    hits.push(hit);
+    if (hit.path === '/drafts/') {
+      return HttpResponse.json({ count: 1, next: null, previous: null, results: [draft()] });
+    }
+    if (hit.path === '/audience/segments/') return segmentsReply();
+    if (hit.path === '/drafts/d-1/audience/' && hit.method === 'GET') return HttpResponse.json(audience);
+    if (hit.path === '/drafts/d-1/audience/' && hit.method === 'PUT') {
+      return HttpResponse.json({ audience: hit.body.audience, is_default: false, preview: preview() });
+    }
+    if (hit.path === '/drafts/d-1/audience/preview/') return previewReply(hit.body.audience);
+    return HttpResponse.json({});
+  }),
+);
+
+beforeAll(() => {
+  server.listen({ onUnhandledRequest: 'error' });
+  setApiBase(`${BASE}/api/v1`);
+});
+afterAll(() => server.close());
+beforeEach(() => {
+  hits = [];
+  audience = { audience: { base: 'all' }, is_default: true, preview: preview() };
+  segmentsReply = () => HttpResponse.json({
+    available: true,
+    segments: [{ key: 'never_designed', label: 'Signed up, never made a design', description: '' },
+      { key: 'paying', label: 'Paying users', description: '' }],
+  });
+  previewReply = (spec) => HttpResponse.json({ audience: spec, is_default: false, preview: preview({ count: 7, excluded: {}, excluded_total: 0, excluded_sample: [] }) });
+});
+afterEach(() => server.resetHandlers());
+
+async function openAudience() {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  const user = userEvent.setup();
+  render(
+    <QueryClientProvider client={qc}>
+      <DraftReview api={createCommsApi(SLUG)} pollIntervalMs={20} />
+    </QueryClientProvider>,
+  );
+  const trigger = await screen.findByRole('button', { name: 'Audience' });
+  return { user, trigger };
+}
+
+const previews = () => hits.filter((h) => h.path === '/drafts/d-1/audience/preview/');
+
+describe('Audience panel', () => {
+  it('asks for nothing until it is opened, then shows who receives it and why others are excluded', async () => {
+    const { user, trigger } = await openAudience();
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(hits.some((h) => h.path.includes('audience'))).toBe(false);
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    expect(await within(region).findByText(/42 people will receive this/)).toBeInTheDocument();
+    expect(within(region).getByText(/8 excluded/)).toBeInTheDocument();
+    expect(within(region).getByText(/5 unsubscribed/)).toBeInTheDocument();
+    expect(within(region).getByText(/3 suppressed/)).toBeInTheDocument();
+    expect(within(region).getByText('a@x.com')).toBeInTheDocument();
+    expect(within(region).getByText(/Using the program default/)).toBeInTheDocument();
+  });
+
+  it('previews a narrower activity audience without saving', async () => {
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    await user.selectOptions(await within(region).findByLabelText('Who'), 'inactive');
+    await waitFor(() => expect(previews().at(-1)?.body.audience).toMatchObject({ base: 'inactive', days: 14 }));
+    expect(await within(region).findByText(/7 people will receive this/)).toBeInTheDocument();
+    expect(hits.some((h) => h.method === 'PUT')).toBe(false);
+  });
+
+  it('lists the foundry\'s segments and previews the chosen one', async () => {
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    await user.selectOptions(await within(region).findByLabelText('Only people in segment'), 'never_designed');
+    await waitFor(() => expect(previews().at(-1)?.body.audience.segment).toEqual({ key: 'never_designed' }));
+  });
+
+  it('says segments are unavailable when the foundry has no backend', async () => {
+    segmentsReply = () => HttpResponse.json({ available: false, segments: [] });
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    expect(await within(region).findByText(/Segments need the foundry's own backend/)).toBeInTheDocument();
+    expect(within(region).queryByLabelText('Only people in segment')).toBeNull();
+  });
+
+  it('takes signup dates and an exclusion list, one address per line', async () => {
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    await user.type(await within(region).findByLabelText('Signed up after'), '2026-10-01');
+    await user.type(within(region).getByLabelText('Never send to'), 'A@x.com{enter}b@x.com');
+    await waitFor(() => expect(previews().at(-1)?.body.audience).toMatchObject({
+      joined_after: '2026-10-01', exclude: { emails: ['a@x.com', 'b@x.com'] },
+    }));
+  });
+
+  it('saves the audience on the draft', async () => {
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    await user.selectOptions(await within(region).findByLabelText('Who'), 'active');
+    await user.click(within(region).getByRole('button', { name: 'Save audience' }));
+    await waitFor(() => expect(hits.find((h) => h.method === 'PUT')?.body).toEqual({
+      audience: { base: 'active', days: 14 },
+    }));
+  });
+
+  it('shows the server\'s reason when the audience cannot be resolved', async () => {
+    previewReply = () => HttpResponse.json({ detail: 'the foundry\'s backend refused the segment request (500)' }, { status: 400 });
+    const { user, trigger } = await openAudience();
+    await user.click(trigger);
+    const region = await screen.findByRole('region', { name: 'Audience' });
+    await user.selectOptions(await within(region).findByLabelText('Who'), 'inactive');
+    expect(await within(region).findByRole('alert')).toHaveTextContent(/refused the segment request/);
+  });
+});

package/src/comms/__tests__/scheduled-send.test.tsx

@@ -0,0 +1,304 @@
+/**
+ * Scheduled and cancellable sends (bd startsim-yzivy): schedule a pending draft,
+ * see it listed with its send time, reschedule / send now / cancel it, and see
+ * scheduled and cancelled drafts in the send log. A mocked Django (msw) behind
+ * the REAL createCommsApi client, so each test is click -> request -> render.
+ */
+import * as React from 'react';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+
+import { DraftReview } from '../components/DraftReview';
+import { SendLog } from '../components/SendLog';
+import { createCommsApi, setApiBase } from '../api/index';
+import type { Draft, ScheduledSend } from '../types/index';
+import { BASE, P, SLUG, draft } from './fixtures';
+
+interface Hit { method: string; path: string; body: any }
+let hits: Hit[] = [];
+let drafts: Draft[] = [];
+let scheduledReport: ScheduledSend[] = [];
+let conflict = false;
+let liveCount = 2;
+
+const rel = (p: string) => p.replace(new URL(P).pathname, '');
+
+const server = setupServer(
+  http.all(`${P}/*`, async ({ request }) => {
+    const url = new URL(request.url);
+    const text = request.method === 'GET' ? '' : await request.text();
+    const hit: Hit = { method: request.method, path: rel(url.pathname), body: text ? JSON.parse(text) : undefined };
+    hits.push(hit);
+    const { method, path, body } = hit;
+    let m: RegExpMatchArray | null;
+    if (path === '/drafts/' && method === 'GET') {
+      const wanted = url.searchParams.get('status');
+      const results = drafts.filter((d) => !wanted || d.approval === wanted);
+      return HttpResponse.json({ count: results.length, next: null, previous: null, results });
+    }
+    if ((m = path.match(/^\/drafts\/([\w-]+)\/(approve|reschedule|cancel)\/$/)) && method === 'POST') {
+      const d = drafts.find((x) => x.id === m![1])!;
+      if (conflict) return HttpResponse.json({ detail: 'the send has already started and cannot be cancelled' }, { status: 409 });
+      if (m[2] === 'approve') {
+        if (body?.send_at && body.send_at < '2026-01-01') Object.assign(d, { approval: 'approved', state: 'sending', sent_immediately: true, requested_send_at: '2020-01-01T00:00:00+00:00' });
+        else if (body?.send_at) Object.assign(d, { approval: 'scheduled', send_at: '2026-11-03T15:00:00+00:00', send_timezone: body.timezone ?? null });
+        else d.approval = 'approved';
+      } else if (m[2] === 'reschedule') {
+        Object.assign(d, { send_at: '2026-11-05T15:00:00+00:00', send_timezone: body.timezone ?? null });
+      } else {
+        Object.assign(d, { approval: 'pending', send_at: null, send_timezone: null, cancelled_at: '2026-11-01T09:00:00+00:00' });
+      }
+      return HttpResponse.json(d);
+    }
+    if ((m = path.match(/^\/drafts\/([\w-]+)\/retry\/$/)) && method === 'POST') {
+      const d = drafts.find((x) => x.id === m![1])!;
+      Object.assign(d, { approval: 'approved', state: 'sending', failure: null, next_actions: ['wait'] });
+      return HttpResponse.json(d);
+    }
+    if ((m = path.match(/^\/drafts\/([\w-]+)\/audience\/$/)) && method === 'GET') {
+      return HttpResponse.json({ audience: { base: 'all' }, is_default: true, preview: { count: liveCount, eligible: liveCount, excluded: {}, excluded_total: 0, sample: [], excluded_sample: [] } });
+    }
+    if (path === '/sends/' && method === 'GET') {
+      return HttpResponse.json({ count: 0, next: null, previous: null, results: [], scheduled: scheduledReport });
+    }
+    return HttpResponse.json({ detail: `unhandled ${method} ${path}` }, { status: 599 });
+  }),
+);
+
+beforeAll(() => {
+  server.listen({ onUnhandledRequest: 'error' });
+  setApiBase(`${BASE}/api/v1`);
+});
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+beforeEach(() => {
+  hits = [];
+  drafts = [draft()];
+  scheduledReport = [];
+  conflict = false;
+  liveCount = 2;
+});
+
+function renderWith(node: (api: ReturnType<typeof createCommsApi>) => React.ReactElement) {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } });
+  return render(<QueryClientProvider client={qc}>{node(createCommsApi(SLUG))}</QueryClientProvider>);
+}
+
+const writes = () => hits.filter((h) => h.method !== 'GET');
+
+async function schedule(when = '2026-11-03T10:00', zone = 'Asia/Tokyo') {
+  await userEvent.click(await screen.findByRole('button', { name: /schedule/i }));
+  fireEvent.change(screen.getByLabelText('Send at'), { target: { value: when } });
+  await userEvent.selectOptions(screen.getByLabelText('Time zone'), zone);
+  await userEvent.click(screen.getByRole('button', { name: /approve and schedule/i }));
+}
+
+describe('scheduling a pending draft', () => {
+  it('Approve and send still sends now, with no schedule on the wire', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await userEvent.click(await screen.findByRole('button', { name: /approve and send/i }));
+    await waitFor(() => expect(writes()[0]).toMatchObject({ method: 'POST', path: '/drafts/d-1/approve/' }));
+    expect(writes()[0].body).toBeUndefined();
+  });
+
+  it('posts the local time with its zone, then lists the draft as scheduled', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await schedule();
+    await waitFor(() =>
+      expect(writes()[0]).toMatchObject({
+        method: 'POST', path: '/drafts/d-1/approve/', body: { send_at: '2026-11-03T10:00', timezone: 'Asia/Tokyo' },
+      }),
+    );
+    const heading = await screen.findByRole('heading', { name: /scheduled to send/i });
+    const list = heading.parentElement as HTMLElement;
+    expect(await within(list).findByText('New: stitch counter')).toBeInTheDocument();
+    expect(within(list).getByText(/^Sends /)).toBeInTheDocument();
+    // it left the waiting-for-approval list
+    expect(screen.queryByRole('button', { name: /approve and send/i })).toBeNull();
+  });
+
+  it('makes no write until the form is submitted', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await userEvent.click(await screen.findByRole('button', { name: /schedule/i }));
+    expect(screen.getByRole('button', { name: /approve and schedule/i })).toBeDisabled(); // no time yet
+    expect(writes()).toEqual([]);
+  });
+
+  it('shows the server reason when scheduling is refused', async () => {
+    conflict = true;
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await schedule();
+    expect((await screen.findByRole('alert')).textContent).toMatch(/already started/i);
+  });
+});
+
+describe('a scheduled draft', () => {
+  beforeEach(() => {
+    drafts = [draft({ approval: 'scheduled', send_at: '2026-11-03T15:00:00+00:00', send_timezone: 'America/New_York' })];
+  });
+
+  it('is listed with its send time, in the zone it was set in', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    expect(await screen.findByRole('heading', { name: /scheduled to send/i })).toBeInTheDocument();
+    expect(await screen.findByText(/^Sends .*(10:00|11:00)/)).toBeInTheDocument();
+    expect(screen.getByText('No updates are waiting for approval.')).toBeInTheDocument();
+  });
+
+  it('cancels the schedule and the draft is waiting for approval again', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await userEvent.click(await screen.findByRole('button', { name: /cancel schedule/i }));
+    await waitFor(() => expect(writes()[0]).toMatchObject({ method: 'POST', path: '/drafts/d-1/cancel/' }));
+    expect(await screen.findByRole('button', { name: /approve and send/i })).toBeInTheDocument();
+    expect(await screen.findByText(/schedule cancelled/i)).toBeInTheDocument();
+  });
+
+  it('reschedules with a new time and zone', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await userEvent.click(await screen.findByRole('button', { name: /^reschedule$/i }));
+    fireEvent.change(screen.getByLabelText('Send at'), { target: { value: '2026-11-05T10:00' } });
+    await userEvent.selectOptions(screen.getByLabelText('Time zone'), 'UTC');
+    await userEvent.click(screen.getByRole('button', { name: /move send/i }));
+    await waitFor(() =>
+      expect(writes()[0]).toMatchObject({
+        method: 'POST', path: '/drafts/d-1/reschedule/', body: { send_at: '2026-11-05T10:00', timezone: 'UTC' },
+      }),
+    );
+  });
+
+  it('sends now', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await userEvent.click(await screen.findByRole('button', { name: /^send now$/i }));
+    await waitFor(() => expect(writes()[0]).toMatchObject({ method: 'POST', path: '/drafts/d-1/approve/' }));
+    expect(writes()[0].body).toBeUndefined();
+  });
+
+  it('shows the server reason when cancel is too late', async () => {
+    conflict = true;
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await userEvent.click(await screen.findByRole('button', { name: /cancel schedule/i }));
+    expect((await screen.findByRole('alert')).textContent).toMatch(/already started/i);
+  });
+});
+
+describe('send log', () => {
+  it('lists scheduled and cancelled drafts above the sent rows', async () => {
+    scheduledReport = [
+      { id: 's-1', program_key: 'product_update', subject: 'Tuesday news', status: 'scheduled',
+        send_at: '2026-11-03T15:00:00+00:00', send_timezone: 'UTC', cancelled_at: null },
+      { id: 's-2', program_key: 'announcement', subject: 'Dropped idea', status: 'cancelled',
+        send_at: null, send_timezone: null, cancelled_at: '2026-11-01T09:00:00+00:00' },
+    ];
+    renderWith((api) => <SendLog api={api} />);
+    const heading = await screen.findByRole('heading', { name: /scheduled and cancelled/i });
+    const table = within(heading.parentElement as HTMLElement);
+    expect(table.getByText('Tuesday news')).toBeInTheDocument();
+    expect(table.getByText('scheduled')).toBeInTheDocument();
+    expect(table.getByText('Dropped idea')).toBeInTheDocument();
+    expect(table.getByText('cancelled')).toBeInTheDocument();
+    expect(table.getByText(/^Cancelled /)).toBeInTheDocument();
+  });
+
+  it('shows no scheduled section when there is nothing scheduled', async () => {
+    renderWith((api) => <SendLog api={api} />);
+    expect(await screen.findByText(/no emails sent yet/i)).toBeInTheDocument();
+    expect(screen.queryByRole('heading', { name: /scheduled and cancelled/i })).toBeNull();
+  });
+});
+
+// ---- the closed loop: every state is named, with a reason and a next action ----
+
+describe('states the admin has to act on', () => {
+  it('says when a past time was sent immediately', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await schedule('2020-01-01T10:00', 'UTC');
+    expect(await screen.findByText(/sent immediately/i)).toBeInTheDocument();
+    expect(screen.getByText(/had already passed/i)).toBeInTheDocument();
+  });
+
+  it('explains the picker: a time that has passed sends now', async () => {
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    await userEvent.click(await screen.findByRole('button', { name: /schedule/i }));
+    expect(screen.getByText(/already passed sends immediately/i)).toBeInTheDocument();
+  });
+
+  it('shows an expired send with its reason and original time, and can approve again', async () => {
+    drafts = [draft({
+      approval: 'expired', state: 'expired', next_actions: ['approve', 'schedule', 'edit', 'discard'],
+      notice: { code: 'expired', reason: 'comms were paused at the scheduled time', send_at: '2026-11-03T15:00:00+00:00' },
+    })];
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    const heading = await screen.findByRole('heading', { name: /needs attention/i });
+    const area = within(heading.parentElement as HTMLElement);
+    expect(await area.findByText(/comms were paused at the scheduled time/i)).toBeInTheDocument();
+    expect(area.getByText(/was scheduled for/i)).toBeInTheDocument();
+    await userEvent.click(area.getByRole('button', { name: /approve and send/i }));
+    await waitFor(() => expect(writes()[0]).toMatchObject({ method: 'POST', path: '/drafts/d-1/approve/' }));
+  });
+
+  it('shows a failed send with the error and a Retry that posts retry', async () => {
+    drafts = [draft({
+      approval: 'failed', state: 'failed', next_actions: ['retry', 'approve', 'discard'],
+      failure: { stage: 'dispatch', code: 'audience_unavailable', reason: 'could not reach the foundry backend (after 3 attempts)', at: '2026-11-03T15:01:00+00:00' },
+    })];
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    expect(await screen.findByText(/could not reach the foundry backend/i)).toBeInTheDocument();
+    await userEvent.click(screen.getByRole('button', { name: /^retry$/i }));
+    await waitFor(() => expect(writes()[0]).toMatchObject({ method: 'POST', path: '/drafts/d-1/retry/' }));
+  });
+
+  it('a send that failed after it started offers only Retry', async () => {
+    drafts = [draft({
+      approval: 'failed', state: 'failed', next_actions: ['retry'],
+      failure: { stage: 'send', code: 'recipients_not_sent', reason: '2 recipients were still unsent after 3 retries', at: '2026-11-03T15:01:00+00:00' },
+    })];
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    expect(await screen.findByText(/2 recipients were still unsent/i)).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /^retry$/i })).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: /approve and send/i })).toBeNull();
+    expect(screen.queryByRole('button', { name: /^discard$/i })).toBeNull();
+  });
+
+  it('shows why an auto-approved draft is still waiting', async () => {
+    drafts = [draft({ notice: { code: 'no_recipients', reason: 'this audience has no recipients (2 opted out)' } })];
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    expect(await screen.findByText(/no recipients \(2 opted out\)/i)).toBeInTheDocument();
+  });
+
+  it('shows a scheduled send that is being retried', async () => {
+    drafts = [draft({
+      approval: 'scheduled', send_at: '2026-11-03T15:00:00+00:00', send_timezone: 'UTC',
+      dispatch_attempts: 1, dispatch_error: 'could not reach the foundry backend',
+    })];
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    expect(await screen.findByText(/trying again.*could not reach the foundry backend/i)).toBeInTheDocument();
+  });
+
+  it('shows both recipient counts when the audience changed since scheduling', async () => {
+    liveCount = 5;
+    drafts = [draft({ approval: 'scheduled', send_at: '2026-11-03T15:00:00+00:00', send_timezone: 'UTC', recipient_count: 2 })];
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    expect(await screen.findByText(/2 recipients when scheduled, 5 now/i)).toBeInTheDocument();
+  });
+
+  it('shows one count when nothing changed', async () => {
+    drafts = [draft({ approval: 'scheduled', send_at: '2026-11-03T15:00:00+00:00', send_timezone: 'UTC', recipient_count: 2 })];
+    renderWith((api) => <DraftReview api={api} pollIntervalMs={10} />);
+    expect(await screen.findByText(/^2 recipients$/i)).toBeInTheDocument();
+  });
+
+  it('the send log gives the reason for expired and failed drafts', async () => {
+    scheduledReport = [
+      { id: 'e-1', program_key: 'announcement', subject: 'Paused one', status: 'expired', reason: 'comms were paused at the scheduled time',
+        send_at: '2026-11-03T15:00:00+00:00', send_timezone: null, cancelled_at: null },
+      { id: 'f-1', program_key: 'announcement', subject: 'Broken one', status: 'failed', reason: 'this audience has no recipients',
+        send_at: null, send_timezone: null, cancelled_at: null },
+    ];
+    renderWith((api) => <SendLog api={api} />);
+    expect(await screen.findByText('comms were paused at the scheduled time')).toBeInTheDocument();
+    expect(screen.getByText('this audience has no recipients')).toBeInTheDocument();
+  });
+});

package/src/comms/api/_fetch.ts

@@ -28,7 +28,7 @@ export function setAuthTokenProvider(
 }
 
 export interface RequestOptions {
-  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
   body?: unknown;
   query?: Record<string, string | number | boolean | undefined | null>;
 }

package/src/comms/api/comms.ts

@@ -21,7 +21,10 @@ import type {
   CommsAsset,
   CommsSettings,
   CommsSettingsPatch,
+  AudienceSegments,
+  AudienceSpec,
   Draft,
+  DraftAudience,
   DraftCreate,
   DraftPatch,
   DraftsQuery,
@@ -31,7 +34,8 @@ import type {
   ProgramUpdateResult,
   RenderedEmail,
   SendNowResult,
-  SendRow,
+  SendsPage,
+  ScheduleInput,
   SendsQuery,
   StepGeneration,
   TestSendInput,
@@ -73,13 +77,25 @@ export interface CommsApi {
   uploadAsset(file: File, alt: string): Promise<CommsAsset>;
   deleteAsset(id: string): Promise<void>;
   updateDraft(id: string, patch: DraftPatch): Promise<Draft>;
-  approveDraft(id: string): Promise<Draft>;
+  /** Without `schedule` the send is queued now; with it the draft is scheduled (status 'scheduled'). */
+  approveDraft(id: string, schedule?: ScheduleInput): Promise<Draft>;
+  /** Move a still-scheduled draft; 409 once the send has started. */
+  rescheduleDraft(id: string, schedule: ScheduleInput): Promise<Draft>;
+  /** Scheduled -> pending again; 409 once the send has started. */
+  cancelDraft(id: string): Promise<Draft>;
+  /** Resume a failed draft (re-run the dispatch, or re-queue the unsent recipients). */
+  retryDraft(id: string): Promise<Draft>;
   discardDraft(id: string): Promise<Draft>;
   previewDraft(id: string): Promise<RenderedEmail>;
+  // per-send audience: the draft's own spec (or the program default) + who it reaches
+  getDraftAudience(id: string): Promise<DraftAudience>;
+  saveDraftAudience(id: string, audience: AudienceSpec): Promise<DraftAudience>;
+  previewDraftAudience(id: string, audience: AudienceSpec): Promise<DraftAudience>;
+  listAudienceSegments(): Promise<AudienceSegments>;
   sendUpdateNow(input?: { notes?: string }): Promise<SendNowResult>;
 
   // results
-  listSends(query?: SendsQuery): Promise<Paginated<SendRow>>;
+  listSends(query?: SendsQuery): Promise<SendsPage>;
   getMetrics(query?: MetricsQuery): Promise<CommsMetrics>;
 }
 
@@ -126,9 +142,19 @@ export function createCommsApi(slug: string): CommsApi {
     },
     deleteAsset: (id) => request(`${P}/assets/${seg(id)}/`, { method: 'DELETE' }),
     updateDraft: (id, patch) => request(draftPath(id), { method: 'PATCH', body: patch }),
-    approveDraft: (id) => request(draftPath(id, 'approve'), { method: 'POST' }),
+    approveDraft: (id, schedule) =>
+      request(draftPath(id, 'approve'), schedule ? { method: 'POST', body: schedule } : { method: 'POST' }),
+    rescheduleDraft: (id, schedule) => request(draftPath(id, 'reschedule'), { method: 'POST', body: schedule }),
+    cancelDraft: (id) => request(draftPath(id, 'cancel'), { method: 'POST' }),
+    retryDraft: (id) => request(draftPath(id, 'retry'), { method: 'POST' }),
     discardDraft: (id) => request(draftPath(id, 'discard'), { method: 'POST' }),
     previewDraft: (id) => request(draftPath(id, 'preview')),
+    getDraftAudience: (id) => request(draftPath(id, 'audience')),
+    saveDraftAudience: (id, audience) =>
+      request(draftPath(id, 'audience'), { method: 'PUT', body: { audience } }),
+    previewDraftAudience: (id, audience) =>
+      request(draftPath(id, 'audience/preview'), { method: 'POST', body: { audience } }),
+    listAudienceSegments: () => request(`${P}/audience/segments/`),
     sendUpdateNow: (input = {}) =>
       request(`${P}/programs/product_update/send-now/`, { method: 'POST', body: input }),