@startsimpli/integrations 0.2.44 → 0.2.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.44",
+  "version": "0.2.46",
   "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",
@@ -35,7 +35,7 @@
     "react": ">=18.0.0",
     "@tanstack/react-query": ">=5.0.0",
     "@startsimpli/llm": ">=0.4.0",
-    "@startsimpli/ui": "^0.4.161"
+    "@startsimpli/ui": "^0.4.162"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -65,7 +65,7 @@
     "typescript": "^6.0.0",
     "vitest": "^3.0.0",
     "@startsimpli/llm": "0.4.25",
-    "@startsimpli/ui": "0.4.161"
+    "@startsimpli/ui": "0.4.162"
   },
   "scripts": {
     "type-check": "tsc --noEmit",

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

@@ -0,0 +1,185 @@
+/**
+ * Announcement composer on the Customer emails page (bd startsim-k0uew, UI lane).
+ *
+ * An "Announcements" fold: write an email yourself, or write from notes. Both go
+ * through POST comms/drafts/ (201 with the content, 202 with a draft the worker
+ * is still writing, polled with GET drafts/{id}/). The draft then lands in the
+ * normal review list; creating never approves or sends.
+ *
+ * (user-event reads `{{` as an escaped `{`, so typed tokens are written `{{{{x}}`.)
+ * Plain text in, safe HTML out: blank lines are paragraphs, markup is escaped,
+ * {{tokens}} pass through untouched (the server validates them).
+ */
+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 { CustomerEmailsPage } from '../components/pages/CustomerEmailsPage';
+import { createCommsApi, setApiBase } from '../api/index';
+import type { Draft } from '../types/index';
+import { BASE, P, SLUG, comeback, draft, productUpdate, settings } from './fixtures';
+
+interface Hit { method: string; path: string; body: any }
+let hits: Hit[] = [];
+let drafts: Draft[] = [];
+let createReply: () => Response;
+let pollsLeft = 0;
+
+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);
+    if (hit.path === '/settings/') return HttpResponse.json(settings());
+    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');
+      return HttpResponse.json({ count: results.length, next: null, previous: null, results });
+    }
+    const m = hit.path.match(/^\/drafts\/([^/]+)\/$/);
+    if (m && hit.method === 'GET') {
+      const d = drafts.find((x) => x.id === m[1])!;
+      if (d.generating && --pollsLeft <= 0) {
+        Object.assign(d, { generating: false, subject: 'Written from your notes', html: '<p>Done</p>', text: 'Done' });
+      }
+      return HttpResponse.json(d);
+    }
+    return HttpResponse.json({});
+  }),
+);
+
+beforeAll(() => {
+  server.listen({ onUnhandledRequest: 'error' });
+  setApiBase(`${BASE}/api/v1`);
+});
+afterAll(() => server.close());
+beforeEach(() => {
+  hits = [];
+  drafts = [];
+  pollsLeft = 1;
+  createReply = () => HttpResponse.json({}, { status: 500 });
+});
+afterEach(() => server.resetHandlers());
+
+function mount() {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <QueryClientProvider client={qc}>
+      <CustomerEmailsPage api={createCommsApi(SLUG)} foundrySlug={SLUG} pollIntervalMs={20} />
+    </QueryClientProvider>,
+  );
+}
+
+async function openFold() {
+  const user = userEvent.setup();
+  mount();
+  const trigger = await screen.findByRole('button', { name: 'Announcements' });
+  expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  await user.click(trigger);
+  return { user, region: await screen.findByRole('region', { name: 'Announcements' }) };
+}
+
+const posts = () => hits.filter((h) => h.method === 'POST' && h.path === '/drafts/');
+
+describe('Announcements fold', () => {
+  it('is a collapsed fold with a write mode by default and a submit that waits for content', async () => {
+    const { user, region } = await openFold();
+    const send = within(region).getByRole('button', { name: 'Save as draft' });
+    expect(send).toBeDisabled();
+    await user.type(within(region).getByLabelText('Subject'), 'Hello');
+    expect(send).toBeDisabled();
+    await user.type(within(region).getByLabelText('Message'), 'Body');
+    expect(send).toBeEnabled();
+  });
+
+  it('writes an authored draft: plain text becomes escaped paragraphs, tokens untouched', async () => {
+    createReply = () => {
+      const d = draft({ id: 'a-1', program_key: 'announcement', subject: 'New engine', window: [] as any, item_keys: [] });
+      drafts.push(d);
+      return HttpResponse.json(d, { status: 201 });
+    };
+    const { user, region } = await openFold();
+    await user.type(within(region).getByLabelText('Subject'), 'New engine');
+    await user.type(within(region).getByLabelText('Preview text (optional)'), 'Hi {{{{first_name}}');
+    await user.type(within(region).getByLabelText('Message'), 'Hi {{{{first_name}}, <b>we</b> rebuilt it.{Enter}{Enter}Try it at {{{{app_url}}.');
+    await user.click(within(region).getByRole('button', { name: 'Save as draft' }));
+
+    await waitFor(() => expect(posts()).toHaveLength(1));
+    expect(posts()[0].body).toEqual({
+      subject: 'New engine',
+      preheader: 'Hi {{first_name}}',
+      html: '<p>Hi {{first_name}}, &lt;b&gt;we&lt;/b&gt; rebuilt it.</p><p>Try it at {{app_url}}.</p>',
+      text: 'Hi {{first_name}}, <b>we</b> rebuilt it.\n\nTry it at {{app_url}}.',
+    });
+    expect(await within(region).findByText(/saved as a draft/i)).toBeInTheDocument();
+    expect(within(region).getByLabelText('Subject')).toHaveValue('');
+  });
+
+  it('never approves or sends on create', async () => {
+    createReply = () => HttpResponse.json(draft({ id: 'a-1', program_key: 'announcement' }), { status: 201 });
+    const { user, region } = await openFold();
+    await user.type(within(region).getByLabelText('Subject'), 'S');
+    await user.type(within(region).getByLabelText('Message'), 'B');
+    await user.click(within(region).getByRole('button', { name: 'Save as draft' }));
+    await waitFor(() => expect(posts()).toHaveLength(1));
+    expect(hits.some((h) => /approve|send-now|test-send/.test(h.path))).toBe(false);
+  });
+
+  it('writes from notes: posts only the notes, follows the 202 draft until it is written', async () => {
+    createReply = () => {
+      const d = draft({ id: 'n-1', program_key: 'announcement', subject: '(generating)', generating: true });
+      drafts.push(d);
+      return HttpResponse.json(d, { status: 202 });
+    };
+    const { user, region } = await openFold();
+    await user.click(within(region).getByRole('radio', { name: 'Write it from my notes' }));
+    expect(within(region).queryByLabelText('Subject')).not.toBeInTheDocument();
+    await user.type(within(region).getByLabelText('Notes'), 'We rebuilt the design engine.');
+    await user.click(within(region).getByRole('button', { name: 'Write a draft from my notes' }));
+
+    await waitFor(() => expect(posts()).toHaveLength(1));
+    expect(posts()[0].body).toEqual({ notes: 'We rebuilt the design engine.' });
+    expect(await within(region).findByText(/writing/i)).toBeInTheDocument();
+    expect(await within(region).findByText(/draft is ready/i)).toBeInTheDocument();
+    expect(hits.some((h) => h.method === 'GET' && h.path === '/drafts/n-1/')).toBe(true);
+  });
+
+  it('shows a failed generation as an alert', async () => {
+    createReply = () => {
+      const d = draft({ id: 'n-2', program_key: 'announcement', generating: true });
+      drafts.push(d);
+      return HttpResponse.json(d, { status: 202 });
+    };
+    const { user, region } = await openFold();
+    await user.click(within(region).getByRole('radio', { name: 'Write it from my notes' }));
+    await user.type(within(region).getByLabelText('Notes'), 'n');
+    await user.click(within(region).getByRole('button', { name: 'Write a draft from my notes' }));
+    await waitFor(() => expect(drafts).toHaveLength(1));
+    Object.assign(drafts[0], { generating: false, error: 'model down', subject: '(generation failed)' });
+    expect(await within(region).findByRole('alert')).toHaveTextContent(/model down/i);
+  });
+
+  it("shows the server's reason for a rejected draft (an unknown token) and keeps what was typed", async () => {
+    createReply = () => HttpResponse.json({ detail: 'unknown token {{plan_name}} in comms content' }, { status: 400 });
+    const { user, region } = await openFold();
+    await user.type(within(region).getByLabelText('Subject'), 'Keep me');
+    await user.type(within(region).getByLabelText('Message'), 'Hi {{{{plan_name}}');
+    await user.click(within(region).getByRole('button', { name: 'Save as draft' }));
+    expect(await within(region).findByRole('alert')).toHaveTextContent('unknown token {{plan_name}}');
+    expect(within(region).getByLabelText('Subject')).toHaveValue('Keep me');
+  });
+
+  it('lists the new draft for review in the same fold', async () => {
+    drafts.push(draft({ id: 'a-9', program_key: 'announcement', subject: 'Waiting for you' }));
+    const { region } = await openFold();
+    expect(await within(region).findByText('Waiting for you')).toBeInTheDocument();
+  });
+});

