@venizia/ignis 0.4.3 → 0.4.5

package/dist/esm/components/mail/utilities/attachment.utility.js

@@ -0,0 +1,208 @@
+import { constants } from 'node:fs';
+import { open, realpath } from 'node:fs/promises';
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path';
+import { ContentTypeTable } from '@venizia/ignis-helpers/common';
+import { getError } from '@venizia/ignis-helpers/core';
+import { LoggerFactory } from '@venizia/ignis-helpers';
+import { MailErrors } from '../common/index.js';
+const logger = LoggerFactory.getLogger(['MailAttachments']);
+// O_NONBLOCK: opening a FIFO must not wait for a writer; the fstat check then refuses it.
+// Windows has neither flag; there the realpath containment check stands alone.
+const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+// One reason for missing, directory, unreadable and escaping paths: no existence oracle.
+const PATH_OUTSIDE_REASON = 'attachment.path must name a readable file inside attachmentRoot | pass the bytes as content instead';
+const buildPathRefusedError = (opts) => {
+    return getError({
+        error: MailErrors.ATTACHMENT_PATH_REFUSED,
+        message: `Mail attachment path refused | ${opts.reason}`,
+        cause: opts.cause,
+    });
+};
+const buildTooLargeError = (opts) => {
+    return getError({
+        error: MailErrors.ATTACHMENT_TOO_LARGE,
+        message: `Mail attachments are over maxAttachmentBytes (${opts.maxBytes} bytes per message) | raise maxAttachmentBytes on the mail options, or send smaller attachments`,
+    });
+};
+const assertWithinLimit = (opts) => {
+    const { byteLength, usedBytes, maxBytes } = opts;
+    if (maxBytes === undefined || usedBytes + byteLength <= maxBytes) {
+        return;
+    }
+    throw buildTooLargeError({ maxBytes });
+};
+const isAttachmentStream = (value) => {
+    return typeof value === 'object' && value !== null && Symbol.asyncIterator in value;
+};
+const toBuffer = (chunk) => {
+    if (typeof chunk === 'string') {
+        return Buffer.from(chunk);
+    }
+    return Buffer.isBuffer(chunk)
+        ? chunk
+        : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+};
+/** Throwing out of `for await` destroys a Node Readable and cancels a web ReadableStream. */
+const drainStream = async (opts) => {
+    const { stream, usedBytes, maxBytes } = opts;
+    const chunks = [];
+    let streamBytes = 0;
+    for await (const chunk of stream) {
+        const buffer = toBuffer(chunk);
+        streamBytes += buffer.byteLength;
+        // Per chunk: a stream has no length up front, and the rest must never be buffered.
+        assertWithinLimit({ byteLength: streamBytes, usedBytes, maxBytes });
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks, streamBytes);
+};
+/**
+ * Both sides go through realpath, so neither `..` nor a symlink can leave the root. Not closed: a
+ * directory inside the root swapped for a symlink between this check and `open` - that takes write
+ * access inside the root, so keep the root writable only by what the application trusts.
+ */
+const resolveConfinedPath = async (opts) => {
+    const { path, attachmentRoot } = opts;
+    let rootPath;
+    let filePath;
+    // `resolve` throws synchronously on a non-string `path` from an untyped caller; it lands here too.
+    try {
+        [rootPath, filePath] = await Promise.all([
+            realpath(attachmentRoot),
+            realpath(resolve(attachmentRoot, path)),
+        ]);
+    }
+    catch (error) {
+        throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON, cause: error });
+    }
+    const relation = relative(rootPath, filePath);
+    const isOutside = relation === '' || relation === '..' || relation.startsWith(`..${sep}`) || isAbsolute(relation);
+    if (isOutside) {
+        throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON });
+    }
+    return filePath;
+};
+const readConfinedFile = async (opts) => {
+    const { path, usedBytes, attachmentRoot, maxBytes } = opts;
+    if (!attachmentRoot) {
+        throw buildPathRefusedError({
+            reason: 'attachment.path is read only under attachmentRoot, which is not set | set attachmentRoot on the mail options, or pass the bytes as content',
+        });
+    }
+    const filePath = await resolveConfinedPath({ path, attachmentRoot });
+    const handle = await open(filePath, OPEN_FLAGS).catch((error) => {
+        throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON, cause: error });
+    });
+    try {
+        const stats = await handle.stat();
+        if (!stats.isFile()) {
+            throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON });
+        }
+        // Sized before reading, so a file known to be oversized is never opened for reading.
+        assertWithinLimit({ byteLength: stats.size, usedBytes, maxBytes });
+        // Counted while read, and read no further than one byte past the budget: the file may have
+        // grown since fstat.
+        const stream = handle.createReadStream({
+            autoClose: false,
+            end: maxBytes === undefined ? Infinity : maxBytes - usedBytes,
+        });
+        return await drainStream({ stream, usedBytes, maxBytes });
+    }
+    finally {
+        await handle.close();
+    }
+};
+/**
+ * Reads one attachment's bytes. A string `content` is raw text unless `encoding` says otherwise
+ * (nodemailer's convention); `null` counts as absent. A `path` is read only inside
+ * `attachmentRoot` and refused without one. `maxBytes` caps the whole message; `usedBytes` is what
+ * earlier attachments already took.
+ */
+export const readAttachmentContent = async (opts) => {
+    const { attachment, attachmentRoot, maxBytes, usedBytes = 0 } = opts;
+    const { content } = attachment;
+    if (content !== undefined && content !== null) {
+        if (typeof content === 'string') {
+            const encoding = attachment.encoding ?? 'utf-8';
+            assertWithinLimit({ byteLength: Buffer.byteLength(content, encoding), usedBytes, maxBytes });
+            return Buffer.from(content, encoding);
+        }
+        if (content instanceof Uint8Array) {
+            assertWithinLimit({ byteLength: content.byteLength, usedBytes, maxBytes });
+            return toBuffer(content);
+        }
+        if (!isAttachmentStream(content)) {
+            throw getError({
+                error: MailErrors.INVALID_CONFIGURATION,
+                message: 'Invalid mail attachment | attachment.content must be a Buffer, a Uint8Array, a string or a stream',
+            });
+        }
+        return drainStream({ stream: content, usedBytes, maxBytes });
+    }
+    if (attachment.path !== undefined && attachment.path !== null) {
+        return readConfinedFile({ path: attachment.path, usedBytes, attachmentRoot, maxBytes });
+    }
+    return Buffer.alloc(0);
+};
+/**
+ * Turns every attachment into `content` bytes and drops `path`, so no transport is ever handed a
+ * file or URL to read on its own. `maxBytes` is shared by all attachments of the message. An
+ * attachment read from `path` keeps the file's name and, when none is given, its content type.
+ */
+export const resolveMailAttachments = async (opts) => {
+    const { attachments, attachmentRoot, maxBytes } = opts;
+    const resolved = [];
+    let usedBytes = 0;
+    // Sequential on purpose: each read spends the budget the previous ones left.
+    for (const attachment of attachments) {
+        const { path, href, raw, content, encoding, ...rest } = attachment;
+        // nodemailer reads both on its own - `href` fetches a URL, `raw` can carry a `path`.
+        if ((href !== undefined && href !== null) || (raw !== undefined && raw !== null)) {
+            throw buildPathRefusedError({
+                reason: 'attachment.href and attachment.raw are not supported | pass the bytes as content',
+            });
+        }
+        const bytes = await readAttachmentContent({
+            attachment: { content, encoding, path },
+            attachmentRoot,
+            maxBytes,
+            usedBytes,
+        });
+        usedBytes += bytes.byteLength;
+        const isReadFromPath = (content === undefined || content === null) && typeof path === 'string';
+        const filename = rest.filename ?? (isReadFromPath ? basename(path) : undefined);
+        const contentType = rest.contentType ??
+            (isReadFromPath && filename ? ContentTypeTable.resolve({ filename }) : undefined);
+        resolved.push({
+            ...rest,
+            ...(filename === undefined ? {} : { filename }),
+            ...(contentType === undefined ? {} : { contentType }),
+            content: bytes,
+        });
+    }
+    return resolved;
+};
+/**
+ * Releases every attachment stream of a refused send, read or not, so none keeps a descriptor
+ * open. A drained stream is already closed; releasing it again is harmless.
+ */
+export const releaseAttachmentStreams = (opts) => {
+    for (const attachment of opts.attachments ?? []) {
+        const { content } = attachment;
+        if (content instanceof ReadableStream) {
+            if (!content.locked) {
+                content.cancel().catch((error) => {
+                    logger.warn('[releaseAttachmentStreams] Cancelling a web stream failed | error: %s', error);
+                });
+            }
+            continue;
+        }
+        if (typeof content === 'object' &&
+            content !== null &&
+            'destroy' in content &&
+            typeof content.destroy === 'function') {
+            content.destroy();
+        }
+    }
+};
+//# sourceMappingURL=attachment.utility.js.map

