@startsimpli/integrations 0.2.35 → 0.2.37

package/src/comms/components/SequenceSettings.tsx

@@ -0,0 +1,280 @@
+/**
+ * Comeback sequence settings (A2): inactivity threshold, the steps (day +
+ * content status), and per step: Edit, Preview, Send test to me, Write with AI,
+ * Approve.
+ *
+ * Config is REPLACED whole by the server (trigger + steps are validated
+ * together), so every save sends the full config with only the edited part
+ * changed. content_status is server-owned: an edited step goes back to draft.
+ *
+ * Write with AI is asynchronous: POST answers 202, then the step's generation
+ * status is polled until done (the programs list is refetched) or failed.
+ */
+import { useState, type ReactElement } from 'react';
+import { Button, Input, Label, Textarea } from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import {
+  DEFAULT_POLL_MS,
+  useApproveStep,
+  useGenerateStep,
+  usePrograms,
+  useSendTest,
+  useStepGeneration,
+  useStepPreview,
+  useUpdateProgram,
+} from '../hooks/index';
+import {
+  COMEBACK_PROGRAM_KEY,
+  type ContentStatus,
+  type SequenceProgram,
+  type SequenceStep,
+} from '../types/index';
+import { EmailPreview } from './EmailPreview';
+import { ErrorNotice, Note, humanize, useFieldId } from './_shared';
+
+export interface SequenceSettingsProps {
+  api: CommsApi;
+  /** Program key; the comeback preset by default. */
+  programKey?: string;
+  /** How often to re-ask about a step being written. */
+  pollIntervalMs?: number;
+}
+
+const STATUS_LABEL: Record<ContentStatus, string> = {
+  approved: 'Approved',
+  draft: 'Draft',
+  empty: 'Not written',
+};
+
+function stepStatus(step: SequenceStep): ContentStatus {
+  if (!step.content) return 'empty';
+  return step.content_status === 'approved' ? 'approved' : 'draft';
+}
+
+function intentLabel(intent: string): string {
+  const s = humanize(intent || '');
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : '';
+}
+
+function Threshold({ api, program }: { api: CommsApi; program: SequenceProgram }) {
+  const update = useUpdateProgram(api);
+  const id = useFieldId('comms-threshold');
+  const trigger = program.config.trigger;
+  const [days, setDays] = useState<string>(trigger?.type === 'inactive' ? String(trigger.days) : '');
+  const [saved, setSaved] = useState(false);
+  if (trigger?.type !== 'inactive') return null;
+
+  return (
+    <form
+      className="flex flex-wrap items-end gap-2"
+      onSubmit={(e) => {
+        e.preventDefault();
+        setSaved(false);
+        update.mutate(
+          { key: program.key, patch: { config: { ...program.config, trigger: { ...trigger, days: Number(days) } } } },
+          { onSuccess: () => setSaved(true) },
+        );
+      }}
+    >
+      <div className="space-y-1">
+        <Label htmlFor={id}>Days without logging in</Label>
+        <Input
+          id={id}
+          type="number"
+          min={1}
+          className="w-28"
+          value={days}
+          onChange={(e) => {
+            setSaved(false);
+            setDays(e.target.value);
+          }}
+        />
+      </div>
+      <Button type="submit" disabled={update.isPending || !(Number(days) >= 1)}>Save</Button>
+      {saved ? <Note>Saved.</Note> : null}
+      <div className="basis-full">
+        <ErrorNotice error={update.error} />
+      </div>
+    </form>
+  );
+}
+
+function StepEditor({
+  api,
+  program,
+  index,
+  onDone,
+}: {
+  api: CommsApi;
+  program: SequenceProgram;
+  index: number;
+  onDone: () => void;
+}) {
+  const update = useUpdateProgram(api);
+  const prefix = useFieldId(`comms-step-${index}`);
+  const step = program.config.steps[index];
+  const [day, setDay] = useState(String(step.offset_days));
+  const [c, setC] = useState(step.content ?? null);
+
+  const save = () => {
+    const steps = program.config.steps.map((s, i) =>
+      i === index ? { ...s, offset_days: Number(day), ...(c ? { content: c } : {}) } : s,
+    );
+    update.mutate({ key: program.key, patch: { config: { ...program.config, steps } } }, { onSuccess: onDone });
+  };
+
+  const field = (key: 'subject' | 'preheader', label: string) => (
+    <div className="space-y-1">
+      <Label htmlFor={`${prefix}-${key}`}>{label}</Label>
+      <Input id={`${prefix}-${key}`} value={c?.[key] ?? ''} onChange={(e) => c && setC({ ...c, [key]: e.target.value })} />
+    </div>
+  );
+  const area = (key: 'html' | 'text', label: string) => (
+    <div className="space-y-1">
+      <Label htmlFor={`${prefix}-${key}`}>{label}</Label>
+      <Textarea
+        id={`${prefix}-${key}`}
+        rows={key === 'html' ? 8 : 5}
+        className="font-mono text-xs"
+        value={c?.[key] ?? ''}
+        onChange={(e) => c && setC({ ...c, [key]: e.target.value })}
+      />
+    </div>
+  );
+
+  return (
+    <form
+      className="mt-2 space-y-3 rounded-md border p-3"
+      onSubmit={(e) => {
+        e.preventDefault();
+        save();
+      }}
+    >
+      <div className="space-y-1">
+        <Label htmlFor={`${prefix}-day`}>Day</Label>
+        <Input id={`${prefix}-day`} type="number" min={0} className="w-28" value={day} onChange={(e) => setDay(e.target.value)} />
+      </div>
+      {c ? (
+        <>
+          {field('subject', 'Subject')}
+          {field('preheader', 'Preheader')}
+          {area('html', 'Body (HTML)')}
+          {area('text', 'Plain text')}
+        </>
+      ) : (
+        <Note>This step has no copy yet. Use Write with AI to draft it.</Note>
+      )}
+      <div className="flex gap-2">
+        <Button type="submit" disabled={update.isPending}>Save step</Button>
+        <Button type="button" variant="ghost" onClick={onDone}>Cancel</Button>
+      </div>
+      <ErrorNotice error={update.error} />
+    </form>
+  );
+}
+
+function StepRow({
+  api,
+  program,
+  index,
+  pollIntervalMs,
+}: {
+  api: CommsApi;
+  program: SequenceProgram;
+  index: number;
+  pollIntervalMs: number;
+}) {
+  const step = program.config.steps[index];
+  const status = stepStatus(step);
+  const [editing, setEditing] = useState(false);
+  const [previewing, setPreviewing] = useState(false);
+  const [watching, setWatching] = useState(false);
+  const preview = useStepPreview(api, program.key, index, previewing && status !== 'empty');
+  const sendTest = useSendTest(api);
+  const generate = useGenerateStep(api);
+  const generation = useStepGeneration(api, program.key, index, watching, pollIntervalMs);
+  const approve = useApproveStep(api);
+
+  const writing = generate.isPending || (watching && generation.data?.status === 'pending');
+  const failed = watching && generation.data?.status === 'failed' ? generation.data.error || 'Writing this email failed.' : null;
+
+  return (
+    <li className="py-3">
+      <div className="flex flex-wrap items-center gap-x-4 gap-y-2">
+        <span className="w-16 font-medium">Day {step.offset_days}</span>
+        <span className="min-w-[10rem] flex-1">
+          {step.content?.subject || intentLabel(step.intent)}
+        </span>
+        <span className="text-sm text-muted-foreground">{writing ? 'Writing…' : STATUS_LABEL[status]}</span>
+        <div className="flex flex-wrap gap-2">
+          <Button type="button" size="sm" variant="outline" onClick={() => setEditing((v) => !v)}>Edit</Button>
+          {status !== 'empty' ? (
+            <>
+              <Button type="button" size="sm" variant="outline" onClick={() => setPreviewing((v) => !v)}>Preview</Button>
+              <Button
+                type="button"
+                size="sm"
+                variant="outline"
+                disabled={sendTest.isPending}
+                onClick={() => sendTest.mutate({ program_key: program.key, step_index: index })}
+              >
+                Send test to me
+              </Button>
+            </>
+          ) : null}
+          <Button
+            type="button"
+            size="sm"
+            variant="outline"
+            disabled={writing}
+            onClick={() => {
+              setWatching(false);
+              generate.mutate({ key: program.key, step: index }, { onSuccess: () => setWatching(true) });
+            }}
+          >
+            Write with AI
+          </Button>
+          {status === 'draft' && !writing ? (
+            <Button
+              type="button"
+              size="sm"
+              disabled={approve.isPending}
+              onClick={() => approve.mutate({ key: program.key, step: index })}
+            >
+              Approve
+            </Button>
+          ) : null}
+        </div>
+      </div>
+      {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 ?? generate.error ?? approve.error ?? preview.error ?? (failed ? new Error(failed) : null)} />
+      {editing ? <StepEditor api={api} program={program} index={index} onDone={() => setEditing(false)} /> : null}
+      {previewing && preview.data ? <EmailPreview email={preview.data} /> : null}
+    </li>
+  );
+}
+
+export function SequenceSettings({
+  api,
+  programKey = COMEBACK_PROGRAM_KEY,
+  pollIntervalMs = DEFAULT_POLL_MS,
+}: SequenceSettingsProps): ReactElement | null {
+  const { data: programs } = usePrograms(api);
+  const program = programs?.find((p) => p.key === programKey);
+  if (!program || program.kind !== 'sequence') return null;
+  const steps = program.config.steps ?? [];
+  return (
+    <div className="space-y-4">
+      <Threshold api={api} program={program} />
+      <ol className="divide-y">
+        {steps.map((_, i) => (
+          <StepRow key={i} api={api} program={program} index={i} pollIntervalMs={pollIntervalMs} />
+        ))}
+      </ol>
+    </div>
+  );
+}

