@visulima/email 1.0.0-alpha.1

package/dist/template-engines/handlebars.d.ts

@@ -0,0 +1,25 @@
+import type { TemplateRenderer } from "./types.d.ts";
+/**
+ * Renders Handlebars template.
+ * @param template Handlebars template string.
+ * @param data Data to pass to the template.
+ * @param options Handlebars compile options.
+ * @returns Rendered HTML string.
+ * @throws {TypeError} When template is not a string.
+ * @throws {EmailError} When Handlebars is not installed or rendering fails.
+ */
+export declare const renderHandlebars: TemplateRenderer;
+/**
+ * Registers a Handlebars helper function for use in templates.
+ * @param name The name of the helper to register.
+ * @param helper The helper function to register.
+ * @throws {EmailError} When Handlebars is not installed.
+ */
+export declare const registerHandlebarsHelper: (name: string, helper: unknown) => void;
+/**
+ * Registers a Handlebars partial template for reuse in other templates.
+ * @param name The name of the partial to register.
+ * @param partial The partial template string to register.
+ * @throws {EmailError} When Handlebars is not installed.
+ */
+export declare const registerHandlebarsPartial: (name: string, partial: string) => void;

package/dist/template-engines/handlebars.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var d=(a,r)=>i(a,"name",{value:r,configurable:!0});import t from"handlebars";import s from"../packem_shared/EmailError-zm2ffVav.js";var o=Object.defineProperty,l=d((a,r)=>o(a,"name",{value:r,configurable:!0}),"s");const p=l((a,r,e)=>{try{if(typeof a!="string")throw new TypeError("Handlebars template must be a string");return t.compile(a,e)(r||{})}catch(n){throw n instanceof Error&&n.message.includes("Cannot find module")?new s("handlebars","Handlebars is not installed. Please install it: pnpm add handlebars",{cause:n}):new s("handlebars",`Failed to render Handlebars template: ${n.message}`,{cause:n})}},"renderHandlebars"),u=l((a,r)=>{try{t.registerHelper(a,r)}catch(e){throw e instanceof Error&&e.message.includes("Cannot find module")?new s("handlebars","Handlebars is not installed. Please install it: pnpm add handlebars",{cause:e}):e}},"registerHandlebarsHelper"),h=l((a,r)=>{try{t.registerPartial(a,r)}catch(e){throw e instanceof Error&&e.message.includes("Cannot find module")?new s("handlebars","Handlebars is not installed. Please install it: pnpm add handlebars",{cause:e}):e}},"registerHandlebarsPartial");export{u as registerHandlebarsHelper,h as registerHandlebarsPartial,p as renderHandlebars};

package/dist/template-engines/html-to-text.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Converts HTML content to plain text format.
+ * @param html The HTML string to convert.
+ * @param options Configuration options for the html-to-text conversion.
+ * @param options.longWordSplit Options for handling long words that exceed the word wrap limit.
+ * @param options.longWordSplit.forceWrapOnLimit Whether to force wrap on the limit.
+ * @param options.longWordSplit.wrapCharacters Characters to use for wrapping.
+ * @param options.preserveNewlines Whether to preserve newlines in the output.
+ * @param options.selectors Custom selectors for formatting specific HTML elements.
+ * @param options.wordwrap The word wrap limit (number of characters) or false to disable.
+ * @returns The converted plain text string.
+ * @throws {EmailError} When html-to-text is not installed or conversion fails.
+ */
+declare const htmlToText: (html: string, options?: {
+    longWordSplit?: {
+        forceWrapOnLimit?: boolean;
+        wrapCharacters?: string[];
+    };
+    preserveNewlines?: boolean;
+    selectors?: {
+        format?: string;
+        options?: Record<string, unknown>;
+        selector: string;
+    }[];
+    wordwrap?: number | false;
+}) => string;
+export default htmlToText;

package/dist/template-engines/html-to-text.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var o=(t,e)=>n(t,"name",{value:e,configurable:!0});import{convert as a}from"html-to-text";import l from"../packem_shared/EmailError-zm2ffVav.js";var s=Object.defineProperty,i=o((t,e)=>s(t,"name",{value:e,configurable:!0}),"o");const p=i((t,e)=>{try{return a(t,{longWordSplit:e?.longWordSplit,preserveNewlines:e?.preserveNewlines??!1,selectors:e?.selectors,wordwrap:e?.wordwrap??80})}catch(r){throw r instanceof Error&&r.message.includes("Cannot find module")?new l("html-to-text","html-to-text is not installed. Please install it: pnpm add html-to-text",{cause:r}):new l("html-to-text",`Failed to convert HTML to text: ${r.message}`,{cause:r})}},"htmlToText");export{p as default};

