@startsimpli/integrations 0.2.35 → 0.2.37

package/src/comms/__tests__/fixtures.ts

@@ -0,0 +1,133 @@
+/**
+ * Wire fixtures shaped exactly like ADR startsim-bzcrj section 2. Shared by the
+ * client and page suites so both pin the same contract.
+ */
+import type {
+  StepGeneration,
+  CommsMetrics,
+  CommsSettings,
+  Draft,
+  BroadcastProgram,
+  SendRow,
+  SequenceProgram,
+} from '../types/index';
+
+export const BASE = 'https://api.test';
+export const SLUG = 'crochets';
+export const P = `${BASE}/api/v1/foundry/tenants/${SLUG}/comms`;
+
+export const settings = (over: Partial<CommsSettings> = {}): CommsSettings => ({
+  approval_mode: 'approve',
+  voice: {
+    product: 'AI crochet patterns from a photo',
+    tone: 'warm, plain',
+    audience: 'hobby crocheters',
+    cta_url: 'https://crochets.site/app',
+    avoid_words: ['synergy'],
+  },
+  sender_name: 'Crochets',
+  reply_to: '',
+  postal_address: '',
+  sending_domain: '',
+  domain_status: 'none',
+  domain_records: [],
+  domain_checked_at: null,
+  paused: false,
+  source_repos: [],
+  from_address: 'Crochets <crochets@mail.startsimpli.com>',
+  ...over,
+});
+
+export const comeback = (over: Partial<SequenceProgram> = {}): SequenceProgram => ({
+  key: 'comeback',
+  kind: 'sequence',
+  category: 'lifecycle',
+  enabled: true,
+  version: 3,
+  config: {
+    trigger: { type: 'inactive', days: 14 },
+    steps: [
+      {
+        offset_days: 0,
+        intent: 'nudge',
+        content: { subject: 'Your hook misses you', preheader: 'New patterns', html: '<p>Hi {{first_name}}</p>', text: 'Hi {{first_name}}' },
+        content_status: 'approved',
+        generated_at: '2026-10-10T00:00:00Z',
+      },
+      {
+        offset_days: 5,
+        intent: 'value_reminder',
+        content: { subject: 'Three patterns to try', preheader: '', html: '<p>Try these</p>', text: 'Try these' },
+        content_status: 'draft',
+        generated_at: '2026-10-10T00:00:00Z',
+      },
+      { offset_days: 10, intent: 'last_call', content: null, content_status: 'empty', generated_at: null },
+    ],
+    exit: ['active', 'unsubscribed'],
+    cooldown_days: 30,
+  },
+  ...over,
+});
+
+export const productUpdate = (over: Partial<BroadcastProgram> = {}): BroadcastProgram => ({
+  key: 'product_update',
+  kind: 'broadcast',
+  category: 'product_updates',
+  enabled: false,
+  version: 1,
+  config: { cadence: 'on_deploy', audience: 'all', active_days: 14 },
+  ...over,
+});
+
+export const draft = (over: Partial<Draft> = {}): Draft => ({
+  id: 'd-1',
+  program_key: 'product_update',
+  subject: 'New: stitch counter',
+  preheader: 'Count rows hands-free',
+  html: '<h1>Stitch counter</h1>',
+  text: 'Stitch counter',
+  approval: 'pending',
+  item_keys: ['gh:pr:qosha1/crochet#412'],
+  window: ['2026-10-01T00:00:00Z', '2026-10-15T00:00:00Z'],
+  created_at: '2026-10-15T09:00:00Z',
+  error: null,
+  generating: false,
+  ...over,
+});
+
+export const metrics = (over: Partial<CommsMetrics> = {}): CommsMetrics => ({
+  sent: 120,
+  delivered: 117,
+  opened: 61,
+  clicked: 19,
+  bounced: 3,
+  complained: 0,
+  unsubscribed: 2,
+  came_back: 11,
+  ...over,
+});
+
+export function sendRows(n: number, offset = 0): SendRow[] {
+  return Array.from({ length: n }, (_, i) => ({
+    id: `s-${offset + i + 1}`,
+    email: `customer${offset + i + 1}@example.com`,
+    program_key: 'comeback',
+    step_index: 0,
+    subject: 'Your hook misses you',
+    status: 'delivered',
+    sent_at: '2026-10-14T10:00:00Z',
+    opened_at: null,
+    clicked_at: null,
+    error: null,
+  }));
+}
+
+export const generation = (over: Partial<StepGeneration> = {}): StepGeneration => ({
+  step_index: 2,
+  status: 'pending',
+  error: '',
+  requested_at: '2026-10-16T10:00:00Z',
+  finished_at: null,
+  step: null,
+  ...over,
+});

