import type * as React from "react" /** * Email composer contract. * * Any hub opens the composer by handing it an `EmailComposerContext`: who can be * emailed, which fields feed merge tags, which templates exist, and who is sending. * The composer owns the UI; a page only maps its rows to `EmailRecipient`s. */ /** A group of recipients that share one message (students, preceptors, faculty). */ export interface EmailAudience { id: string /** Plural, shown in the audience select: "Students". */ label: string /** Singular, used in counts: "student". Defaults to `label` lowercased. */ noun?: string /** Font Awesome glyph on the Recipients page card, e.g. `fa-user-graduate`. */ icon?: string /** Start with "Separate emails" (one per record) instead of "One email" per person. */ separateByDefault?: boolean } export interface EmailRecipient { id: string /** `EmailAudience.id` this person belongs to. */ audience: string name: string email: string /** Values for merge fields, keyed by `EmailMergeField.key`. */ fields?: Record /** Pre-formatted, e.g. "Emailed Oct 28". Lets the sender skip people who already got one. */ lastEmailed?: string /** Records (schedules, placements…) this person is on. More than one makes send mode matter. */ records?: number /** Why this person cannot be emailed yet, e.g. "No students assigned to this record". */ blockedReason?: string } /** A value a user can drop into the subject or body as `{{key}}`. */ export interface EmailMergeField { key: string label: string /** What the field becomes and where its value comes from. Shown when its chip is clicked. */ description?: string /** Colour group 1–5 so related fields share a chip colour. Default brand. */ tone?: 1 | 2 | 3 | 4 | 5 } export interface EmailAttachmentFile { id: string name: string /** Bytes. */ size: number /** Brought in by the template rather than added by the sender. */ fromTemplate?: boolean /** The file the sender attached. Template files have a name only (or a `url`). */ file?: File /** Hosted copy of a template file, for preview. */ url?: string } export interface EmailTemplateDefinition { id: string label: string /** One line on what the template is for, shown in the template menu. */ description?: string /** Applied when the composer opens for this audience. */ isDefault?: boolean /** Header and footer the template brings. Default: logo with name above, product logo below. */ header?: "none" | "logo" | "logo-name" footer?: "none" | "logo" | "product" | "contact" subject: string /** HTML body. Merge fields are written as `{{key}}`. */ body: string attachments?: { name: string; size: number; /** Hosted copy to preview. */ url?: string }[] } export interface EmailBrand { name: string /** * The school or site's logo as the app already draws it (its scope avatar). Used by the * header and the footer. Falls back to `logoUrl`, then a letter tile. */ logo?: React.ReactNode /** Image URL for the school or site logo, when no `logo` node is given. */ logoUrl?: string /** The product logo as the app already draws it (the Exxat product lock-up), for the footer. */ productLogo?: React.ReactNode /** Office or unit line under the name: "Clinical Placements Office". */ unit?: string address?: string contact?: string } export interface EmailHistoryItem { id: string audience: string subject: string /** HTML body as it was sent. */ body: string /** Pre-formatted, e.g. "Oct 28, 2026 · 9:00 AM". */ sentAt: string sentBy: string /** Who it went to, e.g. "12 students". */ recipientsLabel: string status: "sent" | "scheduled" | "failed" note?: string } export interface EmailSender { name: string email: string replyTo?: string /** Address "Send me a copy" and "Send test email" go to. Defaults to `email`. */ me?: string brand: EmailBrand } /** An address the sender can pick from, or add as Cc, Bcc or Reply to. */ export interface EmailContact { name: string email: string /** Small label next to the name: "Shared inbox", "Student". */ tag?: string } export interface EmailComposerContext { /** Where the composer was opened from, e.g. "Students". Shown as the sheet subtitle. */ source: string audiences: EmailAudience[] recipients: EmailRecipient[] /** Singular name for what recipients are attached to: "schedule". Default "record". */ recordNoun?: string sender: EmailSender /** Extra "From" choices beyond `sender`. */ senders?: EmailContact[] /** Per-audience templates. Falls back to a single blank template. */ templates?: Record /** Merge fields offered in "Insert field". Defaults to first name and sender name. */ mergeFields?: EmailMergeField[] /** Earlier emails relevant to these recipients, newest first. */ history?: EmailHistoryItem[] /** Opens with this message already in place (e.g. reusing a history item). */ prefill?: { audience: string; subject: string; body: string } } export interface EmailSendPayload { audience: string subject: string /** HTML body with `{{key}}` merge fields still in place. */ body: string recipients: EmailRecipient[] /** Addresses typed into To beyond the audience. */ extraTo: string[] cc: string[] bcc: string[] from: string replyTo: string /** One email per record (true) or one email per person listing all their records (false). */ separateEmails: boolean header: "none" | "logo" | "logo-name" footer: "none" | "logo" | "product" | "contact" attachments: EmailAttachmentFile[] copyToSender: boolean /** ISO local date-time when scheduled, otherwise `null` for send now. */ scheduledFor: string | null } export const BLANK_EMAIL_BODY = "


" /** Every template opens with a header and a footer unless it says otherwise. */ export const DEFAULT_TEMPLATE_HEADER = "logo-name" as const export const DEFAULT_TEMPLATE_FOOTER = "product" as const export const BLANK_EMAIL_TEMPLATE: EmailTemplateDefinition = { id: "blank", label: "Blank email", subject: "", body: BLANK_EMAIL_BODY, header: "none", footer: "none", } export const DEFAULT_MERGE_FIELDS: EmailMergeField[] = [ { key: "first_name", label: "Recipient first name", description: "The first name of whoever gets the email, so one message can greet everyone personally." }, { key: "name", label: "Recipient full name", description: "The full name of whoever gets the email." }, { key: "sender_name", label: "Sender name", description: "The name the email is sent from." }, ] const TOKEN = /\{\{\s*([\w.-]+)\s*\}\}/g /** Values every recipient has without the page supplying them. */ function builtInFields(person: EmailRecipient, senderName: string): Record { return { first_name: person.name.trim().split(/\s+/)[0] ?? person.name, name: person.name, sender_name: senderName, } } /** Replace `{{key}}` with this recipient's value. An unknown key is left visible so it gets noticed. */ export function resolveMergeFields( text: string, person: EmailRecipient, senderName: string, ): string { const values = { ...builtInFields(person, senderName), ...person.fields } return text.replace(TOKEN, (match, key: string) => values[key] ?? match) } export const emailProblem = (person: Pick): "" | "No email address" | "Invalid email" => !person.email.trim() ? "No email address" : /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(person.email.trim()) ? "" : "Invalid email" export function formatFileSize(bytes: number): string { return bytes >= 1_048_576 ? `${(bytes / 1_048_576).toFixed(1)} MB` : `${Math.max(1, Math.round(bytes / 1024))} KB` } export function audienceNoun(audience: EmailAudience, count = 2): string { const noun = audience.noun ?? audience.label.toLowerCase() return count === 1 ? noun : audience.noun ? `${noun}s` : noun }