@fmontoya/aws-ses-adapter 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,652 @@
+/**
+ * @module types
+ * Core types and interfaces for the aws-ses-adapter library.
+ */
+/**
+ * Configuration options for initializing the SES Adapter.
+ * All credential fields are optional and will fall back to the corresponding
+ * environment variables if not provided.
+ *
+ * @example
+ * ```ts
+ * const config: SesAdapterConfig = {
+ *   region: 'us-east-1',
+ *   accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
+ *   secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+ *   defaultFrom: 'noreply@example.com',
+ * };
+ * ```
+ */
+interface SesAdapterConfig {
+    /**
+     * AWS region where SES is configured.
+     * Falls back to the `AWS_SES_REGION` environment variable if not provided.
+     */
+    region?: string;
+    /**
+     * AWS access key ID for authentication.
+     * Falls back to the `AWS_ACCESS_KEY_ID` environment variable if not provided.
+     */
+    accessKeyId?: string;
+    /**
+     * AWS secret access key for authentication.
+     * Falls back to the `AWS_SECRET_ACCESS_KEY` environment variable if not provided.
+     */
+    secretAccessKey?: string;
+    /**
+     * Default "From" email address used when no `from` is specified in {@link SendEmailOptions}.
+     * Falls back to the `AWS_SES_FROM_EMAIL` environment variable if not provided.
+     * This field is optional — emails can still provide their own `from` address.
+     */
+    defaultFrom?: string;
+}
+/**
+ * A file attachment to include in an email sent via {@link sendEmailWithAttachments}.
+ *
+ * @example
+ * ```ts
+ * const attachment: EmailAttachment = {
+ *   filename: 'report.pdf',
+ *   content: fs.readFileSync('./report.pdf'),
+ *   contentType: 'application/pdf',
+ * };
+ * ```
+ */
+interface EmailAttachment {
+    /**
+     * The filename shown to the recipient (e.g. `'report.pdf'`).
+     */
+    filename: string;
+    /**
+     * The attachment content. Use a `Buffer` for binary files (images, PDFs, etc.)
+     * or a `string` for plain text files.
+     */
+    content: Buffer | string;
+    /**
+     * MIME content type of the attachment (e.g. `'application/pdf'`, `'image/png'`).
+     */
+    contentType: string;
+}
+/**
+ * Options for sending an email with attachments via SES.
+ * Extends {@link SendEmailOptions} with a required `attachments` array.
+ * At least one of `html` or `text` must be provided, plus at least one attachment.
+ *
+ * @example
+ * ```ts
+ * const options: SendEmailWithAttachmentsOptions = {
+ *   to: 'user@example.com',
+ *   subject: 'Your report',
+ *   html: '<p>Please find the report attached.</p>',
+ *   attachments: [
+ *     { filename: 'report.pdf', content: pdfBuffer, contentType: 'application/pdf' },
+ *   ],
+ * };
+ * ```
+ */
+interface SendEmailWithAttachmentsOptions extends SendEmailOptions {
+    /**
+     * List of file attachments to include in the email.
+     * Must contain at least one item.
+     */
+    attachments: EmailAttachment[];
+}
+/**
+ * Options for sending an email via SES.
+ * At least one of `html` or `text` must be provided.
+ *
+ * @example
+ * ```ts
+ * const options: SendEmailOptions = {
+ *   to: 'user@example.com',
+ *   subject: 'Hello!',
+ *   html: '<h1>Hello World</h1>',
+ *   cc: ['manager@example.com'],
+ * };
+ * ```
+ */
+interface SendEmailOptions {
+    /**
+     * Recipient email address or array of addresses.
+     */
+    to: string | string[];
+    /**
+     * Subject line of the email.
+     */
+    subject: string;
+    /**
+     * HTML body of the email.
+     * At least one of `html` or `text` must be provided.
+     */
+    html?: string;
+    /**
+     * Plain text body of the email.
+     * At least one of `html` or `text` must be provided.
+     */
+    text?: string;
+    /**
+     * Sender email address. Overrides the `defaultFrom` configured during initialization.
+     * Must be a verified SES identity.
+     */
+    from?: string;
+    /**
+     * Reply-To email address or array of addresses.
+     */
+    replyTo?: string | string[];
+    /**
+     * CC email address or array of addresses.
+     */
+    cc?: string | string[];
+    /**
+     * BCC email address or array of addresses.
+     */
+    bcc?: string | string[];
+}
+/**
+ * Result object returned by {@link sendEmail}, {@link sendEmailWithAttachments},
+ * and {@link sendRawEmail} on success.
+ *
+ * All send methods throw a typed error on failure (see {@link SesSendError},
+ * {@link SesValidationError}), so a returned `SendEmailResult` always represents
+ * a successful send.
+ *
+ * @example
+ * ```ts
+ * const result = await sendEmail(options);
+ * console.log('Message ID:', result.messageId);
+ * ```
+ */
+interface SendEmailResult {
+    /**
+     * Always `true` for a returned result — failures are thrown as errors.
+     */
+    success: true;
+    /**
+     * The SES message ID returned by AWS.
+     */
+    messageId?: string;
+}
+
+/**
+ * @module adapter
+ * Core SesAdapter class that wraps the AWS SES client and provides
+ * simplified email sending methods.
+ */
+
+/**
+ * Core adapter class that wraps the AWS SES client and provides a simplified
+ * API for sending emails.
+ *
+ * This class is not meant to be instantiated directly by consumers.
+ * Use the singleton functions exported from the main module instead.
+ *
+ * @see {@link init} to initialize the singleton.
+ * @see {@link sendEmail} to send a standard email.
+ * @see {@link sendRawEmail} to send a raw MIME email.
+ */
+declare class SesAdapter {
+    /** @internal */
+    private readonly sesClient;
+    /** @internal */
+    private readonly config;
+    /**
+     * Creates a new SesAdapter instance.
+     *
+     * @param userConfig - Optional configuration. Missing fields fall back to environment variables.
+     * @throws {SesConfigError} When required configuration fields are missing.
+     */
+    constructor(userConfig?: SesAdapterConfig);
+    /**
+     * Sends an email using AWS SES.
+     *
+     * At least one of `options.html` or `options.text` must be provided.
+     * If `options.from` is not specified, the `defaultFrom` configured during
+     * initialization is used. If neither is available, the call throws.
+     *
+     * @param options - Email sending options.
+     * @returns A promise resolving to a {@link SendEmailResult}.
+     * @throws {SesValidationError} When required email fields are missing or invalid.
+     * @throws {SesSendError} When the AWS SES API call fails.
+     *
+     * @example
+     * ```ts
+     * const result = await adapter.sendEmail({
+     *   to: ['alice@example.com', 'bob@example.com'],
+     *   subject: 'Hello!',
+     *   html: '<p>Hello World</p>',
+     *   text: 'Hello World',
+     *   cc: 'manager@example.com',
+     * });
+     * ```
+     */
+    sendEmail(options: SendEmailOptions): Promise<SendEmailResult>;
+    /**
+     * Sends a raw MIME email using AWS SES.
+     *
+     * Use this method when you need full control over the email format, such as
+     * sending emails with attachments or custom headers.
+     *
+     * @param rawMessage - The raw MIME email message as a string.
+     * @returns A promise resolving to a {@link SendEmailResult}.
+     * @throws {SesValidationError} When the raw message is empty.
+     * @throws {SesSendError} When the AWS SES API call fails.
+     *
+     * @example
+     * ```ts
+     * const mimeMessage = [
+     *   'From: sender@example.com',
+     *   'To: recipient@example.com',
+     *   'Subject: Test',
+     *   'MIME-Version: 1.0',
+     *   'Content-Type: text/plain',
+     *   '',
+     *   'Hello World',
+     * ].join('\r\n');
+     *
+     * const result = await adapter.sendRawEmail(mimeMessage);
+     * ```
+     */
+    sendRawEmail(rawMessage: string): Promise<SendEmailResult>;
+    /**
+     * Sends an email with one or more file attachments using AWS SES.
+     *
+     * Internally builds a multipart/mixed MIME message and dispatches it via
+     * `SendRawEmailCommand`, giving you full attachment support without needing
+     * to craft raw MIME by hand.
+     *
+     * At least one of `options.html` or `options.text` must be provided.
+     * The `options.attachments` array must contain at least one item.
+     *
+     * @param options - Email options including the attachments array.
+     * @returns A promise resolving to a {@link SendEmailResult}.
+     * @throws {SesValidationError} When required fields are missing or invalid.
+     * @throws {SesSendError} When the AWS SES API call fails.
+     *
+     * @example
+     * ```ts
+     * const result = await adapter.sendEmailWithAttachments({
+     *   to: 'alice@example.com',
+     *   subject: 'Your invoice',
+     *   html: '<p>Please find the invoice attached.</p>',
+     *   attachments: [
+     *     {
+     *       filename: 'invoice.pdf',
+     *       content: fs.readFileSync('./invoice.pdf'),
+     *       contentType: 'application/pdf',
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    sendEmailWithAttachments(options: SendEmailWithAttachmentsOptions): Promise<SendEmailResult>;
+    /**
+     * Returns whether the adapter has a default "From" address configured.
+     *
+     * @returns `true` if a default from address is available.
+     *
+     * @example
+     * ```ts
+     * if (adapter.hasDefaultFrom()) {
+     *   console.log('Default from:', adapter.getDefaultFrom());
+     * }
+     * ```
+     */
+    hasDefaultFrom(): boolean;
+    /**
+     * Returns the default "From" email address, or `undefined` if not set.
+     *
+     * @returns The default sender address, or `undefined`.
+     *
+     * @example
+     * ```ts
+     * const from = adapter.getDefaultFrom();
+     * // => 'noreply@example.com' or undefined
+     * ```
+     */
+    getDefaultFrom(): string | undefined;
+    /**
+     * Returns the AWS region the adapter is configured to use.
+     *
+     * @returns The AWS region string.
+     *
+     * @example
+     * ```ts
+     * console.log(adapter.getRegion()); // => 'us-east-1'
+     * ```
+     */
+    getRegion(): string;
+}
+
+/**
+ * @module errors
+ * Custom error classes for the aws-ses-adapter library.
+ * All errors extend the native `Error` class and include a `name` property
+ * suitable for programmatic error identification.
+ */
+/**
+ * Thrown when an operation is attempted before the adapter has been initialized
+ * via {@link init}.
+ *
+ * @example
+ * ```ts
+ * import { sendEmail } from 'aws-ses-adapter';
+ *
+ * // Calling sendEmail before init() throws this error
+ * try {
+ *   await sendEmail({ to: 'user@example.com', subject: 'Hi', text: 'Hello' });
+ * } catch (err) {
+ *   if (err instanceof SesNotInitializedError) {
+ *     console.error('Call init() first');
+ *   }
+ * }
+ * ```
+ */
+declare class SesNotInitializedError extends Error {
+    /** @override */
+    readonly name: "SesNotInitializedError";
+    constructor();
+}
+/**
+ * Thrown when the configuration provided to {@link init} is invalid or incomplete.
+ * This typically happens when required credentials are missing from both the config
+ * object and the environment variables.
+ *
+ * @example
+ * ```ts
+ * import { init } from 'aws-ses-adapter';
+ *
+ * try {
+ *   init({}); // No region, no env vars set
+ * } catch (err) {
+ *   if (err instanceof SesConfigError) {
+ *     console.error('Config error:', err.message);
+ *   }
+ * }
+ * ```
+ */
+declare class SesConfigError extends Error {
+    /** @override */
+    readonly name: "SesConfigError";
+    /**
+     * @param message - Description of the configuration issue.
+     */
+    constructor(message: string);
+}
+/**
+ * Thrown when an email send operation fails at the AWS SES level.
+ * The original AWS error is available via the `cause` property (ES2022+).
+ *
+ * @example
+ * ```ts
+ * import { sendEmail, SesSendError } from 'aws-ses-adapter';
+ *
+ * try {
+ *   await sendEmail({ to: 'user@example.com', subject: 'Hi', text: 'Hello' });
+ * } catch (err) {
+ *   if (err instanceof SesSendError) {
+ *     console.error('Send failed:', err.message);
+ *     console.error('Original cause:', err.cause);
+ *   }
+ * }
+ * ```
+ */
+declare class SesSendError extends Error {
+    /** @override */
+    readonly name: "SesSendError";
+    /**
+     * @param message - Description of the send failure.
+     * @param cause   - The underlying error from AWS SDK.
+     */
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown when {@link SendEmailOptions} are invalid, such as missing both
+ * `html` and `text`, or having an invalid email address format.
+ *
+ * @example
+ * ```ts
+ * import { sendEmail, SesValidationError } from 'aws-ses-adapter';
+ *
+ * try {
+ *   // Missing both html and text
+ *   await sendEmail({ to: 'user@example.com', subject: 'Hi' });
+ * } catch (err) {
+ *   if (err instanceof SesValidationError) {
+ *     console.error('Validation error:', err.message);
+ *   }
+ * }
+ * ```
+ */
+declare class SesValidationError extends Error {
+    /** @override */
+    readonly name: "SesValidationError";
+    /**
+     * @param message - Description of the validation failure.
+     */
+    constructor(message: string);
+}
+
+/**
+ * @module aws-ses-adapter
+ *
+ * A lightweight adapter that simplifies the AWS SES email sending API for Node.js.
+ *
+ * ## Quick Start
+ *
+ * **1. Initialize once** (at application startup):
+ * ```ts
+ * import { init } from 'aws-ses-adapter';
+ *
+ * init({
+ *   region: 'us-east-1',
+ *   accessKeyId: 'YOUR_KEY',
+ *   secretAccessKey: 'YOUR_SECRET',
+ *   defaultFrom: 'noreply@example.com',
+ * });
+ * ```
+ *
+ * **2. Use anywhere** in your application:
+ * ```ts
+ * import { sendEmail } from 'aws-ses-adapter';
+ *
+ * await sendEmail({
+ *   to: 'user@example.com',
+ *   subject: 'Welcome!',
+ *   html: '<h1>Welcome</h1>',
+ * });
+ * ```
+ *
+ * ## Environment Variables
+ *
+ * If credentials are not passed to `init()`, the adapter reads:
+ * - `AWS_SES_REGION`
+ * - `AWS_ACCESS_KEY_ID`
+ * - `AWS_SECRET_ACCESS_KEY`
+ * - `AWS_SES_FROM_EMAIL` (optional default sender)
+ */
+
+/**
+ * Initializes the SES Adapter singleton.
+ *
+ * Must be called **once** before any other function in this module.
+ * Calling `init()` again will replace the existing singleton instance,
+ * which is useful for reconfiguration during testing.
+ *
+ * Credentials are resolved in the following order:
+ * 1. Values provided in the `config` argument.
+ * 2. Environment variables (`AWS_SES_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`).
+ *
+ * @param config - Optional configuration. Omit any field to fall back to environment variables.
+ * @throws {SesConfigError} When required credentials cannot be resolved.
+ *
+ * @example
+ * ```ts
+ * // Using explicit credentials
+ * init({
+ *   region: 'us-east-1',
+ *   accessKeyId: process.env.MY_KEY_ID,
+ *   secretAccessKey: process.env.MY_SECRET,
+ *   defaultFrom: 'no-reply@myapp.com',
+ * });
+ *
+ * // Relying entirely on environment variables
+ * init();
+ * ```
+ */
+declare function init(config?: SesAdapterConfig): void;
+/**
+ * Sends an email using the initialized SES Adapter.
+ *
+ * At least one of `options.html` or `options.text` must be provided.
+ * If `options.from` is not specified, the `defaultFrom` set during {@link init} is used.
+ *
+ * @param options - Email sending options.
+ * @returns A promise resolving to a {@link SendEmailResult}.
+ * @throws {SesNotInitializedError} If {@link init} has not been called.
+ * @throws {SesValidationError} When required email fields are missing or invalid.
+ * @throws {SesSendError} When the AWS SES API call fails.
+ *
+ * @example
+ * ```ts
+ * import { sendEmail } from 'aws-ses-adapter';
+ *
+ * const result = await sendEmail({
+ *   to: 'alice@example.com',
+ *   subject: 'Hello Alice',
+ *   html: '<p>Hi Alice!</p>',
+ *   text: 'Hi Alice!',
+ *   cc: 'manager@example.com',
+ *   bcc: ['audit@example.com'],
+ *   replyTo: 'support@example.com',
+ * });
+ *
+ * console.log(result.messageId);
+ * ```
+ */
+declare function sendEmail(options: SendEmailOptions): Promise<SendEmailResult>;
+/**
+ * Sends an email with one or more file attachments using the initialized SES Adapter.
+ *
+ * Internally builds a multipart/mixed MIME message, so you don't need to
+ * construct raw MIME yourself. At least one of `options.html` or `options.text`
+ * must be provided, and `options.attachments` must contain at least one item.
+ *
+ * @param options - Email options including the attachments array.
+ * @returns A promise resolving to a {@link SendEmailResult}.
+ * @throws {SesNotInitializedError} If {@link init} has not been called.
+ * @throws {SesValidationError} When required fields are missing or invalid.
+ * @throws {SesSendError} When the AWS SES API call fails.
+ *
+ * @example
+ * ```ts
+ * import { sendEmailWithAttachments } from 'aws-ses-adapter';
+ * import { readFileSync } from 'fs';
+ *
+ * const result = await sendEmailWithAttachments({
+ *   to: 'alice@example.com',
+ *   subject: 'Your invoice',
+ *   html: '<p>Please find the invoice attached.</p>',
+ *   attachments: [
+ *     {
+ *       filename: 'invoice.pdf',
+ *       content: readFileSync('./invoice.pdf'),
+ *       contentType: 'application/pdf',
+ *     },
+ *   ],
+ * });
+ *
+ * console.log(result.messageId);
+ * ```
+ */
+declare function sendEmailWithAttachments(options: SendEmailWithAttachmentsOptions): Promise<SendEmailResult>;
+/**
+ * Sends a raw MIME email using the initialized SES Adapter.
+ *
+ * Use this when you need full control over the email, such as including
+ * attachments or custom MIME headers.
+ *
+ * @param rawMessage - The raw MIME email message as a string.
+ * @returns A promise resolving to a {@link SendEmailResult}.
+ * @throws {SesNotInitializedError} If {@link init} has not been called.
+ * @throws {SesValidationError} When the raw message is empty.
+ * @throws {SesSendError} When the AWS SES API call fails.
+ *
+ * @example
+ * ```ts
+ * import { sendRawEmail } from 'aws-ses-adapter';
+ *
+ * const mime = [
+ *   'From: sender@example.com',
+ *   'To: recipient@example.com',
+ *   'Subject: File attached',
+ *   'MIME-Version: 1.0',
+ *   'Content-Type: text/plain',
+ *   '',
+ *   'Please find the attachment.',
+ * ].join('\r\n');
+ *
+ * const result = await sendRawEmail(mime);
+ * ```
+ */
+declare function sendRawEmail(rawMessage: string): Promise<SendEmailResult>;
+/**
+ * Returns whether the singleton has been initialized via {@link init}.
+ *
+ * @returns `true` if `init()` has been called successfully.
+ *
+ * @example
+ * ```ts
+ * import { isInitialized } from 'aws-ses-adapter';
+ *
+ * if (!isInitialized()) {
+ *   init();
+ * }
+ * ```
+ */
+declare function isInitialized(): boolean;
+/**
+ * Returns whether a default "From" address is configured in the singleton.
+ *
+ * @returns `true` if a default sender address is set.
+ * @throws {SesNotInitializedError} If {@link init} has not been called.
+ *
+ * @example
+ * ```ts
+ * import { hasDefaultFrom } from 'aws-ses-adapter';
+ *
+ * console.log(hasDefaultFrom()); // => true
+ * ```
+ */
+declare function hasDefaultFrom(): boolean;
+/**
+ * Returns the default "From" email address configured in the singleton,
+ * or `undefined` if none was set.
+ *
+ * @returns The default sender address, or `undefined`.
+ * @throws {SesNotInitializedError} If {@link init} has not been called.
+ *
+ * @example
+ * ```ts
+ * import { getDefaultFrom } from 'aws-ses-adapter';
+ *
+ * const from = getDefaultFrom();
+ * // => 'noreply@example.com' or undefined
+ * ```
+ */
+declare function getDefaultFrom(): string | undefined;
+/**
+ * Returns the AWS region the singleton is configured to use.
+ *
+ * @returns The AWS region string (e.g. `'us-east-1'`).
+ * @throws {SesNotInitializedError} If {@link init} has not been called.
+ *
+ * @example
+ * ```ts
+ * import { getRegion } from 'aws-ses-adapter';
+ *
+ * console.log(getRegion()); // => 'us-east-1'
+ * ```
+ */
+declare function getRegion(): string;
+
+export { type EmailAttachment, type SendEmailOptions, type SendEmailResult, type SendEmailWithAttachmentsOptions, SesAdapter, type SesAdapterConfig, SesConfigError, SesNotInitializedError, SesSendError, SesValidationError, getDefaultFrom, getRegion, hasDefaultFrom, init, isInitialized, sendEmail, sendEmailWithAttachments, sendRawEmail };