Repository Public
1// Envoi d'un modèle : définition des variables, contrôle du formulaire, corps de la demande, exemples d'API, refus, états.2import assert from "node:assert/strict"3import { test } from "node:test"4import {5 API_KEY_PLACEHOLDER, DESCRIPTION_MAX, EXAMPLE_FROM, EXAMPLE_MAX, EXAMPLE_TO, OUTBOUND_STATUSES, SEND_AT_MAX_DAYS, SEND_ERROR_CODES, VALUE_MAX, apiExample, buildSendPayload, indexVariables, isSendableEmail,6 knownStatus, newIdempotencyKey, overlayVariables, parseLocalDateTime, patchVariable, previewValues, readSendError, sendProblems, sendVariables, shouldPoll, statusTone, toLocalInput, variablesDirty, type SendForm,7} from "./send"8import { alignVariables, type TemplateVariable } from "./variables"9import { enTemplates } from "../i18n/en.templates"10import { frTemplates } from "../i18n/fr.templates"1112const VARS: TemplateVariable[] = [13 { name: "code", description: "Code à usage unique", example: "424242", required: false },14 { name: "first_name", description: "Prénom", example: "Zoé", required: true },15]16const NOW = new Date(2026, 10, 19, 12, 0, 0).getTime()17const form = (over: Partial<SendForm> = {}): SendForm => ({18 from: "a@stg.example.org", to: [{ email: "b@stg.example.org" }], cc: [], bcc: [], variables: VARS, values: { first_name: "Maëlle" }, subject: "", schedule: false, sendAt: "", ...over,19})20const codes = (f: SendForm) => sendProblems(f, NOW).map((p) => p.code)2122// ================================================================ définition des variables23test("variables : la définition saisie recouvre celle du contenu, le nom ne change jamais", () => {24 const names = alignVariables(VARS, "Bonjour {{first_name}}, {{code}} {{nouvelle}}")25 assert.deepEqual(names.map((v) => v.name), ["code", "first_name", "nouvelle"])26 let defs = indexVariables(VARS)27 defs = patchVariable(defs, names[2], { description: "Ajoutée", required: true })28 defs = patchVariable(defs, defs.code, { example: "111111", name: "pirate" } as never)29 const shown = overlayVariables(names, defs)30 assert.deepEqual(shown, [31 { name: "code", description: "Code à usage unique", example: "111111", required: false },32 { name: "first_name", description: "Prénom", example: "Zoé", required: true },33 { name: "nouvelle", description: "Ajoutée", example: "", required: true },34 ])35 // une définition orpheline (variable retirée du contenu) n'apparaît pas36 assert.deepEqual(overlayVariables(alignVariables(VARS, "{{code}}"), defs).map((v) => v.name), ["code"])37 // pas de collision avec les propriétés héritées d'un objet38 assert.deepEqual(overlayVariables([{ name: "constructor", description: "", example: "", required: false }], {}), [{ name: "constructor", description: "", example: "", required: false }])39})4041test("variables : bornes du serveur (description 300 sans saut de ligne, exemple 2000)", () => {42 const defs = patchVariable({}, VARS[0], { description: `a\nb${"x".repeat(400)}`, example: "y".repeat(3000) })43 assert.equal(defs.code.description.length, DESCRIPTION_MAX)44 assert.ok(defs.code.description.startsWith("a bx"))45 assert.equal(defs.code.example.length, EXAMPLE_MAX)46 // l'objet d'origine n'est pas modifié47 assert.equal(VARS[0].example, "424242")48})4950test("variables : état « modifié » — seules les définitions comptent", () => {51 assert.equal(variablesDirty(VARS, VARS), false)52 assert.equal(variablesDirty([...VARS].reverse(), VARS), false)53 assert.equal(variablesDirty([{ ...VARS[0], required: true }, VARS[1]], VARS), true)54 assert.equal(variablesDirty([{ ...VARS[0], example: "1" }, VARS[1]], VARS), true)55 assert.equal(variablesDirty([{ ...VARS[0], description: "autre" }, VARS[1]], VARS), true)56 // variable nouvelle, encore sans définition : c'est le contenu qui a changé, pas les variables57 assert.equal(variablesDirty([...VARS, { name: "nouvelle", description: "", example: "", required: false }], VARS), false)58 assert.equal(variablesDirty([...VARS, { name: "nouvelle", description: "", example: "x", required: false }], VARS), true)59 // variable disparue du contenu : idem60 assert.equal(variablesDirty([VARS[0]], VARS), false)61})6263// ================================================================ contrôle du formulaire64test("formulaire : complet → aucun obstacle", () => {65 assert.deepEqual(codes(form()), [])66 assert.deepEqual(codes(form({ to: [], bcc: [{ email: "c@stg.example.org" }] })), [])67})6869test("formulaire : expéditeur, destinataires, adresses invalides", () => {70 assert.deepEqual(codes(form({ from: null })), ["no_sender"])71 assert.deepEqual(codes(form({ to: [] })), ["no_recipient"])72 const p = sendProblems(form({ to: [{ email: "pas une adresse" }], cc: [{ email: "ok@stg.example.org" }, { email: "x@y" }] }), NOW)73 assert.deepEqual(p, [{ code: "invalid_recipient", addresses: ["pas une adresse", "x@y"] }])74 assert.equal(isSendableEmail("Prenom.Nom+tag@Sous.Exemple.org"), true)75 assert.equal(isSendableEmail("a@b.org\r\nBcc: x@y.org"), false)76 assert.equal(isSendableEmail("a b@c.org"), false)77 const many = Array.from({ length: 101 }, (_, i) => ({ email: `u${i}@stg.example.org` }))78 assert.deepEqual(codes(form({ to: many })), ["too_many_recipients"])79})8081test("formulaire : une variable obligatoire vide (ou faite d'espaces) bloque l'envoi ; une facultative non", () => {82 assert.deepEqual(sendProblems(form({ values: {} }), NOW), [{ code: "missing_variables", variables: ["first_name"] }])83 assert.deepEqual(sendProblems(form({ values: { first_name: " ", code: "1" } }), NOW), [{ code: "missing_variables", variables: ["first_name"] }])84 assert.deepEqual(codes(form({ values: { first_name: "Zoé" } })), [])85 // l'exemple ne compte jamais comme une valeur86 assert.deepEqual(codes(form({ variables: [{ ...VARS[1], example: "Zoé" }], values: {} })), ["missing_variables"])87 assert.deepEqual(sendProblems(form({ values: { first_name: "a", code: "x".repeat(VALUE_MAX + 1) } }), NOW), [{ code: "value_too_long", variables: ["code"] }])88})8990test("formulaire : objet de remplacement (longueur, caractères de contrôle)", () => {91 assert.deepEqual(codes(form({ subject: "Bonjour" })), [])92 assert.deepEqual(codes(form({ subject: "a\r\nBcc: x@y.org" })), ["subject_invalid"])93 assert.deepEqual(codes(form({ subject: "x".repeat(999) })), ["subject_invalid"])94})9596test("formulaire : programmation — futur, au plus 30 jours", () => {97 const at = (ms: number) => toLocalInput(new Date(NOW + ms))98 assert.deepEqual(codes(form({ schedule: true, sendAt: "" })), ["send_at_invalid"])99 assert.deepEqual(codes(form({ schedule: true, sendAt: "demain" })), ["send_at_invalid"])100 assert.deepEqual(codes(form({ schedule: true, sendAt: at(-3600_000) })), ["send_at_past"])101 // à quelques secondes près le serveur enverrait tout de suite : refusé ici102 assert.deepEqual(codes(form({ schedule: true, sendAt: at(0) })), ["send_at_past"])103 assert.deepEqual(codes(form({ schedule: true, sendAt: at(86400_000) })), [])104 assert.deepEqual(codes(form({ schedule: true, sendAt: at(SEND_AT_MAX_DAYS * 86400_000 - 3600_000) })), [])105 assert.deepEqual(codes(form({ schedule: true, sendAt: at((SEND_AT_MAX_DAYS + 1) * 86400_000) })), ["send_at_too_far"])106 // case décochée : la date saisie est ignorée107 assert.deepEqual(codes(form({ schedule: false, sendAt: at(-3600_000) })), [])108})109110test("dates : champ datetime-local ⇄ instant (heure locale)", () => {111 const d = parseLocalDateTime("2026-11-20T09:30")112 assert.ok(d)113 assert.deepEqual([d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), d.getMinutes()], [2026, 10, 20, 9, 30])114 assert.equal(toLocalInput(d), "2026-11-20T09:30")115 assert.equal(toLocalInput(new Date(2026, 0, 5, 7, 4, 59)), "2026-01-05T07:04")116 assert.equal(parseLocalDateTime("2026-11-20"), null)117 assert.equal(parseLocalDateTime("2026-13-40T99:99"), null)118 assert.equal(parseLocalDateTime(""), null)119})120121// ================================================================ corps de la demande122test("demande : template_id + variables, jamais html ni text ; champs facultatifs absents", () => {123 const p = buildSendPayload("6f1c0c1e-0000-4000-8000-000000000001", form({ from: " A@Stg.Example.org " }))124 assert.deepEqual(p, { from: "a@stg.example.org", to: [{ email: "b@stg.example.org" }], template_id: "6f1c0c1e-0000-4000-8000-000000000001", variables: { first_name: "Maëlle" } })125 assert.equal("html" in p, false)126 assert.equal("text" in p, false)127 assert.equal("subject" in p, false)128 assert.equal("send_at" in p, false)129 assert.equal("cc" in p, false)130 assert.equal("bcc" in p, false)131})132133test("demande : variables filtrées aux noms déclarés, facultatives vides omises, valeurs envoyées telles que saisies", () => {134 const values = { first_name: " Zoé <b>& ", code: "", fantome: "x", constructor: "y", __proto__x: "z" }135 assert.deepEqual(sendVariables(VARS, values), { first_name: " Zoé <b>& " })136 assert.deepEqual(sendVariables(VARS, { first_name: "A", code: " " }), { first_name: "A" })137 assert.deepEqual(sendVariables(VARS, { first_name: "A", code: "0" }), { code: "0", first_name: "A" })138 assert.deepEqual(sendVariables([], { first_name: "A" }), {})139 // l'aperçu, lui, reçoit chaque variable (vide comprise) pour qu'aucun exemple ne s'y glisse140 assert.deepEqual(previewValues(VARS, { first_name: "A", fantome: "x" }), { code: "", first_name: "A" })141})142143test("demande : destinataires (nom gardé s'il apporte quelque chose), Cc / Cci, objet, send_at en ISO", () => {144 const f = form({145 to: [{ email: "B@Stg.Example.org", name: "Béa Tremblay" }, { email: "c@stg.example.org", name: "c@stg.example.org" }, { email: "d@stg.example.org", name: null }],146 cc: [{ email: "cc@stg.example.org", name: "Ligne\r\nBcc: x" }],147 bcc: [{ email: "bcc@stg.example.org" }],148 subject: " Objet de remplacement ",149 schedule: true,150 sendAt: "2026-11-20T09:30",151 })152 const p = buildSendPayload("id", f)153 assert.deepEqual(p.to, [{ email: "b@stg.example.org", name: "Béa Tremblay" }, { email: "c@stg.example.org" }, { email: "d@stg.example.org" }])154 assert.deepEqual(p.cc, [{ email: "cc@stg.example.org", name: "Ligne Bcc: x" }])155 assert.deepEqual(p.bcc, [{ email: "bcc@stg.example.org" }])156 assert.equal(p.subject, "Objet de remplacement")157 assert.equal(p.send_at, new Date(2026, 10, 20, 9, 30).toISOString())158 assert.match(p.send_at ?? "", /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/)159 // case décochée : pas de send_at, même si une date traîne dans le champ160 assert.equal("send_at" in buildSendPayload("id", { ...f, schedule: false }), false)161})162163test("clé d'idempotence : neuve à chaque appel, acceptée par le serveur", () => {164 const a = newIdempotencyKey()165 const b = newIdempotencyKey()166 assert.notEqual(a, b)167 assert.match(a, /^[\x21-\x7e]{1,200}$/)168 assert.equal(newIdempotencyKey(() => "fixe"), "studio-fixe")169})170171// ================================================================ exemples d'API172test("exemple d'API : identifiant réel, variables préremplies par leurs exemples, jamais de jeton", () => {173 const ex = apiExample({ origin: "https://mail.example.org/", templateId: "6f1c0c1e-0000-4000-8000-000000000001", from: "a@stg.example.org", variables: VARS })174 assert.deepEqual(ex.body, { from: "a@stg.example.org", to: [{ email: EXAMPLE_TO }], template_id: "6f1c0c1e-0000-4000-8000-000000000001", variables: { code: "424242", first_name: "Zoé" } })175 assert.deepEqual(JSON.parse(ex.json), ex.body)176 assert.ok(ex.curl.startsWith('curl -X POST "https://mail.example.org/api/v1/messages/send" \\\n'))177 assert.ok(ex.curl.includes(`-H "Authorization: Bearer ${API_KEY_PLACEHOLDER}"`))178 assert.equal(API_KEY_PLACEHOLDER, "$SPMAIL_API_KEY")179 assert.ok(ex.curl.includes('-H "Idempotency-Key: $(uuidgen)"'))180 assert.ok(ex.curl.includes('"template_id": "6f1c0c1e-0000-4000-8000-000000000001"'))181 // rien qui ressemble à une clé d'API ni à un jeton de session182 assert.doesNotMatch(`${ex.curl}\n${ex.json}`, /spm_[A-Za-z0-9]|Bearer (?!\$SPMAIL_API_KEY)|cookie/i)183 assert.equal("html" in ex.body, false)184})185186test("exemple d'API : valeurs saisies prioritaires, expéditeur d'exemple sans identité, apostrophes protégées pour le shell", () => {187 const ex = apiExample({ origin: "http://localhost:8811", templateId: "id", from: null, variables: VARS, values: { first_name: "L'été d'Zoé", code: " ", fantome: "x" } })188 assert.equal(ex.body.from, EXAMPLE_FROM)189 assert.deepEqual(ex.body.variables, { code: "424242", first_name: "L'été d'Zoé" })190 // le corps est entre apostrophes : chaque apostrophe de la valeur est fermée, échappée, rouverte191 assert.ok(ex.curl.includes(`L'\\''été d'\\''Zoé`))192 const data = ex.curl.slice(ex.curl.indexOf("-d '") + 4, -1).replace(/'\\''/g, "'")193 assert.deepEqual(JSON.parse(data), ex.body)194 assert.deepEqual(apiExample({ origin: "http://x", templateId: "id", from: "a@b.org", variables: [] }).body.variables, {})195})196197// ================================================================ refus de l'API198test("refus : variables manquantes ou inconnues nommées", () => {199 assert.deepEqual(readSendError({ status: 400, code: "missing_variables", details: { variables: ["first_name", 3] } }), { code: "missing_variables", variables: ["first_name"], keepKey: false })200 assert.deepEqual(readSendError({ status: 400, code: "unknown_variables", details: { variables: ["x", "y"] } }), { code: "unknown_variables", variables: ["x", "y"], keepKey: false })201 assert.deepEqual(readSendError({ status: 400, code: "missing_variables" }).variables, [])202})203204test("refus : chaque code de l'API a son message ; l'inconnu reste honnête", () => {205 for (const code of ["send_at_too_far", "from_not_allowed", "address_inactive", "address_cannot_send", "template_conflict", "unknown_template", "rate_limited", "no_recipients", "too_many_recipients", "invalid_request", "message_rejected"] as const)206 assert.equal(readSendError({ status: 400, code }).code, code)207 assert.equal(readSendError({ status: 429, code: "daily_send_limit_exceeded" }).code, "rate_limited")208 assert.equal(readSendError({ status: 429, code: "http_429" }).code, "rate_limited")209 assert.equal(readSendError({ status: 502, code: "mail_server_unavailable" }).code, "mail_server")210 assert.equal(readSendError({ status: 401, code: "unauthenticated" }).code, "unauthorized")211 assert.equal(readSendError({ status: 403, code: "external_send_denied" }).code, "unknown")212 assert.equal(readSendError({ status: 409, code: "idempotency_key_expired" }).code, "idempotency_conflict")213 // tout code rendu a une phrase en français et en anglais214 for (const code of SEND_ERROR_CODES) {215 assert.ok(frTemplates[`tpl.send.err.${code}` as keyof typeof frTemplates], `fr ${code}`)216 assert.ok(enTemplates[`tpl.send.err.${code}` as keyof typeof frTemplates], `en ${code}`)217 }218})219220test("refus : la clé d'idempotence n'est gardée que si le sort de la demande est inconnu", () => {221 // aucune réponse : la demande a pu arriver → même clé au prochain essai222 assert.deepEqual(readSendError(null), { code: "offline", variables: [], keepKey: true })223 assert.equal(readSendError({ status: 409, code: "idempotency_in_progress" }).keepKey, true)224 assert.equal(readSendError({ status: 502, code: "http_502" }).keepKey, true)225 // refus net de l'API (mémorisé avec la clé côté serveur) : clé neuve, sinon le refus serait rejoué226 assert.equal(readSendError({ status: 400, code: "missing_variables" }).keepKey, false)227 assert.equal(readSendError({ status: 502, code: "mail_server_unavailable" }).keepKey, false)228 assert.equal(readSendError({ status: 409, code: "idempotency_conflict" }).keepKey, false)229})230231// ================================================================ états232test("états : seul « delivered » est un succès ; « sent » (accepté) n'est pas « remis »", () => {233 assert.equal(statusTone("delivered"), "ok")234 assert.equal(statusTone("sent"), "info")235 assert.equal(statusTone("queued"), "info")236 assert.equal(statusTone("scheduled"), "info")237 assert.equal(statusTone("bounced"), "danger")238 assert.equal(statusTone("failed"), "danger")239 assert.equal(statusTone("deferred"), "warn")240 assert.equal(statusTone("pending_approval"), "warn")241 assert.equal(statusTone("nouveau"), "info")242 assert.equal(knownStatus("delivered"), "delivered")243 assert.equal(knownStatus("nouveau"), "unknown")244 assert.notEqual(frTemplates["tpl.send.status.sent"], frTemplates["tpl.send.status.delivered"])245 assert.doesNotMatch(frTemplates["tpl.send.status.sent"], /remis/i)246 assert.doesNotMatch(enTemplates["tpl.send.status.sent"], /deliver/i)247 for (const s of [...OUTBOUND_STATUSES, "unknown"] as const) {248 for (const dict of [frTemplates, enTemplates]) {249 assert.ok(dict[`tpl.send.status.${s}` as keyof typeof frTemplates], `status ${s}`)250 assert.ok(dict[`tpl.send.explain.${s}` as keyof typeof frTemplates], `explain ${s}`)251 }252 }253})254255test("états : suivi rapproché seulement quand l'état peut changer sous peu", () => {256 assert.deepEqual(["queued", "sent", "deferred"].map(shouldPoll), [true, true, true])257 assert.deepEqual(["scheduled", "pending_approval", "delivered", "bounced", "failed", "cancelled", "draft"].map(shouldPoll), [false, false, false, false, false, false, false])258})259