mail-plugin/src/index.ts - Setu-TS documentation

Classes

LogProvider(options?: LogProviderOptions)

Records outgoing mail instead of sending it.

connect(): Promise<void>
Establishes any backing connection/client. No-op for stateless providers.
disconnect(): Promise<void>
Releases any backing connection/client. No-op for stateless providers.
isHealthy(): Promise<boolean>
M70c: a log provider never touches a network, so it is always reachable (M47).
isReady(): boolean
Reports whether the provider is ready to send.
messages(): readonly OutgoingMail[]
Every message recorded by this provider, in send order.
send(message: OutgoingMail): Promise<void>
Records and logs a message.

MailService(

provider: MailProvider,

templates: TemplateEngine,

options?: MailServiceOptions

)

Mailer backed by a pluggable provider and a template engine.

isHealthy(): Promise<boolean | undefined>
Reports whether the backing provider's transport is reachable right now.
send(message: MailMessage): Promise<void>
Sends an email, resolving from from the message or the configured default.
sendTemplate(
template: string,
message: Omit<MailMessage, "html" | "text">,
data: Readonly<Record<string, unknown>>
): Promise<void>
Renders a named template and sends the result. The subject is taken verbatim from message; the template supplies the html/text bodies.

SendGridProvider(options?: SendGridProviderOptions)

SendGrid provider over fetch.

connect(): Promise<void>
Establishes any backing connection/client. No-op for stateless providers.
disconnect(): Promise<void>
Releases any backing connection/client. No-op for stateless providers.
isHealthy(): Promise<boolean>
M70c: a GET /v3/scopes through the existing IMailHttp seam. 2xx means the key is valid; 401 means the API reached us (so the backend is reachable even though the key is wrong); any other status or a network failure means unreachable.
isReady(): boolean
Reports whether the provider is ready to send.
send(message: OutgoingMail): Promise<void>
Sends a message via the SendGrid v3 API.

SesProvider(options?: SesProviderOptions)

AWS SESv2 provider.

connect(): Promise<void>
Establishes any backing connection/client. No-op for stateless providers.
disconnect(): Promise<void>
Releases any backing connection/client. No-op for stateless providers.
isHealthy: () => Promise<boolean>
M70c: present only when the client exposes isHealthy?() (the real adapter issues GetAccount); its absence is unknown reachability, not false.
isReady(): boolean
Reports whether the provider is ready to send.
send(message: OutgoingMail): Promise<void>
Sends a message via SES.

SmtpProvider(options?: SmtpProviderOptions)

SMTP provider over nodemailer.

connect(): Promise<void>
Establishes any backing connection/client. No-op for stateless providers.
disconnect(): Promise<void>
Releases any backing connection/client. No-op for stateless providers.
isHealthy: () => Promise<boolean>
M70c: present only when the transport exposes verify(); its absence is unknown reachability, not false (a minimal injected fake has not told us the server is dead).
isReady(): boolean
Reports whether the provider is ready to send.
send(message: OutgoingMail): Promise<void>
Sends a message over SMTP.

TemplateEngine(templates?: Readonly<Record<string, MailTemplate>>)

A registry of named body templates with {{ variable }} interpolation.

has(name: string): boolean
Reports whether a template is registered.
render(
name: string,
data: Readonly<Record<string, unknown>>
): RenderedTemplate
Renders a template's bodies with data.

Functions

adaptNodemailerModule(

mod: NodemailerModule,

options: SmtpProviderOptions

): ISmtpTransport

Adapts the nodemailer module to a transport facade. Pure — unit-tested with a fake module; the real module is supplied on the lazy path by loadNodemailerModule.

adaptSesModule(

mod: SesSdkModule,

options: SesProviderOptions

): ISesClient

Adapts the AWS SESv2 SDK module to the facade. Pure — unit-tested with a fake module; the real module is supplied on the lazy path by loadSesModule.

createProvider(

type: MailProviderType,

options: MailProviderOptions,

ctx: IPluginContext

): MailProvider

Builds the provider adapter for the configured backend.

escapeHtml(value: string): string

Escapes the five HTML-significant characters so interpolated user data cannot inject markup into an HTML body.

loadNodemailerModule(): Promise<NodemailerModule>

Lazily imports nodemailer. Only exercised on the lazy path.

loadSesModule(): Promise<SesSdkModule>

Lazily imports the AWS SESv2 SDK. Only exercised on the lazy path.

MailPlugin(options?: MailPluginOptions): IPlugin

Creates the MailPlugin.

toNodemailerMessage(message: OutgoingMail): Parameters<ISmtpTransport["sendMail"]>[0]

Maps an OutgoingMail to nodemailer's message fields.

toSendGridBody(message: OutgoingMail): Record<string, unknown>

Maps an OutgoingMail to a SendGrid v3 request body.

toSesInput(message: OutgoingMail): Record<string, unknown>

Maps an OutgoingMail to a SendEmailCommand input.

validateSesClient(client: unknown): client is ISesClient

Validates that an injected object matches ISesClient.

validateSmtpTransport(transport: unknown): transport is ISmtpTransport

Validates that an injected object matches ISmtpTransport.

Interfaces

IMailer

Email sender.

isHealthy(): Promise<boolean | undefined>
Reports whether the mail transport is REACHABLE right now, distinct from whether the mailer was constructed. Optional: a mailer whose transport exposes no side-effect-free probe omits it, and so does an implementation that does not answer the question at all.
send(message: MailMessage): Promise<void>
Sends an email.
sendTemplate(
template: string,
message: Omit<MailMessage, "html" | "text">,
data: Readonly<Record<string, unknown>>
): Promise<void>
Renders a named template and sends the result.

