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

package/dist/providers/utils/payload-builder.d.ts

@@ -1,78 +0,0 @@
-import type { EmailAddress, EmailOptions } from "../../types.d.ts";
-/**
- * Common payload building utilities for email providers
- */
-export declare class PayloadBuilder {
-    private payload;
-    constructor(initialPayload?: Record<string, unknown>);
-    /**
-     * Sets a field in the payload.
-     * @param key The field key to set.
-     * @param value The field value to set (undefined and null values are ignored).
-     * @returns This instance for method chaining.
-     */
-    set(key: string, value: unknown): this;
-    /**
-     * Sets multiple fields conditionally in the payload.
-     * @param fields An object containing key-value pairs to set.
-     * @returns This instance for method chaining.
-     */
-    setMultiple(fields: Record<string, unknown>): this;
-    /**
-     * Adds recipients (to, cc, bcc) to the payload using a formatter function.
-     * @param emailOptions The email options containing recipient addresses.
-     * @param formatter A function to format the addresses for the specific provider.
-     * @returns This instance for method chaining.
-     */
-    addRecipients(emailOptions: EmailOptions, formatter: (addresses: EmailAddress | EmailAddress[]) => unknown): this;
-    /**
-     * Adds standard email fields (subject, html, text, replyTo) to the payload.
-     * @param emailOptions The email options containing the standard fields.
-     * @returns This instance for method chaining.
-     */
-    addStandardFields(emailOptions: EmailOptions): this;
-    /**
-     * Adds template-related fields to the payload.
-     * @param emailOptions The email options containing template information.
-     * @param templateKey The key name to use for the template ID (default: "template_id").
-     * @returns This instance for method chaining.
-     */
-    addTemplateFields(emailOptions: EmailOptions, templateKey?: string): this;
-    /**
-     * Adds scheduling fields to the payload for delayed sending.
-     * @param emailOptions The email options containing scheduling information.
-     * @returns This instance for method chaining.
-     */
-    addSchedulingFields(emailOptions: EmailOptions): this;
-    /**
-     * Adds tags to the payload for email categorization.
-     * @param emailOptions The email options containing tags.
-     * @param formatter An optional function to format tags for the specific provider.
-     * @returns This instance for method chaining.
-     */
-    addTags(emailOptions: EmailOptions, formatter?: (tags: unknown[]) => unknown): this;
-    /**
-     * Adds custom headers to the payload.
-     * @param emailOptions The email options containing custom headers.
-     * @param formatter An optional function to format headers for the specific provider.
-     * @returns This instance for method chaining.
-     */
-    addHeaders(emailOptions: EmailOptions, formatter?: (headers: Record<string, string>) => unknown): this;
-    /**
-     * Adds a batch ID to the payload for batch email operations.
-     * @param emailOptions The email options containing the batch ID.
-     * @returns This instance for method chaining.
-     */
-    addBatchId(emailOptions: EmailOptions): this;
-    /**
-     * Builds and returns the final payload object.
-     * @returns The complete payload object ready for API submission.
-     */
-    build(): Record<string, unknown>;
-}
-/**
- * Creates a new payload builder instance.
- * @param initialPayload Optional initial payload object to start with.
- * @returns A new PayloadBuilder instance.
- */
-export declare const createPayloadBuilder: (initialPayload?: Record<string, unknown>) => PayloadBuilder;

package/dist/providers/utils/provider-base.d.ts

@@ -1,69 +0,0 @@
-import EmailError from "../../errors/email-error.d.ts";
-import type { MaybePromise } from "../../types.d.ts";
-/**
- * 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;
-};
-/**
- * Common provider configuration interface
- */
-export interface BaseProviderConfig {
-    debug?: boolean;
-    logger?: Console;
-    timeout?: number;
-}
-/**
- * Provider initialization state management
- */
-export declare class ProviderState {
-    private isInitialized;
-    /**
-     * Checks if the provider has been initialized.
-     * @returns True if the provider is initialized, false otherwise.
-     */
-    get initialized(): boolean;
-    /**
-     * Marks the provider as initialized.
-     */
-    setInitialized(): void;
-    /**
-     * Ensures the provider is initialized, initializing it if not already done.
-     * @param initializeFunction The function to call for initialization.
-     * @param providerName The name of the provider (for error messages).
-     * @throws {EmailError} When initialization fails.
-     */
-    ensureInitialized(initializeFunction: () => MaybePromise<void>, providerName: string): Promise<void>;
-}
-/**
- * Creates a logger instance for a provider.
- * @param providerName The name of the provider (used as prefix in log messages).
- * @param customLogger Optional Console instance for logging output.
- * @returns A logger instance with debug, error, info, and warn methods.
- */
-export declare const createProviderLogger: (providerName: string, customLogger?: Console) => Logger;
-/**
- * Checks if an HTTP response indicates success (2xx status codes).
- * @param result The result object containing response data and success status.
- * @param result.data The response data object.
- * @param result.success The success flag indicating if the request was successful.
- * @returns True if the response indicates success, false otherwise.
- */
-export declare const isSuccessfulResponse: (result: {
-    data?: unknown;
-    success: boolean;
-}) => boolean;
-/**
- * Handles errors from provider operations and converts them to EmailError instances.
- * @param providerName The name of the provider where the error occurred.
- * @param operation The operation that failed.
- * @param error The error that occurred.
- * @param logger Optional logger instance for debug messages.
- * @returns An EmailError instance with appropriate error information.
- */
-export declare const handleProviderError: (providerName: string, operation: string, error: unknown, logger?: Logger) => EmailError;
-export {};

package/dist/providers/zeptomail/provider.d.ts

@@ -1,7 +0,0 @@
-import type { ProviderFactory } from "../provider.d.ts";
-import type { ZeptomailConfig, ZeptomailEmailOptions } from "./types.d.ts";
-/**
- * Zeptomail Provider for sending emails through Zeptomail API
- */
-declare const zeptomailProvider: ProviderFactory<ZeptomailConfig, unknown, ZeptomailEmailOptions>;
-export default zeptomailProvider;

package/dist/providers/zeptomail/types.d.ts

@@ -1,29 +0,0 @@
-import type { BaseConfig, EmailOptions } from "../../types.d.ts";
-/**
- * Zeptomail configuration
- */
-export interface ZeptomailConfig extends BaseConfig {
-    endpoint?: string;
-    token: string;
-}
-/**
- * Zeptomail-specific email options
- */
-export interface ZeptomailEmailOptions extends EmailOptions {
-    /**
-     * Client reference - identifier set by the user to track a particular transaction
-     */
-    clientReference?: string;
-    /**
-     * MIME headers - additional headers sent in the email for reference
-     */
-    mimeHeaders?: Record<string, string>;
-    /**
-     * Track email clicks - enables tracking for click events
-     */
-    trackClicks?: boolean;
-    /**
-     * Track email opens - enables tracking for open events
-     */
-    trackOpens?: boolean;
-}

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

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