package/dist/esm/components/mail/utilities/attachment.utility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.utility.js","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/attachment.utility.ts"],"names":[],"mappings":"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","sourcesContent":["import { constants } from 'node:fs';\nimport { open, realpath } from 'node:fs/promises';\nimport { basename, isAbsolute, relative, resolve, sep } from 'node:path';\nimport { ContentTypeTable } from '@venizia/ignis-helpers/common';\nimport { getError } from '@venizia/ignis-helpers/core';\nimport { LoggerFactory } from '@venizia/ignis-helpers';\nimport { MailErrors, type IMailAttachment } from '../common';\n\nconst logger = LoggerFactory.getLogger(['MailAttachments']);\n\n// O_NONBLOCK: opening a FIFO must not wait for a writer; the fstat check then refuses it.\n// Windows has neither flag; there the realpath containment check stands alone.\nconst OPEN_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);\n\n// One reason for missing, directory, unreadable and escaping paths: no existence oracle.\nconst PATH_OUTSIDE_REASON =\n  'attachment.path must name a readable file inside attachmentRoot | pass the bytes as content instead';\n\ntype TAttachmentStream = AsyncIterable<Uint8Array | string>;\n\nconst buildPathRefusedError = (opts: { reason: string; cause?: unknown }) => {\n  return getError({\n    error: MailErrors.ATTACHMENT_PATH_REFUSED,\n    message: `Mail attachment path refused | ${opts.reason}`,\n    cause: opts.cause,\n  });\n};\n\nconst buildTooLargeError = (opts: { maxBytes: number }) => {\n  return getError({\n    error: MailErrors.ATTACHMENT_TOO_LARGE,\n    message: `Mail attachments are over maxAttachmentBytes (${opts.maxBytes} bytes per message) | raise maxAttachmentBytes on the mail options, or send smaller attachments`,\n  });\n};\n\nconst assertWithinLimit = (opts: { byteLength: number; usedBytes: number; maxBytes?: number }) => {\n  const { byteLength, usedBytes, maxBytes } = opts;\n\n  if (maxBytes === undefined || usedBytes + byteLength <= maxBytes) {\n    return;\n  }\n\n  throw buildTooLargeError({ maxBytes });\n};\n\nconst isAttachmentStream = (value: unknown): value is TAttachmentStream => {\n  return typeof value === 'object' && value !== null && Symbol.asyncIterator in value;\n};\n\nconst toBuffer = (chunk: Uint8Array | string): Buffer => {\n  if (typeof chunk === 'string') {\n    return Buffer.from(chunk);\n  }\n\n  return Buffer.isBuffer(chunk)\n    ? chunk\n    : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);\n};\n\n/** Throwing out of `for await` destroys a Node Readable and cancels a web ReadableStream. */\nconst drainStream = async (opts: {\n  stream: TAttachmentStream;\n  usedBytes: number;\n  maxBytes?: number;\n}): Promise<Buffer> => {\n  const { stream, usedBytes, maxBytes } = opts;\n  const chunks: Buffer[] = [];\n  let streamBytes = 0;\n\n  for await (const chunk of stream) {\n    const buffer = toBuffer(chunk);\n    streamBytes += buffer.byteLength;\n\n    // Per chunk: a stream has no length up front, and the rest must never be buffered.\n    assertWithinLimit({ byteLength: streamBytes, usedBytes, maxBytes });\n    chunks.push(buffer);\n  }\n\n  return Buffer.concat(chunks, streamBytes);\n};\n\n/**\n * Both sides go through realpath, so neither `..` nor a symlink can leave the root. Not closed: a\n * directory inside the root swapped for a symlink between this check and `open` - that takes write\n * access inside the root, so keep the root writable only by what the application trusts.\n */\nconst resolveConfinedPath = async (opts: {\n  path: string;\n  attachmentRoot: string;\n}): Promise<string> => {\n  const { path, attachmentRoot } = opts;\n\n  let rootPath: string;\n  let filePath: string;\n\n  // `resolve` throws synchronously on a non-string `path` from an untyped caller; it lands here too.\n  try {\n    [rootPath, filePath] = await Promise.all([\n      realpath(attachmentRoot),\n      realpath(resolve(attachmentRoot, path)),\n    ]);\n  } catch (error) {\n    throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON, cause: error });\n  }\n\n  const relation = relative(rootPath, filePath);\n  const isOutside =\n    relation === '' || relation === '..' || relation.startsWith(`..${sep}`) || isAbsolute(relation);\n\n  if (isOutside) {\n    throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON });\n  }\n\n  return filePath;\n};\n\nconst readConfinedFile = async (opts: {\n  path: string;\n  usedBytes: number;\n  attachmentRoot?: string;\n  maxBytes?: number;\n}): Promise<Buffer> => {\n  const { path, usedBytes, attachmentRoot, maxBytes } = opts;\n\n  if (!attachmentRoot) {\n    throw buildPathRefusedError({\n      reason:\n        'attachment.path is read only under attachmentRoot, which is not set | set attachmentRoot on the mail options, or pass the bytes as content',\n    });\n  }\n\n  const filePath = await resolveConfinedPath({ path, attachmentRoot });\n  const handle = await open(filePath, OPEN_FLAGS).catch((error) => {\n    throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON, cause: error });\n  });\n\n  try {\n    const stats = await handle.stat();\n\n    if (!stats.isFile()) {\n      throw buildPathRefusedError({ reason: PATH_OUTSIDE_REASON });\n    }\n\n    // Sized before reading, so a file known to be oversized is never opened for reading.\n    assertWithinLimit({ byteLength: stats.size, usedBytes, maxBytes });\n\n    // Counted while read, and read no further than one byte past the budget: the file may have\n    // grown since fstat.\n    const stream = handle.createReadStream({\n      autoClose: false,\n      end: maxBytes === undefined ? Infinity : maxBytes - usedBytes,\n    });\n\n    return await drainStream({ stream, usedBytes, maxBytes });\n  } finally {\n    await handle.close();\n  }\n};\n\n/**\n * Reads one attachment's bytes. A string `content` is raw text unless `encoding` says otherwise\n * (nodemailer's convention); `null` counts as absent. A `path` is read only inside\n * `attachmentRoot` and refused without one. `maxBytes` caps the whole message; `usedBytes` is what\n * earlier attachments already took.\n */\nexport const readAttachmentContent = async (opts: {\n  attachment: IMailAttachment;\n  attachmentRoot?: string;\n  maxBytes?: number;\n  usedBytes?: number;\n}): Promise<Buffer> => {\n  const { attachment, attachmentRoot, maxBytes, usedBytes = 0 } = opts;\n  const { content } = attachment;\n\n  if (content !== undefined && content !== null) {\n    if (typeof content === 'string') {\n      const encoding = attachment.encoding ?? 'utf-8';\n      assertWithinLimit({ byteLength: Buffer.byteLength(content, encoding), usedBytes, maxBytes });\n      return Buffer.from(content, encoding);\n    }\n\n    if (content instanceof Uint8Array) {\n      assertWithinLimit({ byteLength: content.byteLength, usedBytes, maxBytes });\n      return toBuffer(content);\n    }\n\n    if (!isAttachmentStream(content)) {\n      throw getError({\n        error: MailErrors.INVALID_CONFIGURATION,\n        message:\n          'Invalid mail attachment | attachment.content must be a Buffer, a Uint8Array, a string or a stream',\n      });\n    }\n\n    return drainStream({ stream: content, usedBytes, maxBytes });\n  }\n\n  if (attachment.path !== undefined && attachment.path !== null) {\n    return readConfinedFile({ path: attachment.path, usedBytes, attachmentRoot, maxBytes });\n  }\n\n  return Buffer.alloc(0);\n};\n\n/**\n * Turns every attachment into `content` bytes and drops `path`, so no transport is ever handed a\n * file or URL to read on its own. `maxBytes` is shared by all attachments of the message. An\n * attachment read from `path` keeps the file's name and, when none is given, its content type.\n */\nexport const resolveMailAttachments = async (opts: {\n  attachments: IMailAttachment[];\n  attachmentRoot?: string;\n  maxBytes?: number;\n}): Promise<IMailAttachment[]> => {\n  const { attachments, attachmentRoot, maxBytes } = opts;\n  const resolved: IMailAttachment[] = [];\n  let usedBytes = 0;\n\n  // Sequential on purpose: each read spends the budget the previous ones left.\n  for (const attachment of attachments) {\n    const { path, href, raw, content, encoding, ...rest } = attachment;\n\n    // nodemailer reads both on its own - `href` fetches a URL, `raw` can carry a `path`.\n    if ((href !== undefined && href !== null) || (raw !== undefined && raw !== null)) {\n      throw buildPathRefusedError({\n        reason: 'attachment.href and attachment.raw are not supported | pass the bytes as content',\n      });\n    }\n\n    const bytes = await readAttachmentContent({\n      attachment: { content, encoding, path },\n      attachmentRoot,\n      maxBytes,\n      usedBytes,\n    });\n\n    usedBytes += bytes.byteLength;\n\n    const isReadFromPath = (content === undefined || content === null) && typeof path === 'string';\n    const filename = rest.filename ?? (isReadFromPath ? basename(path) : undefined);\n    const contentType =\n      rest.contentType ??\n      (isReadFromPath && filename ? ContentTypeTable.resolve({ filename }) : undefined);\n\n    resolved.push({\n      ...rest,\n      ...(filename === undefined ? {} : { filename }),\n      ...(contentType === undefined ? {} : { contentType }),\n      content: bytes,\n    });\n  }\n\n  return resolved;\n};\n\n/**\n * Releases every attachment stream of a refused send, read or not, so none keeps a descriptor\n * open. A drained stream is already closed; releasing it again is harmless.\n */\nexport const releaseAttachmentStreams = (opts: { attachments?: IMailAttachment[] }): void => {\n  for (const attachment of opts.attachments ?? []) {\n    const { content } = attachment;\n\n    if (content instanceof ReadableStream) {\n      if (!content.locked) {\n        content.cancel().catch((error) => {\n          logger.warn(\n            '[releaseAttachmentStreams] Cancelling a web stream failed | error: %s',\n            error,\n          );\n        });\n      }\n\n      continue;\n    }\n\n    if (\n      typeof content === 'object' &&\n      content !== null &&\n      'destroy' in content &&\n      typeof content.destroy === 'function'\n    ) {\n      content.destroy();\n    }\n  }\n};\n"]}

