@withstudiocms/effect/dist/smtp.d.ts

Effect-TS Utilities for Astro

import _nodemailer from 'nodemailer';
import type Mail from 'nodemailer/lib/mailer';
import type SMTPTransport from 'nodemailer/lib/smtp-transport';
import { Brand, Context, Effect, Layer } from './effect.js';
export type { Mail, SMTPTransport };
/**
 * Custom Transport interface for nodemailer that extends the SMTPTransport.Options to
 * include an optional proxy configuration.
 */
export interface Transport extends SMTPTransport.Options {
    proxy?: string;
}
/**
 * Configuration interface for the mail transporter.
 *
 * This interface defines the structure for configuring the mail transporter,
 * including options for the SMTP server, authentication, and TLS settings.
 * @interface TransportConfig
 * @property {Transport} [transport] - The transport options for the mail transporter.
 * @property {SMTPTransport.Options} [defaults] - Default options for the mail transporter.
 * Note: Proxy configuration is specified on `transport.proxy`.
 */
export type TransportConfig = {
    transport?: Transport;
    defaults?: SMTPTransport.Options;
} & Brand.Brand<'TransportConfig'>;
/**
 * Nominal type for TransportConfig to ensure type safety and prevent accidental misuse.
 * @remarks
 * The `Brand.nominal` utility is used to create a unique type that cannot be
 * accidentally substituted with other types, even if they have the same structure.
 * @example
 * ```typescript
 * const config: TransportConfig = {
 *   transport: {
 *     host: 'smtp.example.com',
 *     port: 587,
 *     secure: false,
 *     auth: {
 *       user: 'user',
 *       pass: 'pass'
 *     }
 *   }
 * };
 *
 * // This ensures that the config variable is treated as a TransportConfig type,
 * // preventing accidental assignment of incompatible types.
 * const transportConfig: TransportConfig = TransportConfig(config);
 * ```
 */
export declare const TransportConfig: Brand.Brand.Constructor<TransportConfig>;
declare const SMTPTransportConfig_base: Context.TagClass<SMTPTransportConfig, "SMTPTransportConfig", TransportConfig>;
/**
 * A context tag for SMTP transport configuration, extending the base Context.Tag
 * with the specific identifier 'SMTPTransportConfig'. This class is used to
 * provide and manage SMTP transport configuration within the application's context.
 *
 * @template SMTPTransportConfig - The type representing the SMTP transport config context.
 * @template TransportConfig - The type representing the SMTP transport configuration.
 *
 * @example
 * ```typescript
 * const smtpLayer = SMTPTransportConfig.makeLive({
 *   host: 'smtp.example.com',
 *   port: 587,
 *   secure: false,
 *   auth: { user: 'user', pass: 'pass' }
 * });
 * ```
 */
export declare class SMTPTransportConfig extends SMTPTransportConfig_base {
    static makeLive(config: TransportConfig): Layer.Layer<SMTPTransportConfig, never, never>;
}
declare const SMTPService_base: Effect.Service.Class<SMTPService, "SMTPService", {
    readonly effect: Effect.Effect<{
        Mailer: <T>(fn: (mailer: _nodemailer.Transporter<SMTPTransport.SentMessageInfo, SMTPTransport.Options>) => Promise<T> | T) => Effect.Effect<T, Error, never>;
        verifyTransport: () => Effect.Effect<true, Error, never>;
        sendMail: (mailOptions: Mail.Options) => Effect.Effect<SMTPTransport.SentMessageInfo, Error, never>;
        isIdle: () => Effect.Effect<boolean, Error, never>;
        getVersionString: () => Effect.Effect<string, Error, never>;
        close: () => Effect.Effect<void, Error, never>;
    }, Error, SMTPTransportConfig>;
}>;
/**
 * The `SMTPService` provides an Effect-based abstraction for sending emails using SMTP via nodemailer.
 *
 * This service is responsible for:
 * - Creating and configuring a nodemailer transport instance with support for proxies.
 * - Exposing a `Mailer` function to run user-defined operations with the configured mailer.
 * - Verifying the SMTP transport configuration.
 * - Sending emails using the configured SMTP transport.
 * - Checking if the SMTP transport is idle.
 * - Retrieving the version string of the SMTP transport.
 *
 * All operations are wrapped in Effect for composability and error handling.
 *
 * @remarks
 * This service expects an `SMTPTransportConfig` to be available in the Effect context.
 *
 * @example
 * ```typescript
 * const result = Effect.runPromise(
 *   SMTPService.sendMail({ to: "user@example.com", subject: "Hello", text: "Hi!" })
 * );
 * ```
 */
export declare class SMTPService extends SMTPService_base {
}