package/src/comms/components/VoiceSettings.tsx

@@ -0,0 +1,84 @@
+/**
+ * The foundry voice the AI copy follows (A5): product one-liner, tone,
+ * audience, CTA link, words to avoid. `voice` is replaced whole server-side, so
+ * Save sends every field (keys this form does not know are kept).
+ */
+import { useState, type ReactElement } from 'react';
+import { Button, Input, Label } from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import { useCommsSettings, useUpdateCommsSettings } from '../hooks/index';
+import type { CommsVoice } from '../types/index';
+import { ErrorNotice, Note, useFieldId } from './_shared';
+
+export interface VoiceSettingsProps {
+  api: CommsApi;
+}
+
+type Fields = Omit<CommsVoice, 'avoid_words'> & { avoid_words: string };
+
+const FIELDS: { key: keyof Fields; label: string; placeholder: string }[] = [
+  { key: 'product', label: 'Product', placeholder: 'What the product does, in one line' },
+  { key: 'tone', label: 'Tone', placeholder: 'e.g. warm, plain' },
+  { key: 'audience', label: 'Audience', placeholder: 'Who the customers are' },
+  { key: 'cta_url', label: 'Call-to-action link', placeholder: 'https://' },
+  { key: 'avoid_words', label: 'Words to avoid', placeholder: 'Comma separated' },
+];
+
+function VoiceForm({ api, voice }: { api: CommsApi; voice: Partial<CommsVoice> }) {
+  const update = useUpdateCommsSettings(api);
+  const prefix = useFieldId('comms-voice');
+  const [saved, setSaved] = useState(false);
+  const [f, setF] = useState<Fields>({
+    product: voice.product ?? '',
+    tone: voice.tone ?? '',
+    audience: voice.audience ?? '',
+    cta_url: voice.cta_url ?? '',
+    avoid_words: (voice.avoid_words ?? []).join(', '),
+  });
+
+  const save = () => {
+    setSaved(false);
+    const avoid_words = f.avoid_words.split(',').map((w) => w.trim()).filter(Boolean);
+    update.mutate(
+      { voice: { ...(voice as CommsVoice), ...f, avoid_words } },
+      { onSuccess: () => setSaved(true) },
+    );
+  };
+
+  return (
+    <form
+      className="space-y-3"
+      onSubmit={(e) => {
+        e.preventDefault();
+        save();
+      }}
+    >
+      {FIELDS.map(({ key, label, placeholder }) => (
+        <div key={key} className="space-y-1">
+          <Label htmlFor={`${prefix}-${key}`}>{label}</Label>
+          <Input
+            id={`${prefix}-${key}`}
+            value={f[key]}
+            placeholder={placeholder}
+            onChange={(e) => {
+              setSaved(false);
+              setF({ ...f, [key]: e.target.value });
+            }}
+          />
+        </div>
+      ))}
+      <div className="flex items-center gap-3">
+        <Button type="submit" disabled={update.isPending}>Save voice</Button>
+        {saved ? <Note>Saved.</Note> : null}
+      </div>
+      <ErrorNotice error={update.error} />
+    </form>
+  );
+}
+
+export function VoiceSettings({ api }: VoiceSettingsProps): ReactElement | null {
+  const { data: settings } = useCommsSettings(api);
+  if (!settings) return null;
+  return <VoiceForm api={api} voice={settings.voice ?? {}} />;
+}