package/dist/esm/components/mail/utilities/body.utility.d.ts

@@ -0,0 +1,6 @@
+import { type IMailMessage } from '../common/index.js';
+/** nodemailer reads a `text`/`html` given as `{ path }` or `{ href }`, so only a string may pass; `null` counts as absent. */
+export declare const assertMailBodyIsText: (opts: {
+    message: IMailMessage;
+}) => void;
+//# sourceMappingURL=body.utility.d.ts.map

package/dist/esm/components/mail/utilities/body.utility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body.utility.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/body.utility.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAE1D,8HAA8H;AAC9H,eAAO,MAAM,oBAAoB,GAAI,MAAM;IAAE,OAAO,EAAE,YAAY,CAAA;CAAE,KAAG,IActE,CAAC"}

package/dist/esm/components/mail/utilities/body.utility.js

@@ -0,0 +1,16 @@
+import { getError } from '@venizia/ignis-helpers/core';
+import { MailErrors } from '../common/index.js';
+/** nodemailer reads a `text`/`html` given as `{ path }` or `{ href }`, so only a string may pass; `null` counts as absent. */
+export const assertMailBodyIsText = (opts) => {
+    const { text, html } = opts.message;
+    const isTextValid = text === undefined || text === null || typeof text === 'string';
+    const isHtmlValid = html === undefined || html === null || typeof html === 'string';
+    if (isTextValid && isHtmlValid) {
+        return;
+    }
+    throw getError({
+        error: MailErrors.BODY_SOURCE_REFUSED,
+        message: 'Mail body refused | text and html must be strings; pass the content itself, not a { path } or { href } for the transport to read',
+    });
+};
+//# sourceMappingURL=body.utility.js.map

