@visulima/email 1.0.0-alpha.1

package/dist/attachment-helpers.d.ts

@@ -0,0 +1,64 @@
+import type { Buffer } from "node:buffer";
+/**
+ * Detects MIME type from filename using mime package.
+ * Falls back to application/octet-stream if not found.
+ * @param filename The filename or path.
+ * @returns MIME type or application/octet-stream as fallback.
+ */
+export declare const detectMimeType: (filename: string) => string;
+/**
+ * Generates a Content-ID for inline attachments.
+ * @param filename The filename to generate CID from.
+ * @returns A unique Content-ID string.
+ */
+export declare const generateContentId: (filename: string) => string;
+/**
+ * Reads file and returns its content as Buffer.
+ * @param filePath Path to the file.
+ * @returns Buffer containing file content.
+ */
+export declare const readFileAsBuffer: (filePath: string) => Promise<Buffer>;
+/**
+ * Attachment options for helper methods
+ */
+export interface AttachmentOptions {
+    /**
+     * Content-ID for inline attachments (used in HTML with cid:).
+     * If not provided and contentDisposition is 'inline', will be auto-generated.
+     */
+    cid?: string;
+    /**
+     * Content disposition type.
+     * 'attachment' (default) or 'inline'.
+     */
+    contentDisposition?: "attachment" | "inline";
+    /**
+     * MIME type of the attachment.
+     * If not provided, will be detected from filename.
+     */
+    contentType?: string;
+    /**
+     * Content transfer encoding.
+     * Examples: 'base64', '7bit', 'quoted-printable'.
+     */
+    encoding?: string;
+    /**
+     * Custom filename.
+     * Used when different from the file path.
+     */
+    filename?: string;
+    /**
+     * Custom headers for this attachment.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Attachment data options (for raw data attachments)
+ */
+export interface AttachmentDataOptions extends AttachmentOptions {
+    /**
+     * Filename for the attachment.
+     * Required for raw data attachments.
+     */
+    filename: string;
+}

package/dist/crypto/dkim-signer.d.ts

@@ -0,0 +1,48 @@
+import type { EmailOptions } from "../types.d.ts";
+import type { DkimOptions, EmailSigner } from "./types.d.ts";
+/**
+ * DKIM signer implementation
+ */
+export declare class DkimSigner implements EmailSigner {
+    /**
+     * Sanitizes a display name for use in quoted email headers per RFC 5322.
+     * Removes/replaces CR, LF, tabs with space, escapes backslashes and quotes,
+     * and strips non-printable control characters.
+     * @param name The display name to sanitize.
+     * @returns The sanitized display name, or empty string if nothing remains.
+     */
+    private static sanitizeDisplayName;
+    /**
+     * Formats an email address for use in email headers.
+     * @param address The email address object to format.
+     * @param address.email The email address string.
+     * @param address.name Optional display name for the email address.
+     * @returns The formatted email address string in RFC 5322 format.
+     */
+    private static formatAddress;
+    /**
+     * Formats email addresses for headers.
+     * @param addresses The email address(es) to format (single or array).
+     * @returns The formatted email addresses string (comma-separated if multiple).
+     */
+    private static formatAddresses;
+    private readonly options;
+    /**
+     * Creates a new DKIM signer.
+     * @param options DKIM signing options.
+     */
+    constructor(options: DkimOptions);
+    /**
+     * Signs an email message with DKIM.
+     * @param email The email options to sign.
+     * @returns The email options with DKIM signature header added.
+     * @throws {Error} When signing fails (e.g., invalid private key).
+     */
+    sign(email: EmailOptions): Promise<EmailOptions>;
+}
+/**
+ * Creates a DKIM signer instance.
+ * @param options DKIM signing options.
+ * @returns A new DkimSigner instance.
+ */
+export declare const createDkimSigner: (options: DkimOptions) => DkimSigner;

package/dist/crypto/index.d.ts

@@ -0,0 +1,4 @@
+export { createDkimSigner, DkimSigner } from "./dkim-signer.d.ts";
+export { createSmimeEncrypter, SmimeEncrypter } from "./smime-encrypter.d.ts";
+export { createSmimeSigner, SmimeSigner } from "./smime-signer.d.ts";
+export type { DkimOptions, EmailEncrypter, EmailSigner, SmimeEncryptOptions, SmimeSignOptions } from "./types.d.ts";

package/dist/crypto/index.js

@@ -0,0 +1 @@
+import{DkimSigner as m,createDkimSigner as i}from"../packem_shared/DkimSigner-Z8D4Il10.js";import{SmimeEncrypter as S,createSmimeEncrypter as n}from"../packem_shared/SmimeEncrypter-CBevU534.js";import{SmimeSigner as c,createSmimeSigner as p}from"../packem_shared/SmimeSigner-02aXVi90.js";export{m as DkimSigner,S as SmimeEncrypter,c as SmimeSigner,i as createDkimSigner,n as createSmimeEncrypter,p as createSmimeSigner};

package/dist/crypto/smime-encrypter.d.ts

@@ -0,0 +1,53 @@
+import type { EmailOptions } from "../types.d.ts";
+import type { EmailEncrypter, SmimeEncryptOptions } from "./types.d.ts";
+/**
+ * S/MIME encrypter implementation using PKIjs
+ * Note: Requires pkijs and asn1js for S/MIME operations
+ * Uses Node.js crypto for all cryptographic operations
+ */
+export declare class SmimeEncrypter implements EmailEncrypter {
+    /**
+     * Collects and normalizes all recipients (to, cc, bcc) from email options.
+     * Normalizes each to an array, extracts email addresses, and deduplicates.
+     * @param email The email options containing recipients.
+     * @returns An array of unique email addresses (strings).
+     */
+    private static collectRecipients;
+    /**
+     * Formats an email address for use in email headers.
+     * @param address The email address to format (string or EmailAddress object).
+     * @returns The formatted email address string in RFC 5322 format.
+     */
+    private static formatAddress;
+    /**
+     * Formats email addresses for use in email headers.
+     * @param addresses The email addresses to format (single or array, string or EmailAddress objects).
+     * @returns The formatted email addresses string (comma-separated if multiple).
+     */
+    private static formatAddresses;
+    private readonly options;
+    /**
+     * Creates a new S/MIME encrypter.
+     * @param options S/MIME encryption options.
+     */
+    constructor(options: SmimeEncryptOptions);
+    /**
+     * Encrypts an email message with S/MIME.
+     * @param email The email options to encrypt.
+     * @returns The encrypted email options.
+     * @throws {Error} When encryption fails (e.g., invalid certificate).
+     */
+    encrypt(email: EmailOptions): Promise<EmailOptions>;
+    /**
+     * Builds the email message string from email options.
+     * @param email The email options to build the message from.
+     * @returns The formatted email message as a string.
+     */
+    private buildMessage;
+}
+/**
+ * Creates a new S/MIME encrypter instance.
+ * @param options The S/MIME encryption options.
+ * @returns A new SmimeEncrypter instance ready to encrypt emails.
+ */
+export declare const createSmimeEncrypter: (options: SmimeEncryptOptions) => SmimeEncrypter;

package/dist/crypto/smime-signer.d.ts

@@ -0,0 +1,48 @@
+import type { EmailOptions } from "../types.d.ts";
+import type { EmailSigner, SmimeSignOptions } from "./types.d.ts";
+/**
+ * S/MIME signer implementation using PKIjs
+ * Note: Requires pkijs and asn1js for S/MIME operations
+ * Uses Node.js crypto for all cryptographic operations
+ */
+export declare class SmimeSigner implements EmailSigner {
+    /**
+     * Formats an email address for use in email headers.
+     * @param address The email address object to format.
+     * @param address.email The email address string.
+     * @param address.name Optional display name for the email address.
+     * @returns The formatted email address string in RFC 5322 format.
+     */
+    private static formatAddress;
+    private readonly options;
+    /**
+     * Creates a new S/MIME signer.
+     * @param options S/MIME signing options.
+     */
+    constructor(options: SmimeSignOptions);
+    /**
+     * Signs an email message with S/MIME.
+     * @param email The email options to sign.
+     * @returns The email options with S/MIME signature.
+     * @throws {Error} When signing fails (e.g., invalid certificate/key).
+     */
+    sign(email: EmailOptions): Promise<EmailOptions>;
+    /**
+     * Builds the email message string from email options.
+     * @param email The email options to build the message from.
+     * @returns The formatted email message as a string.
+     */
+    private buildMessage;
+    /**
+     * Formats email addresses for use in email headers.
+     * @param addresses The email addresses to format (single or array).
+     * @returns The formatted email addresses string (comma-separated if multiple).
+     */
+    private formatAddresses;
+}
+/**
+ * Creates a new S/MIME signer instance.
+ * @param options The S/MIME signing options.
+ * @returns A new SmimeSigner instance ready to sign emails.
+ */
+export declare const createSmimeSigner: (options: SmimeSignOptions) => SmimeSigner;

package/dist/crypto/types.d.ts

@@ -0,0 +1,101 @@
+import type { EmailOptions } from "../types.d.ts";
+/**
+ * Options for DKIM signing
+ */
+export interface DkimOptions {
+    /**
+     * Body canonicalization algorithm ('simple' or 'relaxed')
+     * Default: 'simple'
+     */
+    bodyCanon?: "relaxed" | "simple";
+    /**
+     * Domain name used for DKIM signing
+     */
+    domainName: string;
+    /**
+     * Header canonicalization algorithm ('simple' or 'relaxed')
+     * Default: 'simple'
+     */
+    headerCanon?: "relaxed" | "simple";
+    /**
+     * List of header names to ignore when signing
+     */
+    headersToIgnore?: string[];
+    /**
+     * Key selector used for DNS lookup
+     */
+    keySelector: string;
+    /**
+     * Passphrase for the private key (if encrypted)
+     */
+    passphrase?: string;
+    /**
+     * Private key for signing (PEM format)
+     * Can be a string with the key content or a path prefixed with 'file://'
+     */
+    privateKey: string;
+}
+/**
+ * Options for S/MIME signing
+ */
+export interface SmimeSignOptions {
+    /**
+     * Path to the certificate file (PEM format)
+     */
+    certificate: string;
+    /**
+     * Path to intermediate certificates (optional)
+     */
+    intermediateCerts?: string[];
+    /**
+     * Signing options flags
+     * Reserved for future use
+     */
+    options?: number;
+    /**
+     * Passphrase for the private key (if encrypted)
+     */
+    passphrase?: string;
+    /**
+     * Path to the private key file (PEM format)
+     */
+    privateKey: string;
+}
+/**
+ * Options for S/MIME encryption
+ */
+export interface SmimeEncryptOptions {
+    /**
+     * Encryption algorithm (cipher)
+     * Supported: 'aes-256-cbc', 'aes-192-cbc', 'aes-128-cbc'
+     * Default: 'aes-256-cbc'
+     */
+    algorithm?: string;
+    /**
+     * Certificate(s) for encryption
+     * Can be a single certificate path or a map of email -> certificate path
+     */
+    certificates: string | Record<string, string>;
+}
+/**
+ * Interface for email signers
+ */
+export interface EmailSigner {
+    /**
+     * Sign an email message
+     * @param email The email options to sign
+     * @returns The signed email options (may include additional headers or modified content)
+     */
+    sign: (email: EmailOptions) => Promise<EmailOptions>;
+}
+/**
+ * Interface for email encrypters
+ */
+export interface EmailEncrypter {
+    /**
+     * Encrypt an email message
+     * @param email The email options to encrypt
+     * @returns The encrypted email options (content will be encrypted)
+     */
+    encrypt: (email: EmailOptions) => Promise<EmailOptions>;
+}

package/dist/errors/email-error.d.ts

@@ -0,0 +1,17 @@
+import { VisulimaError } from "@visulima/error";
+/**
+ * Base error class for email package operations.
+ * @param component The component name where the error occurred.
+ * @param message The error message describing what went wrong.
+ * @param options Optional error options including cause, code, and hint.
+ */
+declare class EmailError extends VisulimaError {
+    readonly component: string;
+    readonly code?: string;
+    constructor(component: string, message: string, options?: {
+        cause?: Error | unknown;
+        code?: string;
+        hint?: string | string[];
+    });
+}
+export default EmailError;

package/dist/errors/required-option-error.d.ts

@@ -0,0 +1,10 @@
+import EmailError from "./email-error.d.ts";
+/**
+ * Error for missing required options
+ * @param component The component name where the error occurred
+ * @param name The name(s) of the missing required option(s)
+ */
+declare class RequiredOptionError extends EmailError {
+    constructor(component: string, name: string | string[]);
+}
+export default RequiredOptionError;

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export { type AttachmentDataOptions, type AttachmentOptions, detectMimeType, generateContentId, readFileAsBuffer } from "./attachment-helpers.d.ts";
+export { default as EmailError } from "./errors/email-error.d.ts";
+export { default as RequiredOptionError } from "./errors/required-option-error.d.ts";
+export { createMail, Mail, type Mailable, MailMessage } from "./mail.d.ts";
+export type { Provider, ProviderFactory } from "./providers/provider.d.ts";
+export { defineProvider } from "./providers/provider.d.ts";
+export type { TemplateRenderer } from "./template-engines/types.d.ts";
+export type { Attachment, BaseConfig, EmailAddress, EmailHeaders, EmailOptions, EmailResult, EmailTag, FeatureFlags, ImmutableHeaders, MaybePromise, Priority, Receipt, Result, } from "./types.d.ts";
+export { default as buildMimeMessage } from "./utils/build-mime-message.d.ts";
+export { default as comparePriority } from "./utils/compare-priority.d.ts";
+export { default as createLogger } from "./utils/create-logger.d.ts";
+export { default as formatEmailAddress } from "./utils/format-email-address.d.ts";
+export { default as formatEmailAddresses } from "./utils/format-email-addresses.d.ts";
+export { default as generateBoundary } from "./utils/generate-boundary.d.ts";
+export { default as generateMessageId } from "./utils/generate-message-id.d.ts";
+export { default as headersToRecord } from "./utils/headers-to-record.d.ts";
+export { default as isPortAvailable } from "./utils/is-port-available.d.ts";
+export { makeRequest, type RequestOptions } from "./utils/make-request.d.ts";
+export { default as parseAddress } from "./utils/parse-address.d.ts";
+export { default as retry } from "./utils/retry.d.ts";
+export { default as validateEmail } from "./utils/validate-email.d.ts";
+export { default as validateEmailOptions } from "./utils/validate-email-options.d.ts";

package/dist/index.js

@@ -0,0 +1 @@
+import{detectMimeType as a,generateContentId as o,readFileAsBuffer as t}from"./packem_shared/detectMimeType-S8WRsNtY.js";import{default as d}from"./packem_shared/EmailError-zm2ffVav.js";import{default as m}from"./packem_shared/RequiredOptionError-CevW3u2K.js";import{Mail as p,MailMessage as i,createMail as u}from"./packem_shared/MailMessage-Hdgowmvi.js";import{defineProvider as n}from"./packem_shared/defineProvider-B9rSklAJ.js";import{default as M}from"./packem_shared/buildMimeMessage-BPtd0pno.js";import{default as c}from"./packem_shared/comparePriority-BfiwjVsV.js";import{default as v}from"./packem_shared/createLogger-DlElSVQP.js";import{default as P}from"./packem_shared/formatEmailAddress-CHeME3Vk.js";import{default as b}from"./packem_shared/formatEmailAddresses-UegVOe5A.js";import{default as B}from"./packem_shared/generateBoundary-CZ8kJuY6.js";import{default as O}from"./packem_shared/generateMessageId-11Ls5JsR.js";import{default as h}from"./packem_shared/headersToRecord-BKUTr40L.js";import{default as C}from"./packem_shared/isPortAvailable-5kfsfo8u.js";import{makeRequest as L}from"./packem_shared/makeRequest-DwxHX0xo.js";import{default as w}from"./packem_shared/parseAddress-CATTKGe_.js";import{default as D}from"./packem_shared/retry-D1MBqS49.js";import{default as H}from"./packem_shared/validateEmail-BkVdVioP.js";import{default as K}from"./packem_shared/validateEmailOptions-BzlJECG5.js";export{d as EmailError,p as Mail,i as MailMessage,m as RequiredOptionError,M as buildMimeMessage,c as comparePriority,v as createLogger,u as createMail,n as defineProvider,a as detectMimeType,P as formatEmailAddress,b as formatEmailAddresses,B as generateBoundary,o as generateContentId,O as generateMessageId,h as headersToRecord,C as isPortAvailable,L as makeRequest,w as parseAddress,t as readFileAsBuffer,D as retry,H as validateEmail,K as validateEmailOptions};