package/src/comms/components/_shared.tsx

@@ -0,0 +1,55 @@
+/**
+ * Small pieces every comms fold uses. Package-private (not exported).
+ */
+import * as React from 'react';
+import { Alert } from '@startsimpli/ui';
+
+/** A failed request as a role=alert carrying the server's own reason. */
+export function ErrorNotice({ error }: { error: unknown }) {
+  if (!error) return null;
+  const message = error instanceof Error ? error.message : String(error);
+  return (
+    <Alert variant="destructive" className="py-2 text-sm">
+      {message}
+    </Alert>
+  );
+}
+
+/** A quiet one-line status message (not an alert). */
+export function Note({ children }: { children: React.ReactNode }) {
+  return <p className="text-sm text-muted-foreground">{children}</p>;
+}
+
+/** Native <select>, styled like the package inputs. */
+export function NativeSelect(props: React.SelectHTMLAttributes<HTMLSelectElement>) {
+  const { className, ...rest } = props;
+  return (
+    <select
+      {...rest}
+      className={
+        'h-9 rounded-md border border-input bg-background px-2 text-sm shadow-sm focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring ' +
+        (className ?? '')
+      }
+    />
+  );
+}
+
+export function formatDate(iso: string | null | undefined): string {
+  if (!iso) return '';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '';
+  return d.toLocaleDateString(undefined, { day: 'numeric', month: 'short', year: 'numeric' });
+}
+
+/** A readable reason code: "not_allowlisted" -> "not allowlisted". */
+export function humanize(code: string): string {
+  return code.replace(/_/g, ' ');
+}
+
+let seq = 0;
+/** Stable unique id for label/control pairs (React 18+ useId, with a fallback). */
+export function useFieldId(prefix: string): string {
+  const id = (React as { useId?: () => string }).useId?.();
+  const [fallback] = React.useState(() => `${prefix}-${++seq}`);
+  return id ? `${prefix}-${id.replace(/:/g, '')}` : fallback;
+}