package/src/comms/__tests__/image-library.test.tsx

@@ -0,0 +1,230 @@
+/**
+ * Image library inside the Announcements fold (bd startsim-ktuhz, picker lane).
+ *
+ * "Images" is a small section of the composer: upload a picture with its alt
+ * text (alt is required), see the foundry's library as thumbnails, insert one
+ * into the message, delete one. Uploads are multipart POSTs to comms/assets/.
+ *
+ * Inserting writes `![alt](url)` on its own paragraph; saving the draft turns
+ * that into an <img> (escaped, max-width 100%) in the html and `[Image: alt]` in
+ * the plain-text part. The server sanitiser has the last word on which hosts
+ * survive.
+ *
+ * TEST ENVIRONMENT NOTE: jsdom's FormData is not recognised by Node's fetch (it is
+ * sent as "[object FormData]"), so the tests wrap fetch: a FormData body is read
+ * field by field and forwarded as JSON with an X-Test-Form header. That keeps
+ * "the request carries file and alt" under test; the multipart encoding itself
+ * is the browser's. The helper test below checks the real fetch call directly.
+ */
+import * as React from 'react';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } 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 { CustomerEmailsPage } from '../components/pages/CustomerEmailsPage';
+import { textToHtml, textToPlain } from '../components/AnnouncementComposer';
+import { createCommsApi, setApiBase } from '../api/index';
+import type { CommsAsset } from '../types/index';
+import { BASE, P, SLUG, comeback, draft, productUpdate, settings } from './fixtures';
+
+const asset = (over: Partial<CommsAsset> = {}): CommsAsset => ({
+  id: 'img-1',
+  key: 'crochets/img-1.png',
+  url: 'https://cdn.test/crochets/img-1.png',
+  filename: 'cat.png',
+  content_type: 'image/png',
+  bytes: 1234,
+  width: 60,
+  height: 40,
+  alt: 'A cat',
+  created_at: '2026-10-31T10:00:00Z',
+  ...over,
+});
+
+interface Hit { method: string; path: string; body: any; form?: Record<string, string> }
+let hits: Hit[] = [];
+let library: CommsAsset[] = [];
+let uploadReply: () => Response;
+
+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 isForm = request.headers.get('X-Test-Form') === '1';
+    let body: any;
+    let form: Hit['form'];
+    if (request.method !== 'GET') {
+      const t = await request.text();
+      const parsed = t ? JSON.parse(t) : undefined;
+      if (isForm) form = parsed;
+      else body = parsed;
+    }
+    const hit: Hit = { method: request.method, path: rel(url.pathname), body, form };
+    hits.push(hit);
+    if (hit.path === '/settings/') return HttpResponse.json(settings());
+    if (hit.path === '/programs/') return HttpResponse.json([comeback(), productUpdate()]);
+    if (hit.path === '/drafts/' && hit.method === 'POST') return HttpResponse.json(draft({ id: 'a-1' }), { status: 201 });
+    if (hit.path === '/drafts/') return HttpResponse.json({ count: 0, next: null, previous: null, results: [] });
+    if (hit.path === '/assets/' && hit.method === 'POST') return uploadReply();
+    if (hit.path === '/assets/') return HttpResponse.json({ count: library.length, next: null, previous: null, results: library });
+    const m = hit.path.match(/^\/assets\/([^/]+)\/$/);
+    if (m && hit.method === 'DELETE') {
+      library = library.filter((a) => a.id !== m[1]);
+      return new HttpResponse(null, { status: 204 });
+    }
+    return HttpResponse.json({});
+  }),
+);
+
+let realFetch: typeof fetch;
+let lastInit: RequestInit | undefined;
+
+beforeAll(() => {
+  server.listen({ onUnhandledRequest: 'error' });
+  realFetch = globalThis.fetch; // msw's patched fetch, captured after listen()
+  vi.stubGlobal('fetch', (input: RequestInfo | URL, init?: RequestInit) => {
+    if (init?.body instanceof FormData) {
+      lastInit = init; // the upload call itself (later refetches must not overwrite it)
+      const entries = Object.fromEntries(init.body.entries());
+      const headers = { ...(init.headers as Record<string, string>), 'X-Test-Form': '1', 'Content-Type': 'application/json' };
+      return realFetch.call(globalThis, input, {
+        ...init,
+        headers,
+        body: JSON.stringify({ file: (entries.file as File).name, alt: String(entries.alt) }),
+      });
+    }
+    return realFetch.call(globalThis, input, init);
+  });
+  setApiBase(`${BASE}/api/v1`);
+});
+afterAll(() => {
+  server.close();
+  vi.unstubAllGlobals();
+});
+beforeEach(() => {
+  hits = [];
+  library = [];
+  uploadReply = () => HttpResponse.json({}, { status: 500 });
+});
+afterEach(() => server.resetHandlers());
+
+async function openImages() {
+  const user = userEvent.setup();
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  render(
+    <QueryClientProvider client={qc}>
+      <CustomerEmailsPage api={createCommsApi(SLUG)} foundrySlug={SLUG} pollIntervalMs={20} />
+    </QueryClientProvider>,
+  );
+  await user.click(await screen.findByRole('button', { name: 'Announcements' }));
+  const region = await screen.findByRole('region', { name: 'Announcements' });
+  return { user, region };
+}
+
+const png = () => new File([new Uint8Array([137, 80, 78, 71])], 'cat.png', { type: 'image/png' });
+const uploads = () => hits.filter((h) => h.method === 'POST' && h.path === '/assets/');
+
+describe('textToHtml / textToPlain with images', () => {
+  it('turns a paragraph that is only an image into an escaped, responsive <img>', () => {
+    expect(textToHtml('Hello\n\n![A "cat"](https://cdn.test/a.png)')).toBe(
+      '<p>Hello</p><p><img src="https://cdn.test/a.png" alt="A &quot;cat&quot;" style="max-width:100%;height:auto;border:0"></p>',
+    );
+  });
+  it('handles an image inline and escapes markup around it', () => {
+    expect(textToHtml('See ![x](https://cdn.test/a.png) <b>now</b>')).toBe(
+      '<p>See <img src="https://cdn.test/a.png" alt="x" style="max-width:100%;height:auto;border:0"> &lt;b&gt;now&lt;/b&gt;</p>',
+    );
+  });
+  it('never turns a non-http(s) target into an image', () => {
+    expect(textToHtml('![x](javascript:alert(1))')).toBe('<p>![x](javascript:alert(1))</p>');
+  });
+  it('writes [Image: alt] in the plain-text part', () => {
+    expect(textToPlain('Hi\n\n![A cat](https://cdn.test/a.png)')).toBe('Hi\n\n[Image: A cat]');
+  });
+});
+
+describe('Images section', () => {
+  it('lists the foundry library as thumbnails with their alt text', async () => {
+    library = [asset(), asset({ id: 'img-2', alt: 'A dog', url: 'https://cdn.test/crochets/img-2.png' })];
+    const { region } = await openImages();
+    const imgs = await within(region).findAllByRole('img', { name: 'A cat' });
+    expect(imgs[0]).toHaveAttribute('src', 'https://cdn.test/crochets/img-1.png');
+    expect(within(region).getByRole('img', { name: 'A dog' })).toBeInTheDocument();
+  });
+
+  it('needs a file AND alt text before it will upload', async () => {
+    const { user, region } = await openImages();
+    const button = await within(region).findByRole('button', { name: 'Upload image' });
+    expect(button).toBeDisabled();
+    await user.upload(within(region).getByLabelText('Image file'), png());
+    expect(button).toBeDisabled();
+    await user.type(within(region).getByLabelText('Describe the image'), 'A cat');
+    expect(button).toBeEnabled();
+  });
+
+  it('uploads multipart with the file and alt, then shows it in the library', async () => {
+    uploadReply = () => {
+      library = [asset()];
+      return HttpResponse.json(asset(), { status: 201 });
+    };
+    const { user, region } = await openImages();
+    await user.upload(await within(region).findByLabelText('Image file'), png());
+    await user.type(within(region).getByLabelText('Describe the image'), 'A cat');
+    await user.click(within(region).getByRole('button', { name: 'Upload image' }));
+    await waitFor(() => expect(uploads()).toHaveLength(1));
+    const form = uploads()[0].form!;
+    expect(form.file).toBe('cat.png');
+    expect(form.alt).toBe('A cat');
+    // what the helper really sent: a FormData body and NO forced JSON content type
+    expect(lastInit?.body).toBeInstanceOf(FormData);
+    expect((lastInit?.headers as Record<string, string>)['Content-Type']).toBeUndefined();
+    expect(await within(region).findByRole('img', { name: 'A cat' })).toBeInTheDocument();
+    expect(within(region).getByLabelText('Describe the image')).toHaveValue('');
+  });
+
+  it("shows the server's reason when an upload is refused", async () => {
+    uploadReply = () => HttpResponse.json({ detail: 'that is not a PNG, JPEG, GIF or WebP image' }, { status: 400 });
+    const { user, region } = await openImages();
+    await user.upload(await within(region).findByLabelText('Image file'), png());
+    await user.type(within(region).getByLabelText('Describe the image'), 'x');
+    await user.click(within(region).getByRole('button', { name: 'Upload image' }));
+    expect(await within(region).findByRole('alert')).toHaveTextContent('not a PNG, JPEG, GIF or WebP');
+  });
+
+  it('inserts an image into the message as its own paragraph', async () => {
+    library = [asset()];
+    const { user, region } = await openImages();
+    await user.type(within(region).getByLabelText('Message'), 'Hello there');
+    await user.click(await within(region).findByRole('button', { name: 'Insert A cat' }));
+    expect(within(region).getByLabelText('Message')).toHaveValue(
+      'Hello there\n\n![A cat](https://cdn.test/crochets/img-1.png)',
+    );
+  });
+
+  it('saves a draft whose html has the <img> and whose text part says [Image: alt]', async () => {
+    library = [asset()];
+    const { user, region } = await openImages();
+    await user.type(within(region).getByLabelText('Subject'), 'Pics');
+    await user.type(within(region).getByLabelText('Message'), 'Look');
+    await user.click(await within(region).findByRole('button', { name: 'Insert A cat' }));
+    await user.click(within(region).getByRole('button', { name: 'Save as draft' }));
+    await waitFor(() => expect(hits.some((h) => h.method === 'POST' && h.path === '/drafts/')).toBe(true));
+    const body = hits.find((h) => h.method === 'POST' && h.path === '/drafts/')!.body;
+    expect(body.html).toBe(
+      '<p>Look</p><p><img src="https://cdn.test/crochets/img-1.png" alt="A cat" style="max-width:100%;height:auto;border:0"></p>',
+    );
+    expect(body.text).toBe('Look\n\n[Image: A cat]');
+  });
+
+  it('deletes an image from the library', async () => {
+    library = [asset()];
+    const { user, region } = await openImages();
+    await user.click(await within(region).findByRole('button', { name: 'Delete A cat' }));
+    await waitFor(() => expect(hits.some((h) => h.method === 'DELETE' && h.path === '/assets/img-1/')).toBe(true));
+    await waitFor(() => expect(within(region).queryByRole('img', { name: 'A cat' })).not.toBeInTheDocument());
+  });
+});

