@startsimpli/integrations 0.2.46 → 0.2.48

package/src/comms/components/_shared.tsx

@@ -41,6 +41,41 @@ export function formatDate(iso: string | null | undefined): string {
   return d.toLocaleDateString(undefined, { day: 'numeric', month: 'short', year: 'numeric' });
 }
 
+/** "Nov 3, 2026, 10:00 AM EST" in `timeZone` (IANA), or the viewer's zone when absent or unknown. */
+export function formatDateTime(iso: string | null | undefined, timeZone?: string | null): string {
+  if (!iso) return '';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '';
+  const opts: Intl.DateTimeFormatOptions = {
+    year: 'numeric', month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit', timeZoneName: 'short',
+  };
+  try {
+    return d.toLocaleString(undefined, timeZone ? { ...opts, timeZone } : opts);
+  } catch {
+    return d.toLocaleString(undefined, opts);
+  }
+}
+
+/** The viewer's IANA zone, or 'UTC' when the runtime cannot say. */
+export function localTimeZone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC';
+  } catch {
+    return 'UTC';
+  }
+}
+
+/** IANA zones for a picker: the runtime's list when it has one, always with the viewer's zone and UTC. */
+export function timeZoneOptions(): string[] {
+  let zones: string[] = [];
+  try {
+    zones = (Intl as unknown as { supportedValuesOf?: (k: string) => string[] }).supportedValuesOf?.('timeZone') ?? [];
+  } catch {
+    zones = [];
+  }
+  return Array.from(new Set([localTimeZone(), 'UTC', ...zones]));
+}
+
 /** A readable reason code: "not_allowlisted" -> "not allowlisted". */
 export function humanize(code: string): string {
   return code.replace(/_/g, ' ');

package/src/comms/components/index.ts

@@ -7,5 +7,8 @@ export * from './VoiceSettings';
 export * from './SendingDomain';
 export * from './ProductUpdates';
 export * from './DraftReview';
+export * from './SchedulePicker';
+export * from './ScheduledSends';
 export * from './ResultsPanel';
 export * from './SendLog';
+export * from './AudiencePanel';

package/src/comms/hooks/index.ts

@@ -20,12 +20,15 @@ import {
 import type { CommsApi } from '../api/comms';
 import type {
   AssetsQuery,
+  AudienceSegments,
+  AudienceSpec,
   CommsAsset,
   CommsMetrics,
   CommsProgram,
   CommsSettings,
   CommsSettingsPatch,
   Draft,
+  DraftAudience,
   DraftCreate,
   DraftPatch,
   DraftsQuery,
@@ -35,7 +38,8 @@ import type {
   ProgramUpdateResult,
   RenderedEmail,
   SendNowResult,
-  SendRow,
+  ScheduleInput,
+  SendsPage,
   SendsQuery,
   StepGeneration,
   TestSendInput,
@@ -55,6 +59,8 @@ export const commsKeys = {
   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,
+  audience: (slug: string, id: string) => ['startsimpli', 'comms', slug, 'audience', id] as const,
+  audienceSegments: (slug: string) => ['startsimpli', 'comms', slug, 'audience-segments'] as const,
   draftPreview: (slug: string, id: string) => ['startsimpli', 'comms', slug, 'draft-preview', id] as const,
   sends: (slug: string, q: SendsQuery = {}) => ['startsimpli', 'comms', slug, 'sends', q] as const,
   metrics: (slug: string, q: MetricsQuery = {}) => ['startsimpli', 'comms', slug, 'metrics', q] as const,
@@ -210,6 +216,41 @@ export function useDraftPreview(api: CommsApi, id: string, enabled: boolean): Us
   });
 }
 
+// per-send audience -----------------------------------------------------------
+
+export function useDraftAudience(api: CommsApi, id: string, enabled: boolean): UseQueryResult<DraftAudience> {
+  return useQuery({
+    queryKey: commsKeys.audience(api.slug, id),
+    queryFn: () => api.getDraftAudience(id),
+    enabled,
+    staleTime: 0,
+  });
+}
+
+export function useAudienceSegments(api: CommsApi, enabled: boolean): UseQueryResult<AudienceSegments> {
+  return useQuery({
+    queryKey: commsKeys.audienceSegments(api.slug),
+    queryFn: () => api.listAudienceSegments(),
+    enabled,
+  });
+}
+
+/** Who a candidate audience would reach; nothing is saved. */
+export function usePreviewAudience(api: CommsApi, id: string): UseMutationResult<DraftAudience, Error, AudienceSpec> {
+  return useMutation({ mutationFn: (spec: AudienceSpec) => api.previewDraftAudience(id, spec) });
+}
+
+export function useSaveAudience(api: CommsApi, id: string): UseMutationResult<DraftAudience, Error, AudienceSpec> {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (spec: AudienceSpec) => api.saveDraftAudience(id, spec),
+    onSuccess: (data) => {
+      qc.setQueryData(commsKeys.audience(api.slug, id), data);
+      return qc.invalidateQueries({ queryKey: commsKeys.draftsAll(api.slug) });
+    },
+  });
+}
+
 function useDraftsWrite<R, V>(api: CommsApi, fn: (v: V) => Promise<R>) {
   const qc = useQueryClient();
   return useMutation<R, Error, V>({
@@ -234,8 +275,39 @@ export function useUpdateDraft(api: CommsApi): UseMutationResult<Draft, Error, {
   });
 }
 
-export function useApproveDraft(api: CommsApi): UseMutationResult<Draft, Error, string> {
-  return useDraftsWrite(api, (id: string) => api.approveDraft(id));
+/** A draft id to send now, or {id, ...schedule} to schedule it. */
+export type ApproveDraftVars = string | ({ id: string } & Partial<ScheduleInput>);
+
+export function useApproveDraft(api: CommsApi): UseMutationResult<Draft, Error, ApproveDraftVars> {
+  return useScheduleWrite(api, (v: ApproveDraftVars) => {
+    if (typeof v === 'string') return api.approveDraft(v);
+    const { id, send_at, timezone } = v;
+    return api.approveDraft(id, send_at ? { send_at, timezone } : undefined);
+  });
+}
+
+/** Drafts and the sends report both change when a schedule does. */
+function useScheduleWrite<R, V>(api: CommsApi, fn: (v: V) => Promise<R>) {
+  const qc = useQueryClient();
+  return useMutation<R, Error, V>({
+    mutationFn: fn,
+    onSuccess: () => Promise.all([
+      qc.invalidateQueries({ queryKey: commsKeys.draftsAll(api.slug) }),
+      qc.invalidateQueries({ queryKey: ['startsimpli', 'comms', api.slug, 'sends'] }),
+    ]),
+  });
+}
+
+export function useRescheduleDraft(api: CommsApi): UseMutationResult<Draft, Error, { id: string } & ScheduleInput> {
+  return useScheduleWrite(api, ({ id, ...schedule }: { id: string } & ScheduleInput) => api.rescheduleDraft(id, schedule));
+}
+
+export function useRetryDraft(api: CommsApi): UseMutationResult<Draft, Error, string> {
+  return useScheduleWrite(api, (id: string) => api.retryDraft(id));
+}
+
+export function useCancelDraft(api: CommsApi): UseMutationResult<Draft, Error, string> {
+  return useScheduleWrite(api, (id: string) => api.cancelDraft(id));
 }
 
 export function useDiscardDraft(api: CommsApi): UseMutationResult<Draft, Error, string> {
@@ -272,7 +344,7 @@ export function useDeleteAsset(api: CommsApi): UseMutationResult<void, Error, st
 // results ------------------------------------------------------------------
 
 /** Server-side pagination: page/page_size go to the server, never sliced here. */
-export function useSends(api: CommsApi, q: SendsQuery): UseQueryResult<Paginated<SendRow>> {
+export function useSends(api: CommsApi, q: SendsQuery): UseQueryResult<SendsPage> {
   return useQuery({
     queryKey: commsKeys.sends(api.slug, q),
     queryFn: () => api.listSends(q),

package/src/comms/types/index.ts

@@ -194,7 +194,32 @@ export interface ChangesResponse {
   unclassified: string[];
 }
 
-export type DraftApproval = 'pending' | 'approved' | 'discarded';
+export type DraftApproval = 'pending' | 'scheduled' | 'expired' | 'failed' | 'approved' | 'discarded';
+
+/** The named state of a draft/send (server `state`); every one has a reason and a next action. */
+export type DraftState =
+  | 'generating' | 'writing_failed' | 'pending' | 'cancelled' | 'scheduled'
+  | 'expired' | 'failed' | 'sending' | 'sent' | 'discarded';
+
+export type DraftAction =
+  | 'approve' | 'schedule' | 'edit' | 'discard' | 'reschedule' | 'send_now' | 'cancel' | 'retry' | 'wait';
+
+/** Why a pending or expired draft needs a person (no recipients, paused at the scheduled time...). */
+export interface DraftNotice {
+  code: string;
+  reason: string;
+  /** The original send time, on an expired draft. */
+  send_at?: string | null;
+  at?: string;
+}
+
+/** Why a draft failed, and where: dispatch (before any recipient was queued), queue, or send. */
+export interface DraftFailure {
+  stage: 'dispatch' | 'queue' | 'send' | string;
+  code: string;
+  reason: string;
+  at?: string;
+}
 
 export interface Draft {
   id: string;
@@ -211,6 +236,92 @@ export interface Draft {
   error: string | null;
   /** True while a worker is still writing the content: poll getDraft(id). */
   generating: boolean;
+  /** This send's own audience; null/absent = the program default. */
+  audience?: AudienceSpec | null;
+  audience_is_default?: boolean;
+  /** Recipients queued, set at approve. */
+  recipient_count?: number | null;
+  /** UTC instant a scheduled draft goes out (approval 'scheduled'; kept after it starts). */
+  send_at?: string | null;
+  /** IANA zone the admin typed send_at in; display only, never changes when it sends. */
+  send_timezone?: string | null;
+  /** Set on a pending draft whose schedule was cancelled. */
+  cancelled_at?: string | null;
+  state?: DraftState;
+  /** What the admin can do next; absent on older servers (treated as the pending set). */
+  next_actions?: DraftAction[];
+  notice?: DraftNotice | null;
+  failure?: DraftFailure | null;
+  /** The requested send_at was already past, so it was sent right away. */
+  sent_immediately?: boolean;
+  requested_send_at?: string | null;
+  completed_at?: string | null;
+  /** A scheduled send whose audience lookup failed and is being retried. */
+  dispatch_attempts?: number;
+  dispatch_error?: string | null;
+}
+
+/** A tenant-evaluated segment: the key (and params) the foundry's backend understands. */
+export interface SegmentRef {
+  key: string;
+  params?: Record<string, unknown>;
+}
+
+/** Who one send goes to. Always narrows the foundry's customers; never widens. */
+export interface AudienceSpec {
+  base?: 'all' | 'active' | 'inactive';
+  days?: number;
+  joined_after?: string;
+  joined_before?: string;
+  segment?: SegmentRef;
+  exclude?: { emails?: string[]; segment?: SegmentRef };
+}
+
+export type ExcludedReason =
+  | 'no_email'
+  | 'excluded'
+  | 'excluded_segment'
+  | 'undeliverable'
+  | 'unverified'
+  | 'opted_out'
+  | 'suppressed';
+
+export interface AudiencePreview {
+  /** Who will receive it. */
+  count: number;
+  /** Matched the audience before mailability and exclusions. */
+  eligible: number;
+  excluded: Partial<Record<ExcludedReason, number>>;
+  excluded_total: number;
+  sample: string[];
+  excluded_sample: { email: string; reason: ExcludedReason }[];
+}
+
+export interface DraftAudience {
+  audience: AudienceSpec;
+  is_default: boolean;
+  preview: AudiencePreview;
+}
+
+export interface AudienceSegment {
+  key: string;
+  label: string;
+  description: string;
+}
+
+export interface AudienceSegments {
+  available: boolean;
+  segments: AudienceSegment[];
+}
+
+/**
+ * When to send an approved draft. `send_at` is ISO 8601: with an offset or Z it
+ * is an exact instant; a local time ("2026-11-03T10:00") needs `timezone` (IANA).
+ * Stored and dispatched in UTC by the server.
+ */
+export interface ScheduleInput {
+  send_at: string;
+  timezone?: string;
 }
 
 /** POST drafts/: either the email as written (201) or notes to write it from (202, generating). */
@@ -282,6 +393,22 @@ export interface SendRow {
   error: string | null;
 }
 
+/** A draft waiting for its send_at, or one whose schedule was cancelled (sends report). */
+export interface ScheduledSend {
+  id: string;
+  program_key: string;
+  subject: string;
+  status: 'scheduled' | 'expired' | 'failed' | 'cancelled';
+  /** Why: the failure, the pause that expired it, or who cancelled it. */
+  reason?: string;
+  send_at: string | null;
+  send_timezone: string | null;
+  cancelled_at: string | null;
+}
+
+/** GET sends/: the recipient rows (paginated) plus the not-yet-sent drafts. */
+export type SendsPage = Paginated<SendRow> & { scheduled?: ScheduledSend[] };
+
 export interface SendsQuery extends PageParams {
   program?: string;
   status?: string;