package/src/comms/components/index.ts

@@ -0,0 +1,11 @@
+export * from './pages/CustomerEmailsPage';
+export * from './ProgramToggles';
+export * from './SequenceSettings';
+export * from './EmailPreview';
+export * from './ApprovalModeSetting';
+export * from './VoiceSettings';
+export * from './SendingDomain';
+export * from './ProductUpdates';
+export * from './DraftReview';
+export * from './ResultsPanel';
+export * from './SendLog';

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

@@ -0,0 +1,112 @@
+/**
+ * CUSTOMER EMAILS: the whole per-foundry comms screen, as one composer
+ * (lane startsim-r7hws; persona A screens A1-A8 in startsim-lzfsd).
+ *
+ * `<CustomerEmailsPage api={createCommsApi(slug)} foundrySlug={slug} />` is the
+ * entire integration; apps/foundry owns only the mount and the token wiring.
+ *
+ * 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
+ * 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
+ * renders that as a plain notice and no controls.
+ */
+import type { ReactElement, ReactNode } from 'react';
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@startsimpli/ui';
+
+import type { CommsApi } from '../../api/comms';
+import { DEFAULT_POLL_MS, useCommsSettings, usePrograms } from '../../hooks/index';
+import { CommsApiError } from '../../types/index';
+import { ApprovalModeSetting } from '../ApprovalModeSetting';
+import { ProductUpdates } from '../ProductUpdates';
+import { ProgramToggles } from '../ProgramToggles';
+import { ResultsPanel } from '../ResultsPanel';
+import { SendLog } from '../SendLog';
+import { SendingDomain } from '../SendingDomain';
+import { SequenceSettings } from '../SequenceSettings';
+import { VoiceSettings } from '../VoiceSettings';
+import { ErrorNotice, Note } from '../_shared';
+
+export interface CustomerEmailsPageProps {
+  api: CommsApi;
+  foundrySlug: string;
+  /** Rows per page in the send log (server-side). Default 25. */
+  sendLogPageSize?: number;
+  /** How often background work (AI writing) is re-checked. Default 2s. */
+  pollIntervalMs?: number;
+}
+
+function Fold({ value, title, children }: { value: string; title: string; children: ReactNode }) {
+  return (
+    <AccordionItem value={value}>
+      <AccordionTrigger className="text-base">{title}</AccordionTrigger>
+      <AccordionContent>{children}</AccordionContent>
+    </AccordionItem>
+  );
+}
+
+export function CustomerEmailsPage({
+  api,
+  foundrySlug,
+  sendLogPageSize = 25,
+  pollIntervalMs = DEFAULT_POLL_MS,
+}: CustomerEmailsPageProps): ReactElement {
+  const settings = useCommsSettings(api);
+  const programs = usePrograms(api);
+  const error = settings.error ?? programs.error;
+  const status = error instanceof CommsApiError ? error.status : 0;
+
+  let body: ReactNode;
+  if (status === 403) {
+    body = <ErrorNotice error={new Error('Only foundry admins can manage customer emails.')} />;
+  } else if (status === 401) {
+    // Not a permissions answer: the request carried no valid bearer, which is
+    // the host's token wiring (see apps/foundry customer-emails.tsx), not the user.
+    body = <ErrorNotice error={new Error('Your sign-in was not accepted for this page. Reload, or sign in again.')} />;
+  } else if (error) {
+    body = <ErrorNotice error={error} />;
+  } else if (!settings.data || !programs.data) {
+    body = <Note>Loading…</Note>;
+  } else {
+    const sender = settings.data.sender_name || foundrySlug;
+    body = (
+      <>
+        <Note>Emails your customers get from {sender}, written by AI from your voice settings.</Note>
+        <ProgramToggles api={api} />
+        <Accordion type="multiple" className="w-full">
+          <Fold value="sequence" title="Comeback sequence settings">
+            <SequenceSettings api={api} pollIntervalMs={pollIntervalMs} />
+          </Fold>
+          <Fold value="updates" title="Product updates">
+            <ProductUpdates api={api} pollIntervalMs={pollIntervalMs} />
+          </Fold>
+          <Fold value="approval" title="Approval">
+            <ApprovalModeSetting api={api} />
+          </Fold>
+          <Fold value="voice" title="Voice">
+            <VoiceSettings api={api} />
+          </Fold>
+          <Fold value="domain" title="Sending domain">
+            <SendingDomain api={api} />
+          </Fold>
+          <Fold value="results" title="Results">
+            <ResultsPanel api={api} />
+          </Fold>
+          <Fold value="log" title="Send log">
+            <SendLog api={api} pageSize={sendLogPageSize} />
+          </Fold>
+        </Accordion>
+      </>
+    );
+  }
+
+  return (
+    <section className="mx-auto w-full max-w-4xl space-y-4">
+      <h2 className="text-2xl font-semibold tracking-tight">Customer emails</h2>
+      {body}
+    </section>
+  );
+}