@startsimpli/integrations 0.2.35 → 0.2.37

package/src/comms/components/ProductUpdates.tsx

@@ -0,0 +1,178 @@
+/**
+ * Product update emails (A3): cadence, audience, "Send an update now" with
+ * optional notes, plus the pending drafts (DraftReview).
+ *
+ * Send-now is asynchronous: a 202 hands back a placeholder draft still being
+ * written, which is polled (drafts/{id}/) until done. It can also end with
+ * nothing customer-facing (200 straight away, or a draft the worker discarded),
+ * or point at the update already waiting for approval.
+ */
+import { useCallback, useEffect, useState, type ReactElement } from 'react';
+import { Button, Label, Textarea } from '@startsimpli/ui';
+import { useQueryClient } from '@tanstack/react-query';
+
+import type { CommsApi } from '../api/comms';
+import { DEFAULT_POLL_MS, commsKeys, useDraft, usePrograms, useSendUpdateNow, useUpdateProgram } from '../hooks/index';
+import {
+  DRAFT_PENDING,
+  NOTHING_CUSTOMER_FACING,
+  PRODUCT_UPDATE_PROGRAM_KEY,
+  type BroadcastAudience,
+  type BroadcastCadence,
+  type BroadcastProgram,
+} from '../types/index';
+import { DraftReview } from './DraftReview';
+import { ErrorNotice, NativeSelect, Note, humanize, useFieldId } from './_shared';
+
+export interface ProductUpdatesProps {
+  api: CommsApi;
+  pollIntervalMs?: number;
+}
+
+const CADENCES: { value: BroadcastCadence; label: string }[] = [
+  { value: 'on_deploy', label: 'Each deploy with customer-facing changes' },
+  { value: 'weekly', label: 'Weekly' },
+  { value: 'monthly', label: 'Monthly' },
+  { value: 'manual', label: 'Only when I click Send an update now' },
+];
+
+const AUDIENCES: { value: BroadcastAudience; label: string }[] = [
+  { value: 'all', label: 'All customers' },
+  { value: 'active', label: 'Active customers' },
+  { value: 'inactive', label: 'Inactive customers' },
+];
+
+const NOTHING = 'Nothing customer-facing has changed since the last update, so there is nothing to send.';
+
+/** Follows one send-now draft until the worker has finished writing it. */
+function SendNowProgress({
+  api,
+  id,
+  pollIntervalMs,
+  onFinished,
+}: {
+  api: CommsApi;
+  id: string;
+  pollIntervalMs: number;
+  onFinished: (message: string | null, error: string | null) => void;
+}) {
+  const qc = useQueryClient();
+  const draft = useDraft(api, id, pollIntervalMs);
+  const d = draft.data;
+  useEffect(() => {
+    if (draft.error) {
+      onFinished(null, draft.error.message);
+      return;
+    }
+    if (!d || d.generating) return;
+    void qc.invalidateQueries({ queryKey: commsKeys.draftsAll(api.slug) });
+    if (d.error === NOTHING_CUSTOMER_FACING) onFinished(NOTHING, null);
+    else if (d.error) onFinished(null, `Writing this update failed: ${humanize(d.error)}`);
+    else onFinished(null, null);
+  }, [d, draft.error, qc, api.slug, onFinished]);
+  return <Note>Writing the update… this can take a few minutes.</Note>;
+}
+
+function Config({ api, program }: { api: CommsApi; program: BroadcastProgram }) {
+  const update = useUpdateProgram(api);
+  const cadenceId = useFieldId('comms-cadence');
+  const audienceId = useFieldId('comms-audience');
+  const set = (patch: Partial<BroadcastProgram['config']>) =>
+    update.mutate({ key: program.key, patch: { config: { ...program.config, ...patch } } });
+
+  return (
+    <div className="space-y-2">
+      <div className="flex flex-wrap gap-4">
+        <div className="space-y-1">
+          <Label htmlFor={cadenceId}>Cadence</Label>
+          <div>
+            <NativeSelect
+              id={cadenceId}
+              value={program.config.cadence}
+              disabled={update.isPending}
+              onChange={(e) => set({ cadence: e.target.value as BroadcastCadence })}
+            >
+              {CADENCES.map((c) => (
+                <option key={c.value} value={c.value}>{c.label}</option>
+              ))}
+            </NativeSelect>
+          </div>
+        </div>
+        <div className="space-y-1">
+          <Label htmlFor={audienceId}>Audience</Label>
+          <div>
+            <NativeSelect
+              id={audienceId}
+              value={program.config.audience}
+              disabled={update.isPending}
+              onChange={(e) => set({ audience: e.target.value as BroadcastAudience })}
+            >
+              {AUDIENCES.map((a) => (
+                <option key={a.value} value={a.value}>{a.label}</option>
+              ))}
+            </NativeSelect>
+          </div>
+        </div>
+      </div>
+      <ErrorNotice error={update.error} />
+    </div>
+  );
+}
+
+export function ProductUpdates({ api, pollIntervalMs = DEFAULT_POLL_MS }: ProductUpdatesProps): ReactElement | null {
+  const { data: programs } = usePrograms(api);
+  const sendNow = useSendUpdateNow(api);
+  const notesId = useFieldId('comms-notes');
+  const [notes, setNotes] = useState('');
+  const [message, setMessage] = useState<string | null>(null);
+  const [failure, setFailure] = useState<string | null>(null);
+  const [following, setFollowing] = useState<string | null>(null);
+  const program = programs?.find((p) => p.key === PRODUCT_UPDATE_PROGRAM_KEY);
+
+  const onFinished = useCallback((msg: string | null, err: string | null) => {
+    setFollowing(null);
+    setMessage(msg);
+    setFailure(err);
+  }, []);
+
+  return (
+    <div className="space-y-4">
+      {program && program.kind === 'broadcast' ? <Config api={api} program={program} /> : null}
+      <form
+        className="space-y-2"
+        onSubmit={(e) => {
+          e.preventDefault();
+          setMessage(null);
+          setFailure(null);
+          sendNow.mutate(notes.trim() ? { notes: notes.trim() } : {}, {
+            onSuccess: (res) => {
+              if (res.reason === NOTHING_CUSTOMER_FACING) setMessage(NOTHING);
+              else if (res.reason === DRAFT_PENDING) setMessage('An update is already waiting for your approval below.');
+              else if (res.draft?.generating) setFollowing(res.draft.id);
+              if (res.draft) setNotes('');
+            },
+          });
+        }}
+      >
+        <div className="space-y-1">
+          <Label htmlFor={notesId}>Notes for this update (optional)</Label>
+          <Textarea
+            id={notesId}
+            rows={2}
+            value={notes}
+            placeholder="Anything the changelog will not show, e.g. a launch you want to mention"
+            onChange={(e) => setNotes(e.target.value)}
+          />
+        </div>
+        <Button type="submit" disabled={sendNow.isPending || !!following}>Send an update now</Button>
+        <Note>Writes a draft from what changed since the last update. Nothing goes out until it is approved, unless approval is set to automatic.</Note>
+      </form>
+      {following ? (
+        <SendNowProgress api={api} id={following} pollIntervalMs={pollIntervalMs} onFinished={onFinished} />
+      ) : null}
+      {message ? <Note>{message}</Note> : null}
+      <ErrorNotice error={sendNow.error ?? (failure ? new Error(failure) : null)} />
+      <DraftReview api={api} pollIntervalMs={pollIntervalMs} />
+    </div>
+  );
+}

