@visulima/email 1.0.0-alpha.8 → 1.0.0

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

@@ -1,53 +0,0 @@
-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

@@ -1,48 +0,0 @@
-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

@@ -1,101 +0,0 @@
-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/draft-mail-message.d.ts

@@ -1,13 +0,0 @@
-import MailMessage from "./mail-message.d.ts";
-/**
- * Draft mail message - extends MailMessage with X-Unsent header automatically set.
- * Draft messages cannot be sent directly - they must be converted to regular messages first.
- */
-export declare class DraftMailMessage extends MailMessage {
-    /**
-     * Creates a new draft mail message.
-     * The X-Unsent header is automatically set to '1' to mark this as a draft.
-     */
-    constructor();
-}
-export default DraftMailMessage;

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

@@ -1,17 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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/mail-message.d.ts

@@ -1,425 +0,0 @@
-import type { ICalCalendar } from "ical-generator";
-import type { AttachmentDataOptions, AttachmentOptions } from './attachment-helpers.d.ts';
-import type { EmailEncrypter, EmailSigner } from './crypto/index.d.ts';
-import type { TemplateRenderer } from './template-engines/types.d.ts';
-import type { Attachment, CalendarEventOptions, EmailAddress, EmailHeaders, EmailOptions, Priority } from './types.d.ts';
-type AddressInput = EmailAddress | EmailAddress[] | string | string[];
-/**
- * Mail message builder - provides fluent interface for building emails.
- */
-export declare class MailMessage {
-    private fromAddress?;
-    private toAddresses;
-    private ccAddresses;
-    private bccAddresses;
-    private subjectText;
-    private textContent?;
-    private textCharset;
-    private autoTextEnabled;
-    private htmlContent?;
-    private htmlCharset;
-    private dateValue?;
-    private returnPathAddress?;
-    private senderAddress?;
-    private headers;
-    private attachments;
-    private replyToAddress?;
-    private priorityValue?;
-    private tagsValue;
-    private signer?;
-    private encrypter?;
-    private logger?;
-    private icalEventData?;
-    /**
-     * Sets the sender address.
-     * @param address The sender email address (string or EmailAddress object).
-     * @returns This instance for method chaining.
-     */
-    from(address: EmailAddress | string): this;
-    /**
-     * Sets the recipient address(es).
-     * @param address The recipient email address(es) (string, EmailAddress, or arrays of either).
-     * @returns This instance for method chaining.
-     */
-    to(address: AddressInput): this;
-    /**
-     * Sets the CC recipient address(es).
-     * @param address The CC recipient email address(es) (string, EmailAddress, or arrays of either).
-     * @returns This instance for method chaining.
-     */
-    cc(address: AddressInput): this;
-    /**
-     * Sets the BCC recipient address(es).
-     * @param address The BCC recipient email address(es) (string, EmailAddress, or arrays of either).
-     * @returns This instance for method chaining.
-     */
-    bcc(address: AddressInput): this;
-    /**
-     * Sets the subject line for the email message.
-     * @param text The subject text to set.
-     * @returns This instance for method chaining.
-     */
-    subject(text: string): this;
-    /**
-     * Sets the plain text content of the email.
-     * @param content The plain text content to set.
-     * @param charset Optional charset for the text content (default: 'utf8').
-     * @returns This instance for method chaining.
-     */
-    text(content: string, charset?: string): this;
-    /**
-     * Sets the HTML content of the email.
-     * @param content The HTML content to set.
-     * @param charset Optional charset for the HTML content (default: 'utf8').
-     * @returns This instance for method chaining.
-     */
-    html(content: string, charset?: string): this;
-    /**
-     * Sets a custom email header.
-     * @param name The header name to set.
-     * @param value The header value to set.
-     * @returns This instance for method chaining.
-     */
-    header(name: string, value: string): this;
-    /**
-     * Sets multiple headers.
-     * Accepts both Record<string, string> and ImmutableHeaders.
-     * @param headers The headers to set (Record or ImmutableHeaders).
-     * @returns This instance for method chaining.
-     */
-    setHeaders(headers: EmailHeaders): this;
-    /**
-     * Attaches a file from path (reads file from filesystem).
-     * Similar to Laravel's attach() method.
-     * @param filePath The absolute or relative filesystem path to the file to attach.
-     * @param options Optional attachment configuration (filename, contentType, etc.).
-     * @returns This instance for method chaining.
-     * @example
-     * ```ts
-     * message.attachFromPath('/path/to/file.pdf')
-     * message.attachFromPath('/path/to/file.pdf', { filename: 'custom-name.pdf' })
-     * ```
-     */
-    attachFromPath(filePath: string, options?: AttachmentOptions): Promise<this>;
-    /**
-     * Attaches raw data (string or Buffer).
-     * Similar to Laravel's attachData() method.
-     * @param content The content to attach (string or Buffer).
-     * @param options Attachment options including filename.
-     * @returns This instance for method chaining.
-     * @example
-     * ```ts
-     * message.attachData(Buffer.from('content'), 'file.txt')
-     * message.attachData('content', 'file.txt', { contentType: 'text/plain' })
-     * ```
-     */
-    attachData(content: string | Buffer, options: AttachmentDataOptions): this;
-    /**
-     * Embeds an inline attachment from file path (for images in HTML).
-     * Similar to Laravel's embed() method.
-     * Returns the Content-ID that can be used in HTML: &lt;img src="cid:{cid}">.
-     * @param filePath The path to the file to embed.
-     * @param options Optional attachment options (filename, contentType, etc.).
-     * @returns The Content-ID string that can be used in HTML.
-     * @example
-     * ```ts
-     * const cid = await message.embedFromPath('/path/to/logo.png')
-     * message.html(`<img src="cid:${cid}">`)
-     * ```
-     */
-    embedFromPath(filePath: string, options?: Omit<AttachmentOptions, "contentDisposition" | "cid">): Promise<string>;
-    /**
-     * Embeds raw data as inline attachment (for images in HTML).
-     * Similar to Laravel's embedData() method.
-     * Returns the Content-ID that can be used in HTML: &lt;img src="cid:{cid}">.
-     * @param content The content to embed (string or Buffer).
-     * @param filename The filename for the embedded attachment.
-     * @param options Optional attachment options (contentType, etc.).
-     * @returns The Content-ID string that can be used in HTML.
-     * @example
-     * ```ts
-     * const imageBuffer = Buffer.from('...')
-     * const cid = message.embedData(imageBuffer, 'logo.png', { contentType: 'image/png' })
-     * message.html(`<img src="cid:${cid}">`)
-     * ```
-     */
-    embedData(content: string | Buffer, filename: string, options?: Omit<AttachmentDataOptions, "filename" | "contentDisposition" | "cid">): string;
-    /**
-     * Sets the reply-to address.
-     * @param address The reply-to email address (string or EmailAddress object).
-     * @returns This instance for method chaining.
-     */
-    replyTo(address: EmailAddress | string): this;
-    /**
-     * Sets the date header for the email.
-     * @param date The date to set (Date object or ISO string).
-     * @returns This instance for method chaining.
-     */
-    date(date: Date | string): this;
-    /**
-     * Sets the return-path address (bounce address).
-     * @param address The return-path email address (string or EmailAddress object).
-     * @returns This instance for method chaining.
-     */
-    returnPath(address: EmailAddress | string): this;
-    /**
-     * Sets the sender address (different from From - used when From contains multiple addresses).
-     * @param address The sender email address (string or EmailAddress object).
-     * @returns This instance for method chaining.
-     */
-    sender(address: EmailAddress | string): this;
-    /**
-     * Adds recipient address(es) without replacing existing ones.
-     * @param address The recipient email address(es) (string, EmailAddress, or arrays of either).
-     * @returns This instance for method chaining.
-     */
-    addTo(address: AddressInput): this;
-    /**
-     * Adds CC recipient address(es) without replacing existing ones.
-     * @param address The CC recipient email address(es) (string, EmailAddress, or arrays of either).
-     * @returns This instance for method chaining.
-     */
-    addCc(address: AddressInput): this;
-    /**
-     * Adds BCC recipient address(es) without replacing existing ones.
-     * @param address The BCC recipient email address(es) (string, EmailAddress, or arrays of either).
-     * @returns This instance for method chaining.
-     */
-    addBcc(address: AddressInput): this;
-    /**
-     * Adds reply-to address(es) without replacing existing ones.
-     * @param address The reply-to email address(es) (string, EmailAddress, or arrays of either).
-     * @returns This instance for method chaining.
-     */
-    addReplyTo(address: EmailAddress | string | (EmailAddress | string)[]): this;
-    /**
-     * Adds from address(es) without replacing existing ones.
-     * @param address The sender email address(es) (string, EmailAddress, or arrays of either).
-     * @returns This instance for method chaining.
-     */
-    addFrom(address: EmailAddress | string | (EmailAddress | string)[]): this;
-    /**
-     * Sets the email priority.
-     * @param priority The priority level ('high', 'normal', or 'low').
-     * @returns This instance for method chaining.
-     */
-    priority(priority: Priority): this;
-    /**
-     * Sets email tags for categorization.
-     * @param tags The tags to set (string or array of strings).
-     * @returns This instance for method chaining.
-     */
-    tags(tags: string | string[]): this;
-    /**
-     * Signs the email message using a signer (DKIM or S/MIME).
-     * @param signer The signer instance to use.
-     * @example
-     * ```ts
-     * import { createDkimSigner } from '@visulima/email/crypto';
-     * const signer = createDkimSigner({
-     *   domainName: 'example.com',
-     *   keySelector: 'default',
-     *   privateKey: '-----BEGIN PRIVATE KEY-----...'
-     * });
-     * message.sign(signer)
-     * ```
-     */
-    sign(signer: EmailSigner): this;
-    /**
-     * Encrypts the email message using an encrypter (S/MIME).
-     * @param encrypter The encrypter instance to use.
-     * @example
-     * ```ts
-     * import { createSmimeEncrypter } from '@visulima/email/crypto';
-     * const encrypter = createSmimeEncrypter({
-     *   certificates: '/path/to/certificate.crt'
-     * });
-     * message.encrypt(encrypter)
-     * ```
-     */
-    encrypt(encrypter: EmailEncrypter): this;
-    /**
-     * Sets the logger instance for this message.
-     * @param logger The logger instance (Console) to use for logging.
-     * @returns This instance for method chaining.
-     * @example
-     * ```ts
-     * message.logger(console)
-     * ```
-     */
-    setLogger(logger: Console): this;
-    /**
-     * Attach a calendar event and define contents as string or function.
-     * @param contents The calendar content as a string or a function that receives an ICalCalendar instance.
-     * @param options Optional calendar event options (method, alternativeText).
-     * @returns This instance for method chaining.
-     * @example
-     * ```ts
-     * message.icalEvent((calendar) => {
-     *   calendar.createEvent({
-     *     start: new Date(),
-     *     summary: 'Meeting'
-     *   });
-     * })
-     * message.icalEvent('BEGIN:VCALENDAR...')
-     * ```
-     */
-    icalEvent(contents: ((calendar: ICalCalendar) => void) | string, options?: CalendarEventOptions): this;
-    /**
-     * Attach a calendar event and load contents from a file.
-     * @param file The file path (string or URL) to load the calendar event from.
-     * @param options Optional calendar event options (method, alternativeText).
-     * @returns This instance for method chaining.
-     * @example
-     * ```ts
-     * message.icalEventFromFile('/path/to/event.ics')
-     * message.icalEventFromFile(new URL('file:///path/to/event.ics'))
-     * ```
-     */
-    icalEventFromFile(file: string | URL, options?: CalendarEventOptions): this;
-    /**
-     * Attach a calendar event and load contents from a URL.
-     * @param url The URL to fetch the calendar event from.
-     * @param options Optional calendar event options (method, alternativeText).
-     * @returns This instance for method chaining.
-     * @example
-     * ```ts
-     * message.icalEventFromUrl('https://example.com/event.ics')
-     * ```
-     */
-    icalEventFromUrl(url: string, options?: CalendarEventOptions): this;
-    /**
-     * Renders a template and sets as HTML content.
-     * Accepts a render function for flexible template engine support.
-     * @param render The template renderer function.
-     * @param template The template content (string, React component, etc.).
-     * @param data Optional data/variables to pass to the template.
-     * @param options Optional renderer-specific options.
-     * @param options.autoText Whether to auto-generate text version from HTML (default: true).
-     * @returns This instance for method chaining.
-     * @example
-     * ```ts
-     * import { renderHandlebars } from '@visulima/email/template/handlebars';
-     * message.view(renderHandlebars, '<h1>Hello {{name}}!</h1>', { name: 'John' })
-     *
-     * import { renderMjml } from '@visulima/email/template/mjml';
-     * message.view(renderMjml, mjmlTemplate)
-     *
-     * import { renderReactEmail } from '@visulima/email/template/react-email';
-     * message.view(renderReactEmail, <WelcomeEmail name="John" />)
-     * ```
-     */
-    view(render: TemplateRenderer, template: unknown, data?: Record<string, unknown>, options?: {
-        [key: string]: unknown;
-        autoText?: boolean;
-    }): Promise<this>;
-    /**
-     * Renders a text template and sets as text content.
-     * @param render The template renderer function.
-     * @param template The text template content.
-     * @param data Optional data/variables to pass to the template.
-     * @param options Optional renderer-specific options.
-     * @returns This instance for method chaining.
-     * @example
-     * ```ts
-     * import { renderHandlebars } from '@visulima/email/template/handlebars';
-     * message.viewText(renderHandlebars, 'Hello {{name}}!', { name: 'John' })
-     * ```
-     */
-    viewText(render: TemplateRenderer, template: string, data?: Record<string, unknown>, options?: Record<string, unknown>): Promise<this>;
-    /**
-     * Builds the email options.
-     * @returns The built email options ready for sending.
-     * @throws {Error} When required fields (from, to, subject, content) are missing.
-     */
-    build(): Promise<EmailOptions>;
-    /**
-     * Gets the subject of the email.
-     * @returns The subject text or empty string if not set.
-     */
-    getSubject(): string;
-    /**
-     * Gets the from address.
-     * @returns The from address or undefined if not set.
-     */
-    getFrom(): EmailAddress | undefined;
-    /**
-     * Gets the recipient addresses.
-     * @returns Array of recipient addresses.
-     */
-    getTo(): EmailAddress[];
-    /**
-     * Gets the CC recipient addresses.
-     * @returns Array of CC recipient addresses.
-     */
-    getCc(): EmailAddress[];
-    /**
-     * Gets the BCC recipient addresses.
-     * @returns Array of BCC recipient addresses.
-     */
-    getBcc(): EmailAddress[];
-    /**
-     * Gets the reply-to address.
-     * @returns The reply-to address or undefined if not set.
-     */
-    getReplyTo(): EmailAddress | undefined;
-    /**
-     * Gets the sender address.
-     * @returns The sender address or undefined if not set.
-     */
-    getSender(): EmailAddress | undefined;
-    /**
-     * Gets the return-path address.
-     * @returns The return-path address or undefined if not set.
-     */
-    getReturnPath(): EmailAddress | undefined;
-    /**
-     * Gets the date header.
-     * @returns The date or undefined if not set.
-     */
-    getDate(): Date | undefined;
-    /**
-     * Gets the priority of the email.
-     * @returns The priority ('high', 'normal', 'low') or undefined if not set.
-     */
-    getPriority(): Priority | undefined;
-    /**
-     * Gets the plain text content.
-     * @returns The text content or undefined if not set.
-     */
-    getTextBody(): string | undefined;
-    /**
-     * Gets the charset for the text content.
-     * @returns The text charset (default: 'utf8').
-     */
-    getTextCharset(): string;
-    /**
-     * Gets the HTML content.
-     * @returns The HTML content or undefined if not set.
-     */
-    getHtmlBody(): string | undefined;
-    /**
-     * Gets the charset for the HTML content.
-     * @returns The HTML charset (default: 'utf8').
-     */
-    getHtmlCharset(): string;
-    /**
-     * Gets the attachments.
-     * @returns Array of attachments.
-     */
-    getAttachments(): Attachment[];
-    /**
-     * Attempts to auto-generate text content from HTML.
-     * @param html The HTML content to convert.
-     * @private
-     */
-    private tryAutoGenerateText;
-    /**
-     * Creates an error, logs it, and throws it.
-     * @param message Error message to throw.
-     * @param logMessage Optional log message (defaults to message).
-     * @private
-     */
-    private throwAndLogError;
-}
-export default MailMessage;