package/src/comms/api/_fetch.ts

@@ -47,7 +47,9 @@ export async function request<T>(path: string, opts: RequestOptions = {}): Promi
   }
 
   const headers: Record<string, string> = { Accept: 'application/json' };
-  if (body !== undefined) headers['Content-Type'] = 'application/json';
+  const isForm = typeof FormData !== 'undefined' && body instanceof FormData;
+  // A FormData body carries its own multipart boundary: the browser sets the header.
+  if (body !== undefined && !isForm) headers['Content-Type'] = 'application/json';
   if (_tokenProvider) {
     try {
       const token = await _tokenProvider();
@@ -61,7 +63,7 @@ export async function request<T>(path: string, opts: RequestOptions = {}): Promi
     method,
     headers,
     credentials: 'include',
-    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    ...(body !== undefined ? { body: isForm ? (body as FormData) : JSON.stringify(body) } : {}),
   });
 
   const contentType = resp.headers.get('Content-Type') || '';

package/src/comms/api/comms.ts

@@ -17,9 +17,12 @@ import type {
   ChangesResponse,
   CommsMetrics,
   CommsProgram,
+  AssetsQuery,
+  CommsAsset,
   CommsSettings,
   CommsSettingsPatch,
   Draft,
+  DraftCreate,
   DraftPatch,
   DraftsQuery,
   MetricsQuery,
@@ -63,6 +66,12 @@ export interface CommsApi {
   listChanges(query?: { since?: string; until?: string }): Promise<ChangesResponse>;
   listDrafts(query?: DraftsQuery): Promise<Paginated<Draft>>;
   getDraft(id: string): Promise<Draft>;
+  createDraft(input: DraftCreate): Promise<Draft>;
+
+  // image library
+  listAssets(query?: AssetsQuery): Promise<Paginated<CommsAsset>>;
+  uploadAsset(file: File, alt: string): Promise<CommsAsset>;
+  deleteAsset(id: string): Promise<void>;
   updateDraft(id: string, patch: DraftPatch): Promise<Draft>;
   approveDraft(id: string): Promise<Draft>;
   discardDraft(id: string): Promise<Draft>;
@@ -107,6 +116,15 @@ export function createCommsApi(slug: string): CommsApi {
     listChanges: (query = {}) => request(`${P}/changes/`, { query: { ...query } }),
     listDrafts: (query = {}) => request(`${P}/drafts/`, { query: { ...query } }),
     getDraft: (id) => request(draftPath(id)),
+    createDraft: (input) => request(`${P}/drafts/`, { method: 'POST', body: input }),
+    listAssets: (query = {}) => request(`${P}/assets/`, { query: { ...query } }),
+    uploadAsset: (file, alt) => {
+      const form = new FormData();
+      form.append('file', file);
+      form.append('alt', alt);
+      return request(`${P}/assets/`, { method: 'POST', body: form });
+    },
+    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' }),
     discardDraft: (id) => request(draftPath(id, 'discard'), { method: 'POST' }),

package/src/comms/components/AnnouncementComposer.tsx

@@ -0,0 +1,196 @@
+/**
+ * Announcements (bd startsim-k0uew): a one-off email to the customers, written
+ * by hand or by AI from notes. Both go through POST drafts/. The draft lands in
+ * the normal review list below the form (preview, test send, edit, approve);
+ * creating one never approves or sends it.
+ *
+ * Plain text in, safe HTML out: blank lines make paragraphs, markup is escaped,
+ * {{tokens}} are left for the server to validate and fill in.
+ */
+import { useCallback, useEffect, useState, type ReactElement } from 'react';
+import { Button, Input, Label, Textarea } from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import { DEFAULT_POLL_MS, useCreateDraft, useDraft } from '../hooks/index';
+import type { CommsAsset } from '../types/index';
+import { DraftReview } from './DraftReview';
+import { ImageLibrary } from './ImageLibrary';
+import { ErrorNotice, Note, humanize, useFieldId } from './_shared';
+
+export interface AnnouncementComposerProps {
+  api: CommsApi;
+  pollIntervalMs?: number;
+}
+
+type Mode = 'write' | 'notes';
+
+const escapeHtml = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+const IMAGE = /!\[([^\]]*)\]\((https?:\/\/[^\s)]+)\)/g;
+const escapeAttr = (v: string) => escapeHtml(v).replace(/"/g, '&quot;');
+
+/** One paragraph's text, with `![alt](https://url)` turned into an <img> and everything else escaped. */
+function inlineHtml(text: string): string {
+  let out = '';
+  let last = 0;
+  for (const m of text.matchAll(IMAGE)) {
+    out += escapeHtml(text.slice(last, m.index)).replace(/\n/g, '<br>');
+    out += `<img src="${escapeAttr(m[2])}" alt="${escapeAttr(m[1])}" style="max-width:100%;height:auto;border:0">`;
+    last = (m.index ?? 0) + m[0].length;
+  }
+  return out + escapeHtml(text.slice(last)).replace(/\n/g, '<br>');
+}
+
+/** Blank-line-separated paragraphs; a single newline is a line break; an image is `![alt](https://url)`. */
+export function textToHtml(text: string): string {
+  return text
+    .trim()
+    .split(/\n{2,}/)
+    .map((p) => `<p>${inlineHtml(p.trim())}</p>`)
+    .join('');
+}
+
+/** The plain-text part: each image reads `[Image: alt]`. */
+export function textToPlain(text: string): string {
+  return text.trim().replace(IMAGE, (_m, alt: string) => `[Image: ${alt}]`);
+}
+
+/** Follows one notes draft until the worker has finished writing it. */
+function NotesProgress({
+  api,
+  id,
+  pollIntervalMs,
+  onFinished,
+}: {
+  api: CommsApi;
+  id: string;
+  pollIntervalMs: number;
+  onFinished: (error: string | null) => void;
+}) {
+  const draft = useDraft(api, id, pollIntervalMs);
+  const d = draft.data;
+  useEffect(() => {
+    if (draft.error) onFinished(draft.error.message);
+    else if (d && !d.generating) onFinished(d.error ? `Writing this draft failed: ${humanize(d.error)}` : null);
+  }, [d, draft.error, onFinished]);
+  return <Note>Writing the draft… this can take a minute.</Note>;
+}
+
+export function AnnouncementComposer({ api, pollIntervalMs = DEFAULT_POLL_MS }: AnnouncementComposerProps): ReactElement {
+  const create = useCreateDraft(api);
+  const ids = useFieldId('comms-announce');
+  const [mode, setMode] = useState<Mode>('write');
+  const [subject, setSubject] = useState('');
+  const [preheader, setPreheader] = useState('');
+  const [message, setMessage] = useState('');
+  const [notes, setNotes] = useState('');
+  const [following, setFollowing] = useState<string | null>(null);
+  const [status, setStatus] = useState<string | null>(null);
+  const [failure, setFailure] = useState<string | null>(null);
+
+  const onFinished = useCallback((error: string | null) => {
+    setFollowing(null);
+    if (error) setFailure(error);
+    else setStatus('Your draft is ready. Review it below.');
+  }, []);
+
+  const insertImage = (a: CommsAsset) =>
+    setMessage((m) => `${m.trimEnd()}${m.trim() ? '\n\n' : ''}![${a.alt}](${a.url})`);
+
+  const canSave = mode === 'write' ? !!subject.trim() && !!message.trim() : !!notes.trim();
+
+  const submit = () => {
+    setStatus(null);
+    setFailure(null);
+    const input =
+      mode === 'write'
+        ? {
+            subject: subject.trim(),
+            ...(preheader.trim() ? { preheader: preheader.trim() } : {}),
+            html: textToHtml(message),
+            text: textToPlain(message),
+          }
+        : { notes: notes.trim() };
+    create.mutate(input, {
+      onSuccess: (d) => {
+        if (mode === 'write') {
+          setSubject('');
+          setPreheader('');
+          setMessage('');
+          setStatus('Saved as a draft. Review it below; nothing is sent until you approve it.');
+        } else {
+          setNotes('');
+          if (d.generating) setFollowing(d.id);
+        }
+      },
+    });
+  };
+
+  return (
+    <div className="space-y-4">
+      <form
+        className="space-y-3"
+        onSubmit={(e) => {
+          e.preventDefault();
+          if (canSave) submit();
+        }}
+      >
+        <fieldset className="flex flex-wrap gap-4">
+          <legend className="sr-only">How to write it</legend>
+          {(
+            [
+              ['write', 'Write it myself'],
+              ['notes', 'Write it from my notes'],
+            ] as const
+          ).map(([value, label]) => (
+            <label key={value} className="flex items-center gap-2 text-sm">
+              <input type="radio" name={`${ids}-mode`} checked={mode === value} onChange={() => setMode(value)} />
+              {label}
+            </label>
+          ))}
+        </fieldset>
+
+        {mode === 'write' ? (
+          <>
+            <div className="space-y-1">
+              <Label htmlFor={`${ids}-subject`}>Subject</Label>
+              <Input id={`${ids}-subject`} value={subject} onChange={(e) => setSubject(e.target.value)} />
+            </div>
+            <div className="space-y-1">
+              <Label htmlFor={`${ids}-pre`}>Preview text (optional)</Label>
+              <Input id={`${ids}-pre`} value={preheader} onChange={(e) => setPreheader(e.target.value)} />
+            </div>
+            <div className="space-y-1">
+              <Label htmlFor={`${ids}-msg`}>Message</Label>
+              <Textarea id={`${ids}-msg`} rows={8} value={message} onChange={(e) => setMessage(e.target.value)} />
+              <Note>Plain text: leave a blank line between paragraphs, and anything in angle brackets is shown as typed. {'{{first_name}}'} and {'{{app_url}}'} are filled in for each customer.</Note>
+            </div>
+            <ImageLibrary api={api} onInsert={insertImage} />
+          </>
+        ) : (
+          <div className="space-y-1">
+            <Label htmlFor={`${ids}-notes`}>Notes</Label>
+            <Textarea
+              id={`${ids}-notes`}
+              rows={6}
+              value={notes}
+              placeholder="What to tell customers, in your own words. The AI writes the email from this alone."
+              onChange={(e) => setNotes(e.target.value)}
+            />
+          </div>
+        )}
+
+        <Button type="submit" disabled={!canSave || create.isPending || !!following}>
+          {mode === 'write' ? 'Save as draft' : 'Write a draft from my notes'}
+        </Button>
+      </form>
+
+      {following ? (
+        <NotesProgress api={api} id={following} pollIntervalMs={pollIntervalMs} onFinished={onFinished} />
+      ) : null}
+      {status ? <Note>{status}</Note> : null}
+      <ErrorNotice error={create.error ?? (failure ? new Error(failure) : null)} />
+      <DraftReview api={api} pollIntervalMs={pollIntervalMs} />
+    </div>
+  );
+}

package/src/comms/components/ImageLibrary.tsx

@@ -0,0 +1,115 @@
+/**
+ * The foundry's email image library, inside the announcement composer (bd
+ * startsim-ktuhz): upload a picture with its alt text (required), browse the
+ * library as thumbnails (server-paged), insert one into the message, delete one.
+ * The server decides what an image is (type sniffed, EXIF dropped) and which hosts
+ * survive the email sanitiser; this only collects, lists and hands back a url.
+ */
+import { useState, type ReactElement } from 'react';
+import { Button, Input, Label } from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import { useAssets, useDeleteAsset, useUploadAsset } from '../hooks/index';
+import type { CommsAsset } from '../types/index';
+import { ErrorNotice, Note, useFieldId } from './_shared';
+
+export interface ImageLibraryProps {
+  api: CommsApi;
+  /** Called with the chosen image; the composer puts it in the message. */
+  onInsert: (asset: CommsAsset) => void;
+  pageSize?: number;
+}
+
+export function ImageLibrary({ api, onInsert, pageSize = 12 }: ImageLibraryProps): ReactElement {
+  const ids = useFieldId('comms-images');
+  const [page, setPage] = useState(1);
+  const assets = useAssets(api, { page, page_size: pageSize });
+  const upload = useUploadAsset(api);
+  const remove = useDeleteAsset(api);
+  const [file, setFile] = useState<File | null>(null);
+  const [alt, setAlt] = useState('');
+  const [inputKey, setInputKey] = useState(0);
+
+  const results = assets.data?.results ?? [];
+
+  const submit = () => {
+    if (!file || !alt.trim()) return;
+    upload.mutate(
+      { file, alt: alt.trim() },
+      {
+        onSuccess: () => {
+          setFile(null);
+          setAlt('');
+          setInputKey((k) => k + 1);
+          setPage(1);
+        },
+      },
+    );
+  };
+
+  return (
+    <div className="space-y-3 rounded-md border p-3">
+      <p className="text-sm font-medium">Images</p>
+      <div className="flex flex-wrap items-end gap-3">
+        <div className="space-y-1">
+          <Label htmlFor={`${ids}-file`}>Image file</Label>
+          <input
+            key={inputKey}
+            id={`${ids}-file`}
+            type="file"
+            accept="image/png,image/jpeg,image/gif,image/webp"
+            onChange={(e) => setFile(e.target.files?.[0] ?? null)}
+            className="block text-sm"
+          />
+        </div>
+        <div className="min-w-48 flex-1 space-y-1">
+          <Label htmlFor={`${ids}-alt`}>Describe the image</Label>
+          <Input id={`${ids}-alt`} value={alt} onChange={(e) => setAlt(e.target.value)} />
+        </div>
+        <Button type="button" disabled={!file || !alt.trim() || upload.isPending} onClick={submit}>
+          Upload image
+        </Button>
+      </div>
+      <Note>PNG, JPEG, GIF or WebP. The description is read aloud by screen readers and shown when images are blocked.</Note>
+      <ErrorNotice error={upload.error ?? remove.error ?? assets.error} />
+
+      {results.length ? (
+        <ul className="grid grid-cols-2 gap-3 sm:grid-cols-4">
+          {results.map((a) => (
+            <li key={a.id} className="space-y-1">
+              <img src={a.url} alt={a.alt} className="h-20 w-full rounded border object-cover" />
+              <div className="flex gap-1">
+                <Button type="button" size="sm" variant="outline" aria-label={`Insert ${a.alt}`} onClick={() => onInsert(a)}>
+                  Insert
+                </Button>
+                <Button
+                  type="button"
+                  size="sm"
+                  variant="ghost"
+                  aria-label={`Delete ${a.alt}`}
+                  disabled={remove.isPending}
+                  onClick={() => remove.mutate(a.id)}
+                >
+                  Delete
+                </Button>
+              </div>
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <Note>{assets.isLoading ? 'Loading images…' : 'No images yet.'}</Note>
+      )}
+
+      {assets.data && (assets.data.previous || assets.data.next) ? (
+        <div className="flex items-center gap-2">
+          <Button type="button" size="sm" variant="outline" disabled={!assets.data.previous} onClick={() => setPage((p) => p - 1)}>
+            Previous
+          </Button>
+          <Button type="button" size="sm" variant="outline" disabled={!assets.data.next} onClick={() => setPage((p) => p + 1)}>
+            Next
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/comms/components/pages/CustomerEmailsPage.tsx

@@ -8,7 +8,7 @@
  * LAYOUT (Quinn): a normal app. ONE title ("Customer emails"), the two switches
  * directly under it, then folded sections in one column. No side rail, no card
  * stack, no second header. Folds: Comeback sequence settings, Product updates,
- * Approval, Voice, Sending domain, Results, Send log. Fold bodies mount only
+ * Announcements, Approval, Voice, Sending domain, Results, Send log. Fold bodies mount only
  * when opened, so nothing below the switches is fetched until asked for.
  *
  * Admin-only: the comms routes answer 403 to anyone without view_comms; the page
@@ -20,6 +20,7 @@ import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@s
 import type { CommsApi } from '../../api/comms';
 import { DEFAULT_POLL_MS, useCommsSettings, usePrograms } from '../../hooks/index';
 import { CommsApiError } from '../../types/index';
+import { AnnouncementComposer } from '../AnnouncementComposer';
 import { ApprovalModeSetting } from '../ApprovalModeSetting';
 import { ProductUpdates } from '../ProductUpdates';
 import { ProgramToggles } from '../ProgramToggles';
@@ -83,6 +84,9 @@ export function CustomerEmailsPage({
           <Fold value="updates" title="Product updates">
             <ProductUpdates api={api} pollIntervalMs={pollIntervalMs} />
           </Fold>
+          <Fold value="announcements" title="Announcements">
+            <AnnouncementComposer api={api} pollIntervalMs={pollIntervalMs} />
+          </Fold>
           <Fold value="approval" title="Approval">
             <ApprovalModeSetting api={api} />
           </Fold>

package/src/comms/hooks/index.ts

@@ -19,11 +19,14 @@ import {
 
 import type { CommsApi } from '../api/comms';
 import type {
+  AssetsQuery,
+  CommsAsset,
   CommsMetrics,
   CommsProgram,
   CommsSettings,
   CommsSettingsPatch,
   Draft,
+  DraftCreate,
   DraftPatch,
   DraftsQuery,
   MetricsQuery,
@@ -47,6 +50,8 @@ export const commsKeys = {
     ['startsimpli', 'comms', slug, 'generation', key, step] as const,
   preview: (slug: string, key: string, step: number) =>
     ['startsimpli', 'comms', slug, 'preview', key, step] as const,
+  assetsAll: (slug: string) => ['startsimpli', 'comms', slug, 'assets'] as const,
+  assets: (slug: string, q: AssetsQuery = {}) => ['startsimpli', 'comms', slug, 'assets', q] as const,
   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,
@@ -213,6 +218,11 @@ function useDraftsWrite<R, V>(api: CommsApi, fn: (v: V) => Promise<R>) {
   });
 }
 
+/** A one-off announcement: the email as written (201) or notes to write it from (202, still generating: follow with useDraft). */
+export function useCreateDraft(api: CommsApi): UseMutationResult<Draft, Error, DraftCreate> {
+  return useDraftsWrite(api, (input: DraftCreate) => api.createDraft(input));
+}
+
 export function useUpdateDraft(api: CommsApi): UseMutationResult<Draft, Error, { id: string; patch: DraftPatch }> {
   const qc = useQueryClient();
   return useMutation({
@@ -237,6 +247,28 @@ export function useSendUpdateNow(api: CommsApi): UseMutationResult<SendNowResult
   return useDraftsWrite(api, (input: { notes?: string }) => api.sendUpdateNow(input));
 }
 
+// image library ---------------------------------------------------------------
+
+export function useAssets(api: CommsApi, q: AssetsQuery): UseQueryResult<Paginated<CommsAsset>> {
+  return useQuery({ queryKey: commsKeys.assets(api.slug, q), queryFn: () => api.listAssets(q) });
+}
+
+function useAssetsWrite<R, V>(api: CommsApi, fn: (v: V) => Promise<R>) {
+  const qc = useQueryClient();
+  return useMutation<R, Error, V>({
+    mutationFn: fn,
+    onSuccess: () => qc.invalidateQueries({ queryKey: commsKeys.assetsAll(api.slug) }),
+  });
+}
+
+export function useUploadAsset(api: CommsApi): UseMutationResult<CommsAsset, Error, { file: File; alt: string }> {
+  return useAssetsWrite(api, ({ file, alt }: { file: File; alt: string }) => api.uploadAsset(file, alt));
+}
+
+export function useDeleteAsset(api: CommsApi): UseMutationResult<void, Error, string> {
+  return useAssetsWrite(api, (id: string) => api.deleteAsset(id));
+}
+
 // results ------------------------------------------------------------------
 
 /** Server-side pagination: page/page_size go to the server, never sliced here. */

package/src/comms/types/index.ts

@@ -157,6 +157,7 @@ export interface StepGeneration {
 
 /** The two switches persona A sees (A1). Presets are data server-side. */
 export const COMEBACK_PROGRAM_KEY = 'comeback';
+export const ANNOUNCEMENT_PROGRAM_KEY = 'announcement';
 export const PRODUCT_UPDATE_PROGRAM_KEY = 'product_update';
 
 // ---- preview / test send ----------------------------------------------------
@@ -212,6 +213,28 @@ export interface Draft {
   generating: boolean;
 }
 
+/** POST drafts/: either the email as written (201) or notes to write it from (202, generating). */
+export type DraftCreate =
+  | { subject: string; html: string; preheader?: string; text?: string }
+  | { notes: string };
+
+/** One image in the foundry's email image library (comms/assets/). */
+export interface CommsAsset {
+  id: string;
+  key: string;
+  /** Public CDN url; the only host the server's email sanitiser keeps. */
+  url: string;
+  filename: string;
+  content_type: string;
+  bytes: number;
+  width: number;
+  height: number;
+  alt: string;
+  created_at: string;
+}
+
+export type AssetsQuery = PageParams;
+
 export type DraftPatch = Partial<Pick<Draft, 'subject' | 'preheader' | 'html' | 'text'>>;
 
 export const NOTHING_CUSTOMER_FACING = 'nothing_customer_facing';