@visulima/email 1.0.0-alpha.4 → 1.0.0-alpha.40

package/dist/types.d.ts

@@ -1,203 +0,0 @@
-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;
-/**
- * Options for calendar event attachments
- */
-export interface CalendarEventOptions {
-    /**
-     * Alternative text for the calendar event
-     */
-    alternativeText?: string;
-    /**
-     * Method for the calendar event (e.g., 'REQUEST', 'CANCEL', 'REPLY')
-     */
-    method?: string;
-}
-/**
- * Common email options that all providers support
- */
-export interface EmailOptions {
-    attachments?: Attachment[];
-    bcc?: EmailAddress | EmailAddress[];
-    cc?: EmailAddress | EmailAddress[];
-    from: EmailAddress;
-    headers?: EmailHeaders;
-    html?: string;
-    icalEvent?: CalendarEventOptions & {
-        content?: string;
-        href?: string;
-        path?: 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

@@ -1,8 +0,0 @@
-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/create-logger.d.ts

@@ -1,16 +0,0 @@
-/**
- * Logger interface with debug, error, info, and warn methods.
- */
-export 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.
- */
-export declare const createLogger: (providerName: string, logger?: Console) => Logger;

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

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

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

@@ -1,6 +0,0 @@
-/**
- * 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

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

@@ -1,9 +0,0 @@
-/**
- * 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

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

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

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,8 +0,0 @@
-/**
- * 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/validation/validate-email-options.d.ts

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