ISesClient

Structural shape of an AWS SESv2 client facade (injected or SDK-adapted). The plugin never hard-depends on @aws-sdk/client-sesv2.

isHealthy(): Promise<boolean>
M70c: reports whether the SES account is reachable — the real adapter issues GetAccount. Optional so a minimal injected fake still type-checks; a client that omits it is unknown, not false.
sendEmail(message: OutgoingMail): Promise<void>
Sends one message via SES.

ISmtpTransport

Structural shape of a nodemailer transport. The plugin never hard-depends on nodemailer; inject this shape, or SmtpProvider lazily loads the package and adapts it to this facade.

sendMail(mail: { from: string; to: string; subject: string; text?: string; html?: string; cc?: string; bcc?: string; }): Promise<unknown>
Sends one message.
verify(): Promise<unknown>
M70c: verifies the SMTP connection. nodemailer's real transport exposes this; a minimal injected fake may omit it, in which case the provider reports unknown reachability rather than false.

LogProviderOptions

Options for LogProvider.

logger: ILogger
Logger to write each send to (typically ctx.logger).
sink: (message: OutgoingMail) => void
Called with each sent message — a read-back seam for tests/hooks.

MailMessage

An outgoing email message.

bcc: readonly string[]
Blind-carbon-copy recipients.
cc: readonly string[]
Carbon-copy recipients.
from: string
Sender address; omitted to use the provider default.
html: string
HTML body.
subject: string
Subject line.
text: string
Plain-text body.
to: string | readonly string[]
Recipient address(es).

MailPluginOptions

Options for the MailPlugin factory.

defaults: { from?: string; }
Message defaults applied when a message omits the field.
options: MailProviderOptions
Provider-specific options.
provider: MailProviderType
Provider backend. Defaults to 'log'.
templates: Record<string, MailTemplate>
Named body templates available to sendTemplate.

MailProviderOptions

Provider-specific options. Fields are consumed only by the matching provider; unrelated fields are ignored (mirrors SecretsProviderOptions).

accessKeyId: string
(ses) AWS access key id for the lazily-loaded client.
apiKey: string
(sendgrid) SendGrid API key sent as a Bearer token.
auth: { user: string; pass: string; }
(smtp) SMTP auth credentials.
client: ISesClient
(ses) Injected client facade; bypasses the lazy SDK import.
endpoint: string
(sendgrid) API endpoint. Default https://api.sendgrid.com/v3/mail/send.
host: string
(smtp) SMTP server host.
http: IMailHttp
(sendgrid) Injected fetch-shaped function; defaults to global fetch.
port: number
(smtp) SMTP server port. Default 587.
region: string
(ses) AWS region for the lazily-loaded client.
secretAccessKey: string
(ses) AWS secret access key for the lazily-loaded client.
secure: boolean
(smtp) Use an implicit TLS connection. Default false.
sink: (message: OutgoingMail) => void
(log) Called with each sent message — a read-back seam for tests/hooks.
transport: ISmtpTransport
(smtp) Injected transport facade; bypasses the lazy nodemailer import.

MailServiceOptions

Options for MailService.

defaultFrom: string
Default sender used when a message omits from.
probeTiming: ProbeTiming
Monotonic clock and timers used to cache and bound MailService.isHealthy.

MailTemplate

A named body template. At least one of html/text must be present.

html: string
HTML body template with {{ variable }} placeholders (values escaped).
text: string
Plain-text body template with {{ variable }} placeholders (raw).

NodemailerModule

The subset of nodemailer the adapter uses.

createTransport: (options: Record<string, unknown>) => ISmtpTransport

RenderedTemplate

A rendered template body. Only present bodies are returned.

SendGridProviderOptions

Options for SendGridProvider.

apiKey: string | undefined
SendGrid API key sent as a Bearer token.
endpoint: string | undefined
API endpoint. Default https://api.sendgrid.com/v3/mail/send.
http: IMailHttp | undefined
Injected fetch-shaped function; defaults to global fetch.

SesProviderOptions

Options for SesProvider.

accessKeyId: string | undefined
AWS access key id for the lazily-loaded client.
client: ISesClient | undefined
Injected client facade; bypasses the lazy SDK import.
region: string | undefined
AWS region for the lazily-loaded client.
secretAccessKey: string | undefined
AWS secret access key for the lazily-loaded client.

SesSdkModule

The subset of the AWS SESv2 SDK the adapter uses.

SmtpProviderOptions

Options for SmtpProvider.

auth: { user: string; pass: string; } | undefined
SMTP auth credentials.
host: string | undefined
SMTP server host.
port: number | undefined
SMTP server port. Default 587.
secure: boolean | undefined
Use an implicit TLS connection. Default false.
transport: ISmtpTransport | undefined
Injected transport facade; bypasses the lazy nodemailer import.

Type Aliases

IMailHttp = (

url: string,

init?: RequestInit

) => Promise<Response>

A fetch-shaped function used by SendGridProvider so it stays runtime-agnostic and testable.

MailProviderType = "log" | "smtp" | "ses" | "sendgrid"

Supported mail provider backends.

OutgoingMail = MailMessage & { readonly from: string; }

An outgoing email whose sender has already been resolved by MailService (from the message or the configured default). This is the shape every MailProvider receives — from is never absent.

Classes

Functions

Interfaces

Type Aliases

Usage