package/dist/esm/components/mail/utilities/body.utility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body.utility.js","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/body.utility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAqB,MAAM,WAAW,CAAC;AAE1D,8HAA8H;AAC9H,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,IAA+B,EAAQ,EAAE;IAC5E,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;IACpC,MAAM,WAAW,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC;IACpF,MAAM,WAAW,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC;IAEpF,IAAI,WAAW,IAAI,WAAW,EAAE,CAAC;QAC/B,OAAO;IACT,CAAC;IAED,MAAM,QAAQ,CAAC;QACb,KAAK,EAAE,UAAU,CAAC,mBAAmB;QACrC,OAAO,EACL,kIAAkI;KACrI,CAAC,CAAC;AACL,CAAC,CAAC","sourcesContent":["import { getError } from '@venizia/ignis-helpers/core';\nimport { MailErrors, type IMailMessage } from '../common';\n\n/** nodemailer reads a `text`/`html` given as `{ path }` or `{ href }`, so only a string may pass; `null` counts as absent. */\nexport const assertMailBodyIsText = (opts: { message: IMailMessage }): void => {\n  const { text, html } = opts.message;\n  const isTextValid = text === undefined || text === null || typeof text === 'string';\n  const isHtmlValid = html === undefined || html === null || typeof html === 'string';\n\n  if (isTextValid && isHtmlValid) {\n    return;\n  }\n\n  throw getError({\n    error: MailErrors.BODY_SOURCE_REFUSED,\n    message:\n      'Mail body refused | text and html must be strings; pass the content itself, not a { path } or { href } for the transport to read',\n  });\n};\n"]}