package/dist/template-engines/mjml.d.ts

@@ -0,0 +1,12 @@
+import type { TemplateRenderer } from "./types.d.ts";
+/**
+ * Renders MJML to HTML.
+ * @param template MJML template string.
+ * @param _data Data (not used for MJML).
+ * @param options MJML options (beautify, fonts, keepComments, minify, validationLevel).
+ * @returns Rendered HTML string.
+ * @throws {TypeError} When template is not a string.
+ * @throws {EmailError} When MJML is not installed, validation fails, or rendering fails.
+ */
+declare const mjml: TemplateRenderer;
+export default mjml;

package/dist/template-engines/mjml.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var a=(t,o)=>i(t,"name",{value:o,configurable:!0});import l from"mjml";import r from"../packem_shared/EmailError-zm2ffVav.js";var f=Object.defineProperty,d=a((t,o)=>f(t,"name",{value:o,configurable:!0}),"o");const v=d((t,o,n)=>{try{if(typeof t!="string")throw new TypeError("MJML template must be a string");const e=l(t,{beautify:n?.beautify??!1,fonts:n?.fonts,keepComments:n?.keepComments??!0,minify:n?.minify??!1,validationLevel:n?.validationLevel??"soft"});if(e.errors&&e.errors.length>0){const s=e.errors.map(m=>m.message).join("; ");throw new r("mjml",`MJML validation errors: ${s}`)}return e.html}catch(e){throw e instanceof Error&&e.message.includes("Cannot find module")?new r("mjml","MJML is not installed. Please install it: pnpm add mjml",{cause:e}):e instanceof r?e:new r("mjml",`Failed to render MJML: ${e.message}`,{cause:e})}},"mjml");export{v as default};

package/dist/template-engines/react-email.d.ts

@@ -0,0 +1,11 @@
+import type { TemplateRenderer } from "./types.d.ts";
+/**
+ * Renders a React Email component to HTML.
+ * @param template The React component from \@react-email/components to render.
+ * @param _data Data object (not used for React Email, but kept for API compatibility).
+ * @param options Render options including plainText and pretty formatting.
+ * @returns The rendered HTML string.
+ * @throws {EmailError} When \@react-email/render is not installed or rendering fails.
+ */
+declare const reactEmail: TemplateRenderer;
+export default reactEmail;

package/dist/template-engines/react-email.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var n=(e,t)=>l(e,"name",{value:t,configurable:!0});import{render as c}from"@react-email/render";import i from"../packem_shared/EmailError-zm2ffVav.js";var o=Object.defineProperty,m=n((e,t)=>o(e,"name",{value:t,configurable:!0}),"t");const u=m(async(e,t,r)=>{try{return await c(e,{plainText:r?.plainText,pretty:r?.pretty})}catch(a){throw a instanceof Error&&a.message.includes("Cannot find module")?new i("react-email","@react-email/render is not installed. Please install it: pnpm add @react-email/render",{cause:a}):new i("react-email",`Failed to render React Email component: ${a.message}`,{cause:a})}},"reactEmail");export{u as default};

package/dist/template-engines/types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Template render function type.
+ * @param template Template content (string, React component, etc.).
+ * @param data Data/variables to pass to the template.
+ * @param options Options specific to the template engine.
+ * @returns Rendered HTML string.
+ */
+export type TemplateRenderer = (template: unknown, data?: Record<string, unknown>, options?: Record<string, unknown>) => string | Promise<string>;

package/dist/template-engines/vue-email.d.ts

@@ -0,0 +1,11 @@
+import type { TemplateRenderer } from "./types.d.ts";
+/**
+ * Renders a Vue Email component to HTML.
+ * @param template The Vue component from \@vue-email/components to render.
+ * @param data Data and variables to pass to the template.
+ * @param options Render options including pretty formatting, plainText output, and htmlToTextOptions.
+ * @returns The rendered HTML or plain text string.
+ * @throws {EmailError} When \@vue-email/render is not installed or rendering fails.
+ */
+declare const vueEmail: TemplateRenderer;
+export default vueEmail;

