From 6c1842660686e8dae1f2e6ee221a65cec44b42bb Mon Sep 17 00:00:00 2001 From: Maxime Westhoven Date: Tue, 17 Nov 2026 09:46:12 +0100 Subject: [PATCH 1/3] feat(dms-mailing): send template e-mails with attachments --- .../app/components/SendDrawer.vue | 26 ++ .../frontend-vue/app/types/mailing.ts | 2 + .../frontend-vue/app/utils/attachments.ts | 53 ++++ .../frontend-vue/app/utils/send-actions.ts | 6 +- .../i18n/locales/mailing-en-GB.json | 5 + .../i18n/locales/mailing-fr-FR.json | 5 + .../frontend-vue/tests/attachments.test.ts | 40 +++ .../frontend-vue/tests/send-actions.test.ts | 11 + .../frontend-vue/tests/send-drawer.test.ts | 32 +- packages/dms-mailing/src/config.ts | 12 + .../dms-mailing/src/db/tables/sends.table.ts | 7 + .../src/implementations/dms-mailing/index.ts | 1 + packages/dms-mailing/src/routes/sends.ts | 11 +- .../dms-mailing/src/services/attachments.ts | 279 ++++++++++++++++++ .../dms-mailing/src/services/send-error.ts | 11 + packages/dms-mailing/src/services/send.ts | 22 +- packages/dms-mailing/src/test/helpers/smtp.ts | 13 + .../test/integration/send-attachments.test.ts | 162 ++++++++++ .../src/test/unit/attachments.test.ts | 235 +++++++++++++++ .../dms-mailing/src/test/unit/send.test.ts | 1 + .../src/validation/attachments.schema.ts | 14 + packages/interface-dms-mailing/src/index.ts | 75 +++++ 22 files changed, 1009 insertions(+), 14 deletions(-) create mode 100644 packages/dms-mailing/frontend-vue/app/utils/attachments.ts create mode 100644 packages/dms-mailing/frontend-vue/tests/attachments.test.ts create mode 100644 packages/dms-mailing/src/services/attachments.ts create mode 100644 packages/dms-mailing/src/services/send-error.ts create mode 100644 packages/dms-mailing/src/test/helpers/smtp.ts create mode 100644 packages/dms-mailing/src/test/integration/send-attachments.test.ts create mode 100644 packages/dms-mailing/src/test/unit/attachments.test.ts create mode 100644 packages/dms-mailing/src/validation/attachments.schema.ts diff --git a/packages/dms-mailing/frontend-vue/app/components/SendDrawer.vue b/packages/dms-mailing/frontend-vue/app/components/SendDrawer.vue index 2851f3ba..2d3e6434 100644 --- a/packages/dms-mailing/frontend-vue/app/components/SendDrawer.vue +++ b/packages/dms-mailing/frontend-vue/app/components/SendDrawer.vue @@ -19,6 +19,7 @@ import { type SendActionId, } from '../utils/send-actions' import { renderingTitleKey } from '../utils/rendering-title' +import { formatFileSize, sentAttachments, shortHash } from '../utils/attachments' import { formatLatency, isSlowLatency } from '../utils/send-stats' import { isSuppressedStatus, @@ -211,6 +212,8 @@ const stats = computed(() => { ] }) +const attachments = computed(() => sentAttachments(send.value?.json_attachments)) + const originTitle = computed(() => { const template = detail.value?.template const name = template?.name ?? send.value?.templateSlug ?? '' @@ -600,6 +603,22 @@ onMounted(() => { /> + + + {{ file.filename }} + + @@ -618,6 +637,13 @@ onMounted(() => { +

+ {{ key('attachments_not_kept') }} +

diff --git a/packages/dms-mailing/frontend-vue/app/types/mailing.ts b/packages/dms-mailing/frontend-vue/app/types/mailing.ts index 0a523f90..3d1cc96c 100644 --- a/packages/dms-mailing/frontend-vue/app/types/mailing.ts +++ b/packages/dms-mailing/frontend-vue/app/types/mailing.ts @@ -465,6 +465,8 @@ export interface SendRow { error?: string source?: string json_variables: string + /** The files it carried (`SentAttachment[]` as JSON); absent for most sends. */ + json_attachments?: string opens: number clicks: number createdAt: string diff --git a/packages/dms-mailing/frontend-vue/app/utils/attachments.ts b/packages/dms-mailing/frontend-vue/app/utils/attachments.ts new file mode 100644 index 00000000..0d43ab02 --- /dev/null +++ b/packages/dms-mailing/frontend-vue/app/utils/attachments.ts @@ -0,0 +1,53 @@ +/** A file a send carried, as the send log keeps it: never its bytes. */ +export interface SentAttachment { + filename: string + contentType: string + size: number + sha256: string +} + +const KILOBYTE = 1024 +const MEGABYTE = KILOBYTE * KILOBYTE +const SHORT_HASH_LENGTH = 12 + +function isSentAttachment(value: unknown): value is SentAttachment { + if (typeof value !== 'object' || value === null) return false + const entry = value as Record + return ( + typeof entry.filename === 'string' && + typeof entry.contentType === 'string' && + typeof entry.size === 'number' && + typeof entry.sha256 === 'string' + ) +} + +/** The files of a send's `json_attachments`; none when absent or unreadable. */ +export function sentAttachments(json: string | undefined): SentAttachment[] { + if (!json) return [] + try { + const parsed: unknown = JSON.parse(json) + return Array.isArray(parsed) ? parsed.filter(isSentAttachment) : [] + } catch { + return [] + } +} + +/** `size` in the largest unit that keeps it above one: "120 kB", "2.4 MB". */ +export function formatFileSize(size: number, locale: string): string { + const [value, unit] = + size >= MEGABYTE + ? [size / MEGABYTE, 'megabyte'] + : size >= KILOBYTE + ? [size / KILOBYTE, 'kilobyte'] + : [size, 'byte'] + return new Intl.NumberFormat(locale, { + style: 'unit', + unit, + unitDisplay: 'short', + maximumFractionDigits: 1, + }).format(value) +} + +/** The start of a file's SHA-256, enough to match it against an archive by eye. */ +export const shortHash = (sha256: string): string => + sha256.slice(0, SHORT_HASH_LENGTH) diff --git a/packages/dms-mailing/frontend-vue/app/utils/send-actions.ts b/packages/dms-mailing/frontend-vue/app/utils/send-actions.ts index 399cff6a..26557fe1 100644 --- a/packages/dms-mailing/frontend-vue/app/utils/send-actions.ts +++ b/packages/dms-mailing/frontend-vue/app/utils/send-actions.ts @@ -31,7 +31,7 @@ export interface DrawerSend extends SendRow { /** What decides a drawer's footer. */ export interface FooterSend extends Pick< DrawerSend, - 'status' | 'isSoftBounce' | 'replayedBy' + 'status' | 'isSoftBounce' | 'replayedBy' | 'json_attachments' > { /** * Whether the recipient is on the suppression list today; unknown until @@ -99,12 +99,14 @@ const ACTIONS_BY_STATUS: Partial> = { } /** - * Footers that win over the status: a send someone already sent again offers + * Footers that win over the status: a send that carried attachments cannot be + * repeated since the log keeps no file, a send someone already sent again offers * no second one, a temporary bounce (a full mailbox) may go to the same * address later, and so may a suppressed send once its address is * reactivated. */ const FOOTER_RULES: FooterRule[] = [ + { matches: (send) => !!send.json_attachments, actions: LOOK_ONLY }, { matches: (send) => !!send.replayedBy, actions: LOOK_ONLY }, { matches: (send) => send.status === 'bounced' && !!send.isSoftBounce, diff --git a/packages/dms-mailing/frontend-vue/i18n/locales/mailing-en-GB.json b/packages/dms-mailing/frontend-vue/i18n/locales/mailing-en-GB.json index 3e7cf437..d386fcdc 100644 --- a/packages/dms-mailing/frontend-vue/i18n/locales/mailing-en-GB.json +++ b/packages/dms-mailing/frontend-vue/i18n/locales/mailing-en-GB.json @@ -411,6 +411,10 @@ "no_replay_after_spam": "The recipient reported this e-mail as spam: it is not sent again.", "nothing_to_publish": "This template has no content to publish yet.", "replay_needs_new_address": "This address bounced. Send to a corrected address instead.", + "no_replay_with_attachments": "This e-mail carried attachments, which the send log does not keep. Send it again from the application that sent it.", + "attachments_unsupported": "The e-mail provider cannot send attachments.", + "attachments_too_large": "The attachments are too large, or too many.", + "invalid_attachment": "An attachment has no usable name, an unaccepted type or no content.", "starter_not_found": "This starter template does not exist.", "template_in_use": "Only an archived template that was never sent can be deleted. Archive it instead.", "invalid_template": "The template name or slug is invalid.", @@ -500,6 +504,7 @@ }, "description": "Every e-mail your workspace sent: to whom, with which data, and what the provider reported back.", "drawer": { + "attachments_not_kept": "The send log keeps their name, size and fingerprint, not the files: this e-mail cannot be sent again from here.", "latency": "API latency", "locale": "Locale", "payload": "Data sent", diff --git a/packages/dms-mailing/frontend-vue/i18n/locales/mailing-fr-FR.json b/packages/dms-mailing/frontend-vue/i18n/locales/mailing-fr-FR.json index d17406e5..4f64502f 100644 --- a/packages/dms-mailing/frontend-vue/i18n/locales/mailing-fr-FR.json +++ b/packages/dms-mailing/frontend-vue/i18n/locales/mailing-fr-FR.json @@ -411,6 +411,10 @@ "no_replay_after_spam": "Le destinataire a signalé cet e-mail comme spam : il n’est pas renvoyé.", "nothing_to_publish": "Ce modèle n’a pas encore de contenu à publier.", "replay_needs_new_address": "Cette adresse a rebondi. Envoyez plutôt à une adresse corrigée.", + "no_replay_with_attachments": "Cet e-mail portait des pièces jointes, que le journal des envois ne garde pas. Renvoyez-le depuis l’application qui l’a envoyé.", + "attachments_unsupported": "Le fournisseur d’e-mails ne peut pas envoyer de pièces jointes.", + "attachments_too_large": "Les pièces jointes sont trop lourdes, ou trop nombreuses.", + "invalid_attachment": "Une pièce jointe n’a pas de nom utilisable, a un type refusé ou est vide.", "starter_not_found": "Ce modèle de départ n’existe pas.", "template_in_use": "Seul un modèle archivé et jamais envoyé peut être supprimé. Archivez-le plutôt.", "invalid_template": "Le nom ou le slug du modèle est invalide.", @@ -500,6 +504,7 @@ }, "description": "Chaque e-mail envoyé par votre espace de travail : à qui, avec quelles données, et ce que le fournisseur a répondu.", "drawer": { + "attachments_not_kept": "Le journal des envois garde leur nom, leur taille et leur empreinte, pas les fichiers : cet e-mail ne peut pas être renvoyé d’ici.", "latency": "Latence API", "locale": "Langue", "payload": "Données envoyées", diff --git a/packages/dms-mailing/frontend-vue/tests/attachments.test.ts b/packages/dms-mailing/frontend-vue/tests/attachments.test.ts new file mode 100644 index 00000000..07c99c5e --- /dev/null +++ b/packages/dms-mailing/frontend-vue/tests/attachments.test.ts @@ -0,0 +1,40 @@ +import { describe, expect, it } from 'vitest' +import { + formatFileSize, + sentAttachments, + shortHash, +} from '../app/utils/attachments' + +const FILE = { + filename: 'invoice.pdf', + contentType: 'application/pdf', + size: 120, + sha256: '0123456789abcdef', +} + +describe('sentAttachments', () => { + it('reads the files the send log kept', () => { + expect(sentAttachments(JSON.stringify([FILE]))).toEqual([FILE]) + }) + + it('reads nothing from an absent, broken or foreign value', () => { + expect(sentAttachments(undefined)).toEqual([]) + expect(sentAttachments('{not json')).toEqual([]) + expect(sentAttachments('{"filename":"a"}')).toEqual([]) + expect(sentAttachments('[{"filename":"a"}]')).toEqual([]) + }) +}) + +describe('formatFileSize', () => { + it('picks the unit that keeps the figure readable', () => { + expect(formatFileSize(512, 'en')).toBe('512 byte') + expect(formatFileSize(2048, 'en')).toBe('2 kB') + expect(formatFileSize(2.5 * 1024 * 1024, 'en')).toBe('2.5 MB') + }) +}) + +describe('shortHash', () => { + it('keeps the first twelve characters', () => { + expect(shortHash(FILE.sha256)).toBe('0123456789ab') + }) +}) diff --git a/packages/dms-mailing/frontend-vue/tests/send-actions.test.ts b/packages/dms-mailing/frontend-vue/tests/send-actions.test.ts index 004a29ec..3e59b80c 100644 --- a/packages/dms-mailing/frontend-vue/tests/send-actions.test.ts +++ b/packages/dms-mailing/frontend-vue/tests/send-actions.test.ts @@ -64,6 +64,17 @@ describe('sendFooterActions', () => { expect(actions.map((action) => action.id)).not.toContain('fix_address') }) + it('offers no send again of a send whose files the log does not keep', () => { + const json = '[{"filename":"a.pdf","contentType":"application/pdf","size":3,"sha256":"ab"}]' + for (const status of ['failed', 'bounced', 'sent'] as const) { + const actions = sendFooterActions({ status, json_attachments: json }) + expect(actions.map((action) => action.id)).toEqual([ + 'rendering', + 'copy_address', + ]) + } + }) + it('always offers the rendering', () => { for (const status of SEND_STATUSES) expect(ids(status)).toContain('rendering') diff --git a/packages/dms-mailing/frontend-vue/tests/send-drawer.test.ts b/packages/dms-mailing/frontend-vue/tests/send-drawer.test.ts index a8fa76e4..7829c1b1 100644 --- a/packages/dms-mailing/frontend-vue/tests/send-drawer.test.ts +++ b/packages/dms-mailing/frontend-vue/tests/send-drawer.test.ts @@ -42,8 +42,8 @@ const STUBS = Object.fromEntries( STUB_NAMES.map((name) => [name, slotStub(name)]), ) -async function render(): Promise { - const { host } = mount(SendDrawer, { rowData: SEND }, STUBS) +async function render(row: SendRow = SEND): Promise { + const { host } = mount(SendDrawer, { rowData: row }, STUBS) await flush() return host } @@ -116,4 +116,32 @@ describe('send drawer layout', () => { expect(row?.getAttribute('meta')).toContain('source') expect(row?.textContent).toContain(SEND.source) }) + + it('lists the files a send carried and says the log keeps none of them', async () => { + const row: SendRow = { + ...SEND, + json_attachments: JSON.stringify([ + { + filename: 'invoice-001.pdf', + contentType: 'application/pdf', + size: 2048, + sha256: 'a'.repeat(64), + }, + ]), + } + stubApiData().respond( + mailingReads({ send: () => ({ send: row, events: [] }) }), + ) + const host = await render(row) + const listed = host.querySelector('[data-send-attachment]') + expect(listed?.textContent).toContain('invoice-001.pdf') + expect(listed?.getAttribute('meta')).toContain('2 kB') + expect(host.querySelector('[data-attachments-not-kept]')).not.toBeNull() + }) + + it('shows no attachment section for a send without files', async () => { + const host = await render() + expect(host.querySelector('[data-send-attachment]')).toBeNull() + expect(host.querySelector('[data-attachments-not-kept]')).toBeNull() + }) }) diff --git a/packages/dms-mailing/src/config.ts b/packages/dms-mailing/src/config.ts index aa3eb00b..c80dbd85 100644 --- a/packages/dms-mailing/src/config.ts +++ b/packages/dms-mailing/src/config.ts @@ -1,9 +1,21 @@ export interface DmsMailingConfig { useHtmlRender?: boolean; + /** + * Most bytes the attachments of one send add up to, before the provider's + * own limit lowers it. 10 MiB by default: base64 grows it by a third, which + * keeps the message under the 20 to 25 MB most mail servers accept. + */ + maxAttachmentBytes?: number; + /** Most files one send carries. */ + maxAttachments?: number; } +const MIB = 1024 * 1024; + const DEFAULTS: Required = { useHtmlRender: true, + maxAttachmentBytes: 10 * MIB, + maxAttachments: 10, }; let current: Required = DEFAULTS; diff --git a/packages/dms-mailing/src/db/tables/sends.table.ts b/packages/dms-mailing/src/db/tables/sends.table.ts index aef29f53..448b5870 100644 --- a/packages/dms-mailing/src/db/tables/sends.table.ts +++ b/packages/dms-mailing/src/db/tables/sends.table.ts @@ -76,6 +76,13 @@ export class MailingSend extends Table { @Field("string") declare json_variables: string; + /** + * JSON-serialized `AttachmentSummary[]`: name, type, size and hash of each + * file the e-mail carried, never its bytes. Absent for a send without any. + */ + @Field("string") + declare json_attachments?: string; + @Field("number") declare opens: number; diff --git a/packages/dms-mailing/src/implementations/dms-mailing/index.ts b/packages/dms-mailing/src/implementations/dms-mailing/index.ts index 05abc231..69ad1939 100644 --- a/packages/dms-mailing/src/implementations/dms-mailing/index.ts +++ b/packages/dms-mailing/src/implementations/dms-mailing/index.ts @@ -6,4 +6,5 @@ export { importSends as ImportSends } from "../../services/send-import"; export { declareSender as DeclareSender } from "../../services/sender-declaration"; export { declareWebhookSecret as DeclareWebhookSecret } from "../../services/webhook-secret-declaration"; export { recordEmailEvent as RecordEmailEvent } from "../../services/events"; +export { sendCapabilities as GetSendCapabilities } from "../../services/attachments"; export { sendUnlessSuppressed as SendTemplate } from "../../services/checked-send"; diff --git a/packages/dms-mailing/src/routes/sends.ts b/packages/dms-mailing/src/routes/sends.ts index 319445b0..ce683fc6 100644 --- a/packages/dms-mailing/src/routes/sends.ts +++ b/packages/dms-mailing/src/routes/sends.ts @@ -45,7 +45,8 @@ import { type CheckedSendParams, sendUnlessSuppressed, } from "../services/checked-send"; -import { MANUAL_SEND_SOURCE, SendError, subjectFor } from "../services/send"; +import { MANUAL_SEND_SOURCE, subjectFor } from "../services/send"; +import { SendError } from "../services/send-error"; import { buildSendStats, isTransportFailure, @@ -87,6 +88,8 @@ const REPLAY_SKIPPED = "$dms_mailing.sends.banner.replay_skipped"; const RECIPIENT_FIELD = "to"; const NEEDS_NEW_ADDRESS = "$dms_mailing.errors.replay_needs_new_address"; const NO_REPLAY_AFTER_SPAM = "$dms_mailing.errors.no_replay_after_spam"; +const NO_REPLAY_WITH_ATTACHMENTS = + "$dms_mailing.errors.no_replay_with_attachments"; const TEST_SEND_SOURCE = "dms-mailing:test-send"; const REPLAY_SOURCE = "dms-mailing:replay"; const FIX_ADDRESS_SOURCE = "dms-mailing:fix-address"; @@ -517,11 +520,17 @@ export class SendsController extends Controller(API_BASE_PATH) { await this.sends.linkReplayOf(result.sendId, originalId); } + /** + * Sends `send` again from what the log kept. The log keeps no attachment + * bytes, so a send that carried files is refused rather than repeated + * without them. + */ private async repeat( send: MailingSend, to: string | undefined, source: string, ): Promise { + assert(!send.json_attachments, HTTP_CONFLICT, NO_REPLAY_WITH_ATTACHMENTS); const template = await requireTemplate(this.templates, send.templateId); const version = send.templateVersion; const content = diff --git a/packages/dms-mailing/src/services/attachments.ts b/packages/dms-mailing/src/services/attachments.ts new file mode 100644 index 00000000..f9bcc116 --- /dev/null +++ b/packages/dms-mailing/src/services/attachments.ts @@ -0,0 +1,279 @@ +import { createHash } from "node:crypto"; +import type { + Attachment, + ProviderCapabilities, +} from "@antelopejs/interface-email"; +import type { + SendAttachment, + SendCapabilities, +} from "@antelopejs/interface-dms-mailing"; +import { getConfig } from "../config"; +import { sendAttachmentsSchema } from "../validation/attachments.schema"; +import { readCapabilities } from "./provider"; +import { SendError } from "./send-error"; + +/** A file of a send as the send log keeps it: everything but its bytes. */ +export interface AttachmentSummary { + filename: string; + contentType: string; + size: number; + /** Hex SHA-256 of the bytes, to match the log against the caller's archive. */ + sha256: string; +} + +/** A file the checks accepted, with the bytes the provider receives. */ +export interface CheckedAttachment extends AttachmentSummary { + content: Buffer; +} + +/** How many files, and how many bytes, one send may carry. */ +export interface AttachmentLimits { + count: number; + totalBytes: number; + fileBytes: number; +} + +const DEFAULT_CONTENT_TYPE = "application/octet-stream"; +const MIME_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/; +/** Types that would nest a MIME structure or a whole message in the e-mail. */ +const REFUSED_TOP_LEVEL_TYPES = new Set(["multipart", "message"]); +const TYPE_PARAMETERS = ";"; +const TYPE_SEPARATOR = "/"; +const PATH_SEPARATORS = /[\\/]/; +/** Control, formatting (bidi overrides, zero-width) and line-separator characters. */ +const UNSAFE_NAME_CHARACTERS = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu; +const WHITESPACE_RUN = /\s+/g; +const RESERVED_NAMES = new Set([".", ".."]); +const MAX_FILENAME_LENGTH = 200; +const MAX_EXTENSION_LENGTH = 16; +const EXTENSION_DOT = "."; +const NO_POSITION = -1; +const HASH_ALGORITHM = "sha256"; +const HASH_ENCODING = "hex"; +/** Base64 writes three bytes as four characters. */ +const BASE64_RAW_RATIO = 3 / 4; + +const invalid = (index: number, reason: string): SendError => + new SendError("invalid_attachment", `Attachment ${index}: ${reason}`); + +const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" }); + +const graphemesOf = (text: string): string[] => + Array.from(GRAPHEMES.segment(text), (part) => part.segment); + +/** `name` cut to {@link MAX_FILENAME_LENGTH} characters, its extension kept. */ +function shortened(name: string): string { + const characters = graphemesOf(name); + if (characters.length <= MAX_FILENAME_LENGTH) return name; + const dot = name.lastIndexOf(EXTENSION_DOT); + const extension = + dot > NO_POSITION && name.length - dot <= MAX_EXTENSION_LENGTH + ? name.slice(dot) + : ""; + const stemLength = MAX_FILENAME_LENGTH - graphemesOf(extension).length; + return characters.slice(0, stemLength).join("") + extension; +} + +/** + * The name a recipient sees: its last path segment, without the characters + * that could break a header or disguise its extension. + */ +export function safeFilename(name: string, index: number): string { + const segment = name.split(PATH_SEPARATORS).pop() ?? ""; + const cleaned = segment + .replace(UNSAFE_NAME_CHARACTERS, "") + .replace(WHITESPACE_RUN, " ") + .trim(); + if (!cleaned || RESERVED_NAMES.has(cleaned)) + throw invalid(index, "has no usable file name"); + return shortened(cleaned); +} + +/** `type/subtype` in lower case without parameters, or a refusal. */ +export function safeContentType( + type: string | undefined, + index: number, +): string { + if (type === undefined) return DEFAULT_CONTENT_TYPE; + const essence = (type.split(TYPE_PARAMETERS)[0] ?? "").trim().toLowerCase(); + const topLevel = essence.split(TYPE_SEPARATOR)[0] ?? ""; + if (!MIME_TYPE.test(essence) || REFUSED_TOP_LEVEL_TYPES.has(topLevel)) + throw invalid(index, `has a refused content type "${essence}"`); + return essence; +} + +function bytesOf(content: Uint8Array, index: number): Buffer { + if (content.byteLength === 0) throw invalid(index, "is empty"); + return Buffer.isBuffer(content) + ? content + : Buffer.from(content.buffer, content.byteOffset, content.byteLength); +} + +function checkedOne(entry: SendAttachment, index: number): CheckedAttachment { + const content = bytesOf(entry.content, index); + return { + filename: safeFilename(entry.filename, index), + contentType: safeContentType(entry.contentType, index), + size: content.byteLength, + sha256: createHash(HASH_ALGORITHM).update(content).digest(HASH_ENCODING), + content, + }; +} + +/** + * `input` as the attachments schema reads it. A JavaScript caller that passes + * a path, a URL or a string where the bytes belong is refused here. + */ +function parsedAttachments( + input: readonly SendAttachment[] | undefined, +): SendAttachment[] { + const parsed = sendAttachmentsSchema.safeParse(input); + if (!parsed.success) { + const index = parsed.error.issues[0]?.path[0] ?? ""; + throw new SendError( + "invalid_attachment", + `Attachment ${index}: needs a file name and its bytes as a Buffer`, + ); + } + return parsed.data ?? []; +} + +const lowered = (limit: number, providerLimit: number | undefined): number => + providerLimit === undefined ? limit : Math.min(limit, providerLimit); + +/** + * The module's ceilings, lowered to what the provider reports: its largest + * message (of which base64 leaves three quarters to raw bytes) and its + * largest file. + */ +export function attachmentLimits( + capabilities: ProviderCapabilities | null, +): AttachmentLimits { + const config = getConfig(); + const emailSize = capabilities?.maxEmailSize; + const totalBytes = lowered( + config.maxAttachmentBytes, + emailSize === undefined + ? undefined + : Math.floor(emailSize * BASE64_RAW_RATIO), + ); + return { + count: config.maxAttachments, + totalBytes, + fileBytes: lowered(totalBytes, capabilities?.maxAttachmentSize), + }; +} + +/** + * Whether the provider says it cannot carry attachments. The email + * interface's `features` has no such flag yet: a provider that adds one is + * read, one without it is taken at the interface's word, whose `EmailParams` + * carries attachments. + */ +export function refusesAttachments( + capabilities: ProviderCapabilities, +): boolean { + const { features } = capabilities; + return "attachments" in features && features.attachments === false; +} + +function assertWithin( + attachments: CheckedAttachment[], + limits: AttachmentLimits, +): void { + if (attachments.length > limits.count) + throw new SendError( + "attachments_too_large", + `${attachments.length} attachments, at most ${limits.count}`, + ); + const oversized = attachments.find((file) => file.size > limits.fileBytes); + if (oversized) + throw new SendError( + "attachments_too_large", + `"${oversized.filename}" is ${oversized.size} bytes, at most ${limits.fileBytes}`, + ); + const total = attachments.reduce((sum, file) => sum + file.size, 0); + if (total > limits.totalBytes) + throw new SendError( + "attachments_too_large", + `The attachments add up to ${total} bytes, at most ${limits.totalBytes}`, + ); +} + +/** + * The attachments of a send, checked against the module's rules and what the + * provider reports (`null` when it could not be read): a refusal throws a + * `SendError`, a file is never left out. + */ +export function checkAttachments( + input: readonly SendAttachment[] | undefined, + capabilities: ProviderCapabilities | null, +): CheckedAttachment[] { + const entries = parsedAttachments(input); + if (!entries.length) return []; + if (capabilities && refusesAttachments(capabilities)) + throw new SendError( + "attachments_unsupported", + `The e-mail provider "${capabilities.name}" cannot carry attachments`, + ); + const attachments = entries.map(checkedOne); + assertWithin(attachments, attachmentLimits(capabilities)); + return attachments; +} + +/** + * The files as the email interface sends them: bytes, never a path or a URL. + * Absent for a send without any. + */ +export function toEmailAttachments( + attachments: CheckedAttachment[], +): Attachment[] | undefined { + if (!attachments.length) return undefined; + return attachments.map(({ filename, contentType, content }) => ({ + filename, + contentType, + content, + })); +} + +/** What the send log keeps of the files; absent for a send without any. */ +export function attachmentsLog( + attachments: CheckedAttachment[], +): string | undefined { + if (!attachments.length) return undefined; + const summaries: AttachmentSummary[] = attachments.map( + ({ filename, contentType, size, sha256 }) => ({ + filename, + contentType, + size, + sha256, + }), + ); + return JSON.stringify(summaries); +} + +/** What a send can carry today: `GetSendCapabilities`. */ +export async function sendCapabilities( + read: () => Promise = readCapabilities, +): Promise { + const capabilities = await read(); + const limits = attachmentLimits(capabilities); + return { + attachments: !capabilities || !refusesAttachments(capabilities), + maxAttachments: limits.count, + maxAttachmentBytes: limits.totalBytes, + maxAttachmentFileBytes: limits.fileBytes, + provider: capabilities?.name, + }; +} + +/** + * The checked attachments of a send, reading the provider's capabilities + * only when there are some. + */ +export async function attachmentsOfSend( + input: readonly SendAttachment[] | undefined, +): Promise { + const capabilities = input?.length ? await readCapabilities() : null; + return checkAttachments(input, capabilities); +} diff --git a/packages/dms-mailing/src/services/send-error.ts b/packages/dms-mailing/src/services/send-error.ts new file mode 100644 index 00000000..3d09c15a --- /dev/null +++ b/packages/dms-mailing/src/services/send-error.ts @@ -0,0 +1,11 @@ +import type { SendErrorCode } from "@antelopejs/interface-dms-mailing"; + +/** Why a send was refused before anything left: `code` names the rule. */ +export class SendError extends Error { + constructor( + public readonly code: SendErrorCode, + message: string, + ) { + super(message); + } +} diff --git a/packages/dms-mailing/src/services/send.ts b/packages/dms-mailing/src/services/send.ts index 23b2b1db..d3969cb6 100644 --- a/packages/dms-mailing/src/services/send.ts +++ b/packages/dms-mailing/src/services/send.ts @@ -38,7 +38,14 @@ import { type TemplateContent, } from "../types"; import { publishSendCreated } from "../realtime"; +import { + attachmentsLog, + attachmentsOfSend, + type CheckedAttachment, + toEmailAttachments, +} from "./attachments"; import { renderEmailHtml } from "./render"; +import { SendError } from "./send-error"; import { getSettings } from "./settings"; import { toSendStatus } from "./status"; import { refreshAttentionIfFlagged } from "./template-attention"; @@ -54,15 +61,6 @@ import { } from "./templates"; import { isText } from "../validation/guards"; -export class SendError extends Error { - constructor( - public readonly code: string, - message: string, - ) { - super(message); - } -} - export interface PreparedSend { content: TemplateContent; locale: string; @@ -79,6 +77,8 @@ export interface PreparedSend { category: string; /** Why the template needed a look when the send started. */ attention: string; + /** The files every recipient gets, checked; empty for most sends. */ + attachments: CheckedAttachment[]; } /** @@ -273,6 +273,7 @@ export async function prepare( if (missing.length) { throw new SendError("missing_variables", missing.join(", ")); } + const attachments = await attachmentsOfSend(params.attachments); const { content, version, variables } = resolveContent(template, params); const settings = await getSettings(tenantId); const locale = pickLocale(content, params.locale, settings.fallbackLocale); @@ -287,6 +288,7 @@ export async function prepare( tenantId, category: template.category ?? "", attention: template.attention, + attachments, }; } @@ -315,6 +317,7 @@ export function messageFor( templateSlug: prepared.slug, }, tracking: { opens: true, clicks: true }, + attachments: toEmailAttachments(prepared.attachments), }; } @@ -460,6 +463,7 @@ async function record( error: outcome.error, source: params.source, json_variables: JSON.stringify(params.variables ?? {}), + json_attachments: attachmentsLog(prepared.attachments), opens: 0, clicks: 0, isTest: Boolean(params.isTest), diff --git a/packages/dms-mailing/src/test/helpers/smtp.ts b/packages/dms-mailing/src/test/helpers/smtp.ts new file mode 100644 index 00000000..1262baae --- /dev/null +++ b/packages/dms-mailing/src/test/helpers/smtp.ts @@ -0,0 +1,13 @@ +/** + * The raw messages the SMTP fixture received, oldest first. The fixture runs + * in the test process, so a test reads what nodemailer really wrote. + */ +const received: string[] = []; + +export function recordSmtpMessage(message: string): void { + received.push(message); +} + +export function smtpMessages(): string[] { + return [...received]; +} diff --git a/packages/dms-mailing/src/test/integration/send-attachments.test.ts b/packages/dms-mailing/src/test/integration/send-attachments.test.ts new file mode 100644 index 00000000..b795b0a4 --- /dev/null +++ b/packages/dms-mailing/src/test/integration/send-attachments.test.ts @@ -0,0 +1,162 @@ +import { createHash } from "node:crypto"; +import { expect } from "chai"; +import { z } from "zod"; +import { DEFAULT_TENANT_ID } from "@antelopejs/interface-dms/constants"; +import { GetModel } from "@antelopejs/interface-database-decorators"; +import { SendModel } from "../../db"; +import { suppressAddress } from "../../services/suppressions"; +import { declaration, mailing } from "../helpers/declarations"; +import { authorizedClient } from "../helpers/http"; +import { ensureOwnerSession } from "../helpers/owner"; +import { smtpMessages } from "../helpers/smtp"; + +const HTTP_CONFLICT = 409; +const stamp = Date.now(); +const slug = `attachments-${stamp}`; +const VARIABLES = { customer: { firstName: "Sofie" } }; +/** Unique bytes, so the test finds its own message among the fixture's. */ +const PDF = Buffer.from(`%PDF-1.7 invoice ${stamp}`); +const SHA256 = createHash("sha256").update(PDF).digest("hex"); + +const summarySchema = z.array( + z.object({ + filename: z.string(), + contentType: z.string(), + size: z.number(), + sha256: z.string(), + }), +); + +const invoice = { + filename: "../archive/invoice-001.pdf\r\nX-Injected: yes", + contentType: "Application/PDF", + content: PDF, +}; + +async function loggedAttachments(sendId: string) { + const send = await GetModel(SendModel, DEFAULT_TENANT_ID).get(sendId); + return summarySchema.parse(JSON.parse(send?.json_attachments ?? "null")); +} + +const EXPECTED_SUMMARY = [ + { + filename: "invoice-001.pdfX-Injected: yes", + contentType: "application/pdf", + size: PDF.byteLength, + sha256: SHA256, + }, +]; + +describe("[integration] sends with attachments", () => { + before(async () => { + const { DeclareTemplate } = await mailing(); + await DeclareTemplate(declaration(slug)); + }); + + it("delivers the file over SMTP and logs its name, size and hash only", async () => { + const { SendTemplate } = await mailing(); + const result = await SendTemplate(slug, { + tenantId: DEFAULT_TENANT_ID, + to: [`first-${stamp}@example.test`, `second-${stamp}@example.test`], + variables: VARIABLES, + attachments: [invoice], + }); + + const results = result.results ?? []; + expect(results.map((entry) => entry.status)).to.deep.equal([ + "sent", + "sent", + ]); + for (const entry of results) + expect(await loggedAttachments(entry.sendId)).to.deep.equal( + EXPECTED_SUMMARY, + ); + const send = await GetModel(SendModel, DEFAULT_TENANT_ID).get( + result.sendId, + ); + expect(send?.json_attachments).to.not.contain(PDF.toString("base64")); + + const mine = smtpMessages().filter((message) => + message.includes(PDF.toString("base64")), + ); + expect(mine).to.have.length(2); + expect(mine[0]).to.match(/Content-Type: application\/pdf/i); + expect(mine[0]).to.contain("invoice-001.pdf"); + expect(mine[0]).to.not.contain("archive"); + expect(mine[0]).to.not.match(/^X-Injected:/m); + }); + + it("logs the files of a suppressed recipient without sending them", async () => { + const { SendTemplate } = await mailing(); + const address = `suppressed-${stamp}@example.test`; + await suppressAddress(DEFAULT_TENANT_ID, { + email: address, + reason: "manual", + }); + const result = await SendTemplate(slug, { + tenantId: DEFAULT_TENANT_ID, + to: address, + variables: VARIABLES, + attachments: [invoice], + }); + + expect(result.status).to.equal("suppressed"); + expect(await loggedAttachments(result.sendId)).to.deep.equal( + EXPECTED_SUMMARY, + ); + }); + + it("refuses a file over the ceiling before anything is logged", async () => { + const { SendTemplate, GetSendCapabilities } = await mailing(); + const { maxAttachmentBytes } = await GetSendCapabilities(); + const address = `too-large-${stamp}@example.test`; + const refusal = await SendTemplate(slug, { + tenantId: DEFAULT_TENANT_ID, + to: address, + variables: VARIABLES, + attachments: [ + { + filename: "huge.bin", + content: Buffer.alloc(maxAttachmentBytes + 1), + }, + ], + }).catch((error: unknown) => error); + + expect(refusal).to.have.property("code", "attachments_too_large"); + const logged = await GetModel(SendModel, DEFAULT_TENANT_ID).getBy( + "recipientEmail", + address, + ); + expect(logged).to.have.length(0); + }); + + it("reports what a send can carry through nodemailer", async () => { + const { GetSendCapabilities } = await mailing(); + const capabilities = await GetSendCapabilities(); + expect(capabilities.attachments).to.equal(true); + expect(capabilities.maxAttachments).to.equal(10); + expect(capabilities.maxAttachmentBytes).to.equal(10 * 1024 * 1024); + }); + + it("refuses to send again a send whose files the log does not keep", async () => { + const { SendTemplate } = await mailing(); + const sent = await SendTemplate(slug, { + tenantId: DEFAULT_TENANT_ID, + to: `replay-${stamp}@example.test`, + variables: VARIABLES, + attachments: [invoice], + }); + const session = await ensureOwnerSession(); + const client = authorizedClient(session.accessToken); + + const replay = await client.post( + `/api/mailing/sends/${sent.sendId}/replay`, + {}, + ); + + expect(replay.status, JSON.stringify(replay.data)).to.equal(HTTP_CONFLICT); + expect(JSON.stringify(replay.data)).to.contain( + "$dms_mailing.errors.no_replay_with_attachments", + ); + }); +}); diff --git a/packages/dms-mailing/src/test/unit/attachments.test.ts b/packages/dms-mailing/src/test/unit/attachments.test.ts new file mode 100644 index 00000000..fb594c48 --- /dev/null +++ b/packages/dms-mailing/src/test/unit/attachments.test.ts @@ -0,0 +1,235 @@ +import { createHash } from "node:crypto"; +import type { SendAttachment } from "@antelopejs/interface-dms-mailing"; +import type { ProviderCapabilities } from "@antelopejs/interface-email"; +import { expect } from "chai"; +import { getConfig, setConfig } from "../../config"; +import { + attachmentsLog, + checkAttachments, + safeContentType, + safeFilename, + sendCapabilities, + toEmailAttachments, +} from "../../services/attachments"; +import { SendError } from "../../services/send-error"; + +const PDF = Buffer.from("%PDF-1.7 invoice"); +const MIB = 1024 * 1024; + +const capabilities = ( + overrides: Partial = {}, + features: Record = {}, +): ProviderCapabilities => ({ + name: "smtp", + features: { + batch: true, + templates: true, + providerTemplates: false, + scheduling: false, + openTracking: false, + clickTracking: false, + inlineAttachments: true, + tags: false, + metadata: false, + priority: false, + ...features, + }, + ...overrides, +}); + +const invoice = (overrides: Partial = {}): SendAttachment => ({ + filename: "invoice-2026-001.pdf", + contentType: "application/pdf", + content: PDF, + ...overrides, +}); + +function refusalCode(run: () => void): string { + try { + run(); + } catch (error) { + if (error instanceof SendError) return error.code; + throw error; + } + return ""; +} + +describe("[unit] services/attachments file names", () => { + it("keeps only the last path segment, whatever the separator", () => { + expect(safeFilename("../../etc/passwd", 0)).to.equal("passwd"); + expect(safeFilename("C:\\archive\\2026\\invoice.pdf", 0)).to.equal( + "invoice.pdf", + ); + }); + + it("removes line breaks and controls, so a name cannot start a header", () => { + expect(safeFilename("invoice.pdf\r\nBcc: victim@example.test", 0)).to.equal( + "invoice.pdfBcc: victim@example.test", + ); + expect(safeFilename("a\u0000b\u0007c.pdf", 0)).to.equal("abc.pdf"); + }); + + it("removes the bidi override that would disguise an extension", () => { + expect(safeFilename("invoice\u202Efdp.exe", 0)).to.equal("invoicefdp.exe"); + }); + + it("refuses a name left empty or reserved", () => { + expect(refusalCode(() => safeFilename("folder/", 0))).to.equal( + "invalid_attachment", + ); + expect(refusalCode(() => safeFilename("\r\n", 0))).to.equal( + "invalid_attachment", + ); + expect(refusalCode(() => safeFilename("..", 0))).to.equal( + "invalid_attachment", + ); + }); + + it("cuts a long name to 200 characters and keeps its extension", () => { + const name = safeFilename(`${"é".repeat(300)}.pdf`, 0); + expect(Array.from(name)).to.have.length(200); + expect(name.endsWith(".pdf")).to.equal(true); + }); +}); + +describe("[unit] services/attachments content types", () => { + it("lower-cases the type and drops its parameters", () => { + expect( + safeContentType('Application/PDF; name="x"\r\nX-Evil: 1', 0), + ).to.equal("application/pdf"); + }); + + it("falls back to octet-stream when the caller names none", () => { + expect(safeContentType(undefined, 0)).to.equal("application/octet-stream"); + }); + + it("refuses multipart and message types, and anything not type/subtype", () => { + for (const type of ["multipart/mixed", "message/rfc822", "pdf", "a/b c"]) + expect(refusalCode(() => safeContentType(type, 0))).to.equal( + "invalid_attachment", + ); + }); +}); + +describe("[unit] services/attachments checks", () => { + const initial = getConfig(); + afterEach(() => setConfig(initial)); + + it("hashes and sizes each file, and the log keeps no byte of it", () => { + const [checked] = checkAttachments([invoice()], capabilities()); + const sha256 = createHash("sha256").update(PDF).digest("hex"); + + expect(checked).to.include({ size: PDF.byteLength, sha256 }); + expect(JSON.parse(attachmentsLog([checked]) ?? "")).to.deep.equal([ + { + filename: "invoice-2026-001.pdf", + contentType: "application/pdf", + size: PDF.byteLength, + sha256, + }, + ]); + }); + + it("hands the provider the bytes, never a path or a URL", () => { + const sent = toEmailAttachments(checkAttachments([invoice()], null)); + expect(sent).to.deep.equal([ + { + filename: "invoice-2026-001.pdf", + contentType: "application/pdf", + content: PDF, + }, + ]); + }); + + it("accepts a plain Uint8Array without copying it", () => { + const bytes = new Uint8Array([1, 2, 3]); + const [checked] = checkAttachments([invoice({ content: bytes })], null); + expect(checked?.content.buffer).to.equal(bytes.buffer); + }); + + it("refuses a path or a URL passed where the bytes belong", () => { + const fromPath = invoice(); + Reflect.deleteProperty(fromPath, "content"); + Reflect.set(fromPath, "path", "/etc/passwd"); + const fromText = invoice(); + Reflect.set(fromText, "content", "/etc/passwd"); + for (const attachment of [fromPath, fromText]) + expect(refusalCode(() => checkAttachments([attachment], null))).to.equal( + "invalid_attachment", + ); + }); + + it("refuses an empty file", () => { + expect( + refusalCode(() => + checkAttachments([invoice({ content: Buffer.alloc(0) })], null), + ), + ).to.equal("invalid_attachment"); + }); + + it("refuses files over the configured total, and too many files", () => { + setConfig({ maxAttachmentBytes: 10, maxAttachments: 2 }); + const big = invoice({ content: Buffer.alloc(11) }); + expect(refusalCode(() => checkAttachments([big], null))).to.equal( + "attachments_too_large", + ); + const three = [1, 2, 3].map(() => invoice({ content: Buffer.alloc(1) })); + expect(refusalCode(() => checkAttachments(three, null))).to.equal( + "attachments_too_large", + ); + }); + + it("lowers the ceiling to the provider's own limits", () => { + const file = invoice({ content: Buffer.alloc(100) }); + expect( + refusalCode(() => + checkAttachments([file], capabilities({ maxAttachmentSize: 99 })), + ), + ).to.equal("attachments_too_large"); + expect( + refusalCode(() => + checkAttachments([file], capabilities({ maxEmailSize: 120 })), + ), + ).to.equal("attachments_too_large"); + }); + + it("refuses a send when the provider reports it cannot carry files", () => { + const refusing = capabilities({}, { attachments: false }); + expect(refusalCode(() => checkAttachments([invoice()], refusing))).to.equal( + "attachments_unsupported", + ); + expect(checkAttachments([], refusing)).to.deep.equal([]); + }); +}); + +describe("[unit] services/attachments capabilities", () => { + const initial = getConfig(); + afterEach(() => setConfig(initial)); + + it("reports the configured limits lowered to the provider's", async () => { + setConfig({ maxAttachmentBytes: 8 * MIB, maxAttachments: 4 }); + const read = sendCapabilities(() => + Promise.resolve(capabilities({ maxAttachmentSize: 2 * MIB })), + ); + expect(await read).to.deep.equal({ + attachments: true, + maxAttachments: 4, + maxAttachmentBytes: 8 * MIB, + maxAttachmentFileBytes: 2 * MIB, + provider: "smtp", + }); + }); + + it("reports no attachments for a provider that says it cannot", async () => { + const read = sendCapabilities(() => + Promise.resolve(capabilities({}, { attachments: false })), + ); + expect((await read).attachments).to.equal(false); + }); + + it("stays optimistic when the provider cannot be read", async () => { + const read = await sendCapabilities(() => Promise.resolve(null)); + expect(read.attachments).to.equal(true); + expect(read.provider).to.equal(undefined); + }); +}); diff --git a/packages/dms-mailing/src/test/unit/send.test.ts b/packages/dms-mailing/src/test/unit/send.test.ts index 2a2bba19..8f210e7a 100644 --- a/packages/dms-mailing/src/test/unit/send.test.ts +++ b/packages/dms-mailing/src/test/unit/send.test.ts @@ -34,6 +34,7 @@ const PREPARED: PreparedSend = { tenantId: "tenant-1", category: "", attention: "", + attachments: [], }; const SETTINGS: MailingSettingsValues = { diff --git a/packages/dms-mailing/src/validation/attachments.schema.ts b/packages/dms-mailing/src/validation/attachments.schema.ts new file mode 100644 index 00000000..e55008ba --- /dev/null +++ b/packages/dms-mailing/src/validation/attachments.schema.ts @@ -0,0 +1,14 @@ +import { z } from "zod"; + +/** + * An attachment as a caller hands it to `SendTemplate`, checked at run time + * too: a JavaScript caller can pass a path or a URL where the bytes belong, + * and any key but these three is dropped. + */ +const sendAttachmentSchema = z.object({ + filename: z.string(), + contentType: z.string().optional(), + content: z.instanceof(Uint8Array), +}); + +export const sendAttachmentsSchema = z.array(sendAttachmentSchema).optional(); diff --git a/packages/interface-dms-mailing/src/index.ts b/packages/interface-dms-mailing/src/index.ts index e2a51d69..a1618c7a 100644 --- a/packages/interface-dms-mailing/src/index.ts +++ b/packages/interface-dms-mailing/src/index.ts @@ -171,6 +171,27 @@ export interface VariableDefinition { required: boolean; } +/** + * A file a send carries, as bytes the caller already holds: the module never + * reads a path or fetches a URL for it. Every recipient of the call gets the + * same files. + */ +export interface SendAttachment { + /** + * The name the recipient sees. The module keeps its last path segment, + * removes control and formatting characters and refuses a name left empty. + */ + filename: string; + /** + * The MIME type (`application/pdf`), written in lower case without its + * parameters; `application/octet-stream` when absent. `multipart/*`, + * `message/*` and anything that is not `type/subtype` is refused. + */ + contentType?: string; + /** The file's bytes; a `Buffer` is one. An empty file is refused. */ + content: Uint8Array; +} + /** Parameters of a template send triggered from application code. */ export interface SendTemplateParams { tenantId: string; @@ -180,6 +201,52 @@ export interface SendTemplateParams { content?: TemplateContent; source?: string; isTest?: boolean; + /** + * Files the e-mail carries. The send log keeps their names, types, sizes + * and SHA-256 hashes, never their bytes, so a send with attachments cannot + * be sent again from the dashboard. See {@link GetSendCapabilities} for + * the limits. + */ + attachments?: SendAttachment[]; +} + +/** + * The `code` of the error a refused `SendTemplate` call rejects with. The + * interface does not export the error class: branch on `error.code`. + * + * - `attachments_unsupported`: the e-mail provider reports it cannot carry + * attachments. Nothing was sent or logged. + * - `attachments_too_large`: the files exceed the module's or the provider's + * ceiling, or there are too many of them. + * - `invalid_attachment`: a file has no usable name, an unaccepted type or no + * bytes. + */ +export type SendErrorCode = + | "no_recipient" + | "template_not_found" + | "template_not_live" + | "invalid_content" + | "missing_variables" + | "attachments_unsupported" + | "attachments_too_large" + | "invalid_attachment"; + +/** What a send can carry, read before sending. */ +export interface SendCapabilities { + /** + * Whether a send can carry attachments: `false` only when the provider + * reports it cannot. An unreachable provider leaves it `true`; the send + * itself then fails as any send would. + */ + attachments: boolean; + /** Most files one send carries. */ + maxAttachments: number; + /** Most bytes the files of one send add up to: the module's ceiling, lowered to the provider's. */ + maxAttachmentBytes: number; + /** Most bytes one file holds: `maxAttachmentBytes`, lowered to the provider's own per-file limit. */ + maxAttachmentFileBytes: number; + /** The provider's name, when it could be read. */ + provider?: string; } /** @@ -243,6 +310,14 @@ export const SendTemplate = (slug: string, params: SendTemplateParams) => Promise >(); +/** + * What a send can carry today, for a caller that falls back to a link when + * the files cannot travel with the e-mail. `SendTemplate` checks the same + * limits and rejects with an {@link SendErrorCode} instead of dropping a file. + */ +export const GetSendCapabilities = + InterfaceFunction<() => Promise>(); + /** Records a provider event against the send it belongs to. */ export const RecordEmailEvent = InterfaceFunction< From 3295df35c626a897abc27eb139c5d2247aec4dd8 Mon Sep 17 00:00:00 2001 From: Maxime Westhoven Date: Tue, 17 Nov 2026 09:51:12 +0100 Subject: [PATCH 2/3] docs: document attachments and verify them with a journey --- README.md | 2 +- packages/dms-mailing/docs/1.introduction.md | 2 +- packages/dms-mailing/docs/3.configuration.md | 8 ++- packages/dms-mailing/docs/5.extending.md | 22 +++++++ .../dms-mailing/skills/dms-mailing/SKILL.md | 11 +++- .../dms-mailing/src/services/attachments.ts | 10 ++-- packages/dms-mailing/src/test/helpers/smtp.ts | 18 +++--- packages/interface-dms-mailing/README.md | 2 +- .../interface-dms-mailing/docs/1.index.md | 58 ++++++++++++++++++- 9 files changed, 111 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 22b9063f..93ed8a31 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ The [module README compatibility block](packages/dms-mailing/README.md#compatibi | Package | Directory | Role | | --- | --- | --- | | [`@antelopejs/dms-mailing`](https://www.npmjs.com/package/@antelopejs/dms-mailing) | [`packages/dms-mailing`](./packages/dms-mailing) | The module: template library, block editor, send log and delivery metrics. | -| [`@antelopejs/interface-dms-mailing`](https://www.npmjs.com/package/@antelopejs/interface-dms-mailing) | [`packages/interface-dms-mailing`](./packages/interface-dms-mailing) | The interface other modules call: `SendTemplate`, `RecordEmailEvent`, `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender`, `DeclareWebhookSecret` and `ImportSends`. | +| [`@antelopejs/interface-dms-mailing`](https://www.npmjs.com/package/@antelopejs/interface-dms-mailing) | [`packages/interface-dms-mailing`](./packages/interface-dms-mailing) | The interface other modules call: `SendTemplate`, `GetSendCapabilities`, `RecordEmailEvent`, `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender`, `DeclareWebhookSecret` and `ImportSends`. | ## Documentation diff --git a/packages/dms-mailing/docs/1.introduction.md b/packages/dms-mailing/docs/1.introduction.md index 14531239..64a41b5b 100644 --- a/packages/dms-mailing/docs/1.introduction.md +++ b/packages/dms-mailing/docs/1.introduction.md @@ -43,7 +43,7 @@ A test send uses the draft by default and adds `[TEST]` to the subject. It appea The module stores templates and sends per workspace (tenant), in its own tables. E-mails render through the DMS html-render chain, so they share the DMS e-mail branding. If that renderer fails, the module falls back to its own HTML renderer. E-mails go out through the module that implements `@antelopejs/interface-email`, for example `@antelopejs/nodemailer`. -Other modules call the module through `@antelopejs/interface-dms-mailing`. They send with `SendTemplate` and report provider events with `RecordEmailEvent`. When a workspace is provisioned, they can also ship templates, categories, the sender and the webhook secret as code (`DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender`, `DeclareWebhookSecret`) and import past sends (`ImportSends`). +Other modules call the module through `@antelopejs/interface-dms-mailing`. They send with `SendTemplate`, attached files included, and report provider events with `RecordEmailEvent`. When a workspace is provisioned, they can also ship templates, categories, the sender and the webhook secret as code (`DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender`, `DeclareWebhookSecret`) and import past sends (`ImportSends`). ## Where it lives in the dashboard diff --git a/packages/dms-mailing/docs/3.configuration.md b/packages/dms-mailing/docs/3.configuration.md index 3a78846e..1be9afa6 100644 --- a/packages/dms-mailing/docs/3.configuration.md +++ b/packages/dms-mailing/docs/3.configuration.md @@ -4,15 +4,17 @@ description: The module option in antelope.config.ts and every workspace setting mode: reference --- -Mailing has one module option and a set of workspace settings edited in the dashboard. +Mailing has three module options and a set of workspace settings edited in the dashboard. -## Module option +## Module options ```typescript fragment [antelope.config.ts] "dms-mailing": { source: { type: "package", package: "@antelopejs/dms-mailing", version: "^0.10.0" }, config: { useHtmlRender: true, + maxAttachmentBytes: 10 * 1024 * 1024, + maxAttachments: 10, }, }, ``` @@ -20,6 +22,8 @@ Mailing has one module option and a set of workspace settings edited in the dash | Option | Type | Default | Description | | --- | --- | --- | --- | | `useHtmlRender` | `boolean` | `true` | Renders e-mails through the DMS html-render chain, with the DMS e-mail branding. `false` uses the module's own standalone HTML renderer. The module also falls back to that renderer when the DMS renderer fails, and logs `[dms-mailing] html-render unavailable, using fallback`. | +| `maxAttachmentBytes` | `number` | `10485760` (10 MiB) | Most bytes the [attachments](/docs/modules/mailing/extending#attach-files) of one send add up to. A provider that reports a smaller limit lowers it. Base64 makes the files a third larger in the message, so 10 MiB stays under the 20 to 25 MB most mail servers accept. | +| `maxAttachments` | `number` | `10` | Most files one send carries. | The webhook URL starts with the DMS `clientBaseUrl` from the `dms` module config. Without it, the URL starts with the DMS `apiBaseUrl`, and without that, with the origin of the API server itself. The e-mail logo comes from the DMS branding: `branding.logo.email.light`, else `branding.logo.default.light`. Only the html-render chain draws the logo. diff --git a/packages/dms-mailing/docs/5.extending.md b/packages/dms-mailing/docs/5.extending.md index 79cae385..b9634a18 100644 --- a/packages/dms-mailing/docs/5.extending.md +++ b/packages/dms-mailing/docs/5.extending.md @@ -37,6 +37,28 @@ Read `result.results` before you retry a recipient. For several recipients, the `content` sends an alternate body for an existing template without saving or publishing it. `isTest: true` marks a test send. Its subject starts with `[TEST] `, it uses the template's draft when there is one, and production figures leave it out. +### Attach files + +`attachments` sends files with the e-mail, such as the PDF of an invoice. Pass the bytes you already hold, never a path: + +```typescript fragment +const pdf = await readInvoicePdf(invoiceId); // a Buffer + +await SendTemplate("invoice-sent", { + tenantId, + to: "sofie@example.com", + variables: { invoice: { number: "2026-001" } }, + attachments: [{ filename: "invoice-2026-001.pdf", contentType: "application/pdf", content: pdf }], +}); +``` + +- Call `GetSendCapabilities()` first when you have a fallback, such as a link to the document: it says whether the provider carries files (`attachments`) and the ceilings (`maxAttachments`, `maxAttachmentBytes`, `maxAttachmentFileBytes`). +- A call the module cannot honour rejects with an error whose `code` is `attachments_unsupported`, `attachments_too_large` or `invalid_attachment`, before anything is sent or logged. A file is never dropped. +- The module keeps the last segment of the file name without control characters, lower-cases the type, and refuses `multipart/*` and `message/*`. The [consumer reference](/docs/modules/mailing/reference#attachments) lists every rule. +- **Mailing › Sends** lists each file's name and size, and keeps its SHA-256, never its bytes. A send with files cannot be sent again from the dashboard: send it again from your code. + +The ceilings default to 10 files and 10 MiB; the [module options](/docs/modules/mailing/configuration#module-options) change them. + ### Amounts and dates Pass an amount or a date as a value, and the e-mail writes it in the locale of the send. diff --git a/packages/dms-mailing/skills/dms-mailing/SKILL.md b/packages/dms-mailing/skills/dms-mailing/SKILL.md index e7d97ba7..7ef345fb 100644 --- a/packages/dms-mailing/skills/dms-mailing/SKILL.md +++ b/packages/dms-mailing/skills/dms-mailing/SKILL.md @@ -26,7 +26,8 @@ https://dms.antelopejs.com/docs/modules/mailing (sending from code and the webho - The DMS backend and renderer releases the module runs on are in the README compatibility block and in `engines["@antelopejs/dms-frontend"]` of `frontend-vue/package.json`; 0.4 is the DMS 0.8 line. Mailing 0.6 implements `@antelopejs/interface-dms-mailing` `>=0.8.0 <0.9.0`, adding declaration and import calls; interface 0.9 adds `DeclareSender`; `SendTemplate` / `RecordEmailEvent` callers do not change. -- Module option: `useHtmlRender` (default `true`, DMS html-render chain; `false` = built-in standalone HTML). +- Module options: `useHtmlRender` (default `true`, DMS html-render chain; `false` = built-in standalone HTML); + `maxAttachmentBytes` (default 10 MiB, all files of one send) and `maxAttachments` (default 10). - Set the DMS `clientBaseUrl`: the webhook URL and the e-mail logo are built on it. - Per-workspace settings (sender, missing-variable guard, fallback locale, webhook secret, retention, categories) live on the Settings page and `GET`/`PUT /api/mailing/settings` (changed fields only). @@ -51,6 +52,14 @@ const result = await SendTemplate("order-confirmed", { the template; pass every required one. - Don't pre-format amounts and dates per locale: pass `{ value: 987420, currency: "EUR" }` (minor units) or a `Date`, or an ISO string at a `date` path; the send locale formats them. Plain strings print as given. +- Files: `attachments: [{ filename, contentType?, content: Buffer }]`, the same for every recipient. Bytes only + (a path, a URL or a string is refused). `GetSendCapabilities()` → `{ attachments, maxAttachments, + maxAttachmentBytes, maxAttachmentFileBytes }` before sending, to fall back to a link. A refusal rejects before + anything is sent or logged, `error.code` = `attachments_unsupported` (provider reports `features.attachments: + false`) | `attachments_too_large` | `invalid_attachment`; a file is never dropped. Names keep their last path + segment without control characters, types are lower-cased, `multipart/*` and `message/*` refused. The log keeps + name, type, size and SHA-256, never the bytes, so the dashboard cannot send it again (409 + `no_replay_with_attachments`): resend from code. The automation action takes no attachments. - In-process events: `RecordEmailEvent(tenantId, { provider, messageId, type, details })`. HTTP: `POST /api/mailing/events//` with header `x-mailing-webhook-secret`. - Automation (if `interface-dms-automation` is loaded): action `mailing.send-template`, trigger `mailing.email-event`. diff --git a/packages/dms-mailing/src/services/attachments.ts b/packages/dms-mailing/src/services/attachments.ts index f9bcc116..7faea7ec 100644 --- a/packages/dms-mailing/src/services/attachments.ts +++ b/packages/dms-mailing/src/services/attachments.ts @@ -13,7 +13,7 @@ import { readCapabilities } from "./provider"; import { SendError } from "./send-error"; /** A file of a send as the send log keeps it: everything but its bytes. */ -export interface AttachmentSummary { +interface AttachmentSummary { filename: string; contentType: string; size: number; @@ -27,7 +27,7 @@ export interface CheckedAttachment extends AttachmentSummary { } /** How many files, and how many bytes, one send may carry. */ -export interface AttachmentLimits { +interface AttachmentLimits { count: number; totalBytes: number; fileBytes: number; @@ -146,7 +146,7 @@ const lowered = (limit: number, providerLimit: number | undefined): number => * message (of which base64 leaves three quarters to raw bytes) and its * largest file. */ -export function attachmentLimits( +function attachmentLimits( capabilities: ProviderCapabilities | null, ): AttachmentLimits { const config = getConfig(); @@ -170,9 +170,7 @@ export function attachmentLimits( * read, one without it is taken at the interface's word, whose `EmailParams` * carries attachments. */ -export function refusesAttachments( - capabilities: ProviderCapabilities, -): boolean { +function refusesAttachments(capabilities: ProviderCapabilities): boolean { const { features } = capabilities; return "attachments" in features && features.attachments === false; } diff --git a/packages/dms-mailing/src/test/helpers/smtp.ts b/packages/dms-mailing/src/test/helpers/smtp.ts index 1262baae..f5d849d0 100644 --- a/packages/dms-mailing/src/test/helpers/smtp.ts +++ b/packages/dms-mailing/src/test/helpers/smtp.ts @@ -1,13 +1,17 @@ -/** - * The raw messages the SMTP fixture received, oldest first. The fixture runs - * in the test process, so a test reads what nodemailer really wrote. - */ -const received: string[] = []; +declare global { + /** + * The raw messages the SMTP fixture received, oldest first: a global, since + * the fixture's copy of this module is not the one the tests import. + */ + var dmsMailingSmtpMessages: string[] | undefined; +} export function recordSmtpMessage(message: string): void { - received.push(message); + globalThis.dmsMailingSmtpMessages ??= []; + globalThis.dmsMailingSmtpMessages.push(message); } +/** What nodemailer really wrote to the fixture, oldest first. */ export function smtpMessages(): string[] { - return [...received]; + return [...(globalThis.dmsMailingSmtpMessages ?? [])]; } diff --git a/packages/interface-dms-mailing/README.md b/packages/interface-dms-mailing/README.md index d2f3b7d2..d6634ab0 100644 --- a/packages/interface-dms-mailing/README.md +++ b/packages/interface-dms-mailing/README.md @@ -13,7 +13,7 @@ The AntelopeJS interface to send DMS mailing templates and report e-mail events ## What it does -- Sends a published template by its slug, to one recipient or many, in a given locale and with its variables (`SendTemplate`). +- Sends a published template by its slug, to one recipient or many, in a given locale and with its variables and attached files (`SendTemplate`), and says what a send can carry (`GetSendCapabilities`). - Reports a provider event (delivered, opened, clicked, bounced…) against the send it belongs to (`RecordEmailEvent`). - Ships templates and template categories as code when a workspace is provisioned (`DeclareTemplate`, `DeclareTemplateCategory`). A declaration writes once: a template is created already published, and a slug or category id the workspace already has is left as it is. - Writes the workspace sender when a workspace is provisioned (`DeclareSender`). diff --git a/packages/interface-dms-mailing/docs/1.index.md b/packages/interface-dms-mailing/docs/1.index.md index 0ee1b7d4..f7cf3977 100644 --- a/packages/interface-dms-mailing/docs/1.index.md +++ b/packages/interface-dms-mailing/docs/1.index.md @@ -4,9 +4,9 @@ description: Consumer contract for sending templates and recording provider even mode: reference --- -`@antelopejs/interface-dms-mailing` exports seven backend functions and the template types below. `SendTemplate` sends, `RecordEmailEvent` reports provider events, `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender` and `DeclareWebhookSecret` ship templates, categories, the sender and the webhook secret as code, and `ImportSends` imports past sends. They need `@antelopejs/dms-mailing` and an `@antelopejs/interface-email` provider loaded, and are imported from the interface package, not the runtime module's services. +`@antelopejs/interface-dms-mailing` exports eight backend functions and the template types below. `SendTemplate` sends, `GetSendCapabilities` says what a send can carry, `RecordEmailEvent` reports provider events, `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender` and `DeclareWebhookSecret` ship templates, categories, the sender and the webhook secret as code, and `ImportSends` imports past sends. They need `@antelopejs/dms-mailing` and an `@antelopejs/interface-email` provider loaded, and are imported from the interface package, not the runtime module's services. -All seven take an explicit `tenantId`. They are trusted backend calls, not permission-checked HTTP endpoints, so the calling module authenticates and authorizes the tenant. A missing implementation or a storage failure rejects the promise. +All but `GetSendCapabilities` take an explicit `tenantId`. They are trusted backend calls, not permission-checked HTTP endpoints, so the calling module authenticates and authorizes the tenant. A missing implementation or a storage failure rejects the promise. ## Per-recipient results @@ -46,6 +46,13 @@ interface SendTemplateParams { content?: TemplateContent; source?: string; isTest?: boolean; + attachments?: SendAttachment[]; +} + +interface SendAttachment { + filename: string; + contentType?: string; // application/octet-stream when absent + content: Uint8Array; // a Buffer is one } interface SendTemplateResult { @@ -79,10 +86,55 @@ A suppressed address gets no e-mail. Its result has `status: "suppressed"` and a Provider failures become `failed` recipient results. If recording a send fails, its result has `sendId: ""`, `status: "failed"` and an error, and can still carry a provider `messageId`, because delivery may have happened. A `failed` result does not prove that no e-mail left, and retrying the whole call can deliver twice. -Validation failures reject the promise instead of returning recipient results. The runtime's errors carry one of these codes: `no_recipient`, `template_not_found`, `template_not_live`, `invalid_content` or `missing_variables`. The interface does not export the error class. The workspace's **Missing variables** setting decides whether missing variables refuse a send. Marketing footer URLs are required system variables when the template uses them, never for test sends. Storage or notification failures can reject after side effects started, so the call is neither transactional nor idempotent. +Validation failures reject the promise instead of returning recipient results. The runtime's errors carry a `code` typed `SendErrorCode`: `no_recipient`, `template_not_found`, `template_not_live`, `invalid_content`, `missing_variables`, or for [attachments](#attachments) `attachments_unsupported`, `attachments_too_large` or `invalid_attachment`. The interface does not export the error class, so branch on `error.code`. The workspace's **Missing variables** setting decides whether missing variables refuse a send. Marketing footer URLs are required system variables when the template uses them, never for test sends. Storage or notification failures can reject after side effects started, so the call is neither transactional nor idempotent. `variables` is `TemplateVariables`, a record of strings, numbers, booleans, `null`, `Date` values, money values (`{ value: 987420, currency: "EUR" }`, in the currency's minor unit), and lists and records of the same. Dates and money are written in the send's locale. A class instance or a function does not compile, and a template path reads only the keys a record owns. +### Attachments + +`attachments` sends files with the e-mail: the PDF of a quote, an invoice, a signed contract. Every recipient of the call gets the same files. + +```ts docs-check +import { GetSendCapabilities, SendTemplate } from "@antelopejs/interface-dms-mailing"; + +export async function sendInvoice(tenantId: string, to: string, pdf: Buffer) { + const capabilities = await GetSendCapabilities(); + const fits = capabilities.attachments && pdf.byteLength <= capabilities.maxAttachmentFileBytes; + return SendTemplate("invoice-sent", { + tenantId, + to, + variables: { invoice: { number: "2026-001" } }, + attachments: fits ? [{ filename: "invoice-2026-001.pdf", contentType: "application/pdf", content: pdf }] : [], + }); +} +``` + +- **Bytes only.** `content` is a `Uint8Array` (a `Buffer` is one) the caller already read. The module never reads a path or fetches a URL, and a `path`, a `url` or a string where the bytes belong rejects with `invalid_attachment`. Interface functions are in-process calls, so the bytes are not serialized on the way in. +- **Names.** The module keeps the last segment of `filename` (after the last `/` or `\`), removes control and formatting characters (line breaks, bidi overrides, zero-width characters) and cuts it to 200 characters, its extension kept. A name left empty, `.` or `..` rejects with `invalid_attachment`. +- **Types.** `contentType` is written in lower case without its parameters (`Application/PDF; name=x` gives `application/pdf`). Without one, the file is `application/octet-stream`. `multipart/*`, `message/*` and anything that is not `type/subtype` reject with `invalid_attachment`. An empty file does too. +- **Limits.** At most 10 files and 10 MiB in all by default, set by the module options `maxAttachments` and `maxAttachmentBytes`. A provider that reports a `maxEmailSize` lowers the total to three quarters of it (base64 makes the files a third larger), and one that reports a `maxAttachmentSize` caps each file. Over a limit, the call rejects with `attachments_too_large`. +- **Providers.** A provider whose capabilities report `features.attachments: false` makes a call with files reject with `attachments_unsupported`: a file is never dropped. The email interface 0.2 has no such flag yet, so a provider that does not report it is taken to carry attachments, as its `EmailParams.attachments` promises. Nodemailer and Brevo both carry them. +- **Checked first.** Every check runs before anything is sent or logged, suppressed recipients included, so a refused call leaves no row. +- **The send log** keeps each file's name, type, size and SHA-256 (`json_attachments` on the send), never its bytes, for every recipient, a suppressed one included. The send's panel lists them. +- **No send again.** Since the bytes are not kept, **Send again**, **Send to a corrected address** and **Send the failures again** refuse a send that carried files (`409`, `no_replay_with_attachments`): send it again from your code, which holds the files. The module has no queue or retry of its own, and the automation action `mailing.send-template` takes no attachments. +- Previews and test sends from the dashboard carry no attachment. + +### `GetSendCapabilities` + +```ts [Contract] +interface SendCapabilities { + attachments: boolean; // false when the provider reports it cannot carry files + maxAttachments: number; + maxAttachmentBytes: number; // all files of one send + maxAttachmentFileBytes: number; // one file + provider?: string; +} + +declare function GetSendCapabilities(): Promise; +``` + +It reads the provider's capabilities (kept for a minute) and the module options, and applies the rules above, so a caller can send a link instead of a file that would be refused. An unreachable provider leaves `attachments` true: the send itself then fails as any send would. `SendTemplate` applies the same checks, so a caller that skips this call gets the typed rejection instead. + ## `RecordEmailEvent` ```ts [Contract] From 71a020ef084e1e92642429754b3d2c9e3364b1fa Mon Sep 17 00:00:00 2001 From: Antony Rizzitelli Date: Fri, 20 Nov 2026 14:43:15 +0000 Subject: [PATCH 3/3] refactor(dms-mailing): cut attachments down to the pass-through Keep SendTemplateParams.attachments, their pass-through to the email provider, one fixed ceiling (10 files, 10 MiB), the file name's last path segment without line breaks, the json_attachments log summary, the 409 on a replay and the file list in the send drawer. Drop GetSendCapabilities and SendCapabilities, SendErrorCode, the provider features probe, the maxAttachments and maxAttachmentBytes options, the zod schema, the grapheme, bidi, MIME type and multipart rules, the journey (the integration test covers it) and the test SMTP recorder, which main's mail store replaces. --- README.md | 2 +- packages/dms-mailing/docs/3.configuration.md | 8 +- packages/dms-mailing/docs/5.extending.md | 9 +- .../app/components/SendDrawer.vue | 22 +- .../frontend-vue/app/utils/attachments.ts | 44 +-- .../i18n/locales/mailing-en-GB.json | 4 - .../i18n/locales/mailing-fr-FR.json | 4 - .../frontend-vue/tests/attachments.test.ts | 24 +- .../frontend-vue/tests/send-actions.test.ts | 3 +- .../frontend-vue/tests/send-drawer.test.ts | 4 +- .../dms-mailing/skills/dms-mailing/SKILL.md | 14 +- packages/dms-mailing/src/config.ts | 12 - .../dms-mailing/src/db/tables/sends.table.ts | 5 +- .../src/implementations/dms-mailing/index.ts | 1 - packages/dms-mailing/src/routes/sends.ts | 5 - .../dms-mailing/src/services/attachments.ts | 286 ++---------------- .../dms-mailing/src/services/send-error.ts | 4 +- packages/dms-mailing/src/services/send.ts | 16 +- packages/dms-mailing/src/test/helpers/smtp.ts | 17 -- .../test/integration/send-attachments.test.ts | 24 +- .../src/test/unit/attachments.test.ts | 235 -------------- .../dms-mailing/src/test/unit/send.test.ts | 1 - .../src/validation/attachments.schema.ts | 14 - packages/interface-dms-mailing/README.md | 2 +- .../interface-dms-mailing/docs/1.index.md | 53 +--- packages/interface-dms-mailing/src/index.ts | 72 +---- 26 files changed, 100 insertions(+), 785 deletions(-) delete mode 100644 packages/dms-mailing/src/test/helpers/smtp.ts delete mode 100644 packages/dms-mailing/src/test/unit/attachments.test.ts delete mode 100644 packages/dms-mailing/src/validation/attachments.schema.ts diff --git a/README.md b/README.md index 93ed8a31..22b9063f 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ The [module README compatibility block](packages/dms-mailing/README.md#compatibi | Package | Directory | Role | | --- | --- | --- | | [`@antelopejs/dms-mailing`](https://www.npmjs.com/package/@antelopejs/dms-mailing) | [`packages/dms-mailing`](./packages/dms-mailing) | The module: template library, block editor, send log and delivery metrics. | -| [`@antelopejs/interface-dms-mailing`](https://www.npmjs.com/package/@antelopejs/interface-dms-mailing) | [`packages/interface-dms-mailing`](./packages/interface-dms-mailing) | The interface other modules call: `SendTemplate`, `GetSendCapabilities`, `RecordEmailEvent`, `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender`, `DeclareWebhookSecret` and `ImportSends`. | +| [`@antelopejs/interface-dms-mailing`](https://www.npmjs.com/package/@antelopejs/interface-dms-mailing) | [`packages/interface-dms-mailing`](./packages/interface-dms-mailing) | The interface other modules call: `SendTemplate`, `RecordEmailEvent`, `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender`, `DeclareWebhookSecret` and `ImportSends`. | ## Documentation diff --git a/packages/dms-mailing/docs/3.configuration.md b/packages/dms-mailing/docs/3.configuration.md index 1be9afa6..3a78846e 100644 --- a/packages/dms-mailing/docs/3.configuration.md +++ b/packages/dms-mailing/docs/3.configuration.md @@ -4,17 +4,15 @@ description: The module option in antelope.config.ts and every workspace setting mode: reference --- -Mailing has three module options and a set of workspace settings edited in the dashboard. +Mailing has one module option and a set of workspace settings edited in the dashboard. -## Module options +## Module option ```typescript fragment [antelope.config.ts] "dms-mailing": { source: { type: "package", package: "@antelopejs/dms-mailing", version: "^0.10.0" }, config: { useHtmlRender: true, - maxAttachmentBytes: 10 * 1024 * 1024, - maxAttachments: 10, }, }, ``` @@ -22,8 +20,6 @@ Mailing has three module options and a set of workspace settings edited in the d | Option | Type | Default | Description | | --- | --- | --- | --- | | `useHtmlRender` | `boolean` | `true` | Renders e-mails through the DMS html-render chain, with the DMS e-mail branding. `false` uses the module's own standalone HTML renderer. The module also falls back to that renderer when the DMS renderer fails, and logs `[dms-mailing] html-render unavailable, using fallback`. | -| `maxAttachmentBytes` | `number` | `10485760` (10 MiB) | Most bytes the [attachments](/docs/modules/mailing/extending#attach-files) of one send add up to. A provider that reports a smaller limit lowers it. Base64 makes the files a third larger in the message, so 10 MiB stays under the 20 to 25 MB most mail servers accept. | -| `maxAttachments` | `number` | `10` | Most files one send carries. | The webhook URL starts with the DMS `clientBaseUrl` from the `dms` module config. Without it, the URL starts with the DMS `apiBaseUrl`, and without that, with the origin of the API server itself. The e-mail logo comes from the DMS branding: `branding.logo.email.light`, else `branding.logo.default.light`. Only the html-render chain draws the logo. diff --git a/packages/dms-mailing/docs/5.extending.md b/packages/dms-mailing/docs/5.extending.md index b9634a18..27efd21e 100644 --- a/packages/dms-mailing/docs/5.extending.md +++ b/packages/dms-mailing/docs/5.extending.md @@ -39,7 +39,7 @@ Read `result.results` before you retry a recipient. For several recipients, the ### Attach files -`attachments` sends files with the e-mail, such as the PDF of an invoice. Pass the bytes you already hold, never a path: +`attachments` sends files with the e-mail, such as the PDF of an invoice. Pass the bytes you already hold: ```typescript fragment const pdf = await readInvoicePdf(invoiceId); // a Buffer @@ -52,13 +52,10 @@ await SendTemplate("invoice-sent", { }); ``` -- Call `GetSendCapabilities()` first when you have a fallback, such as a link to the document: it says whether the provider carries files (`attachments`) and the ceilings (`maxAttachments`, `maxAttachmentBytes`, `maxAttachmentFileBytes`). -- A call the module cannot honour rejects with an error whose `code` is `attachments_unsupported`, `attachments_too_large` or `invalid_attachment`, before anything is sent or logged. A file is never dropped. -- The module keeps the last segment of the file name without control characters, lower-cases the type, and refuses `multipart/*` and `message/*`. The [consumer reference](/docs/modules/mailing/reference#attachments) lists every rule. +- Every recipient of the call gets the same files. A file name keeps its last path segment, without line breaks. +- A send carries at most 10 files, adding up to at most 10 MiB. Over that, the call rejects with `code` `attachments_too_large` before anything is sent or logged. - **Mailing › Sends** lists each file's name and size, and keeps its SHA-256, never its bytes. A send with files cannot be sent again from the dashboard: send it again from your code. -The ceilings default to 10 files and 10 MiB; the [module options](/docs/modules/mailing/configuration#module-options) change them. - ### Amounts and dates Pass an amount or a date as a value, and the e-mail writes it in the locale of the send. diff --git a/packages/dms-mailing/frontend-vue/app/components/SendDrawer.vue b/packages/dms-mailing/frontend-vue/app/components/SendDrawer.vue index 2d3e6434..600bea83 100644 --- a/packages/dms-mailing/frontend-vue/app/components/SendDrawer.vue +++ b/packages/dms-mailing/frontend-vue/app/components/SendDrawer.vue @@ -19,7 +19,7 @@ import { type SendActionId, } from '../utils/send-actions' import { renderingTitleKey } from '../utils/rendering-title' -import { formatFileSize, sentAttachments, shortHash } from '../utils/attachments' +import { formatFileSize, sentAttachments } from '../utils/attachments' import { formatLatency, isSlowLatency } from '../utils/send-stats' import { isSuppressedStatus, @@ -212,7 +212,9 @@ const stats = computed(() => { ] }) -const attachments = computed(() => sentAttachments(send.value?.json_attachments)) +const attachments = computed(() => + sentAttachments(send.value?.json_attachments), +) const originTitle = computed(() => { const template = detail.value?.template @@ -604,15 +606,12 @@ onMounted(() => { @@ -637,13 +636,6 @@ onMounted(() => { -

- {{ key('attachments_not_kept') }} -

diff --git a/packages/dms-mailing/frontend-vue/app/utils/attachments.ts b/packages/dms-mailing/frontend-vue/app/utils/attachments.ts index 0d43ab02..e425f2e5 100644 --- a/packages/dms-mailing/frontend-vue/app/utils/attachments.ts +++ b/packages/dms-mailing/frontend-vue/app/utils/attachments.ts @@ -1,25 +1,18 @@ /** A file a send carried, as the send log keeps it: never its bytes. */ export interface SentAttachment { filename: string - contentType: string size: number - sha256: string } const KILOBYTE = 1024 -const MEGABYTE = KILOBYTE * KILOBYTE -const SHORT_HASH_LENGTH = 12 -function isSentAttachment(value: unknown): value is SentAttachment { - if (typeof value !== 'object' || value === null) return false - const entry = value as Record - return ( - typeof entry.filename === 'string' && - typeof entry.contentType === 'string' && - typeof entry.size === 'number' && - typeof entry.sha256 === 'string' - ) -} +const isSentAttachment = (value: unknown): value is SentAttachment => + typeof value === 'object' && + value !== null && + 'filename' in value && + typeof value.filename === 'string' && + 'size' in value && + typeof value.size === 'number' /** The files of a send's `json_attachments`; none when absent or unreadable. */ export function sentAttachments(json: string | undefined): SentAttachment[] { @@ -32,22 +25,11 @@ export function sentAttachments(json: string | undefined): SentAttachment[] { } } -/** `size` in the largest unit that keeps it above one: "120 kB", "2.4 MB". */ -export function formatFileSize(size: number, locale: string): string { - const [value, unit] = - size >= MEGABYTE - ? [size / MEGABYTE, 'megabyte'] - : size >= KILOBYTE - ? [size / KILOBYTE, 'kilobyte'] - : [size, 'byte'] - return new Intl.NumberFormat(locale, { +/** `size` in kilobytes, at least one: "120 kB", "2,048 kB". */ +export const formatFileSize = (size: number, locale: string): string => + new Intl.NumberFormat(locale, { style: 'unit', - unit, + unit: 'kilobyte', unitDisplay: 'short', - maximumFractionDigits: 1, - }).format(value) -} - -/** The start of a file's SHA-256, enough to match it against an archive by eye. */ -export const shortHash = (sha256: string): string => - sha256.slice(0, SHORT_HASH_LENGTH) + maximumFractionDigits: 0, + }).format(Math.max(1, Math.round(size / KILOBYTE))) diff --git a/packages/dms-mailing/frontend-vue/i18n/locales/mailing-en-GB.json b/packages/dms-mailing/frontend-vue/i18n/locales/mailing-en-GB.json index d386fcdc..3374ce9c 100644 --- a/packages/dms-mailing/frontend-vue/i18n/locales/mailing-en-GB.json +++ b/packages/dms-mailing/frontend-vue/i18n/locales/mailing-en-GB.json @@ -412,9 +412,6 @@ "nothing_to_publish": "This template has no content to publish yet.", "replay_needs_new_address": "This address bounced. Send to a corrected address instead.", "no_replay_with_attachments": "This e-mail carried attachments, which the send log does not keep. Send it again from the application that sent it.", - "attachments_unsupported": "The e-mail provider cannot send attachments.", - "attachments_too_large": "The attachments are too large, or too many.", - "invalid_attachment": "An attachment has no usable name, an unaccepted type or no content.", "starter_not_found": "This starter template does not exist.", "template_in_use": "Only an archived template that was never sent can be deleted. Archive it instead.", "invalid_template": "The template name or slug is invalid.", @@ -504,7 +501,6 @@ }, "description": "Every e-mail your workspace sent: to whom, with which data, and what the provider reported back.", "drawer": { - "attachments_not_kept": "The send log keeps their name, size and fingerprint, not the files: this e-mail cannot be sent again from here.", "latency": "API latency", "locale": "Locale", "payload": "Data sent", diff --git a/packages/dms-mailing/frontend-vue/i18n/locales/mailing-fr-FR.json b/packages/dms-mailing/frontend-vue/i18n/locales/mailing-fr-FR.json index 4f64502f..01ca6842 100644 --- a/packages/dms-mailing/frontend-vue/i18n/locales/mailing-fr-FR.json +++ b/packages/dms-mailing/frontend-vue/i18n/locales/mailing-fr-FR.json @@ -412,9 +412,6 @@ "nothing_to_publish": "Ce modèle n’a pas encore de contenu à publier.", "replay_needs_new_address": "Cette adresse a rebondi. Envoyez plutôt à une adresse corrigée.", "no_replay_with_attachments": "Cet e-mail portait des pièces jointes, que le journal des envois ne garde pas. Renvoyez-le depuis l’application qui l’a envoyé.", - "attachments_unsupported": "Le fournisseur d’e-mails ne peut pas envoyer de pièces jointes.", - "attachments_too_large": "Les pièces jointes sont trop lourdes, ou trop nombreuses.", - "invalid_attachment": "Une pièce jointe n’a pas de nom utilisable, a un type refusé ou est vide.", "starter_not_found": "Ce modèle de départ n’existe pas.", "template_in_use": "Seul un modèle archivé et jamais envoyé peut être supprimé. Archivez-le plutôt.", "invalid_template": "Le nom ou le slug du modèle est invalide.", @@ -504,7 +501,6 @@ }, "description": "Chaque e-mail envoyé par votre espace de travail : à qui, avec quelles données, et ce que le fournisseur a répondu.", "drawer": { - "attachments_not_kept": "Le journal des envois garde leur nom, leur taille et leur empreinte, pas les fichiers : cet e-mail ne peut pas être renvoyé d’ici.", "latency": "Latence API", "locale": "Langue", "payload": "Données envoyées", diff --git a/packages/dms-mailing/frontend-vue/tests/attachments.test.ts b/packages/dms-mailing/frontend-vue/tests/attachments.test.ts index 07c99c5e..c810e0a9 100644 --- a/packages/dms-mailing/frontend-vue/tests/attachments.test.ts +++ b/packages/dms-mailing/frontend-vue/tests/attachments.test.ts @@ -1,16 +1,7 @@ import { describe, expect, it } from 'vitest' -import { - formatFileSize, - sentAttachments, - shortHash, -} from '../app/utils/attachments' +import { formatFileSize, sentAttachments } from '../app/utils/attachments' -const FILE = { - filename: 'invoice.pdf', - contentType: 'application/pdf', - size: 120, - sha256: '0123456789abcdef', -} +const FILE = { filename: 'invoice.pdf', size: 120 } describe('sentAttachments', () => { it('reads the files the send log kept', () => { @@ -26,15 +17,8 @@ describe('sentAttachments', () => { }) describe('formatFileSize', () => { - it('picks the unit that keeps the figure readable', () => { - expect(formatFileSize(512, 'en')).toBe('512 byte') + it('writes kilobytes, never zero', () => { + expect(formatFileSize(120, 'en')).toBe('1 kB') expect(formatFileSize(2048, 'en')).toBe('2 kB') - expect(formatFileSize(2.5 * 1024 * 1024, 'en')).toBe('2.5 MB') - }) -}) - -describe('shortHash', () => { - it('keeps the first twelve characters', () => { - expect(shortHash(FILE.sha256)).toBe('0123456789ab') }) }) diff --git a/packages/dms-mailing/frontend-vue/tests/send-actions.test.ts b/packages/dms-mailing/frontend-vue/tests/send-actions.test.ts index 3e59b80c..6dd41c94 100644 --- a/packages/dms-mailing/frontend-vue/tests/send-actions.test.ts +++ b/packages/dms-mailing/frontend-vue/tests/send-actions.test.ts @@ -65,7 +65,8 @@ describe('sendFooterActions', () => { }) it('offers no send again of a send whose files the log does not keep', () => { - const json = '[{"filename":"a.pdf","contentType":"application/pdf","size":3,"sha256":"ab"}]' + const json = + '[{"filename":"a.pdf","contentType":"application/pdf","size":3,"sha256":"ab"}]' for (const status of ['failed', 'bounced', 'sent'] as const) { const actions = sendFooterActions({ status, json_attachments: json }) expect(actions.map((action) => action.id)).toEqual([ diff --git a/packages/dms-mailing/frontend-vue/tests/send-drawer.test.ts b/packages/dms-mailing/frontend-vue/tests/send-drawer.test.ts index 7829c1b1..c2e70caf 100644 --- a/packages/dms-mailing/frontend-vue/tests/send-drawer.test.ts +++ b/packages/dms-mailing/frontend-vue/tests/send-drawer.test.ts @@ -117,7 +117,7 @@ describe('send drawer layout', () => { expect(row?.textContent).toContain(SEND.source) }) - it('lists the files a send carried and says the log keeps none of them', async () => { + it('lists the files a send carried', async () => { const row: SendRow = { ...SEND, json_attachments: JSON.stringify([ @@ -136,12 +136,10 @@ describe('send drawer layout', () => { const listed = host.querySelector('[data-send-attachment]') expect(listed?.textContent).toContain('invoice-001.pdf') expect(listed?.getAttribute('meta')).toContain('2 kB') - expect(host.querySelector('[data-attachments-not-kept]')).not.toBeNull() }) it('shows no attachment section for a send without files', async () => { const host = await render() expect(host.querySelector('[data-send-attachment]')).toBeNull() - expect(host.querySelector('[data-attachments-not-kept]')).toBeNull() }) }) diff --git a/packages/dms-mailing/skills/dms-mailing/SKILL.md b/packages/dms-mailing/skills/dms-mailing/SKILL.md index 7ef345fb..4acfb498 100644 --- a/packages/dms-mailing/skills/dms-mailing/SKILL.md +++ b/packages/dms-mailing/skills/dms-mailing/SKILL.md @@ -26,8 +26,7 @@ https://dms.antelopejs.com/docs/modules/mailing (sending from code and the webho - The DMS backend and renderer releases the module runs on are in the README compatibility block and in `engines["@antelopejs/dms-frontend"]` of `frontend-vue/package.json`; 0.4 is the DMS 0.8 line. Mailing 0.6 implements `@antelopejs/interface-dms-mailing` `>=0.8.0 <0.9.0`, adding declaration and import calls; interface 0.9 adds `DeclareSender`; `SendTemplate` / `RecordEmailEvent` callers do not change. -- Module options: `useHtmlRender` (default `true`, DMS html-render chain; `false` = built-in standalone HTML); - `maxAttachmentBytes` (default 10 MiB, all files of one send) and `maxAttachments` (default 10). +- Module option: `useHtmlRender` (default `true`, DMS html-render chain; `false` = built-in standalone HTML). - Set the DMS `clientBaseUrl`: the webhook URL and the e-mail logo are built on it. - Per-workspace settings (sender, missing-variable guard, fallback locale, webhook secret, retention, categories) live on the Settings page and `GET`/`PUT /api/mailing/settings` (changed fields only). @@ -52,14 +51,9 @@ const result = await SendTemplate("order-confirmed", { the template; pass every required one. - Don't pre-format amounts and dates per locale: pass `{ value: 987420, currency: "EUR" }` (minor units) or a `Date`, or an ISO string at a `date` path; the send locale formats them. Plain strings print as given. -- Files: `attachments: [{ filename, contentType?, content: Buffer }]`, the same for every recipient. Bytes only - (a path, a URL or a string is refused). `GetSendCapabilities()` → `{ attachments, maxAttachments, - maxAttachmentBytes, maxAttachmentFileBytes }` before sending, to fall back to a link. A refusal rejects before - anything is sent or logged, `error.code` = `attachments_unsupported` (provider reports `features.attachments: - false`) | `attachments_too_large` | `invalid_attachment`; a file is never dropped. Names keep their last path - segment without control characters, types are lower-cased, `multipart/*` and `message/*` refused. The log keeps - name, type, size and SHA-256, never the bytes, so the dashboard cannot send it again (409 - `no_replay_with_attachments`): resend from code. The automation action takes no attachments. +- Files: `attachments: [{ filename, contentType?, content: Buffer }]`, the same for every recipient; at most 10 files + and 10 MiB, else `error.code` = `attachments_too_large` before anything is sent. The log keeps name, type, size and + SHA-256, never the bytes, so the dashboard cannot send it again (409 `no_replay_with_attachments`): resend from code. - In-process events: `RecordEmailEvent(tenantId, { provider, messageId, type, details })`. HTTP: `POST /api/mailing/events//` with header `x-mailing-webhook-secret`. - Automation (if `interface-dms-automation` is loaded): action `mailing.send-template`, trigger `mailing.email-event`. diff --git a/packages/dms-mailing/src/config.ts b/packages/dms-mailing/src/config.ts index c80dbd85..aa3eb00b 100644 --- a/packages/dms-mailing/src/config.ts +++ b/packages/dms-mailing/src/config.ts @@ -1,21 +1,9 @@ export interface DmsMailingConfig { useHtmlRender?: boolean; - /** - * Most bytes the attachments of one send add up to, before the provider's - * own limit lowers it. 10 MiB by default: base64 grows it by a third, which - * keeps the message under the 20 to 25 MB most mail servers accept. - */ - maxAttachmentBytes?: number; - /** Most files one send carries. */ - maxAttachments?: number; } -const MIB = 1024 * 1024; - const DEFAULTS: Required = { useHtmlRender: true, - maxAttachmentBytes: 10 * MIB, - maxAttachments: 10, }; let current: Required = DEFAULTS; diff --git a/packages/dms-mailing/src/db/tables/sends.table.ts b/packages/dms-mailing/src/db/tables/sends.table.ts index 448b5870..ea24e580 100644 --- a/packages/dms-mailing/src/db/tables/sends.table.ts +++ b/packages/dms-mailing/src/db/tables/sends.table.ts @@ -76,10 +76,7 @@ export class MailingSend extends Table { @Field("string") declare json_variables: string; - /** - * JSON-serialized `AttachmentSummary[]`: name, type, size and hash of each - * file the e-mail carried, never its bytes. Absent for a send without any. - */ + /** JSON list of the name, type, size and SHA-256 of each file the e-mail carried; absent for most sends. */ @Field("string") declare json_attachments?: string; diff --git a/packages/dms-mailing/src/implementations/dms-mailing/index.ts b/packages/dms-mailing/src/implementations/dms-mailing/index.ts index 69ad1939..05abc231 100644 --- a/packages/dms-mailing/src/implementations/dms-mailing/index.ts +++ b/packages/dms-mailing/src/implementations/dms-mailing/index.ts @@ -6,5 +6,4 @@ export { importSends as ImportSends } from "../../services/send-import"; export { declareSender as DeclareSender } from "../../services/sender-declaration"; export { declareWebhookSecret as DeclareWebhookSecret } from "../../services/webhook-secret-declaration"; export { recordEmailEvent as RecordEmailEvent } from "../../services/events"; -export { sendCapabilities as GetSendCapabilities } from "../../services/attachments"; export { sendUnlessSuppressed as SendTemplate } from "../../services/checked-send"; diff --git a/packages/dms-mailing/src/routes/sends.ts b/packages/dms-mailing/src/routes/sends.ts index ce683fc6..96771844 100644 --- a/packages/dms-mailing/src/routes/sends.ts +++ b/packages/dms-mailing/src/routes/sends.ts @@ -520,11 +520,6 @@ export class SendsController extends Controller(API_BASE_PATH) { await this.sends.linkReplayOf(result.sendId, originalId); } - /** - * Sends `send` again from what the log kept. The log keeps no attachment - * bytes, so a send that carried files is refused rather than repeated - * without them. - */ private async repeat( send: MailingSend, to: string | undefined, diff --git a/packages/dms-mailing/src/services/attachments.ts b/packages/dms-mailing/src/services/attachments.ts index 7faea7ec..5ce35b2f 100644 --- a/packages/dms-mailing/src/services/attachments.ts +++ b/packages/dms-mailing/src/services/attachments.ts @@ -1,277 +1,53 @@ import { createHash } from "node:crypto"; -import type { - Attachment, - ProviderCapabilities, -} from "@antelopejs/interface-email"; -import type { - SendAttachment, - SendCapabilities, -} from "@antelopejs/interface-dms-mailing"; -import { getConfig } from "../config"; -import { sendAttachmentsSchema } from "../validation/attachments.schema"; -import { readCapabilities } from "./provider"; +import type { BufferAttachment } from "@antelopejs/interface-email"; +import type { SendAttachment } from "@antelopejs/interface-dms-mailing"; import { SendError } from "./send-error"; -/** A file of a send as the send log keeps it: everything but its bytes. */ -interface AttachmentSummary { - filename: string; - contentType: string; - size: number; - /** Hex SHA-256 of the bytes, to match the log against the caller's archive. */ - sha256: string; -} - -/** A file the checks accepted, with the bytes the provider receives. */ -export interface CheckedAttachment extends AttachmentSummary { - content: Buffer; -} - -/** How many files, and how many bytes, one send may carry. */ -interface AttachmentLimits { - count: number; - totalBytes: number; - fileBytes: number; -} +/** Most files one send carries. */ +export const MAX_ATTACHMENTS = 10; +/** Most bytes the files of one send add up to: base64 grows them by a third, under the 20 MB most mail servers accept. */ +export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024; -const DEFAULT_CONTENT_TYPE = "application/octet-stream"; -const MIME_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/; -/** Types that would nest a MIME structure or a whole message in the e-mail. */ -const REFUSED_TOP_LEVEL_TYPES = new Set(["multipart", "message"]); -const TYPE_PARAMETERS = ";"; -const TYPE_SEPARATOR = "/"; const PATH_SEPARATORS = /[\\/]/; -/** Control, formatting (bidi overrides, zero-width) and line-separator characters. */ -const UNSAFE_NAME_CHARACTERS = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu; -const WHITESPACE_RUN = /\s+/g; -const RESERVED_NAMES = new Set([".", ".."]); -const MAX_FILENAME_LENGTH = 200; -const MAX_EXTENSION_LENGTH = 16; -const EXTENSION_DOT = "."; -const NO_POSITION = -1; -const HASH_ALGORITHM = "sha256"; -const HASH_ENCODING = "hex"; -/** Base64 writes three bytes as four characters. */ -const BASE64_RAW_RATIO = 3 / 4; - -const invalid = (index: number, reason: string): SendError => - new SendError("invalid_attachment", `Attachment ${index}: ${reason}`); - -const GRAPHEMES = new Intl.Segmenter(undefined, { granularity: "grapheme" }); - -const graphemesOf = (text: string): string[] => - Array.from(GRAPHEMES.segment(text), (part) => part.segment); - -/** `name` cut to {@link MAX_FILENAME_LENGTH} characters, its extension kept. */ -function shortened(name: string): string { - const characters = graphemesOf(name); - if (characters.length <= MAX_FILENAME_LENGTH) return name; - const dot = name.lastIndexOf(EXTENSION_DOT); - const extension = - dot > NO_POSITION && name.length - dot <= MAX_EXTENSION_LENGTH - ? name.slice(dot) - : ""; - const stemLength = MAX_FILENAME_LENGTH - graphemesOf(extension).length; - return characters.slice(0, stemLength).join("") + extension; -} - -/** - * The name a recipient sees: its last path segment, without the characters - * that could break a header or disguise its extension. - */ -export function safeFilename(name: string, index: number): string { - const segment = name.split(PATH_SEPARATORS).pop() ?? ""; - const cleaned = segment - .replace(UNSAFE_NAME_CHARACTERS, "") - .replace(WHITESPACE_RUN, " ") - .trim(); - if (!cleaned || RESERVED_NAMES.has(cleaned)) - throw invalid(index, "has no usable file name"); - return shortened(cleaned); -} - -/** `type/subtype` in lower case without parameters, or a refusal. */ -export function safeContentType( - type: string | undefined, - index: number, -): string { - if (type === undefined) return DEFAULT_CONTENT_TYPE; - const essence = (type.split(TYPE_PARAMETERS)[0] ?? "").trim().toLowerCase(); - const topLevel = essence.split(TYPE_SEPARATOR)[0] ?? ""; - if (!MIME_TYPE.test(essence) || REFUSED_TOP_LEVEL_TYPES.has(topLevel)) - throw invalid(index, `has a refused content type "${essence}"`); - return essence; -} - -function bytesOf(content: Uint8Array, index: number): Buffer { - if (content.byteLength === 0) throw invalid(index, "is empty"); - return Buffer.isBuffer(content) - ? content - : Buffer.from(content.buffer, content.byteOffset, content.byteLength); -} - -function checkedOne(entry: SendAttachment, index: number): CheckedAttachment { - const content = bytesOf(entry.content, index); - return { - filename: safeFilename(entry.filename, index), - contentType: safeContentType(entry.contentType, index), - size: content.byteLength, - sha256: createHash(HASH_ALGORITHM).update(content).digest(HASH_ENCODING), - content, - }; -} - -/** - * `input` as the attachments schema reads it. A JavaScript caller that passes - * a path, a URL or a string where the bytes belong is refused here. - */ -function parsedAttachments( - input: readonly SendAttachment[] | undefined, -): SendAttachment[] { - const parsed = sendAttachmentsSchema.safeParse(input); - if (!parsed.success) { - const index = parsed.error.issues[0]?.path[0] ?? ""; - throw new SendError( - "invalid_attachment", - `Attachment ${index}: needs a file name and its bytes as a Buffer`, - ); - } - return parsed.data ?? []; -} - -const lowered = (limit: number, providerLimit: number | undefined): number => - providerLimit === undefined ? limit : Math.min(limit, providerLimit); - -/** - * The module's ceilings, lowered to what the provider reports: its largest - * message (of which base64 leaves three quarters to raw bytes) and its - * largest file. - */ -function attachmentLimits( - capabilities: ProviderCapabilities | null, -): AttachmentLimits { - const config = getConfig(); - const emailSize = capabilities?.maxEmailSize; - const totalBytes = lowered( - config.maxAttachmentBytes, - emailSize === undefined - ? undefined - : Math.floor(emailSize * BASE64_RAW_RATIO), - ); - return { - count: config.maxAttachments, - totalBytes, - fileBytes: lowered(totalBytes, capabilities?.maxAttachmentSize), - }; -} - -/** - * Whether the provider says it cannot carry attachments. The email - * interface's `features` has no such flag yet: a provider that adds one is - * read, one without it is taken at the interface's word, whose `EmailParams` - * carries attachments. - */ -function refusesAttachments(capabilities: ProviderCapabilities): boolean { - const { features } = capabilities; - return "attachments" in features && features.attachments === false; -} - -function assertWithin( - attachments: CheckedAttachment[], - limits: AttachmentLimits, -): void { - if (attachments.length > limits.count) - throw new SendError( - "attachments_too_large", - `${attachments.length} attachments, at most ${limits.count}`, - ); - const oversized = attachments.find((file) => file.size > limits.fileBytes); - if (oversized) - throw new SendError( - "attachments_too_large", - `"${oversized.filename}" is ${oversized.size} bytes, at most ${limits.fileBytes}`, - ); - const total = attachments.reduce((sum, file) => sum + file.size, 0); - if (total > limits.totalBytes) - throw new SendError( - "attachments_too_large", - `The attachments add up to ${total} bytes, at most ${limits.totalBytes}`, - ); -} +const LINE_BREAKS = /[\r\n]/g; /** - * The attachments of a send, checked against the module's rules and what the - * provider reports (`null` when it could not be read): a refusal throws a - * `SendError`, a file is never left out. + * The files as the email interface takes them, each name cut to its last path + * segment without line breaks; absent for a send without any. Over + * {@link MAX_ATTACHMENTS} or {@link MAX_ATTACHMENT_BYTES}, it throws + * `attachments_too_large`. */ export function checkAttachments( input: readonly SendAttachment[] | undefined, - capabilities: ProviderCapabilities | null, -): CheckedAttachment[] { - const entries = parsedAttachments(input); - if (!entries.length) return []; - if (capabilities && refusesAttachments(capabilities)) +): BufferAttachment[] | undefined { + if (!input?.length) return undefined; + const total = input.reduce((sum, file) => sum + file.content.byteLength, 0); + if (input.length > MAX_ATTACHMENTS || total > MAX_ATTACHMENT_BYTES) throw new SendError( - "attachments_unsupported", - `The e-mail provider "${capabilities.name}" cannot carry attachments`, + "attachments_too_large", + `${input.length} files of ${total} bytes, at most ${MAX_ATTACHMENTS} files of ${MAX_ATTACHMENT_BYTES} bytes`, ); - const attachments = entries.map(checkedOne); - assertWithin(attachments, attachmentLimits(capabilities)); - return attachments; -} - -/** - * The files as the email interface sends them: bytes, never a path or a URL. - * Absent for a send without any. - */ -export function toEmailAttachments( - attachments: CheckedAttachment[], -): Attachment[] | undefined { - if (!attachments.length) return undefined; - return attachments.map(({ filename, contentType, content }) => ({ - filename, + return input.map(({ filename, contentType, content }) => ({ + filename: (filename.split(PATH_SEPARATORS).pop() ?? "").replace( + LINE_BREAKS, + "", + ), contentType, - content, + content: Buffer.from(content), })); } -/** What the send log keeps of the files; absent for a send without any. */ +/** What the send log keeps of the files: name, type, size and SHA-256, never the bytes. */ export function attachmentsLog( - attachments: CheckedAttachment[], + files: readonly BufferAttachment[] | undefined, ): string | undefined { - if (!attachments.length) return undefined; - const summaries: AttachmentSummary[] = attachments.map( - ({ filename, contentType, size, sha256 }) => ({ + if (!files) return undefined; + return JSON.stringify( + files.map(({ filename, contentType, content }) => ({ filename, contentType, - size, - sha256, - }), + size: content.byteLength, + sha256: createHash("sha256").update(content).digest("hex"), + })), ); - return JSON.stringify(summaries); -} - -/** What a send can carry today: `GetSendCapabilities`. */ -export async function sendCapabilities( - read: () => Promise = readCapabilities, -): Promise { - const capabilities = await read(); - const limits = attachmentLimits(capabilities); - return { - attachments: !capabilities || !refusesAttachments(capabilities), - maxAttachments: limits.count, - maxAttachmentBytes: limits.totalBytes, - maxAttachmentFileBytes: limits.fileBytes, - provider: capabilities?.name, - }; -} - -/** - * The checked attachments of a send, reading the provider's capabilities - * only when there are some. - */ -export async function attachmentsOfSend( - input: readonly SendAttachment[] | undefined, -): Promise { - const capabilities = input?.length ? await readCapabilities() : null; - return checkAttachments(input, capabilities); } diff --git a/packages/dms-mailing/src/services/send-error.ts b/packages/dms-mailing/src/services/send-error.ts index 3d09c15a..c68c0003 100644 --- a/packages/dms-mailing/src/services/send-error.ts +++ b/packages/dms-mailing/src/services/send-error.ts @@ -1,9 +1,7 @@ -import type { SendErrorCode } from "@antelopejs/interface-dms-mailing"; - /** Why a send was refused before anything left: `code` names the rule. */ export class SendError extends Error { constructor( - public readonly code: SendErrorCode, + public readonly code: string, message: string, ) { super(message); diff --git a/packages/dms-mailing/src/services/send.ts b/packages/dms-mailing/src/services/send.ts index d3969cb6..d9af6824 100644 --- a/packages/dms-mailing/src/services/send.ts +++ b/packages/dms-mailing/src/services/send.ts @@ -2,6 +2,7 @@ import { type BatchEmailMessageResponse, type BatchEmailParams, type BatchEmailResponse, + type BufferAttachment, type EmailAddress, type EmailParams, type EmailResponse, @@ -38,12 +39,7 @@ import { type TemplateContent, } from "../types"; import { publishSendCreated } from "../realtime"; -import { - attachmentsLog, - attachmentsOfSend, - type CheckedAttachment, - toEmailAttachments, -} from "./attachments"; +import { attachmentsLog, checkAttachments } from "./attachments"; import { renderEmailHtml } from "./render"; import { SendError } from "./send-error"; import { getSettings } from "./settings"; @@ -77,8 +73,8 @@ export interface PreparedSend { category: string; /** Why the template needed a look when the send started. */ attention: string; - /** The files every recipient gets, checked; empty for most sends. */ - attachments: CheckedAttachment[]; + /** The files every recipient gets; absent for most sends. */ + attachments?: BufferAttachment[]; } /** @@ -273,7 +269,7 @@ export async function prepare( if (missing.length) { throw new SendError("missing_variables", missing.join(", ")); } - const attachments = await attachmentsOfSend(params.attachments); + const attachments = checkAttachments(params.attachments); const { content, version, variables } = resolveContent(template, params); const settings = await getSettings(tenantId); const locale = pickLocale(content, params.locale, settings.fallbackLocale); @@ -317,7 +313,7 @@ export function messageFor( templateSlug: prepared.slug, }, tracking: { opens: true, clicks: true }, - attachments: toEmailAttachments(prepared.attachments), + attachments: prepared.attachments, }; } diff --git a/packages/dms-mailing/src/test/helpers/smtp.ts b/packages/dms-mailing/src/test/helpers/smtp.ts deleted file mode 100644 index f5d849d0..00000000 --- a/packages/dms-mailing/src/test/helpers/smtp.ts +++ /dev/null @@ -1,17 +0,0 @@ -declare global { - /** - * The raw messages the SMTP fixture received, oldest first: a global, since - * the fixture's copy of this module is not the one the tests import. - */ - var dmsMailingSmtpMessages: string[] | undefined; -} - -export function recordSmtpMessage(message: string): void { - globalThis.dmsMailingSmtpMessages ??= []; - globalThis.dmsMailingSmtpMessages.push(message); -} - -/** What nodemailer really wrote to the fixture, oldest first. */ -export function smtpMessages(): string[] { - return [...(globalThis.dmsMailingSmtpMessages ?? [])]; -} diff --git a/packages/dms-mailing/src/test/integration/send-attachments.test.ts b/packages/dms-mailing/src/test/integration/send-attachments.test.ts index b795b0a4..4fcde1a8 100644 --- a/packages/dms-mailing/src/test/integration/send-attachments.test.ts +++ b/packages/dms-mailing/src/test/integration/send-attachments.test.ts @@ -8,7 +8,8 @@ import { suppressAddress } from "../../services/suppressions"; import { declaration, mailing } from "../helpers/declarations"; import { authorizedClient } from "../helpers/http"; import { ensureOwnerSession } from "../helpers/owner"; -import { smtpMessages } from "../helpers/smtp"; +import { MAX_ATTACHMENT_BYTES } from "../../services/attachments"; +import { capturedMail, rawMail } from "../helpers/mail-store"; const HTTP_CONFLICT = 409; const stamp = Date.now(); @@ -29,7 +30,7 @@ const summarySchema = z.array( const invoice = { filename: "../archive/invoice-001.pdf\r\nX-Injected: yes", - contentType: "Application/PDF", + contentType: "application/pdf", content: PDF, }; @@ -76,9 +77,9 @@ describe("[integration] sends with attachments", () => { ); expect(send?.json_attachments).to.not.contain(PDF.toString("base64")); - const mine = smtpMessages().filter((message) => - message.includes(PDF.toString("base64")), - ); + const mine = capturedMail() + .map(rawMail) + .filter((message) => message.includes(PDF.toString("base64"))); expect(mine).to.have.length(2); expect(mine[0]).to.match(/Content-Type: application\/pdf/i); expect(mine[0]).to.contain("invoice-001.pdf"); @@ -107,8 +108,7 @@ describe("[integration] sends with attachments", () => { }); it("refuses a file over the ceiling before anything is logged", async () => { - const { SendTemplate, GetSendCapabilities } = await mailing(); - const { maxAttachmentBytes } = await GetSendCapabilities(); + const { SendTemplate } = await mailing(); const address = `too-large-${stamp}@example.test`; const refusal = await SendTemplate(slug, { tenantId: DEFAULT_TENANT_ID, @@ -117,7 +117,7 @@ describe("[integration] sends with attachments", () => { attachments: [ { filename: "huge.bin", - content: Buffer.alloc(maxAttachmentBytes + 1), + content: Buffer.alloc(MAX_ATTACHMENT_BYTES + 1), }, ], }).catch((error: unknown) => error); @@ -130,14 +130,6 @@ describe("[integration] sends with attachments", () => { expect(logged).to.have.length(0); }); - it("reports what a send can carry through nodemailer", async () => { - const { GetSendCapabilities } = await mailing(); - const capabilities = await GetSendCapabilities(); - expect(capabilities.attachments).to.equal(true); - expect(capabilities.maxAttachments).to.equal(10); - expect(capabilities.maxAttachmentBytes).to.equal(10 * 1024 * 1024); - }); - it("refuses to send again a send whose files the log does not keep", async () => { const { SendTemplate } = await mailing(); const sent = await SendTemplate(slug, { diff --git a/packages/dms-mailing/src/test/unit/attachments.test.ts b/packages/dms-mailing/src/test/unit/attachments.test.ts deleted file mode 100644 index fb594c48..00000000 --- a/packages/dms-mailing/src/test/unit/attachments.test.ts +++ /dev/null @@ -1,235 +0,0 @@ -import { createHash } from "node:crypto"; -import type { SendAttachment } from "@antelopejs/interface-dms-mailing"; -import type { ProviderCapabilities } from "@antelopejs/interface-email"; -import { expect } from "chai"; -import { getConfig, setConfig } from "../../config"; -import { - attachmentsLog, - checkAttachments, - safeContentType, - safeFilename, - sendCapabilities, - toEmailAttachments, -} from "../../services/attachments"; -import { SendError } from "../../services/send-error"; - -const PDF = Buffer.from("%PDF-1.7 invoice"); -const MIB = 1024 * 1024; - -const capabilities = ( - overrides: Partial = {}, - features: Record = {}, -): ProviderCapabilities => ({ - name: "smtp", - features: { - batch: true, - templates: true, - providerTemplates: false, - scheduling: false, - openTracking: false, - clickTracking: false, - inlineAttachments: true, - tags: false, - metadata: false, - priority: false, - ...features, - }, - ...overrides, -}); - -const invoice = (overrides: Partial = {}): SendAttachment => ({ - filename: "invoice-2026-001.pdf", - contentType: "application/pdf", - content: PDF, - ...overrides, -}); - -function refusalCode(run: () => void): string { - try { - run(); - } catch (error) { - if (error instanceof SendError) return error.code; - throw error; - } - return ""; -} - -describe("[unit] services/attachments file names", () => { - it("keeps only the last path segment, whatever the separator", () => { - expect(safeFilename("../../etc/passwd", 0)).to.equal("passwd"); - expect(safeFilename("C:\\archive\\2026\\invoice.pdf", 0)).to.equal( - "invoice.pdf", - ); - }); - - it("removes line breaks and controls, so a name cannot start a header", () => { - expect(safeFilename("invoice.pdf\r\nBcc: victim@example.test", 0)).to.equal( - "invoice.pdfBcc: victim@example.test", - ); - expect(safeFilename("a\u0000b\u0007c.pdf", 0)).to.equal("abc.pdf"); - }); - - it("removes the bidi override that would disguise an extension", () => { - expect(safeFilename("invoice\u202Efdp.exe", 0)).to.equal("invoicefdp.exe"); - }); - - it("refuses a name left empty or reserved", () => { - expect(refusalCode(() => safeFilename("folder/", 0))).to.equal( - "invalid_attachment", - ); - expect(refusalCode(() => safeFilename("\r\n", 0))).to.equal( - "invalid_attachment", - ); - expect(refusalCode(() => safeFilename("..", 0))).to.equal( - "invalid_attachment", - ); - }); - - it("cuts a long name to 200 characters and keeps its extension", () => { - const name = safeFilename(`${"é".repeat(300)}.pdf`, 0); - expect(Array.from(name)).to.have.length(200); - expect(name.endsWith(".pdf")).to.equal(true); - }); -}); - -describe("[unit] services/attachments content types", () => { - it("lower-cases the type and drops its parameters", () => { - expect( - safeContentType('Application/PDF; name="x"\r\nX-Evil: 1', 0), - ).to.equal("application/pdf"); - }); - - it("falls back to octet-stream when the caller names none", () => { - expect(safeContentType(undefined, 0)).to.equal("application/octet-stream"); - }); - - it("refuses multipart and message types, and anything not type/subtype", () => { - for (const type of ["multipart/mixed", "message/rfc822", "pdf", "a/b c"]) - expect(refusalCode(() => safeContentType(type, 0))).to.equal( - "invalid_attachment", - ); - }); -}); - -describe("[unit] services/attachments checks", () => { - const initial = getConfig(); - afterEach(() => setConfig(initial)); - - it("hashes and sizes each file, and the log keeps no byte of it", () => { - const [checked] = checkAttachments([invoice()], capabilities()); - const sha256 = createHash("sha256").update(PDF).digest("hex"); - - expect(checked).to.include({ size: PDF.byteLength, sha256 }); - expect(JSON.parse(attachmentsLog([checked]) ?? "")).to.deep.equal([ - { - filename: "invoice-2026-001.pdf", - contentType: "application/pdf", - size: PDF.byteLength, - sha256, - }, - ]); - }); - - it("hands the provider the bytes, never a path or a URL", () => { - const sent = toEmailAttachments(checkAttachments([invoice()], null)); - expect(sent).to.deep.equal([ - { - filename: "invoice-2026-001.pdf", - contentType: "application/pdf", - content: PDF, - }, - ]); - }); - - it("accepts a plain Uint8Array without copying it", () => { - const bytes = new Uint8Array([1, 2, 3]); - const [checked] = checkAttachments([invoice({ content: bytes })], null); - expect(checked?.content.buffer).to.equal(bytes.buffer); - }); - - it("refuses a path or a URL passed where the bytes belong", () => { - const fromPath = invoice(); - Reflect.deleteProperty(fromPath, "content"); - Reflect.set(fromPath, "path", "/etc/passwd"); - const fromText = invoice(); - Reflect.set(fromText, "content", "/etc/passwd"); - for (const attachment of [fromPath, fromText]) - expect(refusalCode(() => checkAttachments([attachment], null))).to.equal( - "invalid_attachment", - ); - }); - - it("refuses an empty file", () => { - expect( - refusalCode(() => - checkAttachments([invoice({ content: Buffer.alloc(0) })], null), - ), - ).to.equal("invalid_attachment"); - }); - - it("refuses files over the configured total, and too many files", () => { - setConfig({ maxAttachmentBytes: 10, maxAttachments: 2 }); - const big = invoice({ content: Buffer.alloc(11) }); - expect(refusalCode(() => checkAttachments([big], null))).to.equal( - "attachments_too_large", - ); - const three = [1, 2, 3].map(() => invoice({ content: Buffer.alloc(1) })); - expect(refusalCode(() => checkAttachments(three, null))).to.equal( - "attachments_too_large", - ); - }); - - it("lowers the ceiling to the provider's own limits", () => { - const file = invoice({ content: Buffer.alloc(100) }); - expect( - refusalCode(() => - checkAttachments([file], capabilities({ maxAttachmentSize: 99 })), - ), - ).to.equal("attachments_too_large"); - expect( - refusalCode(() => - checkAttachments([file], capabilities({ maxEmailSize: 120 })), - ), - ).to.equal("attachments_too_large"); - }); - - it("refuses a send when the provider reports it cannot carry files", () => { - const refusing = capabilities({}, { attachments: false }); - expect(refusalCode(() => checkAttachments([invoice()], refusing))).to.equal( - "attachments_unsupported", - ); - expect(checkAttachments([], refusing)).to.deep.equal([]); - }); -}); - -describe("[unit] services/attachments capabilities", () => { - const initial = getConfig(); - afterEach(() => setConfig(initial)); - - it("reports the configured limits lowered to the provider's", async () => { - setConfig({ maxAttachmentBytes: 8 * MIB, maxAttachments: 4 }); - const read = sendCapabilities(() => - Promise.resolve(capabilities({ maxAttachmentSize: 2 * MIB })), - ); - expect(await read).to.deep.equal({ - attachments: true, - maxAttachments: 4, - maxAttachmentBytes: 8 * MIB, - maxAttachmentFileBytes: 2 * MIB, - provider: "smtp", - }); - }); - - it("reports no attachments for a provider that says it cannot", async () => { - const read = sendCapabilities(() => - Promise.resolve(capabilities({}, { attachments: false })), - ); - expect((await read).attachments).to.equal(false); - }); - - it("stays optimistic when the provider cannot be read", async () => { - const read = await sendCapabilities(() => Promise.resolve(null)); - expect(read.attachments).to.equal(true); - expect(read.provider).to.equal(undefined); - }); -}); diff --git a/packages/dms-mailing/src/test/unit/send.test.ts b/packages/dms-mailing/src/test/unit/send.test.ts index 8f210e7a..2a2bba19 100644 --- a/packages/dms-mailing/src/test/unit/send.test.ts +++ b/packages/dms-mailing/src/test/unit/send.test.ts @@ -34,7 +34,6 @@ const PREPARED: PreparedSend = { tenantId: "tenant-1", category: "", attention: "", - attachments: [], }; const SETTINGS: MailingSettingsValues = { diff --git a/packages/dms-mailing/src/validation/attachments.schema.ts b/packages/dms-mailing/src/validation/attachments.schema.ts deleted file mode 100644 index e55008ba..00000000 --- a/packages/dms-mailing/src/validation/attachments.schema.ts +++ /dev/null @@ -1,14 +0,0 @@ -import { z } from "zod"; - -/** - * An attachment as a caller hands it to `SendTemplate`, checked at run time - * too: a JavaScript caller can pass a path or a URL where the bytes belong, - * and any key but these three is dropped. - */ -const sendAttachmentSchema = z.object({ - filename: z.string(), - contentType: z.string().optional(), - content: z.instanceof(Uint8Array), -}); - -export const sendAttachmentsSchema = z.array(sendAttachmentSchema).optional(); diff --git a/packages/interface-dms-mailing/README.md b/packages/interface-dms-mailing/README.md index d6634ab0..d2f3b7d2 100644 --- a/packages/interface-dms-mailing/README.md +++ b/packages/interface-dms-mailing/README.md @@ -13,7 +13,7 @@ The AntelopeJS interface to send DMS mailing templates and report e-mail events ## What it does -- Sends a published template by its slug, to one recipient or many, in a given locale and with its variables and attached files (`SendTemplate`), and says what a send can carry (`GetSendCapabilities`). +- Sends a published template by its slug, to one recipient or many, in a given locale and with its variables (`SendTemplate`). - Reports a provider event (delivered, opened, clicked, bounced…) against the send it belongs to (`RecordEmailEvent`). - Ships templates and template categories as code when a workspace is provisioned (`DeclareTemplate`, `DeclareTemplateCategory`). A declaration writes once: a template is created already published, and a slug or category id the workspace already has is left as it is. - Writes the workspace sender when a workspace is provisioned (`DeclareSender`). diff --git a/packages/interface-dms-mailing/docs/1.index.md b/packages/interface-dms-mailing/docs/1.index.md index f7cf3977..0ce98dee 100644 --- a/packages/interface-dms-mailing/docs/1.index.md +++ b/packages/interface-dms-mailing/docs/1.index.md @@ -4,9 +4,9 @@ description: Consumer contract for sending templates and recording provider even mode: reference --- -`@antelopejs/interface-dms-mailing` exports eight backend functions and the template types below. `SendTemplate` sends, `GetSendCapabilities` says what a send can carry, `RecordEmailEvent` reports provider events, `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender` and `DeclareWebhookSecret` ship templates, categories, the sender and the webhook secret as code, and `ImportSends` imports past sends. They need `@antelopejs/dms-mailing` and an `@antelopejs/interface-email` provider loaded, and are imported from the interface package, not the runtime module's services. +`@antelopejs/interface-dms-mailing` exports seven backend functions and the template types below. `SendTemplate` sends, `RecordEmailEvent` reports provider events, `DeclareTemplate`, `DeclareTemplateCategory`, `DeclareSender` and `DeclareWebhookSecret` ship templates, categories, the sender and the webhook secret as code, and `ImportSends` imports past sends. They need `@antelopejs/dms-mailing` and an `@antelopejs/interface-email` provider loaded, and are imported from the interface package, not the runtime module's services. -All but `GetSendCapabilities` take an explicit `tenantId`. They are trusted backend calls, not permission-checked HTTP endpoints, so the calling module authenticates and authorizes the tenant. A missing implementation or a storage failure rejects the promise. +All seven take an explicit `tenantId`. They are trusted backend calls, not permission-checked HTTP endpoints, so the calling module authenticates and authorizes the tenant. A missing implementation or a storage failure rejects the promise. ## Per-recipient results @@ -51,7 +51,7 @@ interface SendTemplateParams { interface SendAttachment { filename: string; - contentType?: string; // application/octet-stream when absent + contentType?: string; content: Uint8Array; // a Buffer is one } @@ -86,54 +86,11 @@ A suppressed address gets no e-mail. Its result has `status: "suppressed"` and a Provider failures become `failed` recipient results. If recording a send fails, its result has `sendId: ""`, `status: "failed"` and an error, and can still carry a provider `messageId`, because delivery may have happened. A `failed` result does not prove that no e-mail left, and retrying the whole call can deliver twice. -Validation failures reject the promise instead of returning recipient results. The runtime's errors carry a `code` typed `SendErrorCode`: `no_recipient`, `template_not_found`, `template_not_live`, `invalid_content`, `missing_variables`, or for [attachments](#attachments) `attachments_unsupported`, `attachments_too_large` or `invalid_attachment`. The interface does not export the error class, so branch on `error.code`. The workspace's **Missing variables** setting decides whether missing variables refuse a send. Marketing footer URLs are required system variables when the template uses them, never for test sends. Storage or notification failures can reject after side effects started, so the call is neither transactional nor idempotent. +Validation failures reject the promise instead of returning recipient results. The runtime's errors carry one of these codes: `no_recipient`, `template_not_found`, `template_not_live`, `invalid_content`, `missing_variables` or `attachments_too_large`. The interface does not export the error class. The workspace's **Missing variables** setting decides whether missing variables refuse a send. Marketing footer URLs are required system variables when the template uses them, never for test sends. Storage or notification failures can reject after side effects started, so the call is neither transactional nor idempotent. `variables` is `TemplateVariables`, a record of strings, numbers, booleans, `null`, `Date` values, money values (`{ value: 987420, currency: "EUR" }`, in the currency's minor unit), and lists and records of the same. Dates and money are written in the send's locale. A class instance or a function does not compile, and a template path reads only the keys a record owns. -### Attachments - -`attachments` sends files with the e-mail: the PDF of a quote, an invoice, a signed contract. Every recipient of the call gets the same files. - -```ts docs-check -import { GetSendCapabilities, SendTemplate } from "@antelopejs/interface-dms-mailing"; - -export async function sendInvoice(tenantId: string, to: string, pdf: Buffer) { - const capabilities = await GetSendCapabilities(); - const fits = capabilities.attachments && pdf.byteLength <= capabilities.maxAttachmentFileBytes; - return SendTemplate("invoice-sent", { - tenantId, - to, - variables: { invoice: { number: "2026-001" } }, - attachments: fits ? [{ filename: "invoice-2026-001.pdf", contentType: "application/pdf", content: pdf }] : [], - }); -} -``` - -- **Bytes only.** `content` is a `Uint8Array` (a `Buffer` is one) the caller already read. The module never reads a path or fetches a URL, and a `path`, a `url` or a string where the bytes belong rejects with `invalid_attachment`. Interface functions are in-process calls, so the bytes are not serialized on the way in. -- **Names.** The module keeps the last segment of `filename` (after the last `/` or `\`), removes control and formatting characters (line breaks, bidi overrides, zero-width characters) and cuts it to 200 characters, its extension kept. A name left empty, `.` or `..` rejects with `invalid_attachment`. -- **Types.** `contentType` is written in lower case without its parameters (`Application/PDF; name=x` gives `application/pdf`). Without one, the file is `application/octet-stream`. `multipart/*`, `message/*` and anything that is not `type/subtype` reject with `invalid_attachment`. An empty file does too. -- **Limits.** At most 10 files and 10 MiB in all by default, set by the module options `maxAttachments` and `maxAttachmentBytes`. A provider that reports a `maxEmailSize` lowers the total to three quarters of it (base64 makes the files a third larger), and one that reports a `maxAttachmentSize` caps each file. Over a limit, the call rejects with `attachments_too_large`. -- **Providers.** A provider whose capabilities report `features.attachments: false` makes a call with files reject with `attachments_unsupported`: a file is never dropped. The email interface 0.2 has no such flag yet, so a provider that does not report it is taken to carry attachments, as its `EmailParams.attachments` promises. Nodemailer and Brevo both carry them. -- **Checked first.** Every check runs before anything is sent or logged, suppressed recipients included, so a refused call leaves no row. -- **The send log** keeps each file's name, type, size and SHA-256 (`json_attachments` on the send), never its bytes, for every recipient, a suppressed one included. The send's panel lists them. -- **No send again.** Since the bytes are not kept, **Send again**, **Send to a corrected address** and **Send the failures again** refuse a send that carried files (`409`, `no_replay_with_attachments`): send it again from your code, which holds the files. The module has no queue or retry of its own, and the automation action `mailing.send-template` takes no attachments. -- Previews and test sends from the dashboard carry no attachment. - -### `GetSendCapabilities` - -```ts [Contract] -interface SendCapabilities { - attachments: boolean; // false when the provider reports it cannot carry files - maxAttachments: number; - maxAttachmentBytes: number; // all files of one send - maxAttachmentFileBytes: number; // one file - provider?: string; -} - -declare function GetSendCapabilities(): Promise; -``` - -It reads the provider's capabilities (kept for a minute) and the module options, and applies the rules above, so a caller can send a link instead of a file that would be refused. An unreachable provider leaves `attachments` true: the send itself then fails as any send would. `SendTemplate` applies the same checks, so a caller that skips this call gets the typed rejection instead. +`attachments` sends files with the e-mail, the same for every recipient of the call. `content` holds the bytes the caller already read. The module keeps the last path segment of `filename`, without line breaks, and passes the files to the `@antelopejs/interface-email` provider. A call carries at most 10 files adding up to at most 10 MiB, or it rejects with `attachments_too_large` before anything is sent or logged. The send log keeps each file's name, type, size and SHA-256 (`json_attachments`), never its bytes, so the dashboard refuses to send it again (`409`, `no_replay_with_attachments`): the caller, which holds the files, sends it again. ## `RecordEmailEvent` diff --git a/packages/interface-dms-mailing/src/index.ts b/packages/interface-dms-mailing/src/index.ts index a1618c7a..4e2a8a86 100644 --- a/packages/interface-dms-mailing/src/index.ts +++ b/packages/interface-dms-mailing/src/index.ts @@ -172,23 +172,18 @@ export interface VariableDefinition { } /** - * A file a send carries, as bytes the caller already holds: the module never - * reads a path or fetches a URL for it. Every recipient of the call gets the - * same files. + * A file a send carries, as bytes the caller already holds. Every recipient of + * the call gets the same files. */ export interface SendAttachment { /** - * The name the recipient sees. The module keeps its last path segment, - * removes control and formatting characters and refuses a name left empty. + * The name the recipient sees: the module keeps its last path segment, + * without line breaks. */ filename: string; - /** - * The MIME type (`application/pdf`), written in lower case without its - * parameters; `application/octet-stream` when absent. `multipart/*`, - * `message/*` and anything that is not `type/subtype` is refused. - */ + /** The MIME type (`application/pdf`); the provider guesses it when absent. */ contentType?: string; - /** The file's bytes; a `Buffer` is one. An empty file is refused. */ + /** The file's bytes; a `Buffer` is one. */ content: Uint8Array; } @@ -202,53 +197,14 @@ export interface SendTemplateParams { source?: string; isTest?: boolean; /** - * Files the e-mail carries. The send log keeps their names, types, sizes - * and SHA-256 hashes, never their bytes, so a send with attachments cannot - * be sent again from the dashboard. See {@link GetSendCapabilities} for - * the limits. + * Files the e-mail carries: at most 10, adding up to at most 10 MiB, or the + * send rejects with `code` `attachments_too_large`. The send log keeps their + * names, types, sizes and SHA-256 hashes, never their bytes, so a send with + * attachments cannot be sent again from the dashboard. */ attachments?: SendAttachment[]; } -/** - * The `code` of the error a refused `SendTemplate` call rejects with. The - * interface does not export the error class: branch on `error.code`. - * - * - `attachments_unsupported`: the e-mail provider reports it cannot carry - * attachments. Nothing was sent or logged. - * - `attachments_too_large`: the files exceed the module's or the provider's - * ceiling, or there are too many of them. - * - `invalid_attachment`: a file has no usable name, an unaccepted type or no - * bytes. - */ -export type SendErrorCode = - | "no_recipient" - | "template_not_found" - | "template_not_live" - | "invalid_content" - | "missing_variables" - | "attachments_unsupported" - | "attachments_too_large" - | "invalid_attachment"; - -/** What a send can carry, read before sending. */ -export interface SendCapabilities { - /** - * Whether a send can carry attachments: `false` only when the provider - * reports it cannot. An unreachable provider leaves it `true`; the send - * itself then fails as any send would. - */ - attachments: boolean; - /** Most files one send carries. */ - maxAttachments: number; - /** Most bytes the files of one send add up to: the module's ceiling, lowered to the provider's. */ - maxAttachmentBytes: number; - /** Most bytes one file holds: `maxAttachmentBytes`, lowered to the provider's own per-file limit. */ - maxAttachmentFileBytes: number; - /** The provider's name, when it could be read. */ - provider?: string; -} - /** * Outcome of a template send. * @@ -310,14 +266,6 @@ export const SendTemplate = (slug: string, params: SendTemplateParams) => Promise >(); -/** - * What a send can carry today, for a caller that falls back to a link when - * the files cannot travel with the e-mail. `SendTemplate` checks the same - * limits and rejects with an {@link SendErrorCode} instead of dropping a file. - */ -export const GetSendCapabilities = - InterfaceFunction<() => Promise>(); - /** Records a provider event against the send it belongs to. */ export const RecordEmailEvent = InterfaceFunction<