package/src/comms/components/ProgramToggles.tsx

@@ -0,0 +1,93 @@
+/**
+ * The two switches (A1, A8): "Comeback sequence" and "Product update emails".
+ * Turning one off PATCHes enabled:false; the server cancels pending steps in
+ * the same transaction (and says how many), and the page says nothing further
+ * will go out. A refused write leaves the switch where it was.
+ */
+import { useState, type ReactElement } from 'react';
+import { Label, Switch } from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import { usePrograms, useUpdateProgram } from '../hooks/index';
+import {
+  COMEBACK_PROGRAM_KEY,
+  PRODUCT_UPDATE_PROGRAM_KEY,
+  type CommsProgram,
+} from '../types/index';
+import { ErrorNotice, Note, useFieldId } from './_shared';
+
+export interface ProgramTogglesProps {
+  api: CommsApi;
+}
+
+function describe(p: CommsProgram): string {
+  if (p.kind === 'sequence') {
+    const t = p.config.trigger;
+    const when = t?.type === 'inactive' ? `have not logged in for ${t.days} days` : 'match the trigger';
+    return `Emails customers who ${when}. Stops when they come back.`;
+  }
+  return 'Tells customers what changed in the product.';
+}
+
+const LABELS: Record<string, string> = {
+  [COMEBACK_PROGRAM_KEY]: 'Comeback sequence',
+  [PRODUCT_UPDATE_PROGRAM_KEY]: 'Product update emails',
+};
+
+function Toggle({ api, program }: { api: CommsApi; program: CommsProgram }) {
+  const update = useUpdateProgram(api);
+  const [notice, setNotice] = useState<string | null>(null);
+  const id = useFieldId(`comms-switch-${program.key}`);
+  const label = LABELS[program.key] ?? program.key;
+
+  const onChange = (enabled: boolean) => {
+    setNotice(null);
+    update.mutate(
+      { key: program.key, patch: { enabled } },
+      {
+        onSuccess: (res) => {
+          if (enabled) return;
+          const n = res.cancelled ?? 0;
+          setNotice(
+            `${label} is off. Nothing further will be sent.` +
+              (n > 0 ? ` ${n} pending ${n === 1 ? 'email was' : 'emails were'} cancelled.` : ''),
+          );
+        },
+      },
+    );
+  };
+
+  return (
+    <div className="space-y-1 py-2">
+      <div className="flex items-start gap-3">
+        <Switch
+          id={id}
+          checked={program.enabled}
+          disabled={update.isPending}
+          onCheckedChange={onChange}
+        />
+        <div>
+          <Label htmlFor={id} className="font-medium">{label}</Label>
+          <Note>{describe(program)}</Note>
+        </div>
+      </div>
+      {notice ? <Note>{notice}</Note> : null}
+      <ErrorNotice error={update.error} />
+    </div>
+  );
+}
+
+export function ProgramToggles({ api }: ProgramTogglesProps): ReactElement | null {
+  const { data: programs } = usePrograms(api);
+  if (!programs) return null;
+  const shown = [COMEBACK_PROGRAM_KEY, PRODUCT_UPDATE_PROGRAM_KEY]
+    .map((k) => programs.find((p) => p.key === k))
+    .filter((p): p is CommsProgram => !!p);
+  return (
+    <div className="divide-y">
+      {shown.map((p) => (
+        <Toggle key={p.key} api={api} program={p} />
+      ))}
+    </div>
+  );
+}

