@beignet/core/dist/mail/index.d.ts

Core framework primitives for Beignet

/**
 * @beignet/core/mail
 *
 * Shared mail port and test adapters for Beignet applications.
 */
/**
 * Value or promise of that value.
 */
export type MaybePromise<T> = T | Promise<T>;
/**
 * Email address accepted by Beignet mail helpers.
 */
export type MailAddress = string | {
    /**
     * Email address.
     */
    email: string;
    /**
     * Optional display name.
     */
    name?: string;
};
/**
 * Single address or address list.
 */
export type MailAddressList = MailAddress | readonly MailAddress[];
/**
 * Common mail message fields shared by all send options.
 */
export interface MailBaseMessage {
    /**
     * Required recipients.
     */
    to: MailAddressList;
    /**
     * Message subject.
     */
    subject: string;
    /**
     * Sender address. Providers or adapters may supply a default.
     */
    from?: MailAddress;
    /**
     * Carbon-copy recipients.
     */
    cc?: MailAddressList;
    /**
     * Blind-carbon-copy recipients.
     */
    bcc?: MailAddressList;
    /**
     * Reply-to recipients.
     */
    replyTo?: MailAddressList;
    /**
     * Provider-specific message headers.
     */
    headers?: Record<string, string>;
}
/**
 * Mail send options.
 *
 * A message must include at least one body format: `text` or `html`.
 */
export type SendMailOptions = MailBaseMessage & ({
    text: string;
    html?: string;
} | {
    html: string;
    text?: string;
});
/**
 * Normalized mail message with address fields converted to arrays.
 */
export interface NormalizedMailMessage extends MailBaseMessage {
    /**
     * Normalized recipients.
     */
    to: readonly MailAddress[];
    /**
     * Sender address after applying any default.
     */
    from?: MailAddress;
    /**
     * Normalized carbon-copy recipients.
     */
    cc?: readonly MailAddress[];
    /**
     * Normalized blind-carbon-copy recipients.
     */
    bcc?: readonly MailAddress[];
    /**
     * Normalized reply-to recipients.
     */
    replyTo?: readonly MailAddress[];
    /**
     * Plain text body.
     */
    text?: string;
    /**
     * HTML body.
     */
    html?: string;
}
/**
 * Result returned by a mail provider.
 */
export interface SendMailResult {
    /**
     * Provider message ID when available.
     */
    id?: string;
    /**
     * Provider name.
     */
    provider?: string;
}
/**
 * App-facing mailer port.
 */
export interface MailerPort {
    /**
     * Send one mail message.
     */
    send(message: SendMailOptions): Promise<SendMailResult>;
}
/**
 * Delivery captured by the memory mailer.
 */
export interface MemoryMailDelivery {
    /**
     * Generated delivery ID.
     */
    id: string;
    /**
     * Normalized message that would have been sent.
     */
    message: NormalizedMailMessage;
    /**
     * Timestamp assigned by the memory mailer.
     */
    sentAt: Date;
}
/**
 * In-memory mailer port for tests and local examples.
 */
export interface MemoryMailerPort extends MailerPort {
    /**
     * Captured deliveries.
     */
    readonly deliveries: readonly MemoryMailDelivery[];
    /**
     * Clear captured deliveries.
     */
    clear(): void;
}
/**
 * Options for `createMemoryMailer(...)`.
 */
export interface CreateMemoryMailerOptions {
    /**
     * Sender used when a message does not specify `from`.
     */
    defaultFrom?: MailAddress;
    /**
     * Clock used for captured deliveries.
     */
    now?: () => Date;
    /**
     * ID factory used for captured deliveries.
     */
    id?: () => string;
    /**
     * Observer called after a delivery is captured.
     */
    onSend?: (delivery: MemoryMailDelivery) => MaybePromise<void>;
}
/**
 * Error thrown by mail helpers and provider adapters.
 */
export declare class MailDeliveryError extends Error {
    /**
     * Provider name when known.
     */
    readonly provider?: string;
    /**
     * Original provider error when available.
     */
    readonly cause?: unknown;
    constructor(args: {
        provider?: string;
        message: string;
        cause?: unknown;
    });
}
/**
 * Normalize a single address or address list into an array.
 *
 * This helper does not validate email syntax.
 */
export declare function normalizeMailAddressList(addresses: MailAddressList | undefined): readonly MailAddress[] | undefined;
/**
 * Format one address for providers that accept RFC-like address strings.
 *
 * Rejects carriage returns and line feeds so address values cannot inject
 * additional mail header lines. This helper does not validate email syntax.
 */
export declare function formatMailAddress(address: MailAddress): string;
/**
 * Format one or more addresses for providers that accept string address fields.
 */
export declare function formatMailAddressList(addresses: MailAddressList): string | string[];
/**
 * Normalize a mail message and apply a default sender.
 *
 * Throws when the message has no recipients.
 */
export declare function normalizeMailMessage(message: SendMailOptions, options?: {
    defaultFrom?: MailAddress;
}): NormalizedMailMessage;
/**
 * Create an in-memory mailer for tests, local development, and examples.
 *
 * The memory mailer does not send real email or validate address syntax.
 */
export declare function createMemoryMailer(options?: CreateMemoryMailerOptions): MemoryMailerPort;
/**
 * Options for the memory mailer provider.
 */
export interface MemoryMailerProviderOptions extends CreateMemoryMailerOptions {
    /**
     * Provider name. Defaults to "memory-mailer".
     */
    name?: string;
}
/**
 * Ports contributed by the memory mailer provider.
 */
export interface MemoryMailerProviderPorts {
    /**
     * Beignet mailer port.
     */
    mailer: MailerPort;
}
/**
 * Create a provider that contributes an in-memory mailer.
 *
 * Use it as the dev-default `mailer` port in `server/providers.ts` until a
 * real mail provider such as Resend or SMTP takes over. Deliveries are
 * captured in memory and recorded as `mail.sent` devtools events through the
 * `mail` watcher when an instrumentation port is installed.
 */
export declare function createMemoryMailerProvider(options?: MemoryMailerProviderOptions): import("../providers/provider.js").ServiceProvider<unknown, import("@standard-schema/spec").StandardSchemaV1<void, void>, {
    mailer: MailerPort;
}, unknown, void>;
//# sourceMappingURL=index.d.ts.map