Repository Public
1// « Envoyer ce modèle » : définition des variables, contrôle du formulaire, corps de POST /api/v1/messages/send,2// exemples cURL / JSON, lecture des refus de l'API et des états d'envoi. Logique pure (docs/API.md §6, §7, « Templates »).3import type { TemplateVariable } from "./variables"45/** Limites du serveur (server/src/templates.ts, server/src/v1/send.ts). */6export const DESCRIPTION_MAX = 3007export const EXAMPLE_MAX = 20008export const VALUE_MAX = 20_0009export const SUBJECT_MAX = 99810export const NAME_MAX = 12011export const MAX_RECIPIENTS = 10012export const SEND_AT_MAX_DAYS = 3013/** En deçà, le serveur n'y voit pas une programmation et enverrait tout de suite : on exige une vraie marge. */14export const SEND_AT_MIN_MS = 60_0001516const CTRL = /[\u0000-\u001f\u007f\u0085\u2028\u2029]/17const EMAIL = /^[a-z0-9!#$%&'*+/=?^_`{|}~-]+(\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/18/** Même règle que le serveur (adresse ramenée en minuscules). */19export const isSendableEmail = (s: string): boolean => s.length <= 254 && !CTRL.test(s) && EMAIL.test(s.trim().toLowerCase())2021// ---------------------------------------------------------------- définition des variables (description, exemple, obligatoire)22const blank = (name: string): TemplateVariable => ({ name, description: "", example: "", required: false })23const sameDef = (a: TemplateVariable, b: TemplateVariable) => a.description === b.description && a.example === b.example && a.required === b.required2425export type VariableDefs = Readonly<Record<string, TemplateVariable>>26export function indexVariables(variables: readonly TemplateVariable[]): Record<string, TemplateVariable> {27 const out: Record<string, TemplateVariable> = {}28 for (const v of variables) out[v.name] = v29 return out30}31/**32 * Variables montrées dans l'éditeur : les noms viennent du contenu (réalignés par le serveur ou par `alignVariables`),33 * la définition de ce qui a été saisi dans le studio. Un nom sans définition garde celle qu'il porte.34 */35export function overlayVariables(names: readonly TemplateVariable[], defs: VariableDefs): TemplateVariable[] {36 return names.map((v) => (Object.hasOwn(defs, v.name) ? { ...defs[v.name], name: v.name } : v))37}38/** Modifie la définition d'une variable (le nom ne change jamais : il vient des {{variables}} du contenu). */39export function patchVariable(defs: VariableDefs, current: TemplateVariable, patch: Partial<Omit<TemplateVariable, "name">>): Record<string, TemplateVariable> {40 const next: TemplateVariable = { ...current, ...patch, name: current.name }41 next.description = next.description.replace(/[\r\n]+/g, " ").slice(0, DESCRIPTION_MAX)42 next.example = next.example.slice(0, EXAMPLE_MAX)43 return { ...defs, [current.name]: next }44}45/** Les définitions montrées diffèrent-elles de celles enregistrées ? (une variable nouvelle sans définition ne compte pas : c'est le contenu qui a changé) */46export function variablesDirty(current: readonly TemplateVariable[], saved: readonly TemplateVariable[]): boolean {47 const by = indexVariables(saved)48 return current.some((v) => !sameDef(v, Object.hasOwn(by, v.name) ? by[v.name] : blank(v.name)))49}5051// ---------------------------------------------------------------- formulaire d'envoi52export interface SendRecipient {53 email: string54 name?: string | null55}56export interface SendForm {57 /** adresse d'expéditeur choisie (boîte ou alias), null si aucune n'est disponible */58 from: string | null59 to: readonly SendRecipient[]60 cc: readonly SendRecipient[]61 bcc: readonly SendRecipient[]62 variables: readonly TemplateVariable[]63 values: Readonly<Record<string, string>>64 /** objet de remplacement ; vide = objet du modèle */65 subject: string66 schedule: boolean67 /** valeur d'un champ datetime-local (heure locale), lue seulement si `schedule` */68 sendAt: string69}70export type SendProblem =71 | { code: "no_sender" }72 | { code: "no_recipient" }73 | { code: "invalid_recipient"; addresses: string[] }74 | { code: "too_many_recipients" }75 | { code: "missing_variables"; variables: string[] }76 | { code: "value_too_long"; variables: string[] }77 | { code: "subject_invalid" }78 | { code: "send_at_invalid" }79 | { code: "send_at_past" }80 | { code: "send_at_too_far" }8182/** Instant d'un champ datetime-local (« 2026-11-20T09:30 », heure locale) ; null si la saisie n'est pas une date. */83export function parseLocalDateTime(local: string): Date | null {84 if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?$/.test(local)) return null85 const d = new Date(local)86 return Number.isNaN(d.getTime()) ? null : d87}88/** Valeur de champ datetime-local (minute près) pour un instant, en heure locale. */89export function toLocalInput(d: Date): string {90 const p = (n: number) => String(n).padStart(2, "0")91 return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}T${p(d.getHours())}:${p(d.getMinutes())}`92}9394const uniqueRecipients = (form: Pick<SendForm, "to" | "cc" | "bcc">) => new Set([...form.to, ...form.cc, ...form.bcc].map((r) => r.email.trim().toLowerCase()))9596/** Tout ce qui empêche l'envoi, dans l'ordre du formulaire. Liste vide = la demande peut partir. */97export function sendProblems(form: SendForm, now = Date.now()): SendProblem[] {98 const out: SendProblem[] = []99 if (!form.from) out.push({ code: "no_sender" })100 const all = [...form.to, ...form.cc, ...form.bcc]101 if (!all.length) out.push({ code: "no_recipient" })102 const bad = all.filter((r) => !isSendableEmail(r.email)).map((r) => r.email)103 if (bad.length) out.push({ code: "invalid_recipient", addresses: bad })104 if (uniqueRecipients(form).size > MAX_RECIPIENTS || form.to.length > MAX_RECIPIENTS || form.cc.length > MAX_RECIPIENTS || form.bcc.length > MAX_RECIPIENTS) out.push({ code: "too_many_recipients" })105 const missing = form.variables.filter((v) => v.required && !(form.values[v.name] ?? "").trim()).map((v) => v.name)106 if (missing.length) out.push({ code: "missing_variables", variables: missing })107 const long = form.variables.filter((v) => (form.values[v.name] ?? "").length > VALUE_MAX).map((v) => v.name)108 if (long.length) out.push({ code: "value_too_long", variables: long })109 if (form.subject.length > SUBJECT_MAX || CTRL.test(form.subject)) out.push({ code: "subject_invalid" })110 if (form.schedule) {111 const at = parseLocalDateTime(form.sendAt)112 if (!at) out.push({ code: "send_at_invalid" })113 else if (at.getTime() < now + SEND_AT_MIN_MS) out.push({ code: "send_at_past" })114 else if (at.getTime() > now + SEND_AT_MAX_DAYS * 86400_000) out.push({ code: "send_at_too_far" })115 }116 return out117}118119export interface SendPayload {120 from: string121 to: { email: string; name?: string }[]122 cc?: { email: string; name?: string }[]123 bcc?: { email: string; name?: string }[]124 template_id: string125 variables: Record<string, string>126 subject?: string127 send_at?: string128}129const recipient = (r: SendRecipient): { email: string; name?: string } => {130 const name = (r.name ?? "").replace(new RegExp(`${CTRL.source}+`, "g"), " ").trim().slice(0, NAME_MAX)131 const email = r.email.trim().toLowerCase()132 return name && name.toLowerCase() !== email ? { email, name } : { email }133}134/** Valeurs envoyées : seulement les variables déclarées ; une variable facultative laissée vide est omise. */135export function sendVariables(variables: readonly TemplateVariable[], values: Readonly<Record<string, string>>): Record<string, string> {136 const out: Record<string, string> = {}137 for (const v of variables) {138 const value = Object.hasOwn(values, v.name) ? values[v.name] : ""139 if (value.trim()) out[v.name] = value140 }141 return out142}143/**144 * Corps de POST /api/v1/messages/send pour un envoi par modèle : jamais de `html` ni de `text` (400 template_conflict),145 * `subject` seulement s'il remplace celui du modèle, `send_at` (ISO 8601) seulement pour une programmation.146 * À n'appeler que si `sendProblems` est vide.147 */148export function buildSendPayload(templateId: string, form: SendForm): SendPayload {149 const out: SendPayload = { from: (form.from ?? "").trim().toLowerCase(), to: form.to.map(recipient), template_id: templateId, variables: sendVariables(form.variables, form.values) }150 if (form.cc.length) out.cc = form.cc.map(recipient)151 if (form.bcc.length) out.bcc = form.bcc.map(recipient)152 const subject = form.subject.trim()153 if (subject) out.subject = subject154 const at = form.schedule ? parseLocalDateTime(form.sendAt) : null155 if (at) out.send_at = at.toISOString()156 return out157}158159/** Valeurs passées à l'aperçu : chaque variable déclarée y figure (vide comprise), pour qu'aucun exemple ne s'y glisse — comme à l'envoi. */160export function previewValues(variables: readonly TemplateVariable[], values: Readonly<Record<string, string>>): Record<string, string> {161 const out: Record<string, string> = {}162 for (const v of variables) out[v.name] = Object.hasOwn(values, v.name) ? values[v.name] : ""163 return out164}165166/** Clé d'idempotence d'une tentative d'envoi (1 à 200 caractères ASCII imprimables). */167export function newIdempotencyKey(uuid: () => string = () => globalThis.crypto.randomUUID()): string {168 return `studio-${uuid()}`169}170171// ---------------------------------------------------------------- exemples pour l'API172/** Jamais de jeton dans l'interface : l'exemple lit la clé dans une variable d'environnement. */173export const API_KEY_PLACEHOLDER = "$SPMAIL_API_KEY"174export const EXAMPLE_FROM = "expediteur@example.org"175export const EXAMPLE_TO = "destinataire@example.org"176177export interface ApiExampleInput {178 /** origine du site (https://mail.example) */179 origin: string180 templateId: string181 /** identité choisie, sinon la première ; null si aucune */182 from: string | null183 variables: readonly TemplateVariable[]184 /** valeurs saisies ; à défaut, l'exemple de la variable */185 values?: Readonly<Record<string, string>>186}187export interface ApiExample {188 body: { from: string; to: { email: string }[]; template_id: string; variables: Record<string, string> }189 json: string190 curl: string191}192const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`193export function apiExample(input: ApiExampleInput): ApiExample {194 const variables: Record<string, string> = {}195 for (const v of input.variables) {196 const typed = input.values && Object.hasOwn(input.values, v.name) ? input.values[v.name] : ""197 variables[v.name] = typed.trim() ? typed : v.example198 }199 const body = { from: input.from || EXAMPLE_FROM, to: [{ email: EXAMPLE_TO }], template_id: input.templateId, variables }200 const json = JSON.stringify(body, null, 2)201 const url = `${input.origin.replace(/\/+$/, "")}/api/v1/messages/send`202 const curl = [203 `curl -X POST "${url}" \\`,204 ` -H "Authorization: Bearer ${API_KEY_PLACEHOLDER}" \\`,205 ` -H "Content-Type: application/json" \\`,206 ` -H "Idempotency-Key: $(uuidgen)" \\`,207 ` -d ${shellQuote(json)}`,208 ].join("\n")209 return { body, json, curl }210}211212// ---------------------------------------------------------------- refus de l'API213export const SEND_ERROR_CODES = [214 "missing_variables", "unknown_variables", "send_at_too_far", "from_not_allowed", "address_inactive", "address_cannot_send", "template_conflict", "unknown_template",215 "rate_limited", "no_recipients", "too_many_recipients", "invalid_request", "message_rejected", "mail_server", "idempotency_conflict", "idempotency_in_progress",216 "offline", "unauthorized", "unknown",217] as const218export type SendErrorCode = (typeof SEND_ERROR_CODES)[number]219export interface SendError {220 code: SendErrorCode221 /** variables en cause (missing_variables, unknown_variables) */222 variables: string[]223 /**224 * La même clé d'idempotence doit resservir à la prochaine tentative : on ignore si la demande précédente est arrivée225 * (réseau coupé, traitement en cours). Après une réponse nette du serveur, une clé neuve est prise.226 */227 keepKey: boolean228}229const namesIn = (details: unknown): string[] => {230 const v = details && typeof details === "object" ? (details as { variables?: unknown }).variables : null231 return Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : []232}233/** Traduit un échec de POST /messages/send (`null` = aucune réponse HTTP : réseau). */234export function readSendError(e: { status: number; code: string; details?: unknown } | null): SendError {235 if (!e) return { code: "offline", variables: [], keepKey: true }236 const direct: Record<string, SendErrorCode> = {237 missing_variables: "missing_variables", unknown_variables: "unknown_variables", send_at_too_far: "send_at_too_far", from_not_allowed: "from_not_allowed",238 address_inactive: "address_inactive", address_cannot_send: "address_cannot_send", template_conflict: "template_conflict", unknown_template: "unknown_template",239 rate_limited: "rate_limited", daily_send_limit_exceeded: "rate_limited", no_recipients: "no_recipients", too_many_recipients: "too_many_recipients",240 invalid_request: "invalid_request", message_rejected: "message_rejected", mail_server_unavailable: "mail_server", mail_server_error: "mail_server",241 idempotency_conflict: "idempotency_conflict", idempotency_key_expired: "idempotency_conflict", idempotency_in_progress: "idempotency_in_progress",242 }243 const code: SendErrorCode = Object.hasOwn(direct, e.code) ? direct[e.code] : e.status === 401 ? "unauthorized" : e.status === 429 ? "rate_limited" : e.status >= 500 ? "mail_server" : "unknown"244 // 5xx sans enveloppe de l'API (mandataire, coupure) : la demande a pu être traitée, la même clé protège d'un double envoi.245 // Un refus net de l'API, lui, est mémorisé avec la clé : la réutiliser rejouerait ce refus.246 const keepKey = code === "idempotency_in_progress" || (e.status >= 500 && /^http_\d+$/.test(e.code))247 return { code, variables: code === "missing_variables" || code === "unknown_variables" ? namesIn(e.details) : [], keepKey }248}249250// ---------------------------------------------------------------- états d'un envoi251export const OUTBOUND_STATUSES = ["queued", "scheduled", "pending_approval", "sent", "delivered", "deferred", "bounced", "failed", "cancelled", "draft"] as const252export type OutboundStatusName = (typeof OUTBOUND_STATUSES)[number]253export const knownStatus = (s: string): OutboundStatusName | "unknown" => ((OUTBOUND_STATUSES as readonly string[]).includes(s) ? (s as OutboundStatusName) : "unknown")254export type StatusTone = "ok" | "warn" | "danger" | "info"255/** Seul `delivered` est un succès : « accepté » (sent) n'est pas « remis ». */256export function statusTone(status: string): StatusTone {257 if (status === "delivered") return "ok"258 if (status === "bounced" || status === "failed") return "danger"259 if (status === "deferred" || status === "cancelled" || status === "pending_approval") return "warn"260 return "info"261}262/** L'état peut-il encore changer sous peu ? (un envoi programmé ou en attente d'approbation ne se suit pas à la seconde) */263export const shouldPoll = (status: string): boolean => status === "queued" || status === "sent" || status === "deferred"264