package/src/comms/components/ResultsPanel.tsx

@@ -0,0 +1,50 @@
+/**
+ * Results (A7): sent, delivered, opened, clicked, came back, unsubscribed,
+ * bounced and complaints, over the server's default window (last 30 days).
+ *
+ * "Came back after an email" is attribution by timing: the customer logged in
+ * again while enrolled, after at least one email. It does not prove the email
+ * caused it, and the label says no more than that.
+ */
+import type { ReactElement } from 'react';
+
+import type { CommsApi } from '../api/comms';
+import { useCommsMetrics } from '../hooks/index';
+import type { CommsMetrics } from '../types/index';
+import { ErrorNotice, Note } from './_shared';
+
+export interface ResultsPanelProps {
+  api: CommsApi;
+  programKey?: string;
+}
+
+const ROWS: { key: keyof CommsMetrics; label: string }[] = [
+  { key: 'sent', label: 'Sent' },
+  { key: 'delivered', label: 'Delivered' },
+  { key: 'opened', label: 'Opened' },
+  { key: 'clicked', label: 'Clicked' },
+  { key: 'came_back', label: 'Came back after an email' },
+  { key: 'unsubscribed', label: 'Unsubscribed' },
+  { key: 'bounced', label: 'Bounced' },
+  { key: 'complained', label: 'Marked as spam' },
+];
+
+export function ResultsPanel({ api, programKey }: ResultsPanelProps): ReactElement | null {
+  const metrics = useCommsMetrics(api, programKey ? { program: programKey } : {});
+  if (metrics.error) return <ErrorNotice error={metrics.error} />;
+  if (!metrics.data) return null;
+  const m = metrics.data;
+  return (
+    <div className="space-y-2">
+      <dl className="grid grid-cols-2 gap-x-6 gap-y-1 text-sm sm:grid-cols-4">
+        {ROWS.map((r) => (
+          <div key={r.key} className="flex justify-between gap-2 sm:block">
+            <dt className="text-muted-foreground">{r.label}</dt>
+            <dd className="font-medium tabular-nums">{m[r.key]}</dd>
+          </div>
+        ))}
+      </dl>
+      <Note>Last 30 days. "Came back" counts customers who logged in again after an email; it does not prove the email brought them back.</Note>
+    </div>
+  );
+}