package/src/comms/api/_fetch.ts

@@ -0,0 +1,103 @@
+/**
+ * The one HTTP door for @startsimpli/integrations/comms (ADR startsim-bzcrj
+ * section 4, L8).
+ *
+ * Same shape as the package root's `api/_fetch.ts`, but its own module state: base '/api/v1'
+ * (overridable via setApiBase), a module-level bearer provider the mounting app
+ * wires once (setAuthTokenProvider), JSON in/out, and NO key transform, so the
+ * snake_case wire types in ../types hold. Non-2xx becomes CommsApiError carrying
+ * the HTTP status, so the composer can tell "not an admin" (403) from an outage.
+ */
+import { CommsApiError, type CommsErrorPayload } from '../types/index';
+
+let _apiBase = '/api/v1';
+let _tokenProvider: (() => string | null | Promise<string | null>) | null = null;
+
+export function setApiBase(base: string): void {
+  _apiBase = base.replace(/\/$/, '');
+}
+
+export function getApiBase(): string {
+  return _apiBase;
+}
+
+export function setAuthTokenProvider(
+  provider: (() => string | null | Promise<string | null>) | null,
+): void {
+  _tokenProvider = provider;
+}
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+  body?: unknown;
+  query?: Record<string, string | number | boolean | undefined | null>;
+}
+
+export async function request<T>(path: string, opts: RequestOptions = {}): Promise<T> {
+  const { method = 'GET', body, query } = opts;
+  let url = `${_apiBase}${path.startsWith('/') ? path : '/' + path}`;
+  if (query) {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v === undefined || v === null || v === '') continue;
+      params.set(k, String(v));
+    }
+    const qs = params.toString();
+    if (qs) url += `?${qs}`;
+  }
+
+  const headers: Record<string, string> = { Accept: 'application/json' };
+  if (body !== undefined) headers['Content-Type'] = 'application/json';
+  if (_tokenProvider) {
+    try {
+      const token = await _tokenProvider();
+      if (token) headers.Authorization = `Bearer ${token}`;
+    } catch {
+      // Provider failure surfaces as Django's 401 below.
+    }
+  }
+
+  const resp = await fetch(url, {
+    method,
+    headers,
+    credentials: 'include',
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+
+  const contentType = resp.headers.get('Content-Type') || '';
+  let payload: unknown = null;
+  try {
+    payload = contentType.includes('application/json') ? await resp.json() : await resp.text();
+  } catch {
+    payload = null;
+  }
+
+  if (!resp.ok) {
+    const p: CommsErrorPayload = payload && typeof payload === 'object' ? (payload as CommsErrorPayload) : {};
+    throw new CommsApiError(errorMessage(p) || `HTTP ${resp.status}`, resp.status, p);
+  }
+  return payload as T;
+}
+
+/**
+ * One readable line from a DRF error body: `error` / `detail` / `reason`, else
+ * the field errors (`{"domain": ["..."]}`, `{"config": {"steps[1].offset_days": "..."}}`)
+ * flattened to "domain: ...; steps[1].offset_days: ...".
+ */
+export function errorMessage(payload: unknown): string {
+  if (!payload || typeof payload !== 'object') return '';
+  const p = payload as Record<string, unknown>;
+  for (const k of ['error', 'detail', 'reason']) {
+    if (typeof p[k] === 'string' && p[k]) return p[k] as string;
+  }
+  const parts: string[] = [];
+  const walk = (key: string, v: unknown) => {
+    if (typeof v === 'string') parts.push(key ? `${key}: ${v}` : v);
+    else if (Array.isArray(v)) v.forEach((x) => walk(key, x));
+    else if (v && typeof v === 'object') {
+      for (const [k, x] of Object.entries(v)) walk(key === 'config' || !key ? k : `${key}.${k}`, x);
+    }
+  };
+  walk('', p);
+  return parts.join('; ');
+}

package/src/comms/api/comms.ts

@@ -0,0 +1,120 @@
+/**
+ * CommsApi: the foundry comms admin routes (ADR startsim-bzcrj section 2),
+ * bound to ONE foundry by `createCommsApi(slug)`.
+ *
+ *   P = /foundry/tenants/{slug}/comms   (under the /api/v1 base)
+ *
+ * The composer takes a CommsApi as a prop, so tests and other hosts can hand
+ * it a stub; the real one goes through ./_fetch `request()`.
+ *
+ * Two routes are asynchronous on the server (model calls outlast a web worker):
+ * - steps/{i}/generate/: POST answers 202 with a StepGeneration; poll
+ *   getStepGeneration until status is done or failed.
+ * - programs/product_update/send-now/: 202 with a draft whose `generating` is
+ *   true; poll getDraft(id) until it is false.
+ */
+import type {
+  ChangesResponse,
+  CommsMetrics,
+  CommsProgram,
+  CommsSettings,
+  CommsSettingsPatch,
+  Draft,
+  DraftPatch,
+  DraftsQuery,
+  MetricsQuery,
+  Paginated,
+  ProgramPatch,
+  ProgramUpdateResult,
+  RenderedEmail,
+  SendNowResult,
+  SendRow,
+  SendsQuery,
+  StepGeneration,
+  TestSendInput,
+  TestSendResult,
+} from '../types/index';
+import { request } from './_fetch';
+
+export interface CommsApi {
+  /** The foundry this client is bound to. */
+  readonly slug: string;
+
+  // settings
+  getSettings(): Promise<CommsSettings>;
+  updateSettings(patch: CommsSettingsPatch): Promise<CommsSettings>;
+  connectDomain(domain: string): Promise<CommsSettings>;
+  checkDomain(): Promise<CommsSettings>;
+
+  // programs
+  listPrograms(): Promise<CommsProgram[]>;
+  getProgram(key: string): Promise<CommsProgram>;
+  updateProgram(key: string, patch: ProgramPatch): Promise<ProgramUpdateResult>;
+  /** Queues the model call (202). Poll getStepGeneration for the outcome. */
+  generateStep(key: string, stepIndex: number, input?: { instructions?: string }): Promise<StepGeneration>;
+  getStepGeneration(key: string, stepIndex: number): Promise<StepGeneration>;
+  approveStep(key: string, stepIndex: number): Promise<CommsProgram>;
+  previewStep(key: string, stepIndex: number): Promise<RenderedEmail>;
+
+  // test send (always and only to the requesting admin)
+  sendTest(input: TestSendInput): Promise<TestSendResult>;
+
+  // product updates
+  listChanges(query?: { since?: string; until?: string }): Promise<ChangesResponse>;
+  listDrafts(query?: DraftsQuery): Promise<Paginated<Draft>>;
+  getDraft(id: string): Promise<Draft>;
+  updateDraft(id: string, patch: DraftPatch): Promise<Draft>;
+  approveDraft(id: string): Promise<Draft>;
+  discardDraft(id: string): Promise<Draft>;
+  previewDraft(id: string): Promise<RenderedEmail>;
+  sendUpdateNow(input?: { notes?: string }): Promise<SendNowResult>;
+
+  // results
+  listSends(query?: SendsQuery): Promise<Paginated<SendRow>>;
+  getMetrics(query?: MetricsQuery): Promise<CommsMetrics>;
+}
+
+/** The path prefix for one foundry's comms routes, relative to the api base. */
+export function commsBasePath(slug: string): string {
+  return `/foundry/tenants/${encodeURIComponent(slug)}/comms`;
+}
+
+const seg = encodeURIComponent;
+
+export function createCommsApi(slug: string): CommsApi {
+  const P = commsBasePath(slug);
+  const step = (key: string, i: number, action: string) =>
+    `${P}/programs/${seg(key)}/steps/${i}/${action}/`;
+  const draftPath = (id: string, action = '') => `${P}/drafts/${seg(id)}/${action ? `${action}/` : ''}`;
+
+  return {
+    slug,
+    getSettings: () => request(`${P}/settings/`),
+    updateSettings: (patch) => request(`${P}/settings/`, { method: 'PATCH', body: patch }),
+    connectDomain: (domain) => request(`${P}/settings/domain/`, { method: 'POST', body: { domain } }),
+    checkDomain: () => request(`${P}/settings/domain/check/`, { method: 'POST' }),
+
+    listPrograms: () => request(`${P}/programs/`),
+    getProgram: (key) => request(`${P}/programs/${seg(key)}/`),
+    updateProgram: (key, patch) => request(`${P}/programs/${seg(key)}/`, { method: 'PATCH', body: patch }),
+    generateStep: (key, i, input = {}) => request(step(key, i, 'generate'), { method: 'POST', body: input }),
+    getStepGeneration: (key, i) => request(step(key, i, 'generate')),
+    approveStep: (key, i) => request(step(key, i, 'approve'), { method: 'POST' }),
+    previewStep: (key, i) => request(step(key, i, 'preview')),
+
+    sendTest: (input) => request(`${P}/test-send/`, { method: 'POST', body: input }),
+
+    listChanges: (query = {}) => request(`${P}/changes/`, { query: { ...query } }),
+    listDrafts: (query = {}) => request(`${P}/drafts/`, { query: { ...query } }),
+    getDraft: (id) => request(draftPath(id)),
+    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' }),
+    previewDraft: (id) => request(draftPath(id, 'preview')),
+    sendUpdateNow: (input = {}) =>
+      request(`${P}/programs/product_update/send-now/`, { method: 'POST', body: input }),
+
+    listSends: (query = {}) => request(`${P}/sends/`, { query: { ...query } }),
+    getMetrics: (query = {}) => request(`${P}/metrics/`, { query: { ...query } }),
+  };
+}

package/src/comms/api/index.ts

@@ -0,0 +1,2 @@
+export * from './comms';
+export { setApiBase, getApiBase, setAuthTokenProvider, request } from './_fetch';

package/src/comms/components/ApprovalModeSetting.tsx

@@ -0,0 +1,49 @@
+/**
+ * Per-foundry "send automatically" vs "I approve each email" (A4, decision
+ * 13o60=c). PATCH settings.approval_mode.
+ */
+import type { ReactElement } from 'react';
+
+import type { CommsApi } from '../api/comms';
+import { useCommsSettings, useUpdateCommsSettings } from '../hooks/index';
+import type { ApprovalMode } from '../types/index';
+import { ErrorNotice, useFieldId } from './_shared';
+
+export interface ApprovalModeSettingProps {
+  api: CommsApi;
+}
+
+const OPTIONS: { value: ApprovalMode; label: string; hint: string }[] = [
+  { value: 'auto', label: 'Send automatically', hint: 'AI-written emails go out without waiting for you.' },
+  { value: 'approve', label: 'I approve each email', hint: 'Nothing new goes out until you approve it.' },
+];
+
+export function ApprovalModeSetting({ api }: ApprovalModeSettingProps): ReactElement | null {
+  const { data: settings } = useCommsSettings(api);
+  const update = useUpdateCommsSettings(api);
+  const name = useFieldId('comms-approval');
+  if (!settings) return null;
+  return (
+    <fieldset className="space-y-2">
+      <legend className="sr-only">Approval</legend>
+      {OPTIONS.map((o) => (
+        <label key={o.value} className="flex items-start gap-2 text-sm">
+          <input
+            type="radio"
+            name={name}
+            value={o.value}
+            checked={settings.approval_mode === o.value}
+            disabled={update.isPending}
+            onChange={() => update.mutate({ approval_mode: o.value })}
+            className="mt-1"
+          />
+          <span>
+            <span className="font-medium">{o.label}</span>
+            <span className="block text-muted-foreground">{o.hint}</span>
+          </span>
+        </label>
+      ))}
+      <ErrorNotice error={update.error} />
+    </fieldset>
+  );
+}

package/src/comms/components/DraftReview.tsx

@@ -0,0 +1,162 @@
+/**
+ * Pending product-update drafts (A4): review, edit subject/preheader/body,
+ * preview (server-rendered, G2), send a test, approve or discard.
+ *
+ * A draft still being written shows only its state (the server refuses edits,
+ * previews and approval until it is). A draft whose generation failed can only
+ * be discarded; send-now again retries the same window.
+ */
+import { useState, type ReactElement } from 'react';
+import { Button, Input, Label, Textarea } from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import {
+  DEFAULT_POLL_MS,
+  useApproveDraft,
+  useDiscardDraft,
+  useDraftPreview,
+  useDrafts,
+  useSendTest,
+  useUpdateDraft,
+} from '../hooks/index';
+import type { Draft, DraftPatch } from '../types/index';
+import { EmailPreview } from './EmailPreview';
+import { ErrorNotice, Note, formatDate, humanize, useFieldId } from './_shared';
+
+export interface DraftReviewProps {
+  api: CommsApi;
+  pollIntervalMs?: number;
+  /** Drafts per server page. Default 10. */
+  pageSize?: number;
+}
+
+function DraftEditor({ api, draft, onDone }: { api: CommsApi; draft: Draft; onDone: () => void }) {
+  const update = useUpdateDraft(api);
+  const prefix = useFieldId(`comms-draft-${draft.id}`);
+  const [f, setF] = useState<Required<DraftPatch>>({
+    subject: draft.subject,
+    preheader: draft.preheader,
+    html: draft.html,
+    text: draft.text,
+  });
+  const changed = (Object.keys(f) as (keyof DraftPatch)[]).filter((k) => f[k] !== draft[k]);
+
+  return (
+    <form
+      className="mt-2 space-y-3 rounded-md border p-3"
+      onSubmit={(e) => {
+        e.preventDefault();
+        if (!changed.length) return onDone();
+        const patch = Object.fromEntries(changed.map((k) => [k, f[k]])) as DraftPatch;
+        update.mutate({ id: draft.id, patch }, { onSuccess: onDone });
+      }}
+    >
+      {(['subject', 'preheader'] as const).map((k) => (
+        <div key={k} className="space-y-1">
+          <Label htmlFor={`${prefix}-${k}`}>{k === 'subject' ? 'Subject' : 'Preheader'}</Label>
+          <Input id={`${prefix}-${k}`} value={f[k]} onChange={(e) => setF({ ...f, [k]: e.target.value })} />
+        </div>
+      ))}
+      {(['html', 'text'] as const).map((k) => (
+        <div key={k} className="space-y-1">
+          <Label htmlFor={`${prefix}-${k}`}>{k === 'html' ? 'Body (HTML)' : 'Plain text'}</Label>
+          <Textarea
+            id={`${prefix}-${k}`}
+            rows={k === 'html' ? 10 : 6}
+            className="font-mono text-xs"
+            value={f[k]}
+            onChange={(e) => setF({ ...f, [k]: e.target.value })}
+          />
+        </div>
+      ))}
+      <div className="flex gap-2">
+        <Button type="submit" disabled={update.isPending}>Save draft</Button>
+        <Button type="button" variant="ghost" onClick={onDone}>Cancel</Button>
+      </div>
+      <ErrorNotice error={update.error} />
+    </form>
+  );
+}
+
+function DraftItem({ api, draft }: { api: CommsApi; draft: Draft }) {
+  const [editing, setEditing] = useState(false);
+  const [previewing, setPreviewing] = useState(false);
+  const ready = !draft.generating && !draft.error;
+  const preview = useDraftPreview(api, draft.id, previewing && ready);
+  const sendTest = useSendTest(api);
+  const approve = useApproveDraft(api);
+  const discard = useDiscardDraft(api);
+
+  return (
+    <li className="py-3">
+      <div className="flex flex-wrap items-center gap-x-4 gap-y-2">
+        <span className="min-w-[10rem] flex-1 font-medium">
+          {draft.generating ? 'Writing this update…' : draft.subject || '(no subject)'}
+        </span>
+        <span className="text-sm text-muted-foreground">{formatDate(draft.created_at)}</span>
+        <div className="flex flex-wrap gap-2">
+          {ready ? (
+            <>
+              <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"
+                disabled={sendTest.isPending}
+                onClick={() => sendTest.mutate({ draft_id: draft.id })}
+              >
+                Send test to me
+              </Button>
+              <Button type="button" size="sm" disabled={approve.isPending} onClick={() => approve.mutate(draft.id)}>
+                Approve and send
+              </Button>
+            </>
+          ) : null}
+          {!draft.generating ? (
+            <Button type="button" size="sm" variant="ghost" disabled={discard.isPending} onClick={() => discard.mutate(draft.id)}>
+              Discard
+            </Button>
+          ) : null}
+        </div>
+      </div>
+      {draft.error ? <ErrorNotice error={new Error(`Writing this update failed: ${humanize(draft.error)}`)} /> : null}
+      {sendTest.data?.sent ? <Note>Test sent to you.</Note> : null}
+      {sendTest.data && !sendTest.data.sent ? (
+        <ErrorNotice error={new Error(`Test not sent: ${humanize(sendTest.data.reason || 'refused')}`)} />
+      ) : null}
+      <ErrorNotice error={sendTest.error ?? approve.error ?? discard.error ?? preview.error} />
+      {editing && ready ? <DraftEditor api={api} draft={draft} onDone={() => setEditing(false)} /> : null}
+      {previewing && preview.data ? <EmailPreview email={preview.data} /> : null}
+    </li>
+  );
+}
+
+export function DraftReview({ api, pollIntervalMs = DEFAULT_POLL_MS, pageSize = 10 }: DraftReviewProps): ReactElement | null {
+  const [page, setPage] = useState(1);
+  const drafts = useDrafts(api, { status: 'pending', page, page_size: pageSize }, pollIntervalMs);
+  if (drafts.error) return <ErrorNotice error={drafts.error} />;
+  if (!drafts.data) return null;
+  const { results, count } = drafts.data;
+  if (!results.length) return <Note>No updates are waiting for approval.</Note>;
+  return (
+    <div className="space-y-1">
+      <h3 className="text-sm font-medium">Waiting for approval</h3>
+      <ul className="divide-y">
+        {results.map((d) => (
+          <DraftItem key={d.id} api={api} draft={d} />
+        ))}
+      </ul>
+      {count > pageSize ? (
+        <div className="flex items-center gap-2 text-sm">
+          <Button type="button" size="sm" variant="outline" disabled={!drafts.data.previous} onClick={() => setPage(page - 1)}>
+            Previous
+          </Button>
+          <Button type="button" size="sm" variant="outline" disabled={!drafts.data.next} onClick={() => setPage(page + 1)}>
+            Next
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/comms/components/EmailPreview.tsx

@@ -0,0 +1,28 @@
+/**
+ * Renders a server-rendered email (subject, preheader, html) as the customer
+ * would see it: html inside a sandboxed <iframe srcDoc>, never injected into
+ * the admin page (email CSS would leak, and DOMPurify would strip it).
+ */
+import type { ReactElement } from 'react';
+import type { RenderedEmail } from '../types/index';
+
+export interface EmailPreviewProps {
+  email: RenderedEmail;
+  title?: string;
+}
+
+export function EmailPreview({ email, title = 'Email preview' }: EmailPreviewProps): ReactElement {
+  return (
+    <div className="mt-2 rounded-md border">
+      <div className="border-b px-3 py-2 text-sm">
+        <div>
+          <span className="text-muted-foreground">Subject: </span>
+          <span className="font-medium">{email.subject}</span>
+        </div>
+        {email.preheader ? <div className="text-muted-foreground">{email.preheader}</div> : null}
+      </div>
+      {/* sandbox="" : no scripts, no same-origin, no navigation of the admin page. */}
+      <iframe title={title} sandbox="" srcDoc={email.html} className="h-[480px] w-full bg-white" />
+    </div>
+  );
+}