@schemavaults/send-email 0.3.0 → 0.4.0

package/dist/validators/email-attachment-schema.js

@@ -0,0 +1,120 @@
+import { z } from "zod";
+/**
+ * Maximum number of attachments accepted on a single email.
+ */
+export const MAX_ATTACHMENTS_PER_EMAIL = 20;
+/**
+ * Maximum combined size, in decoded bytes, of every attachment on a single
+ *  email (25 MiB). Most receiving mail systems reject whole messages larger
+ *  than this, so bigger payloads would never be deliverable regardless of
+ *  which transport the mail-server uses. The mail-server (and the platform
+ *  it is hosted on) may enforce a lower limit of its own.
+ */
+export const MAX_TOTAL_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+/**
+ * Number of bytes a (padded, whitespace-free) base64 string decodes to,
+ *  computed without actually decoding it.
+ */
+export function base64DecodedByteLength(base64) {
+    if (base64.length === 0)
+        return 0;
+    let padding = 0;
+    if (base64.endsWith("=="))
+        padding = 2;
+    else if (base64.endsWith("="))
+        padding = 1;
+    return Math.floor((base64.length * 3) / 4) - padding;
+}
+function hasControlCharacters(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+/**
+ * Name the recipient's mail client shows for the attached file. Unicode is
+ *  allowed; path separators and control characters are not.
+ */
+export const attachmentFilenameSchema = z
+    .string()
+    .min(1, "Attachment filename must be non-empty!")
+    .max(255, "Attachment filename must be at most 255 characters!")
+    .refine((name) => name !== "." && name !== "..", {
+    message: "Attachment filename must not be '.' or '..'!",
+})
+    .refine((name) => !name.includes("/") && !name.includes("\\"), {
+    message: "Attachment filename must not contain path separators!",
+})
+    .refine((name) => !hasControlCharacters(name), {
+    message: "Attachment filename must not contain control characters!",
+});
+/**
+ * The attached file's bytes, base64-encoded (standard alphabet, padded, no
+ *  line breaks). Request bodies are JSON, so binary content has to travel
+ *  as text.
+ */
+export const attachmentContentSchema = z
+    .base64("Attachment content must be base64-encoded!")
+    .min(1, "Attachment content must not be empty!");
+const MIME_TOKEN = "[A-Za-z0-9!#$&^_.+-]+";
+/**
+ * MIME type of the attachment, e.g. "application/pdf" or
+ *  "text/csv; charset=utf-8". When omitted, the mail-server's transport
+ *  derives it from the filename's extension.
+ */
+export const attachmentContentTypeSchema = z
+    .string()
+    .min(1, "Attachment content type must be non-empty!")
+    .max(255, "Attachment content type must be at most 255 characters!")
+    .regex(new RegExp(`^${MIME_TOKEN}\\/${MIME_TOKEN}(?:\\s*;\\s*${MIME_TOKEN}=(?:"[^"]*"|[^\\s;"]+))*$`), "Attachment content type must be a MIME type such as 'application/pdf'!");
+/**
+ * Content-ID for inline attachments. Setting it marks the attachment as
+ *  inline so the HTML body can reference it as `<img src="cid:<contentId>">`.
+ *  Pass the bare identifier -- without the angle brackets.
+ */
+export const attachmentContentIdSchema = z
+    .string()
+    .min(1, "Attachment content ID must be non-empty!")
+    .max(255, "Attachment content ID must be at most 255 characters!")
+    .regex(/^[^\s<>]+$/, "Attachment content ID must not contain whitespace or angle brackets!");
+/**
+ * A single file attached to an email, in the shape accepted by the
+ *  `@schemavaults/mail-server` `/api/send` route.
+ */
+export const emailAttachmentSchema = z
+    .object({
+    filename: attachmentFilenameSchema,
+    content: attachmentContentSchema,
+    contentType: attachmentContentTypeSchema.optional(),
+    contentId: attachmentContentIdSchema.optional(),
+})
+    .required({
+    filename: true,
+    content: true,
+})
+    .strict();
+/**
+ * The full list of attachments on one email: between 1 and
+ *  {@link MAX_ATTACHMENTS_PER_EMAIL} files whose decoded sizes add up to at
+ *  most {@link MAX_TOTAL_ATTACHMENT_BYTES}.
+ */
+export const emailAttachmentsSchema = z
+    .array(emailAttachmentSchema)
+    .min(1, "Provide at least one attachment, or omit 'attachments' entirely!")
+    .max(MAX_ATTACHMENTS_PER_EMAIL, `An email may have at most ${MAX_ATTACHMENTS_PER_EMAIL} attachments!`)
+    .superRefine((attachments, ctx) => {
+    let totalBytes = 0;
+    for (const attachment of attachments) {
+        totalBytes += base64DecodedByteLength(attachment.content);
+    }
+    if (totalBytes > MAX_TOTAL_ATTACHMENT_BYTES) {
+        ctx.addIssue({
+            code: "custom",
+            message: `Attachments must total at most ${MAX_TOTAL_ATTACHMENT_BYTES} bytes (${MAX_TOTAL_ATTACHMENT_BYTES / (1024 * 1024)} MiB) once decoded; received ${totalBytes} bytes.`,
+        });
+    }
+});
+export default emailAttachmentSchema;
+//# sourceMappingURL=email-attachment-schema.js.map

package/dist/validators/email-attachment-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-attachment-schema.js","sourceRoot":"","sources":["../../src/validators/email-attachment-schema.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schemavaults/send-email",
   "description": "Schema defining the shape of the request body to send an email via @schemavaults/mail-server",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "UNLICENSED",
   "private": false,
   "repository": {
@@ -16,8 +16,8 @@
     "schemavaults-send-email": "dist/cli.js"
   },
   "dependencies": {
-    "zod": "3.25.8",
-    "commander": "^14.0.1"
+    "zod": "4.4.3",
+    "commander": "14.0.1"
   },
   "scripts": {
     "build:lib": "tsc --project tsconfig.json && tsc-alias --project tsconfig.json",
@@ -51,6 +51,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js"
     },
+    "./create-email-attachment-from-file": {
+      "types": "./dist/create-email-attachment-from-file.d.ts",
+      "import": "./dist/create-email-attachment-from-file.js",
+      "require": "./dist/create-email-attachment-from-file.js"
+    },
     "./*": {
       "types": "./dist/*",
       "import": "./dist/*",