package/dist/template-engines/vue-email.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var r=(e,a)=>l(e,"name",{value:a,configurable:!0});import{render as o}from"@vue-email/render";import i from"../packem_shared/EmailError-zm2ffVav.js";var m=Object.defineProperty,s=r((e,a)=>m(e,"name",{value:a,configurable:!0}),"a");const c=s(async(e,a,n)=>{try{return await o(e,a??{},{htmlToTextOptions:n?.htmlToTextOptions,plainText:n?.plainText,pretty:n?.pretty})}catch(t){throw t instanceof Error&&t.message.includes("Cannot find module")?new i("vue-email","@vue-email/render is not installed. Please install it: pnpm add @vue-email/render",{cause:t}):new i("vue-email",`Failed to render Vue Email component: ${t.message}`,{cause:t})}},"vueEmail");export{c as default};

package/dist/types.d.ts

@@ -0,0 +1,185 @@
+import type { Buffer } from "node:buffer";
+/**
+ * Utility type for values that can be promises
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Feature flags indicating what capabilities a provider supports
+ */
+export interface FeatureFlags {
+    attachments?: boolean;
+    batchSending?: boolean;
+    customHeaders?: boolean;
+    html?: boolean;
+    replyTo?: boolean;
+    scheduling?: boolean;
+    tagging?: boolean;
+    templates?: boolean;
+    tracking?: boolean;
+}
+/**
+ * Base configuration for all providers
+ */
+export interface BaseConfig {
+    debug?: boolean;
+    logger?: Console;
+    retries?: number;
+    timeout?: number;
+}
+/**
+ * Email address with optional name
+ */
+export interface EmailAddress {
+    email: string;
+    name?: string;
+}
+/**
+ * Email attachment
+ */
+export interface Attachment {
+    /**
+     * Content-ID for inline attachments (used in HTML with cid:)
+     */
+    cid?: string;
+    /**
+     * Attachment content (string, Buffer, or Promise&lt;Uint8Array> for async loading)
+     * Required if path, href, or raw are not provided
+     */
+    content?: string | Buffer | Promise<Uint8Array>;
+    /**
+     * Content disposition: 'attachment' (default) or 'inline'
+     */
+    contentDisposition?: "attachment" | "inline";
+    /**
+     * MIME type of the attachment
+     */
+    contentType?: string;
+    /**
+     * Content transfer encoding (e.g., 'base64', '7bit', 'quoted-printable')
+     */
+    encoding?: string;
+    /**
+     * Filename for the attachment
+     */
+    filename: string;
+    /**
+     * Custom headers for this attachment
+     */
+    headers?: Record<string, string>;
+    /**
+     * URL to fetch attachment from
+     * Alternative to content or path
+     */
+    href?: string;
+    /**
+     * HTTP headers to use when fetching from href
+     */
+    httpHeaders?: Record<string, string>;
+    /**
+     * File path to read attachment from
+     * Alternative to content
+     */
+    path?: string;
+    /**
+     * Raw attachment data (alternative to content)
+     * Can be used for pre-encoded content
+     */
+    raw?: string | Buffer;
+}
+/**
+ * Email tag for categorization
+ */
+export interface EmailTag {
+    name: string;
+    value: string;
+}
+/**
+ * Priority levels for email messages
+ */
+export type Priority = "high" | "normal" | "low";
+/**
+ * Represents the headers of an email message.
+ * This type is a supertype of the standard `Headers` class, which is used to manage HTTP headers.
+ * Note that this type does not include methods for modifying the headers,
+ * such as `append`, `delete`, or `set`. It is intended to be used for
+ * read-only access to the headers of an email message.
+ */
+export type ImmutableHeaders = Omit<Headers, "append" | "delete" | "set">;
+/**
+ * Email headers can be either a plain object or an ImmutableHeaders instance
+ */
+export type EmailHeaders = Record<string, string> | ImmutableHeaders;
+/**
+ * Common email options that all providers support
+ */
+export interface EmailOptions {
+    attachments?: Attachment[];
+    bcc?: EmailAddress | EmailAddress[];
+    cc?: EmailAddress | EmailAddress[];
+    from: EmailAddress;
+    headers?: EmailHeaders;
+    html?: string;
+    priority?: Priority;
+    replyTo?: EmailAddress;
+    subject: string;
+    tags?: string[];
+    text?: string;
+    to: EmailAddress | EmailAddress[];
+}
+/**
+ * Result of sending an email
+ */
+export interface EmailResult {
+    messageId: string;
+    provider?: string;
+    response?: unknown;
+    sent: boolean;
+    timestamp: Date;
+}
+/**
+ * Receipt type for email sending results
+ * Uses discriminated union for type safety
+ */
+export type Receipt = {
+    /**
+     * The unique identifier for the message that was sent
+     */
+    readonly messageId: string;
+    /**
+     * Optional provider name
+     */
+    readonly provider?: string;
+    /**
+     * Optional response data from provider
+     */
+    readonly response?: unknown;
+    /**
+     * Indicates that the email was sent successfully
+     */
+    readonly successful: true;
+    /**
+     * Timestamp when email was sent
+     */
+    readonly timestamp: Date;
+} | {
+    /**
+     * An array of error messages that occurred during the sending process
+     */
+    readonly errorMessages: ReadonlyArray<string>;
+    /**
+     * Optional provider name
+     */
+    readonly provider?: string;
+    /**
+     * Indicates that the email failed to send
+     */
+    readonly successful: false;
+};
+/**
+ * Generic result type
+ */
+export interface Result<T = unknown> {
+    data?: T;
+    error?: Error | unknown;
+    success: boolean;
+}

