@startsimpli/integrations 0.2.45 → 0.2.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.45",
+  "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",

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,6 +17,8 @@ import type {
   ChangesResponse,
   CommsMetrics,
   CommsProgram,
+  AssetsQuery,
+  CommsAsset,
   CommsSettings,
   CommsSettingsPatch,
   Draft,
@@ -65,6 +67,11 @@ export interface CommsApi {
   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>;
@@ -110,6 +117,14 @@ export function createCommsApi(slug: string): CommsApi {
     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

@@ -12,7 +12,9 @@ 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 {
@@ -24,15 +26,35 @@ type Mode = 'write' | 'notes';
 
 const escapeHtml = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 
-/** Blank-line-separated paragraphs; a single newline is a line break. */
+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>${escapeHtml(p.trim()).replace(/\n/g, '<br>')}</p>`)
+    .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,
@@ -72,6 +94,9 @@ export function AnnouncementComposer({ api, pollIntervalMs = DEFAULT_POLL_MS }:
     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 = () => {
@@ -83,7 +108,7 @@ export function AnnouncementComposer({ api, pollIntervalMs = DEFAULT_POLL_MS }:
             subject: subject.trim(),
             ...(preheader.trim() ? { preheader: preheader.trim() } : {}),
             html: textToHtml(message),
-            text: message.trim(),
+            text: textToPlain(message),
           }
         : { notes: notes.trim() };
     create.mutate(input, {
@@ -140,6 +165,7 @@ export function AnnouncementComposer({ api, pollIntervalMs = DEFAULT_POLL_MS }:
               <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">

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/hooks/index.ts

@@ -19,6 +19,8 @@ import {
 
 import type { CommsApi } from '../api/comms';
 import type {
+  AssetsQuery,
+  CommsAsset,
   CommsMetrics,
   CommsProgram,
   CommsSettings,
@@ -48,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,
@@ -243,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

@@ -218,6 +218,23 @@ 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';