@visulima/email 1.0.0-alpha.1 → 1.0.0-alpha.2

package/dist/draft-mail-message.d.ts

@@ -0,0 +1,13 @@
+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/index.d.ts

@@ -1,22 +1,9 @@
 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 { createMail, Mail, type MailGlobalConfig, type SendableMessage } from "./mail.d.ts";
+export { default as MailMessage } from "./mail-message.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";
+export type { Attachment, BaseConfig, CalendarEventOptions, EmailAddress, EmailHeaders, EmailOptions, EmailResult, EmailTag, FeatureFlags, ImmutableHeaders, MaybePromise, Priority, Receipt, Result, } from "./types.d.ts";

package/dist/index.js

@@ -1 +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};
+import{detectMimeType as o,generateContentId as t,readFileAsBuffer as a}from"./packem_shared/detectMimeType-S8WRsNtY.js";import{default as i}from"./packem_shared/EmailError-zm2ffVav.js";import{default as m}from"./packem_shared/RequiredOptionError-CevW3u2K.js";import{Mail as l,createMail as x}from"./packem_shared/Mail-6Bltpy_p.js";import{MailMessage as s}from"./packem_shared/MailMessage-B76GPBBA.js";import{defineProvider as u}from"./packem_shared/defineProvider-B9rSklAJ.js";export{i as EmailError,l as Mail,s as MailMessage,m as RequiredOptionError,x as createMail,u as defineProvider,o as detectMimeType,t as generateContentId,a as readFileAsBuffer};

package/dist/mail-message.d.ts

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