package/dist/utils/build-mime-message.d.ts

@@ -0,0 +1,8 @@
+import type { EmailOptions } from "../types.d.ts";
+/**
+ * Builds a MIME-formatted email message from email options.
+ * @param options The email options to build the MIME message from.
+ * @returns The MIME-formatted email message as a string.
+ */
+declare const buildMimeMessage: <T extends EmailOptions>(options: T) => Promise<string>;
+export default buildMimeMessage;

package/dist/utils/compare-priority.d.ts

@@ -0,0 +1,16 @@
+import type { Priority } from "../types.d.ts";
+/**
+ * Compares two priority levels and returns a number indicating their relative order.
+ * High priority is considered greater than normal, which is greater than low.
+ * @example Sorting priorities
+ * ```ts
+ * const priorities: Priority[] = ["normal", "low", "high"];
+ * priorities.sort(comparePriority);
+ * // ["high", "normal", "low"]
+ * ```
+ * @param a The first priority to compare
+ * @param b The second priority to compare
+ * @returns A negative number if a is less than b, a positive number if a is greater than b, and zero if they are equal
+ */
+declare const comparePriority: (a: Priority, b: Priority) => number;
+export default comparePriority;

package/dist/utils/create-logger.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Logger interface with debug, error, info, and warn methods.
+ */
+type Logger = {
+    debug: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+};
+/**
+ * Creates a logger instance for a provider with optional console output.
+ * @param providerName The name of the provider (used as prefix in log messages).
+ * @param logger Optional Console instance. If provided, logs will be displayed with prefixes. If not provided, returns a no-op logger.
+ * @returns A logger instance with debug, error, info, and warn methods.
+ */
+declare const createLogger: (providerName: string, logger?: Console) => Logger;
+export type { Logger };
+export default createLogger;

package/dist/utils/format-email-address.d.ts

@@ -0,0 +1,9 @@
+import type { EmailAddress } from "../types.d.ts";
+/**
+ * Formats an email address as "Name <email@example.com>" or just "email@example.com" if no name is provided.
+ * @param address The email address object to format.
+ * @returns The formatted email address string in RFC 5322 format.
+ * @throws {EmailError} When the email address is invalid.
+ */
+declare const formatEmailAddress: (address: EmailAddress) => string;
+export default formatEmailAddress;

package/dist/utils/format-email-addresses.d.ts

@@ -0,0 +1,8 @@
+import type { EmailAddress } from "../types.d.ts";
+/**
+ * Formats a list of email addresses into a comma-separated string.
+ * @param addresses The email address(es) to format (single or array).
+ * @returns The formatted email addresses string (comma-separated if multiple).
+ */
+declare const formatEmailAddresses: (addresses: EmailAddress | EmailAddress[]) => string;
+export default formatEmailAddresses;

package/dist/utils/generate-boundary.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generates a unique boundary string for MIME multipart email messages.
+ * Works across Node.js, Deno, Bun, and Workers.
+ * @returns A unique boundary string for MIME multipart messages.
+ */
+declare const generateBoundary: () => string;
+export default generateBoundary;

package/dist/utils/generate-message-id.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generates a unique message ID for email messages.
+ * @returns A unique message ID in the format <timestamp.random@visulima.local>.
+ */
+declare const generateMessageId: () => string;
+export default generateMessageId;

package/dist/utils/headers-to-record.d.ts

@@ -0,0 +1,9 @@
+import type { EmailHeaders } from "../types.d.ts";
+/**
+ * Converts EmailHeaders (Record<string, string> or ImmutableHeaders) to Record<string, string>.
+ * This allows us to work with headers uniformly regardless of their input type.
+ * @param headers The headers to convert (Record or ImmutableHeaders).
+ * @returns A plain object Record<string, string> representation of the headers.
+ */
+declare const headersToRecord: (headers: EmailHeaders) => Record<string, string>;
+export default headersToRecord;

