@softure-ai/mailing 0.2.3 → 0.2.4

package/src/server/operator-output.ts

@@ -1,6 +1,8 @@
 // What an operator's terminal may show of a mail: addresses masked, link signatures redacted. Command output ends
 // up in shell history, CI logs and pasted chat messages; a full address is personal data, and a signed unsubscribe
 // link lets whoever holds it unsubscribe that address.
+import { describeAttachments } from "../attachments.js";
+import type { ProviderMessage } from "../contract.js";
 import { SIGNATURE_PARAM } from "./unsubscribe-link.js";
 
 /** `ada@example.org` becomes `a**@example.org`: the first character of the local part, then one `*` per other. */
@@ -18,3 +20,25 @@ const SIGNATURE = new RegExp(`([?&](?:amp;)?${SIGNATURE_PARAM}=)[A-Za-z0-9_-]+`,
 export function redactUnsubscribeSignatures(text: string): string {
   return text.replace(SIGNATURE, "$1<signature>");
 }
+
+/**
+ * A mail as the provider would get it (`previewMail`'s value), as terminal lines: the addresses masked, link
+ * signatures redacted, and each attachment by filename, content type and size, never its bytes.
+ */
+export function formatMailPreview(message: ProviderMessage): string[] {
+  const headers = [
+    `From: ${message.from}`,
+    `To: ${maskAddress(message.to)}`,
+    ...(message.replyTo === null ? [] : [`Reply-To: ${maskAddress(message.replyTo)}`]),
+    `Subject: ${message.subject}`,
+    ...Object.entries(message.headers).map(([name, value]) => `${name}: ${value}`),
+  ];
+  const sections = [`--- preview (addresses masked, link signatures redacted) ---`, ...headers, "", "--- text ---", message.text];
+  if (message.html !== null) sections.push("--- html ---", message.html);
+  const attachments = describeAttachments(message.attachments ?? []);
+  if (attachments.length > 0) {
+    sections.push("--- attachments ---", ...attachments.map(({ filename, contentType, size }) => `${filename} (${contentType}, ${String(size)} bytes)`));
+  }
+  sections.push("--- end of preview ---");
+  return redactUnsubscribeSignatures(sections.join("\n")).split("\n");
+}

package/src/server/send-mail.ts

@@ -1,12 +1,15 @@
 // Sends one mail through the configured provider, with three rules: it never throws for a failed
 // send (every failure is a result), nothing of the mail (address, subject, body, key) reaches a log
 // or the result, and `headers` cannot replace the envelope or the sender (a mail's own reply-to is
-// the `replyTo` field, checked like `to`). List mail (any kind but `transactional`) also gets a signed unsubscribe
+// the `replyTo` field, checked like `to`). Attachments go only to a provider that declares it delivers them, and a
+// log line describes them by count, content type and size, never by name or content. List mail (any kind but `transactional`) also gets a signed unsubscribe
 // link in a footer and the RFC 8058 headers, and is refused for a recipient who unsubscribed.
 import { err, type Err, ok, type Ok, selectMessages, type SoftureConfig } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
+import { getContentTypeEssence } from "../attachments.js";
 import {
   TRANSACTIONAL_KIND,
+  type MailAttachment,
   type MailingErrorCode,
   type MailProvider,
   type OutgoingMail,
@@ -42,19 +45,20 @@ export interface MailContext {
  * Throws only when the module is not enabled, or for list mail without `context.db`.
  */
 export async function sendMail(context: MailContext, mail: OutgoingMail, options: SendMailOptions = {}): Promise<SendMailResult> {
-  const { provider, timeoutMs } = getMailingOptions(context.config);
+  const { provider, timeoutMs, attachments: limits } = getMailingOptions(context.config);
 
-  const validation = validateMail(mail, options);
+  const validation = validateMail(mail, options, limits);
   if (!validation.ok) {
     logFailure(provider, "mailing.invalid_input", { fields: validation.fields });
     return err("mailing.invalid_input");
   }
   const valid = validation.value;
+  if (!canCarryAttachments(provider, valid)) return refuseAttachments(provider, valid);
   const secret = readUnsubscribeSecrets().current;
   if (valid.kind !== TRANSACTIONAL_KIND) {
     const refusal = await checkListMail(context, valid, secret);
     if (refusal !== null) {
-      logFailure(provider, refusal.error, { cause: refusal.cause });
+      logFailure(provider, refusal.error, { cause: refusal.cause, attachments: valid.attachments });
       return err(refusal.error);
     }
   }
@@ -68,15 +72,16 @@ export async function sendMail(context: MailContext, mail: OutgoingMail, options
  * code can send list mail to a real recipient past the suppression list.
  */
 export async function sendMailUnchecked(config: SoftureConfig, mail: OutgoingMail, options: SendMailOptions = {}): Promise<SendMailResult> {
-  const { provider, timeoutMs } = getMailingOptions(config);
-  const validation = validateMail(mail, options);
+  const { provider, timeoutMs, attachments: limits } = getMailingOptions(config);
+  const validation = validateMail(mail, options, limits);
   if (!validation.ok) {
     logFailure(provider, "mailing.invalid_input", { fields: validation.fields });
     return err("mailing.invalid_input");
   }
+  if (!canCarryAttachments(provider, validation.value)) return refuseAttachments(provider, validation.value);
   const secret = readUnsubscribeSecrets().current;
   if (validation.value.kind !== TRANSACTIONAL_KIND && secret === null) {
-    logFailure(provider, "mailing.unavailable", { cause: "no_unsubscribe_secret" });
+    logFailure(provider, "mailing.unavailable", { cause: "no_unsubscribe_secret", attachments: validation.value.attachments });
     return err("mailing.unavailable");
   }
   return deliver(provider, composeMessage(config, validation.value, secret), timeoutMs);
@@ -89,7 +94,7 @@ async function deliver(provider: MailProvider, message: ProviderMessage, timeout
     return ok({ id: outcome.id, provider: provider.name });
   }
   const code = FAILURE_CODES[outcome.status];
-  logFailure(provider, code, { status: outcome.httpStatus });
+  logFailure(provider, code, { status: outcome.httpStatus, attachments: message.attachments ?? [] });
   return {
     ...err(code),
     ...(outcome.httpStatus === undefined ? {} : { httpStatus: outcome.httpStatus }),
@@ -97,6 +102,16 @@ async function deliver(provider: MailProvider, message: ProviderMessage, timeout
   };
 }
 
+/** False for a mail with attachments and a provider that does not declare it delivers them. */
+function canCarryAttachments(provider: MailProvider, mail: ValidMail): boolean {
+  return mail.attachments.length === 0 || provider.supportsAttachments === true;
+}
+
+function refuseAttachments(provider: MailProvider, mail: ValidMail): SendMailResult {
+  logFailure(provider, "mailing.invalid_input", { fields: ["attachments"], cause: "provider_without_attachments", attachments: mail.attachments });
+  return err("mailing.invalid_input");
+}
+
 /** Why `previewMail` cannot render a mail: invalid input (with the fields), or list mail without the secret. */
 export type MailPreviewFailure =
   | (Err<"mailing.invalid_input"> & { readonly fields: readonly string[] })
@@ -110,14 +125,15 @@ export interface PreviewMailOptions extends SendMailOptions {
 }
 
 /**
- * Exactly what `sendMail` would hand the provider for `mail`: the sender, the reply-to, and for list mail the
- * footer with a link signed for `mail.to` and the RFC 8058 headers. Sends nothing, logs nothing and needs no
- * database: it does not check the suppression list, so it renders a mail `sendMail` would refuse as suppressed.
+ * Exactly what `sendMail` would hand the provider for `mail`: the sender, the reply-to, the attachments, and for list
+ * mail the footer with a link signed for `mail.to` and the RFC 8058 headers. Sends nothing, logs nothing and needs no
+ * database: it does not check the suppression list, so it renders a mail `sendMail` would refuse as suppressed, nor
+ * whether the provider delivers attachments.
  * The links in it are credentials for `mail.to`. Throws only when the module is not enabled.
  */
 export function previewMail(config: SoftureConfig, mail: OutgoingMail, options: PreviewMailOptions = {}): MailPreviewResult {
   const { env, ...sendOptions } = options;
-  const validation = validateMail(mail, sendOptions);
+  const validation = validateMail(mail, sendOptions, getMailingOptions(config).attachments);
   if (!validation.ok) return { ...err("mailing.invalid_input"), fields: validation.fields };
   const secret = readUnsubscribeSecrets(env).current;
   if (validation.value.kind !== TRANSACTIONAL_KIND && secret === null) return { ...err("mailing.unavailable"), cause: "no_unsubscribe_secret" };
@@ -159,8 +175,8 @@ async function checkListMail(context: MailContext, mail: ValidMail, secret: stri
  */
 function composeMessage(config: SoftureConfig, mail: ValidMail, secret: string | null): ProviderMessage {
   const { from, replyTo } = getMailingOptions(config);
-  const { idempotencyKey, kind, replyTo: mailReplyTo, ...content } = mail;
-  const envelope = { from, replyTo: mailReplyTo ?? replyTo ?? null, idempotencyKey };
+  const { idempotencyKey, kind, replyTo: mailReplyTo, attachments, ...content } = mail;
+  const envelope = { from, replyTo: mailReplyTo ?? replyTo ?? null, idempotencyKey, ...(attachments.length === 0 ? {} : { attachments }) };
   if (kind === TRANSACTIONAL_KIND || secret === null) return { ...content, ...envelope };
   const links = buildUnsubscribeLinks(config, mail.to, secret);
   // The module factory merged the dictionaries; their shape is the module's own.
@@ -226,15 +242,21 @@ function isHttpStatus(value: unknown): value is number {
 
 /**
  * The module's only log line. Deliberately takes nothing but the provider, the code, a status,
- * field names and a fixed cause: anything added "for diagnosis" is where an address leaks first.
+ * field names, a fixed cause and the attachments' content types and sizes: anything added "for
+ * diagnosis" is where an address leaks first. Filenames stay out like the subject: they are the
+ * app's text and often name a person or an invoice.
  */
 function logFailure(
   provider: MailProvider,
   code: MailingErrorCode,
-  details: { readonly status?: number; readonly fields?: readonly string[]; readonly cause?: string },
+  details: { readonly status?: number; readonly fields?: readonly string[]; readonly cause?: string; readonly attachments?: readonly MailAttachment[] },
 ): void {
   const parts = [`provider=${provider.name}`, `reason=${code.slice("mailing.".length)}`, `status=${details.status === undefined ? "none" : String(details.status)}`];
   if (details.fields !== undefined) parts.push(`fields=${details.fields.join(",")}`);
   if (details.cause !== undefined) parts.push(`cause=${details.cause}`);
+  if (details.attachments !== undefined && details.attachments.length > 0) {
+    const attachments = details.attachments.map((attachment) => `${getContentTypeEssence(attachment.contentType)}:${String(attachment.content.byteLength)}`);
+    parts.push(`attachments=${attachments.join(",")}`);
+  }
   console.error(`mailing: send failed ${parts.join(" ")}`);
 }

package/src/server/validate-mail.ts

@@ -2,7 +2,8 @@
 // process. Failures name the fields, never their values (an address is personal data).
 import { z } from "zod";
 import { hasLineBreak, isHeaderName, isIdempotencyKey, isListMailHeader, isMailKind, isReservedHeader, isSingleAddress, MAX_SUBJECT_LENGTH } from "../address.js";
-import { TRANSACTIONAL_KIND } from "../contract.js";
+import { DEFAULT_ATTACHMENT_LIMITS, getContentTypeEssence, isAttachmentFilename, isContentType, type AttachmentLimits } from "../attachments.js";
+import { TRANSACTIONAL_KIND, type MailAttachment } from "../contract.js";
 
 const headersSchema = z.record(z.string(), z.string()).superRefine((headers, context) => {
   for (const [name, value] of Object.entries(headers)) {
@@ -12,7 +13,24 @@ const headersSchema = z.record(z.string(), z.string()).superRefine((headers, con
   }
 });
 
-const mailSchema = z.object({
+const attachmentSchema = z.object({
+  filename: z.string().refine(isAttachmentFilename),
+  contentType: z.string().trim().refine(isContentType),
+  // A Node Buffer is a Uint8Array too; an empty file is almost always a caller's bug.
+  content: z.custom<Uint8Array>((value) => value instanceof Uint8Array && value.byteLength > 0),
+});
+
+/** The attachments within `limits`: count, total bytes and an allowed content type for each. */
+function createAttachmentsSchema(limits: AttachmentLimits) {
+  const allowed = new Set(limits.contentTypes);
+  return z
+    .array(attachmentSchema)
+    .max(limits.maxCount)
+    .refine((attachments) => attachments.every((attachment) => allowed.has(getContentTypeEssence(attachment.contentType))))
+    .refine((attachments) => attachments.reduce((total, attachment) => total + attachment.content.byteLength, 0) <= limits.maxTotalBytes);
+}
+
+const mailFields = {
   to: z.string().trim().refine(isSingleAddress),
   subject: z
     .string()
@@ -25,12 +43,28 @@ const mailSchema = z.object({
   headers: headersSchema.optional(),
   replyTo: z.string().trim().refine(isSingleAddress).optional(),
   kind: z.string().refine(isMailKind).default(TRANSACTIONAL_KIND),
-}).superRefine((mail, context) => {
-  // The module writes these two on list mail; a second, unsigned copy would confuse clients.
-  if (mail.kind !== TRANSACTIONAL_KIND && Object.keys(mail.headers ?? {}).some(isListMailHeader)) {
-    context.addIssue({ code: "custom", path: ["headers"], message: "list mail gets its unsubscribe headers from the module" });
+};
+
+function createMailSchema(limits: AttachmentLimits) {
+  return z.object({ ...mailFields, attachments: createAttachmentsSchema(limits).optional() }).superRefine((mail, context) => {
+    // The module writes these two on list mail; a second, unsigned copy would confuse clients.
+    if (mail.kind !== TRANSACTIONAL_KIND && Object.keys(mail.headers ?? {}).some(isListMailHeader)) {
+      context.addIssue({ code: "custom", path: ["headers"], message: "list mail gets its unsubscribe headers from the module" });
+    }
+  });
+}
+
+/** One schema per limits object: the configured limits are parsed once per config, so this builds each once. */
+const mailSchemas = new WeakMap<AttachmentLimits, ReturnType<typeof createMailSchema>>();
+
+function getMailSchema(limits: AttachmentLimits): ReturnType<typeof createMailSchema> {
+  let schema = mailSchemas.get(limits);
+  if (schema === undefined) {
+    schema = createMailSchema(limits);
+    mailSchemas.set(limits, schema);
   }
-});
+  return schema;
+}
 
 const optionsSchema = z.object({
   idempotencyKey: z.string().refine(isIdempotencyKey).optional(),
@@ -47,25 +81,38 @@ export interface ValidMail {
   /** `transactional` or a list kind. */
   readonly kind: string;
   readonly idempotencyKey: string | null;
+  /** Empty when the mail has none. */
+  readonly attachments: readonly MailAttachment[];
 }
 
 export type MailValidation = { readonly ok: true; readonly value: ValidMail } | { readonly ok: false; readonly fields: readonly string[] };
 
 /**
- * Checks one mail and its send options. `fields` lists what failed (`to`, `subject`, `text`,
- * `html`, `headers`, `replyTo`, `kind`, `idempotencyKey`, or `mail` when the input is not an object).
+ * Checks one mail and its send options, its attachments against `limits` (default: the module's defaults; `sendMail`
+ * passes the configured ones). `fields` lists what failed (`to`, `subject`, `text`, `html`, `headers`, `replyTo`,
+ * `kind`, `attachments`, `idempotencyKey`, or `mail` when the input is not an object).
  */
-export function validateMail(mail: unknown, options: unknown = {}): MailValidation {
-  const parsedMail = mailSchema.safeParse(mail);
+export function validateMail(mail: unknown, options: unknown = {}, limits: AttachmentLimits = DEFAULT_ATTACHMENT_LIMITS): MailValidation {
+  const parsedMail = getMailSchema(limits).safeParse(mail);
   const parsedOptions = optionsSchema.safeParse(options ?? {});
   if (!parsedMail.success || !parsedOptions.success) {
     const issues = [...(parsedMail.error?.issues ?? []), ...(parsedOptions.error?.issues ?? [])];
     const fields = new Set(issues.map((issue) => (issue.path.length === 0 ? "mail" : String(issue.path[0]))));
     return { ok: false, fields: [...fields] };
   }
-  const { to, subject, text, html, headers, replyTo, kind } = parsedMail.data;
+  const { to, subject, text, html, headers, replyTo, kind, attachments = [] } = parsedMail.data;
   return {
     ok: true,
-    value: { to, subject, text, html: html ?? null, headers: headers ?? {}, replyTo: replyTo ?? null, kind, idempotencyKey: parsedOptions.data.idempotencyKey ?? null },
+    value: {
+      to,
+      subject,
+      text,
+      html: html ?? null,
+      headers: headers ?? {},
+      replyTo: replyTo ?? null,
+      kind,
+      idempotencyKey: parsedOptions.data.idempotencyKey ?? null,
+      attachments,
+    },
   };
 }

package/src/testing/fake-provider.ts

@@ -1,6 +1,6 @@
 // A provider that sends nothing: it captures mail in memory (`provider.sent`) and, with an outbox
 // file, appends each mail as one JSON line for a test in another process (an e2e against
-// `next start`). It honours idempotency keys like a real provider: a repeated key answers the
+// `next start`), attachment bytes as base64. It honours idempotency keys like a real provider: a repeated key answers the
 // first id and captures nothing new.
 import { appendFile } from "node:fs/promises";
 import type { MailProvider, ProviderMessage, ProviderOutcome } from "../contract.js";
@@ -34,6 +34,7 @@ export function fakeMailProvider(options: FakeMailProviderOptions = {}): FakeMai
 
   return {
     name: "fake",
+    supportsAttachments: true,
     get sent() {
       return [...sent];
     },
@@ -54,9 +55,14 @@ export function fakeMailProvider(options: FakeMailProviderOptions = {}): FakeMai
       if (knownId !== undefined) return { status: "sent", id: knownId };
 
       counter += 1;
-      const captured: CapturedMail = { ...message, headers: { ...message.headers }, id: `fake-${String(counter)}-${crypto.randomUUID()}` };
+      const captured: CapturedMail = {
+        ...message,
+        headers: { ...message.headers },
+        ...(message.attachments === undefined ? {} : { attachments: message.attachments.map((attachment) => ({ ...attachment, content: attachment.content.slice() })) }),
+        id: `fake-${String(counter)}-${crypto.randomUUID()}`,
+      };
       if (options.outboxFile !== undefined) {
-        await appendFile(options.outboxFile, `${JSON.stringify(captured)}\n`, "utf8");
+        await appendFile(options.outboxFile, `${JSON.stringify(toOutboxLine(captured))}\n`, "utf8");
       }
       sent.push(captured);
       if (message.idempotencyKey !== null) idsByKey.set(message.idempotencyKey, captured.id);
@@ -64,3 +70,12 @@ export function fakeMailProvider(options: FakeMailProviderOptions = {}): FakeMai
     },
   };
 }
+
+/** A captured mail as one outbox line: attachment bytes as base64 (`readMailOutbox` decodes them). */
+function toOutboxLine(mail: CapturedMail): unknown {
+  if (mail.attachments === undefined) return mail;
+  return {
+    ...mail,
+    attachments: mail.attachments.map((attachment) => ({ ...attachment, content: Buffer.from(attachment.content).toString("base64") })),
+  };
+}

package/src/testing/outbox.ts

@@ -13,6 +13,10 @@ const capturedMailSchema = z.object({
   html: z.string().nullable(),
   headers: z.record(z.string(), z.string()),
   idempotencyKey: z.string().nullable(),
+  // Base64 in the file, bytes again here; lines written before attachments existed have none.
+  attachments: z
+    .array(z.object({ filename: z.string(), contentType: z.string(), content: z.base64().transform((content) => new Uint8Array(Buffer.from(content, "base64"))) }))
+    .optional(),
 });
 
 /** Every mail in the outbox, oldest first, optionally only those to `to`. A missing file is an empty outbox. */
@@ -27,6 +31,12 @@ export async function readMailOutbox(file: string, filter: { readonly to?: strin
   return text
     .split("\n")
     .filter((line) => line !== "")
-    .map((line) => capturedMailSchema.parse(JSON.parse(line)))
+    .map((line) => toCapturedMail(capturedMailSchema.parse(JSON.parse(line))))
     .filter((mail) => filter.to === undefined || mail.to === filter.to);
 }
+
+/** A parsed line without an `attachments: undefined` key, so a mail without attachments equals what was sent. */
+function toCapturedMail(line: z.output<typeof capturedMailSchema>): CapturedMail {
+  const { attachments, ...mail } = line;
+  return attachments === undefined ? mail : { ...mail, attachments };
+}