@startsimpli/integrations 0.2.46 → 0.2.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.46",
+  "version": "0.2.47",
   "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__/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/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,
@@ -76,6 +79,11 @@ export interface CommsApi {
   approveDraft(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
@@ -129,6 +137,12 @@ export function createCommsApi(slug: string): CommsApi {
     approveDraft: (id) => request(draftPath(id, 'approve'), { 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 }),
 

package/src/comms/components/AudiencePanel.tsx

@@ -0,0 +1,221 @@
+/**
+ * Per-send audience for one pending draft (bd startsim-xkcnk): who receives it,
+ * narrowed by activity, signup dates and a segment the foundry's own backend
+ * defines, minus explicit exclusions. Shows the recipient count, a sample and an
+ * "excluded and why" breakdown before anyone approves; "Save audience" stores it
+ * on the draft. A segment can only narrow the foundry's customers.
+ */
+import { useEffect, useMemo, useRef, useState, type ReactElement } from 'react';
+import { Button, Input, Label, Textarea } from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import { useAudienceSegments, useDraftAudience, usePreviewAudience, useSaveAudience } from '../hooks/index';
+import type { AudiencePreview, AudienceSegment, AudienceSpec, ExcludedReason } from '../types/index';
+import { ErrorNotice, NativeSelect, Note, useFieldId } from './_shared';
+
+const DEFAULT_DAYS = 14;
+const DEBOUNCE_MS = 250;
+
+const REASON_LABEL: Record<ExcludedReason, string> = {
+  no_email: 'with no email address',
+  excluded: 'excluded by you',
+  excluded_segment: 'in the excluded segment',
+  undeliverable: 'with an undeliverable address',
+  unverified: 'with an unverified email',
+  opted_out: 'unsubscribed',
+  suppressed: 'suppressed (bounce or complaint)',
+};
+
+interface Form {
+  base: 'all' | 'active' | 'inactive';
+  days: string;
+  after: string;
+  before: string;
+  segment: string;
+  excludeSegment: string;
+  exclude: string;
+}
+
+function toForm(spec: AudienceSpec): Form {
+  return {
+    base: spec.base ?? 'all',
+    days: String(spec.days ?? DEFAULT_DAYS),
+    after: (spec.joined_after ?? '').slice(0, 10),
+    before: (spec.joined_before ?? '').slice(0, 10),
+    segment: spec.segment?.key ?? '',
+    excludeSegment: spec.exclude?.segment?.key ?? '',
+    exclude: (spec.exclude?.emails ?? []).join('\n'),
+  };
+}
+
+export function parseEmails(text: string): string[] {
+  return [...new Set(text.split(/[\s,;]+/).map((e) => e.trim().toLowerCase()).filter(Boolean))];
+}
+
+export function toSpec(f: Form): AudienceSpec {
+  const spec: AudienceSpec = { base: f.base };
+  if (f.base !== 'all') spec.days = Math.max(1, Math.floor(Number(f.days)) || DEFAULT_DAYS);
+  if (f.after) spec.joined_after = f.after;
+  if (f.before) spec.joined_before = f.before;
+  if (f.segment) spec.segment = { key: f.segment };
+  const emails = parseEmails(f.exclude);
+  if (emails.length || f.excludeSegment) {
+    spec.exclude = {};
+    if (emails.length) spec.exclude.emails = emails;
+    if (f.excludeSegment) spec.exclude.segment = { key: f.excludeSegment };
+  }
+  return spec;
+}
+
+function Summary({ preview }: { preview: AudiencePreview }) {
+  const reasons = Object.entries(preview.excluded).filter(([, n]) => n) as [ExcludedReason, number][];
+  return (
+    <div className="space-y-2 rounded-md bg-muted/40 p-3 text-sm" aria-live="polite">
+      <p className="font-medium">
+        {preview.count} {preview.count === 1 ? 'person' : 'people'} will receive this
+      </p>
+      {preview.sample.length ? (
+        <ul className="flex flex-wrap gap-x-3 text-xs text-muted-foreground">
+          {preview.sample.map((e) => (
+            <li key={e}>{e}</li>
+          ))}
+        </ul>
+      ) : null}
+      {preview.excluded_total ? (
+        <div>
+          <p>{preview.excluded_total} excluded</p>
+          <ul className="list-disc pl-5 text-muted-foreground">
+            {reasons.map(([reason, n]) => (
+              <li key={reason}>
+                {n} {REASON_LABEL[reason] ?? reason}
+              </li>
+            ))}
+          </ul>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function SegmentSelect({ id, label, value, onChange, segments, none }: {
+  id: string; label: string; value: string; onChange: (v: string) => void; segments: AudienceSegment[]; none: string;
+}) {
+  return (
+    <div className="space-y-1">
+      <Label htmlFor={id}>{label}</Label>
+      <NativeSelect id={id} value={value} onChange={(e) => onChange(e.target.value)}>
+        <option value="">{none}</option>
+        {segments.map((s) => (
+          <option key={s.key} value={s.key}>{s.label}</option>
+        ))}
+      </NativeSelect>
+    </div>
+  );
+}
+
+function AudienceForm({ api, draftId }: { api: CommsApi; draftId: string }) {
+  const prefix = useFieldId(`comms-audience-${draftId}`);
+  const loaded = useDraftAudience(api, draftId, true);
+  const segments = useAudienceSegments(api, true);
+  const previewMut = usePreviewAudience(api, draftId);
+  const save = useSaveAudience(api, draftId);
+  const [form, setForm] = useState<Form | null>(null);
+  const [shown, setShown] = useState<AudiencePreview | null>(null);
+  const initial = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (loaded.data && form === null) {
+      setForm(toForm(loaded.data.audience));
+      setShown(loaded.data.preview);
+      initial.current = JSON.stringify(toSpec(toForm(loaded.data.audience)));
+    }
+  }, [loaded.data, form]);
+
+  const spec = useMemo(() => (form ? toSpec(form) : null), [form]);
+  const specKey = spec ? JSON.stringify(spec) : null;
+  const { mutate } = previewMut;
+  useEffect(() => {
+    if (!spec || specKey === initial.current) return;
+    const t = setTimeout(() => {
+      mutate(spec, {
+        onSuccess: (d) => { setShown(d.preview); },
+        onError: () => setShown(null),
+      });
+    }, DEBOUNCE_MS);
+    return () => clearTimeout(t);
+    // spec is derived from specKey
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [specKey, mutate]);
+
+  if (loaded.error) return <ErrorNotice error={loaded.error} />;
+  if (!form || !spec) return <Note>Loading the audience…</Note>;
+  const set = (patch: Partial<Form>) => setForm({ ...form, ...patch });
+  const dirty = specKey !== initial.current;
+  const available = segments.data?.available ?? false;
+  const list = segments.data?.segments ?? [];
+
+  return (
+    <div className="space-y-3">
+      {loaded.data?.is_default && !dirty ? <Note>Using the program default. Change anything below to set this send's own audience.</Note> : null}
+      <div className="flex flex-wrap items-end gap-3">
+        <div className="space-y-1">
+          <Label htmlFor={`${prefix}-who`}>Who</Label>
+          <NativeSelect id={`${prefix}-who`} value={form.base} onChange={(e) => set({ base: e.target.value as Form['base'] })}>
+            <option value="all">Everyone</option>
+            <option value="active">Seen recently</option>
+            <option value="inactive">Not seen for a while</option>
+          </NativeSelect>
+        </div>
+        {form.base !== 'all' ? (
+          <div className="space-y-1">
+            <Label htmlFor={`${prefix}-days`}>Within days</Label>
+            <Input id={`${prefix}-days`} type="number" min={1} className="w-24" value={form.days} onChange={(e) => set({ days: e.target.value })} />
+          </div>
+        ) : null}
+        <div className="space-y-1">
+          <Label htmlFor={`${prefix}-after`}>Signed up after</Label>
+          <Input id={`${prefix}-after`} type="date" value={form.after} onChange={(e) => set({ after: e.target.value })} />
+        </div>
+        <div className="space-y-1">
+          <Label htmlFor={`${prefix}-before`}>Signed up before</Label>
+          <Input id={`${prefix}-before`} type="date" value={form.before} onChange={(e) => set({ before: e.target.value })} />
+        </div>
+      </div>
+      {available ? (
+        <div className="flex flex-wrap gap-3">
+          <SegmentSelect id={`${prefix}-seg`} label="Only people in segment" value={form.segment}
+            onChange={(v) => set({ segment: v })} segments={list} none="Everyone (no segment)" />
+          <SegmentSelect id={`${prefix}-xseg`} label="Never send to segment" value={form.excludeSegment}
+            onChange={(v) => set({ excludeSegment: v })} segments={list} none="None" />
+        </div>
+      ) : segments.data ? (
+        <Note>Segments need the foundry's own backend, which is not deployed yet. Activity and signup date still work.</Note>
+      ) : null}
+      <ErrorNotice error={segments.error} />
+      <div className="space-y-1">
+        <Label htmlFor={`${prefix}-exclude`}>Never send to</Label>
+        <Textarea id={`${prefix}-exclude`} rows={3} placeholder="One email address per line"
+          value={form.exclude} onChange={(e) => set({ exclude: e.target.value })} />
+      </div>
+      {shown ? <Summary preview={shown} /> : null}
+      {previewMut.isPending ? <Note>Counting…</Note> : null}
+      <ErrorNotice error={previewMut.error ?? save.error} />
+      <div className="flex items-center gap-2">
+        <Button type="button" size="sm" disabled={save.isPending || !dirty}
+          onClick={() => save.mutate(spec, { onSuccess: () => { initial.current = specKey; setForm({ ...form }); } })}>
+          Save audience
+        </Button>
+        {save.isSuccess && !dirty ? <span className="text-sm text-muted-foreground">Saved.</span> : null}
+      </div>
+    </div>
+  );
+}
+
+/** The open panel; the draft row owns the "Audience" button that shows it. */
+export function AudiencePanel({ api, draftId, id }: { api: CommsApi; draftId: string; id?: string }): ReactElement {
+  return (
+    <div id={id} role="region" aria-label="Audience" className="mt-2 space-y-3 rounded-md border p-3">
+      <AudienceForm api={api} draftId={draftId} />
+    </div>
+  );
+}

package/src/comms/components/DraftReview.tsx

@@ -20,6 +20,7 @@ import {
   useUpdateDraft,
 } from '../hooks/index';
 import type { Draft, DraftPatch } from '../types/index';
+import { AudiencePanel } from './AudiencePanel';
 import { EmailPreview } from './EmailPreview';
 import { ErrorNotice, Note, formatDate, humanize, useFieldId } from './_shared';
 
@@ -81,6 +82,7 @@ function DraftEditor({ api, draft, onDone }: { api: CommsApi; draft: Draft; onDo
 function DraftItem({ api, draft }: { api: CommsApi; draft: Draft }) {
   const [editing, setEditing] = useState(false);
   const [previewing, setPreviewing] = useState(false);
+  const [auditing, setAuditing] = useState(false);
   const ready = !draft.generating && !draft.error;
   const preview = useDraftPreview(api, draft.id, previewing && ready);
   const sendTest = useSendTest(api);
@@ -99,6 +101,15 @@ function DraftItem({ api, draft }: { api: CommsApi; draft: Draft }) {
             <>
               <Button type="button" size="sm" variant="outline" onClick={() => setPreviewing((v) => !v)}>Preview</Button>
               <Button type="button" size="sm" variant="outline" onClick={() => setEditing((v) => !v)}>Edit</Button>
+              <Button
+                type="button"
+                size="sm"
+                variant="outline"
+                aria-expanded={auditing}
+                onClick={() => setAuditing((v) => !v)}
+              >
+                Audience
+              </Button>
               <Button
                 type="button"
                 size="sm"
@@ -127,6 +138,7 @@ function DraftItem({ api, draft }: { api: CommsApi; draft: Draft }) {
       ) : null}
       <ErrorNotice error={sendTest.error ?? approve.error ?? discard.error ?? preview.error} />
       {editing && ready ? <DraftEditor api={api} draft={draft} onDone={() => setEditing(false)} /> : null}
+      {auditing && ready ? <AudiencePanel api={api} draftId={draft.id} /> : null}
       {previewing && preview.data ? <EmailPreview email={preview.data} /> : null}
     </li>
   );

package/src/comms/components/index.ts

@@ -9,3 +9,4 @@ export * from './ProductUpdates';
 export * from './DraftReview';
 export * from './ResultsPanel';
 export * from './SendLog';
+export * from './AudiencePanel';

package/src/comms/hooks/index.ts

@@ -20,12 +20,15 @@ import {
 import type { CommsApi } from '../api/comms';
 import type {
   AssetsQuery,
+  AudienceSegments,
+  AudienceSpec,
   CommsAsset,
   CommsMetrics,
   CommsProgram,
   CommsSettings,
   CommsSettingsPatch,
   Draft,
+  DraftAudience,
   DraftCreate,
   DraftPatch,
   DraftsQuery,
@@ -55,6 +58,8 @@ export const commsKeys = {
   draftsAll: (slug: string) => ['startsimpli', 'comms', slug, 'drafts'] as const,
   drafts: (slug: string, q: DraftsQuery = {}) => ['startsimpli', 'comms', slug, 'drafts', q] as const,
   draft: (slug: string, id: string) => ['startsimpli', 'comms', slug, 'drafts', 'one', id] as const,
+  audience: (slug: string, id: string) => ['startsimpli', 'comms', slug, 'audience', id] as const,
+  audienceSegments: (slug: string) => ['startsimpli', 'comms', slug, 'audience-segments'] as const,
   draftPreview: (slug: string, id: string) => ['startsimpli', 'comms', slug, 'draft-preview', id] as const,
   sends: (slug: string, q: SendsQuery = {}) => ['startsimpli', 'comms', slug, 'sends', q] as const,
   metrics: (slug: string, q: MetricsQuery = {}) => ['startsimpli', 'comms', slug, 'metrics', q] as const,
@@ -210,6 +215,41 @@ export function useDraftPreview(api: CommsApi, id: string, enabled: boolean): Us
   });
 }
 
+// per-send audience -----------------------------------------------------------
+
+export function useDraftAudience(api: CommsApi, id: string, enabled: boolean): UseQueryResult<DraftAudience> {
+  return useQuery({
+    queryKey: commsKeys.audience(api.slug, id),
+    queryFn: () => api.getDraftAudience(id),
+    enabled,
+    staleTime: 0,
+  });
+}
+
+export function useAudienceSegments(api: CommsApi, enabled: boolean): UseQueryResult<AudienceSegments> {
+  return useQuery({
+    queryKey: commsKeys.audienceSegments(api.slug),
+    queryFn: () => api.listAudienceSegments(),
+    enabled,
+  });
+}
+
+/** Who a candidate audience would reach; nothing is saved. */
+export function usePreviewAudience(api: CommsApi, id: string): UseMutationResult<DraftAudience, Error, AudienceSpec> {
+  return useMutation({ mutationFn: (spec: AudienceSpec) => api.previewDraftAudience(id, spec) });
+}
+
+export function useSaveAudience(api: CommsApi, id: string): UseMutationResult<DraftAudience, Error, AudienceSpec> {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (spec: AudienceSpec) => api.saveDraftAudience(id, spec),
+    onSuccess: (data) => {
+      qc.setQueryData(commsKeys.audience(api.slug, id), data);
+      return qc.invalidateQueries({ queryKey: commsKeys.draftsAll(api.slug) });
+    },
+  });
+}
+
 function useDraftsWrite<R, V>(api: CommsApi, fn: (v: V) => Promise<R>) {
   const qc = useQueryClient();
   return useMutation<R, Error, V>({

package/src/comms/types/index.ts

@@ -211,6 +211,64 @@ export interface Draft {
   error: string | null;
   /** True while a worker is still writing the content: poll getDraft(id). */
   generating: boolean;
+  /** This send's own audience; null/absent = the program default. */
+  audience?: AudienceSpec | null;
+  audience_is_default?: boolean;
+  /** Recipients queued, set at approve. */
+  recipient_count?: number | null;
+}
+
+/** A tenant-evaluated segment: the key (and params) the foundry's backend understands. */
+export interface SegmentRef {
+  key: string;
+  params?: Record<string, unknown>;
+}
+
+/** Who one send goes to. Always narrows the foundry's customers; never widens. */
+export interface AudienceSpec {
+  base?: 'all' | 'active' | 'inactive';
+  days?: number;
+  joined_after?: string;
+  joined_before?: string;
+  segment?: SegmentRef;
+  exclude?: { emails?: string[]; segment?: SegmentRef };
+}
+
+export type ExcludedReason =
+  | 'no_email'
+  | 'excluded'
+  | 'excluded_segment'
+  | 'undeliverable'
+  | 'unverified'
+  | 'opted_out'
+  | 'suppressed';
+
+export interface AudiencePreview {
+  /** Who will receive it. */
+  count: number;
+  /** Matched the audience before mailability and exclusions. */
+  eligible: number;
+  excluded: Partial<Record<ExcludedReason, number>>;
+  excluded_total: number;
+  sample: string[];
+  excluded_sample: { email: string; reason: ExcludedReason }[];
+}
+
+export interface DraftAudience {
+  audience: AudienceSpec;
+  is_default: boolean;
+  preview: AudiencePreview;
+}
+
+export interface AudienceSegment {
+  key: string;
+  label: string;
+  description: string;
+}
+
+export interface AudienceSegments {
+  available: boolean;
+  segments: AudienceSegment[];
 }
 
 /** POST drafts/: either the email as written (201) or notes to write it from (202, generating). */