package/dist/esm/components/mail/utilities/index.d.ts

@@ -0,0 +1,5 @@
+export * from './type.utility.js';
+export * from './address.utility.js';
+export * from './verification.utility.js';
+export * from './mime.utility.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/components/mail/utilities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}

package/dist/esm/components/mail/utilities/index.js

@@ -0,0 +1,5 @@
+export * from './type.utility.js';
+export * from './address.utility.js';
+export * from './verification.utility.js';
+export * from './mime.utility.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/components/mail/utilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC","sourcesContent":["export * from './type.utility';\nexport * from './address.utility';\nexport * from './verification.utility';\nexport * from './mime.utility';\n"]}

package/dist/esm/components/mail/utilities/mime.utility.d.ts

@@ -0,0 +1,19 @@
+import { type IMailMessage } from '../common/index.js';
+/** Formats a `to`/`cc`/`from`/`replyTo` field as one RFC 5322 address list: splits a
+ * comma-separated string or array into individual mailboxes, RFC 2047-encodes each display name,
+ * and rejoins with `, ` - the same shape whether the caller passed a string or an array. */
+export declare function formatAddressHeader(value: string | string[]): string;
+/**
+ * Builds a raw RFC 822 message with zero external dependencies - Amazon SES's `SendEmailCommand`
+ * `Content.Simple` shape has no attachment field, so attachments require a raw MIME body. Written
+ * by hand instead of depending on `nodemailer`'s `MailComposer` so the `ses` provider never needs
+ * the `nodemailer` peer installed at all.
+ *
+ * Inline (`cid`) attachments nest under `multipart/related` next to the body - a mail client
+ * only renders `cid:` references inline when they share a `multipart/related` parent with the
+ * body; under `multipart/mixed` they show up as ordinary downloadable attachments instead. Plain
+ * file attachments (no `cid`) stay under `multipart/mixed`, alongside the body or the
+ * `multipart/related` group when both kinds are present.
+ */
+export declare function buildRawMimeMessage(message: IMailMessage): Promise<Buffer>;
+//# sourceMappingURL=mime.utility.d.ts.map

package/dist/esm/components/mail/utilities/mime.utility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.utility.d.ts","sourceRoot":"","sources":["../../../../../src/components/mail/utilities/mime.utility.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwC,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AA4FpF;;4FAE4F;AAC5F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,CAEpE;AAqQD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CA6FhF"}