package/src/comms/components/SendLog.tsx

@@ -0,0 +1,118 @@
+/**
+ * Send log (A7): SERVER-SIDE pagination. page/page_size go to the server; the
+ * total shown is the server count, never a client-side slice. Changing a filter
+ * goes back to page 1.
+ */
+import { useState, type ReactElement } from 'react';
+import {
+  Button,
+  Label,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import { useSends } from '../hooks/index';
+import { COMEBACK_PROGRAM_KEY, PRODUCT_UPDATE_PROGRAM_KEY } from '../types/index';
+import { ErrorNotice, NativeSelect, formatDate, useFieldId } from './_shared';
+
+export interface SendLogProps {
+  api: CommsApi;
+  /** Rows per server page. Default 25; the server caps at 100. */
+  pageSize?: number;
+}
+
+const PROGRAMS: { value: string; label: string }[] = [
+  { value: '', label: 'All' },
+  { value: COMEBACK_PROGRAM_KEY, label: 'Comeback' },
+  { value: PRODUCT_UPDATE_PROGRAM_KEY, label: 'Product updates' },
+];
+
+const STATUSES = ['', 'pending', 'sent', 'delivered', 'opened', 'clicked', 'bounced', 'failed', 'suppressed', 'complained'];
+
+const programLabel = (key: string) => PROGRAMS.find((p) => p.value === key)?.label ?? key;
+
+export function SendLog({ api, pageSize = 25 }: SendLogProps): ReactElement {
+  const [page, setPage] = useState(1);
+  const [program, setProgram] = useState('');
+  const [status, setStatus] = useState('');
+  const programId = useFieldId('comms-log-program');
+  const statusId = useFieldId('comms-log-status');
+  const sends = useSends(api, { page, page_size: pageSize, program: program || undefined, status: status || undefined });
+  const data = sends.data;
+  const count = data?.count ?? 0;
+  const first = count ? (page - 1) * pageSize + 1 : 0;
+  const last = data ? first + data.results.length - (count ? 1 : 0) : 0;
+
+  return (
+    <div className="space-y-3">
+      <div className="flex flex-wrap gap-4">
+        <div className="space-y-1">
+          <Label htmlFor={programId}>Program</Label>
+          <div>
+            <NativeSelect id={programId} value={program} onChange={(e) => { setProgram(e.target.value); setPage(1); }}>
+              {PROGRAMS.map((p) => (
+                <option key={p.value} value={p.value}>{p.label}</option>
+              ))}
+            </NativeSelect>
+          </div>
+        </div>
+        <div className="space-y-1">
+          <Label htmlFor={statusId}>Status</Label>
+          <div>
+            <NativeSelect id={statusId} value={status} onChange={(e) => { setStatus(e.target.value); setPage(1); }}>
+              {STATUSES.map((s) => (
+                <option key={s} value={s}>{s ? s.charAt(0).toUpperCase() + s.slice(1) : 'All'}</option>
+              ))}
+            </NativeSelect>
+          </div>
+        </div>
+      </div>
+      <ErrorNotice error={sends.error} />
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Email</TableHead>
+            <TableHead>Program</TableHead>
+            <TableHead>Step</TableHead>
+            <TableHead>Subject</TableHead>
+            <TableHead>Status</TableHead>
+            <TableHead>Sent</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {data && data.results.length === 0 ? (
+            <TableRow>
+              <TableCell colSpan={6} className="text-muted-foreground">No emails sent yet.</TableCell>
+            </TableRow>
+          ) : null}
+          {data?.results.map((r) => (
+            <TableRow key={r.id}>
+              <TableCell>{r.email}</TableCell>
+              <TableCell>{programLabel(r.program_key)}</TableCell>
+              <TableCell>{r.step_index === null ? '' : r.step_index + 1}</TableCell>
+              <TableCell>{r.subject}</TableCell>
+              <TableCell title={r.error || undefined}>{r.status}</TableCell>
+              <TableCell>{formatDate(r.sent_at)}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      <div className="flex flex-wrap items-center justify-between gap-2 text-sm">
+        <span>{`${first}–${last} of ${count}`}</span>
+        <div className="flex gap-2">
+          <Button type="button" size="sm" variant="outline" disabled={!data?.previous || sends.isFetching} onClick={() => setPage(page - 1)}>
+            Previous
+          </Button>
+          <Button type="button" size="sm" variant="outline" disabled={!data?.next || sends.isFetching} onClick={() => setPage(page + 1)}>
+            Next page
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/comms/components/SendingDomain.tsx

@@ -0,0 +1,120 @@
+/**
+ * Sending domain (A6): connect, re-check, SPF/DKIM/DMARC records with their
+ * status, and the fallback-stream note while unverified. The From address in
+ * use comes from the server (settings.from_address).
+ */
+import { useState, type ReactElement } from 'react';
+import {
+  Badge,
+  Button,
+  Input,
+  Label,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@startsimpli/ui';
+
+import type { CommsApi } from '../api/comms';
+import { useCheckDomain, useCommsSettings, useConnectDomain } from '../hooks/index';
+import type { DomainRecord, DomainStatus } from '../types/index';
+import { ErrorNotice, Note, formatDate, useFieldId } from './_shared';
+
+export interface SendingDomainProps {
+  api: CommsApi;
+}
+
+const STATUS: Record<DomainStatus, string> = {
+  none: 'Not connected',
+  pending: 'Pending',
+  verified: 'Verified',
+  failed: 'Failed',
+};
+
+/** The server says which record is which (G7); older rows fall back to the content. */
+export function recordLabel(r: DomainRecord): string {
+  if (r.purpose) return r.purpose.toUpperCase();
+  const v = r.value.toLowerCase();
+  const h = r.host.toLowerCase();
+  if (v.startsWith('v=spf1')) return 'SPF';
+  if (h.startsWith('_dmarc') || v.startsWith('v=dmarc1')) return 'DMARC';
+  if (h.includes('_domainkey')) return 'DKIM';
+  return r.type;
+}
+
+export function SendingDomain({ api }: SendingDomainProps): ReactElement | null {
+  const { data: settings } = useCommsSettings(api);
+  const connect = useConnectDomain(api);
+  const check = useCheckDomain(api);
+  const id = useFieldId('comms-domain');
+  const [domain, setDomain] = useState<string | null>(null);
+  if (!settings) return null;
+
+  const value = domain ?? settings.sending_domain ?? '';
+  const verified = settings.domain_status === 'verified';
+
+  return (
+    <div className="space-y-3">
+      <form
+        className="flex flex-wrap items-end gap-2"
+        onSubmit={(e) => {
+          e.preventDefault();
+          if (value.trim()) connect.mutate(value.trim());
+        }}
+      >
+        <div className="space-y-1">
+          <Label htmlFor={id}>Domain</Label>
+          <Input id={id} value={value} placeholder="example.com" onChange={(e) => setDomain(e.target.value)} />
+        </div>
+        <Button type="submit" disabled={connect.isPending || !value.trim()}>Connect domain</Button>
+      </form>
+
+      {settings.sending_domain ? (
+        <div className="flex flex-wrap items-center gap-2 text-sm">
+          <div className="flex items-center gap-1">
+            Status: <Badge variant={verified ? 'default' : 'secondary'}>{STATUS[settings.domain_status]}</Badge>
+          </div>
+          {settings.domain_checked_at ? <Note>Last checked {formatDate(settings.domain_checked_at)}</Note> : null}
+          <Button type="button" variant="outline" size="sm" disabled={check.isPending} onClick={() => check.mutate()}>
+            Check now
+          </Button>
+        </div>
+      ) : null}
+
+      {settings.domain_records.length > 0 ? (
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Record</TableHead>
+              <TableHead>Type</TableHead>
+              <TableHead>Host</TableHead>
+              <TableHead>Value</TableHead>
+              <TableHead>OK</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {settings.domain_records.map((r, i) => (
+              <TableRow key={`${r.host}-${i}`}>
+                <TableCell>{recordLabel(r)}</TableCell>
+                <TableCell>{r.type}</TableCell>
+                <TableCell className="break-all font-mono text-xs">{r.host}</TableCell>
+                <TableCell className="break-all font-mono text-xs">{r.value}</TableCell>
+                <TableCell>{r.ok ? 'yes' : 'no'}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      ) : null}
+
+      <Note>
+        {verified
+          ? `Mail goes out from ${settings.from_address ?? settings.sending_domain}.`
+          : 'Until a domain is verified, mail goes out via the StartSimpli marketing stream' +
+            (settings.from_address ? ` as ${settings.from_address}.` : '.')}
+      </Note>
+      <ErrorNotice error={connect.error ?? check.error} />
+    </div>
+  );
+}