@startsimpli/integrations 0.2.36 → 0.2.37

package/README.md

@@ -52,6 +52,8 @@ Peer deps (both optional, only needed for the hooks/components subpaths):
 
 You can consume `@startsimpli/integrations/types` and `@startsimpli/integrations/api` from a non-React context (e.g. a Node server, an MSW handler) without pulling in React.
 
+Foundry customer email (comeback sequences, product updates) lives at the `@startsimpli/integrations/comms` subpath (also `/comms/types`, `/comms/api`, `/comms/hooks`, `/comms/components`). It is not re-exported from the root, and it additionally needs the optional peer `@startsimpli/ui`.
+
 ## Public surface
 
 | Export | Type | Description |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.36",
-  "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps.",
+  "version": "0.2.37",
+  "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",
   "exports": {
@@ -11,7 +11,12 @@
     "./corpus": "./src/corpus/index.ts",
     "./corpus-llm": "./src/corpus/llm.ts",
     "./safe-fetch": "./src/safe-fetch/index.ts",
-    "./ingest": "./src/ingest/index.ts"
+    "./ingest": "./src/ingest/index.ts",
+    "./comms": "./src/comms/index.ts",
+    "./comms/types": "./src/comms/types/index.ts",
+    "./comms/api": "./src/comms/api/index.ts",
+    "./comms/hooks": "./src/comms/hooks/index.ts",
+    "./comms/components": "./src/comms/components/index.ts"
   },
   "files": [
     "src",
@@ -29,7 +34,8 @@
   "peerDependencies": {
     "react": ">=18.0.0",
     "@tanstack/react-query": ">=5.0.0",
-    "@startsimpli/llm": ">=0.4.0"
+    "@startsimpli/llm": ">=0.4.0",
+    "@startsimpli/ui": "^0.4.155"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -40,6 +46,9 @@
     },
     "@startsimpli/llm": {
       "optional": true
+    },
+    "@startsimpli/ui": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -55,6 +64,7 @@
     "react-dom": "^19.0.0",
     "typescript": "^6.0.0",
     "vitest": "^3.0.0",
+    "@startsimpli/ui": "0.4.155",
     "@startsimpli/llm": "0.4.25"
   },
   "scripts": {

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

@@ -0,0 +1,327 @@
+/**
+ * CommsApi against a mocked Django (msw). One round-trip per route in ADR
+ * startsim-bzcrj section 2: the method, the path under
+ * /api/v1/foundry/tenants/{slug}/comms/, the body, the query params, and that
+ * the parsed response is what the caller gets back.
+ *
+ * Pagination is pinned to `page` + `page_size`, which is what the ADR specifies.
+ * NOTE for the backend lanes: DRF's DEFAULT paginator here
+ * (core.pagination.StandardPaginatedResponse) reads `pageSize`, so the sends and
+ * drafts views must use core.api.pagination.FlexiblePageNumberPagination or the
+ * page size is silently ignored.
+ */
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+
+import { createCommsApi, setApiBase, setAuthTokenProvider } from '../api/index';
+import { CommsApiError } from '../types/index';
+import { BASE, P, SLUG, comeback, draft, generation, metrics, productUpdate, sendRows, settings } from './fixtures';
+
+interface Seen {
+  method: string;
+  path: string;
+  search: URLSearchParams;
+  body: unknown;
+  auth: string | null;
+}
+
+let seen: Seen[] = [];
+let reply: (s: Seen) => Response = () => HttpResponse.json({});
+
+const server = setupServer(
+  http.all(`${BASE}/api/v1/*`, async ({ request }) => {
+    const url = new URL(request.url);
+    const text = request.method === 'GET' ? '' : await request.text();
+    const s: Seen = {
+      method: request.method,
+      path: url.pathname,
+      search: url.searchParams,
+      body: text ? JSON.parse(text) : undefined,
+      auth: request.headers.get('Authorization'),
+    };
+    seen.push(s);
+    return reply(s);
+  }),
+);
+
+beforeAll(() => {
+  server.listen({ onUnhandledRequest: 'error' });
+  setApiBase(`${BASE}/api/v1`);
+});
+afterEach(() => {
+  server.resetHandlers();
+  setAuthTokenProvider(null);
+});
+afterAll(() => server.close());
+beforeEach(() => {
+  seen = [];
+  reply = () => HttpResponse.json({});
+});
+
+const api = () => createCommsApi(SLUG);
+const pathOf = (url: string) => new URL(url).pathname;
+const last = () => seen[seen.length - 1];
+
+describe('settings', () => {
+  it('GET settings/', async () => {
+    reply = () => HttpResponse.json(settings());
+    const r = await api().getSettings();
+    expect(last().method).toBe('GET');
+    expect(last().path).toBe(pathOf(`${P}/settings/`));
+    expect(r.approval_mode).toBe('approve');
+  });
+
+  it('PATCH settings/ sends only the changed fields', async () => {
+    reply = () => HttpResponse.json(settings({ approval_mode: 'auto' }));
+    const r = await api().updateSettings({ approval_mode: 'auto' });
+    expect(last().method).toBe('PATCH');
+    expect(last().path).toBe(pathOf(`${P}/settings/`));
+    expect(last().body).toEqual({ approval_mode: 'auto' });
+    expect(r.approval_mode).toBe('auto');
+  });
+
+  it('POST settings/domain/ with {domain}', async () => {
+    reply = () => HttpResponse.json(settings({ sending_domain: 'crochets.site', domain_status: 'pending' }));
+    const r = await api().connectDomain('crochets.site');
+    expect(last().method).toBe('POST');
+    expect(last().path).toBe(pathOf(`${P}/settings/domain/`));
+    expect(last().body).toEqual({ domain: 'crochets.site' });
+    expect(r.domain_status).toBe('pending');
+  });
+
+  it('POST settings/domain/check/', async () => {
+    reply = () => HttpResponse.json(settings({ domain_status: 'verified' }));
+    const r = await api().checkDomain();
+    expect(last().method).toBe('POST');
+    expect(last().path).toBe(pathOf(`${P}/settings/domain/check/`));
+    expect(r.domain_status).toBe('verified');
+  });
+});
+
+describe('programs', () => {
+  it('GET programs/', async () => {
+    reply = () => HttpResponse.json([comeback(), productUpdate()]);
+    const r = await api().listPrograms();
+    expect(last().path).toBe(pathOf(`${P}/programs/`));
+    expect(r.map((p) => p.key)).toEqual(['comeback', 'product_update']);
+  });
+
+  it('GET programs/{key}/', async () => {
+    reply = () => HttpResponse.json(comeback());
+    const r = await api().getProgram('comeback');
+    expect(last().path).toBe(pathOf(`${P}/programs/comeback/`));
+    expect(r.kind).toBe('sequence');
+  });
+
+  it('PATCH programs/{key}/ with {enabled:false}', async () => {
+    reply = () => HttpResponse.json(comeback({ enabled: false }));
+    const r = await api().updateProgram('comeback', { enabled: false });
+    expect(last().method).toBe('PATCH');
+    expect(last().path).toBe(pathOf(`${P}/programs/comeback/`));
+    expect(last().body).toEqual({ enabled: false });
+    expect(r.enabled).toBe(false);
+  });
+
+  // Shipped contract (AI lane): generation runs on a worker. POST answers 202
+  // with a status, not the program; GET on the same route is the poll.
+  it('POST programs/{key}/steps/{i}/generate/ with instructions -> 202 status', async () => {
+    reply = () => HttpResponse.json(generation(), { status: 202 });
+    const r = await api().generateStep('comeback', 2, { instructions: 'mention the new stitch counter' });
+    expect(last().method).toBe('POST');
+    expect(last().path).toBe(pathOf(`${P}/programs/comeback/steps/2/generate/`));
+    expect(last().body).toEqual({ instructions: 'mention the new stitch counter' });
+    expect(r.status).toBe('pending');
+  });
+
+  it('GET programs/{key}/steps/{i}/generate/ polls the generation status', async () => {
+    reply = () => HttpResponse.json(generation({ status: 'failed', error: 'model timed out' }));
+    const r = await api().getStepGeneration('comeback', 2);
+    expect(last().method).toBe('GET');
+    expect(last().path).toBe(pathOf(`${P}/programs/comeback/steps/2/generate/`));
+    expect(r).toMatchObject({ status: 'failed', error: 'model timed out' });
+  });
+
+  it('PATCH enabled:false passes the cancelled count through', async () => {
+    reply = () => HttpResponse.json({ ...comeback({ enabled: false }), cancelled: 12 });
+    const r = await api().updateProgram('comeback', { enabled: false });
+    expect(r.cancelled).toBe(12);
+  });
+
+  it('POST programs/{key}/steps/{i}/approve/', async () => {
+    reply = () => HttpResponse.json(comeback());
+    await api().approveStep('comeback', 1);
+    expect(last().method).toBe('POST');
+    expect(last().path).toBe(pathOf(`${P}/programs/comeback/steps/1/approve/`));
+  });
+
+  it('GET programs/{key}/steps/{i}/preview/', async () => {
+    reply = () => HttpResponse.json({ subject: 'S', preheader: 'PH', html: '<p>Hi Quinn</p>', text: 'Hi Quinn' });
+    const r = await api().previewStep('comeback', 0);
+    expect(last().method).toBe('GET');
+    expect(last().path).toBe(pathOf(`${P}/programs/comeback/steps/0/preview/`));
+    expect(r.html).toBe('<p>Hi Quinn</p>');
+  });
+});
+
+describe('test send', () => {
+  it('POST test-send/ for a sequence step', async () => {
+    reply = () => HttpResponse.json({ sent: true });
+    const r = await api().sendTest({ program_key: 'comeback', step_index: 1 });
+    expect(last().method).toBe('POST');
+    expect(last().path).toBe(pathOf(`${P}/test-send/`));
+    expect(last().body).toEqual({ program_key: 'comeback', step_index: 1 });
+    expect(r.sent).toBe(true);
+  });
+
+  it('POST test-send/ for a draft', async () => {
+    reply = () => HttpResponse.json({ sent: false, reason: 'not_allowlisted' });
+    const r = await api().sendTest({ draft_id: 'd-1' });
+    expect(last().body).toEqual({ draft_id: 'd-1' });
+    expect(r).toEqual({ sent: false, reason: 'not_allowlisted' });
+  });
+});
+
+describe('product updates', () => {
+  it('GET changes/?since=&until=', async () => {
+    reply = () => HttpResponse.json({ items: [], window: ['a', 'b'] });
+    await api().listChanges({ since: '2026-10-01T00:00:00Z', until: '2026-10-15T00:00:00Z' });
+    expect(last().path).toBe(pathOf(`${P}/changes/`));
+    expect(last().search.get('since')).toBe('2026-10-01T00:00:00Z');
+    expect(last().search.get('until')).toBe('2026-10-15T00:00:00Z');
+  });
+
+  it('GET drafts/ with status, page and page_size', async () => {
+    reply = () => HttpResponse.json({ count: 1, next: null, previous: null, results: [draft()] });
+    const r = await api().listDrafts({ status: 'pending', page: 2, page_size: 10 });
+    expect(last().path).toBe(pathOf(`${P}/drafts/`));
+    expect(last().search.get('status')).toBe('pending');
+    expect(last().search.get('page')).toBe('2');
+    expect(last().search.get('page_size')).toBe('10');
+    expect(r.results[0].id).toBe('d-1');
+  });
+
+  it('GET drafts/{id}/', async () => {
+    reply = () => HttpResponse.json(draft());
+    await api().getDraft('d-1');
+    expect(last().path).toBe(pathOf(`${P}/drafts/d-1/`));
+  });
+
+  it('PATCH drafts/{id}/ with the edited fields', async () => {
+    reply = () => HttpResponse.json(draft({ subject: 'Edited' }));
+    const r = await api().updateDraft('d-1', { subject: 'Edited' });
+    expect(last().method).toBe('PATCH');
+    expect(last().path).toBe(pathOf(`${P}/drafts/d-1/`));
+    expect(last().body).toEqual({ subject: 'Edited' });
+    expect(r.subject).toBe('Edited');
+  });
+
+  it('POST drafts/{id}/approve/ and drafts/{id}/discard/', async () => {
+    reply = (s) => HttpResponse.json(draft({ approval: s.path.endsWith('approve/') ? 'approved' : 'discarded' }));
+    const a = await api().approveDraft('d-1');
+    expect(last().method).toBe('POST');
+    expect(last().path).toBe(pathOf(`${P}/drafts/d-1/approve/`));
+    expect(a.approval).toBe('approved');
+    const d = await api().discardDraft('d-1');
+    expect(last().path).toBe(pathOf(`${P}/drafts/d-1/discard/`));
+    expect(d.approval).toBe('discarded');
+  });
+
+  it('GET drafts/{id}/preview/ is the server-rendered draft', async () => {
+    reply = () => HttpResponse.json({ subject: 'S', preheader: 'PH', html: '<p>Hi Quinn</p>', text: 'Hi' });
+    const r = await api().previewDraft('d-1');
+    expect(last().method).toBe('GET');
+    expect(last().path).toBe(pathOf(`${P}/drafts/d-1/preview/`));
+    expect(r.html).toBe('<p>Hi Quinn</p>');
+  });
+
+  // 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 });
+    const r = await api().sendUpdateNow({ notes: 'We launched the stitch counter' });
+    expect(last().method).toBe('POST');
+    expect(last().path).toBe(pathOf(`${P}/programs/product_update/send-now/`));
+    expect(last().body).toEqual({ notes: 'We launched the stitch counter' });
+    expect(r.draft?.id).toBe('d-1');
+    expect(r.draft?.generating).toBe(true);
+  });
+
+  it('send-now passes "nothing customer-facing" through as data, not an error', async () => {
+    reply = () => HttpResponse.json({ draft: null, reason: 'nothing_customer_facing' });
+    const r = await api().sendUpdateNow();
+    expect(r).toEqual({ draft: null, reason: 'nothing_customer_facing' });
+  });
+});
+
+describe('results', () => {
+  it('GET sends/ sends page, page_size and filters to the SERVER', async () => {
+    reply = () => HttpResponse.json({ count: 120, next: `${P}/sends/?page=3`, previous: `${P}/sends/?page=1`, results: sendRows(25, 25) });
+    const r = await api().listSends({ program: 'comeback', status: 'bounced', page: 2, page_size: 25 });
+    expect(last().path).toBe(pathOf(`${P}/sends/`));
+    expect(last().search.get('page')).toBe('2');
+    expect(last().search.get('page_size')).toBe('25');
+    expect(last().search.get('program')).toBe('comeback');
+    expect(last().search.get('status')).toBe('bounced');
+    expect(r.count).toBe(120);
+    expect(r.results).toHaveLength(25);
+  });
+
+  it('GET sends/?campaign= narrows to one product-update campaign', async () => {
+    reply = () => HttpResponse.json({ count: 0, next: null, previous: null, results: [] });
+    await api().listSends({ campaign: 'd-1', page: 1, page_size: 25 });
+    expect(last().search.get('campaign')).toBe('d-1');
+  });
+
+  it('GET metrics/?program=&from=&to=', async () => {
+    reply = () => HttpResponse.json(metrics());
+    const r = await api().getMetrics({ program: 'comeback', from: '2026-10-01', to: '2026-10-15' });
+    expect(last().path).toBe(pathOf(`${P}/metrics/`));
+    expect(last().search.get('program')).toBe('comeback');
+    expect(last().search.get('from')).toBe('2026-10-01');
+    expect(last().search.get('to')).toBe('2026-10-15');
+    expect(r.came_back).toBe(11);
+  });
+});
+
+describe('transport', () => {
+  it('binds to the slug it was created with, URL-encoded', async () => {
+    reply = () => HttpResponse.json(settings());
+    await createCommsApi('a b').getSettings();
+    expect(last().path).toBe('/api/v1/foundry/tenants/a%20b/comms/settings/');
+  });
+
+  it('attaches the bearer from the wired token provider', async () => {
+    setAuthTokenProvider(() => 'tok-123');
+    reply = () => HttpResponse.json(settings());
+    await api().getSettings();
+    expect(last().auth).toBe('Bearer tok-123');
+  });
+
+  it('a 403 (not a foundry admin) is a CommsApiError carrying the status', async () => {
+    reply = () => HttpResponse.json({ detail: 'You do not have permission to perform this action.' }, { status: 403 });
+    const err = await api().getSettings().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CommsApiError);
+    expect((err as CommsApiError).status).toBe(403);
+    expect((err as CommsApiError).message).toMatch(/permission/);
+  });
+
+  it('a DRF field error reads as a sentence, not "HTTP 400"', async () => {
+    reply = () => HttpResponse.json({ config: { 'steps[1].offset_days': 'whole days >= 0, not before the previous step' } }, { status: 400 });
+    const err = await api().updateProgram('comeback', { enabled: true }).catch((e: unknown) => e);
+    expect((err as CommsApiError).message).toBe('steps[1].offset_days: whole days >= 0, not before the previous step');
+  });
+
+  it('a refused test send (503) carries its reason', async () => {
+    reply = () => HttpResponse.json({ sent: false, reason: 'marketing email is not configured' }, { status: 503 });
+    const err = await api().sendTest({ draft_id: 'd-1' }).catch((e: unknown) => e);
+    expect((err as CommsApiError).status).toBe(503);
+    expect((err as CommsApiError).message).toMatch(/not configured/);
+  });
+
+  it("another foundry's slug is a 404 CommsApiError, not an empty settings object", async () => {
+    reply = () => HttpResponse.json({ detail: 'Not found.' }, { status: 404 });
+    const err = await api().getSettings().catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(CommsApiError);
+    expect((err as CommsApiError).status).toBe(404);
+  });
+});