package/dist/utils/is-port-available.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Checks if a port is available on a host.
+ * Works across environments with polyfills.
+ * @param host The hostname or IP address to check.
+ * @param port The port number to check.
+ * @returns Promise that resolves to true if the port is available, false otherwise.
+ */
+declare const isPortAvailable: (host: string, port: number) => Promise<boolean>;
+export default isPortAvailable;

package/dist/utils/make-request.d.ts

@@ -0,0 +1,18 @@
+import type { Result } from "../types.d.ts";
+/**
+ * Request options compatible with both Fetch API and Node.js http
+ */
+export interface RequestOptions {
+    [key: string]: unknown;
+    headers?: Record<string, string>;
+    method?: string;
+    timeout?: number;
+}
+/**
+ * Makes an HTTP request using Fetch API (compatible with Node.js 20.19+, Deno, Bun, Cloudflare Workers).
+ * @param url The URL to make the request to.
+ * @param options Request options including method, headers, and timeout.
+ * @param data Optional request body data (string, Buffer, or Uint8Array).
+ * @returns A result object containing the response data or error.
+ */
+export declare const makeRequest: (url: string | URL, options?: RequestOptions, data?: string | Buffer | Uint8Array) => Promise<Result<unknown>>;

package/dist/utils/parse-address.d.ts

@@ -0,0 +1,19 @@
+import type { EmailAddress } from "../types.d.ts";
+/**
+ * Parses a string representation of an email address into an EmailAddress object.
+ * Supports formats: "email@example.com", "Name <email@example.com>", "<email@example.com>".
+ * @example Parsing an address with a name
+ * ```ts
+ * const address = parseAddress("John Doe <john@example.com>");
+ * // { name: "John Doe", email: "john@example.com" }
+ * ```
+ * @example Parsing an address without a name
+ * ```ts
+ * const address = parseAddress("jane@example.com");
+ * // { email: "jane@example.com" }
+ * ```
+ * @param address The string representation of the address to parse.
+ * @returns An EmailAddress object if parsing is successful, or undefined if invalid.
+ */
+declare const parseAddress: (address: string) => EmailAddress | undefined;
+export default parseAddress;

package/dist/utils/retry.d.ts

@@ -0,0 +1,10 @@
+import type { Result } from "../types.d.ts";
+/**
+ * Helper function to retry an async function with exponential backoff.
+ * @param function_ The async function to retry.
+ * @param retries Number of retry attempts (default: 3).
+ * @param delay Initial delay in milliseconds (default: 300, doubles on each retry).
+ * @returns A result object containing the function result or error.
+ */
+declare const retry: <T>(function_: () => Promise<Result<T>>, retries?: number, delay?: number) => Promise<Result<T>>;
+export default retry;

package/dist/utils/sanitize-header.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Sanitizes header values to prevent CRLF injection attacks.
+ * Removes carriage return (\r) and line feed (\n) characters.
+ * @param value The header value to sanitize.
+ * @returns The sanitized header value with CR/LF characters removed.
+ */
+export declare const sanitizeHeaderValue: (value: string) => string;
+/**
+ * Sanitizes header names to prevent CRLF injection attacks.
+ * Removes carriage return (\r) and line feed (\n) characters.
+ * @param name The header name to sanitize.
+ * @returns The sanitized header name with CR/LF characters removed.
+ */
+export declare const sanitizeHeaderName: (name: string) => string;

package/dist/utils/to-base64.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts content to a base64-encoded string.
+ * Works across Node.js, Deno, Bun, and Workers.
+ * @param content The content to convert (string, Buffer, Uint8Array, or ArrayLike<number>).
+ * @returns The base64-encoded string.
+ */
+declare const toBase64: (content: string | Buffer | Uint8Array | ArrayLike<number>) => string;
+export default toBase64;

package/dist/utils/validate-email-options.d.ts

@@ -0,0 +1,8 @@
+import type { EmailOptions } from "../types.d.ts";
+/**
+ * Validates email options and returns any validation errors.
+ * @param options The email options to validate.
+ * @returns Array of error messages (empty if validation passes).
+ */
+declare const validateEmailOptions: <T extends EmailOptions>(options: T) => string[];
+export default validateEmailOptions;

package/dist/utils/validate-email.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validates an email address format according to basic RFC standards.
+ * @param email The email address string to validate.
+ * @returns True if the email address is valid, false otherwise.
+ */
+declare const validateEmail: (email: string) => boolean;
+export default validateEmail;