@decaf-ts/integrations 0.11.0 → 0.14.0

package/lib/types/comms/discord/DiscordService.d.mts

@@ -0,0 +1,285 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+/**
+ * @description Configuration for the Discord service
+ * @summary Extends {@link HttpApiServiceConfig} with the Discord bot token
+ * sent as `Authorization: Bot <token>`. When omitted, the `comms.discord`
+ * environment slice supplies `token` (plus optional `baseUrl`/`timeout`).
+ * The token is a credential reference read from configuration, never a value
+ * to hard-code in source.
+ * @category Comms
+ * @memberOf module:integrations/comms/discord/service
+ */
+export interface DiscordServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Discord bot token
+     * @summary Sent as `Authorization: Bot <token>` with every API call.
+     */
+    token?: string;
+}
+/**
+ * @description Input for sending a Discord channel message
+ * @summary Carries the destination `channelId`, the message `content`, the
+ * optional text-to-speech flag, and optional rich `embeds`.
+ * @category Comms
+ * @memberOf module:integrations/comms/discord/service
+ */
+export interface DiscordMessageInput {
+    /**
+     * @description ID of the channel that receives the message
+     */
+    channelId: string;
+    /**
+     * @description Plain-text message body
+     */
+    content: string;
+    /**
+     * @description Whether Discord reads the message with text-to-speech
+     */
+    tts?: boolean;
+    /**
+     * @description Rich embed payloads attached to the message
+     */
+    embeds?: unknown[];
+}
+/**
+ * @description Input for listing a Discord channel's messages
+ * @summary Carries the `channelId` plus optional page size and a `before`
+ * message ID cursor for fetching older messages.
+ * @category Comms
+ * @memberOf module:integrations/comms/discord/service
+ */
+export interface DiscordMessageListInput {
+    /**
+     * @description ID of the channel to list messages from
+     */
+    channelId: string;
+    /**
+     * @description Maximum number of messages to return
+     */
+    limit?: number;
+    /**
+     * @description Message ID cursor; only older messages are returned
+     */
+    before?: string;
+}
+/**
+ * @description Input for creating a Discord guild channel
+ * @summary Carries the target `guildId`, the new channel `name`, and the
+ * optional channel `type` (Discord numeric type, default `0` for text),
+ * `topic`, and `parentId` (category).
+ * @category Comms
+ * @memberOf module:integrations/comms/discord/service
+ */
+export interface DiscordChannelInput {
+    /**
+     * @description ID of the guild that owns the new channel
+     */
+    guildId: string;
+    /**
+     * @description Name of the new channel
+     */
+    name: string;
+    /**
+     * @description Discord numeric channel type (default `0`, text channel)
+     */
+    type?: number;
+    /**
+     * @description Optional channel topic
+     */
+    topic?: string;
+    /**
+     * @description Optional parent category ID
+     */
+    parentId?: string;
+}
+/**
+ * @description Input for adding a reaction to a Discord message
+ * @summary Identifies the `channelId`, the target `messageId`, and the
+ * `emoji` to add as the bot user.
+ * @category Comms
+ * @memberOf module:integrations/comms/discord/service
+ */
+export interface DiscordReactionInput {
+    /**
+     * @description ID of the channel containing the message
+     */
+    channelId: string;
+    /**
+     * @description ID of the message to react to
+     */
+    messageId: string;
+    /**
+     * @description Emoji to add (Unicode character or `name:id` custom emoji)
+     */
+    emoji: string;
+}
+/**
+ * @description Discord Bot API integration service
+ * @summary An undecorated HTTP service for channel messages
+ * (`sendMessage`, `getMessage`, `listMessages`), channels (`getChannel`,
+ * `listChannels`, `createChannel`, `deleteChannel`), and reactions
+ * (`addReaction`). Every operation requires a bot token and throws
+ * `InternalError` when it is missing or a required identifier is empty;
+ * transport failures are mapped to decaf errors via {@link httpError}. This is
+ * the callable comms surface (`core.comms.discord`), not the mastra agent
+ * trigger/response kinds.
+ * @class DiscordService
+ * @extends HttpApiService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { DiscordService } from "@decaf-ts/integrations/comms/discord";
+ *
+ * const discord = new DiscordService();
+ * await discord.initialize({ token: process.env.GRAPH_CREDENTIAL_DISCORD_TOKEN });
+ * await discord.sendMessage({
+ *   channelId: process.env.DISCORD_CHANNEL_ID ?? "",
+ *   content: "Deployment finished",
+ * });
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as DiscordService
+ *   participant Discord as Discord Bot API
+ *   Caller->>Service: sendMessage(input)
+ *   activate Service
+ *   Service->>Service: requireBotToken()
+ *   Service->>Discord: POST /channels/{id}/messages
+ *   activate Discord
+ *   Discord-->>Service: message payload
+ *   deactivate Discord
+ *   Service-->>Caller: message payload
+ *   deactivate Service
+ * @memberOf module:integrations/comms/discord/service
+ */
+export declare class DiscordService extends HttpApiService<DiscordServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Discord";
+    /**
+     * @description The Discord Bot API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://discord.com/api/v10"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Discord bot authorization header
+     * @summary Returns `Authorization: Bot <token>` when the config carries a
+     * token, and no headers otherwise.
+     * @param {DiscordServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: DiscordServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Discord credentials and defaults from the environment
+     * @summary Reads the `comms.discord` environment slice and returns a partial
+     * config when a bot token is configured, `undefined` otherwise. Values pass
+     * through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<DiscordServiceConfig> | undefined} A partial config, or `undefined` when no Discord token is configured.
+     */
+    protected configFromEnvironment(): Partial<DiscordServiceConfig> | undefined;
+    /**
+     * @description Asserts that a Discord bot token is configured
+     * @summary Called by every operation before it touches the network.
+     * @returns {void}
+     * @throws {InternalError} When the resolved config has no `token`.
+     */
+    protected requireBotToken(): void;
+    /**
+     * @description Builds the encoded path for a channel resource
+     * @summary Validates the channel ID and URL-encodes it into `/channels/<id>`.
+     * @param {string} channelId - The Discord channel ID.
+     * @returns {string} The channel API path.
+     * @throws {InternalError} When `channelId` is empty.
+     */
+    private channelPath;
+    /**
+     * @description Sends a message to a Discord channel
+     * @summary `POST`s the content (and optional `tts`/`embeds`) to the channel
+     * messages endpoint and returns Discord's message payload.
+     * @param {DiscordMessageInput} input - The destination channel and message content.
+     * @returns {Promise<unknown>} The created message payload.
+     * @throws {InternalError} When no bot token is configured.
+     * @throws {BadRequestError} When Discord rejects the request.
+     * @example
+     * ```ts
+     * await discord.sendMessage({ channelId: "1234567890", content: "Hello" });
+     * ```
+     */
+    sendMessage(input: DiscordMessageInput): Promise<unknown>;
+    /**
+     * @description Fetches a single Discord message
+     * @summary `GET`s the message by channel and message ID and returns the
+     * message payload.
+     * @param {string} channelId - The channel containing the message.
+     * @param {string} messageId - The message ID to fetch.
+     * @returns {Promise<unknown>} The message payload.
+     * @throws {InternalError} When no bot token is configured or the message ID is empty.
+     * @throws {NotFoundError} When the message does not exist (HTTP 404).
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    getMessage(channelId: string, messageId: string): Promise<unknown>;
+    /**
+     * @description Lists messages in a Discord channel
+     * @summary `GET`s the channel messages with the optional `limit` and
+     * `before` cursor and returns Discord's message page.
+     * @param {DiscordMessageListInput} input - The channel and paging options.
+     * @returns {Promise<unknown>} The message page payload.
+     * @throws {InternalError} When no bot token is configured.
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    listMessages(input: DiscordMessageListInput): Promise<unknown>;
+    /**
+     * @description Fetches a Discord channel
+     * @summary `GET`s the channel by ID and returns its payload.
+     * @param {string} channelId - The channel ID to fetch.
+     * @returns {Promise<unknown>} The channel payload.
+     * @throws {InternalError} When no bot token is configured or the channel ID is empty.
+     * @throws {NotFoundError} When the channel does not exist (HTTP 404).
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    getChannel(channelId: string): Promise<unknown>;
+    /**
+     * @description Lists every channel in a Discord guild
+     * @summary `GET`s `/guilds/<id>/channels` and returns the channel list.
+     * @param {string} guildId - The guild whose channels are listed.
+     * @returns {Promise<unknown>} The guild channel list payload.
+     * @throws {InternalError} When no bot token is configured or the guild ID is empty.
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    listChannels(guildId: string): Promise<unknown>;
+    /**
+     * @description Creates a channel in a Discord guild
+     * @summary `POST`s the channel `name`, numeric `type` (default text), and
+     * optional `topic`/`parentId` to the guild channels endpoint.
+     * @param {DiscordChannelInput} input - The guild and new channel definition.
+     * @returns {Promise<unknown>} The created channel payload.
+     * @throws {InternalError} When no bot token is configured.
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    createChannel(input: DiscordChannelInput): Promise<unknown>;
+    /**
+     * @description Deletes a Discord channel
+     * @summary `DELETE`s the channel and returns the response payload, falling
+     * back to `{ deleted: true, channelId }` when Discord returns no body.
+     * @param {string} channelId - The channel ID to delete.
+     * @returns {Promise<unknown>} The deletion payload.
+     * @throws {InternalError} When no bot token is configured or the channel ID is empty.
+     * @throws {NotFoundError} When the channel does not exist (HTTP 404).
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    deleteChannel(channelId: string): Promise<unknown>;
+    /**
+     * @description Adds a reaction to a Discord message as the bot
+     * @summary `PUT`s the emoji to the message's `@me` reaction endpoint and
+     * echoes the channel and message IDs on success.
+     * @param {DiscordReactionInput} input - The channel, message, and emoji.
+     * @returns {Promise<unknown>} `{ channelId, messageId }` on success.
+     * @throws {InternalError} When no bot token is configured, or the message ID or emoji is empty.
+     * @throws {BadRequestError} When Discord rejects the request.
+     */
+    addReaction(input: DiscordReactionInput): Promise<unknown>;
+}

package/lib/types/comms/discord/index.d.cts

@@ -0,0 +1 @@
+export * from "./DiscordService.d.cts";

package/lib/types/comms/discord/index.d.mts

@@ -0,0 +1 @@
+export * from "./DiscordService.d.mts";

package/lib/types/comms/email/EmailService.d.cts

@@ -0,0 +1,184 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+import { type EmailMessageInput } from "./mime.d.cts";
+/**
+ * @description Delivery provider selected for a send
+ * @summary `smtp` delivers through the built-in raw-MIME client; `graph`
+ * posts to the Microsoft Graph `sendMail` endpoint.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export type EmailProvider = "smtp" | "graph";
+/**
+ * @description Configuration for the Email service
+ * @summary Extends {@link HttpApiServiceConfig} with the SMTP connection
+ * settings and the Microsoft Graph token/base URL. Every field falls back to
+ * the `comms.email` environment slice when omitted. A `host` selects the SMTP
+ * provider; a `token` (without `host`) selects Graph.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailServiceConfig extends HttpApiServiceConfig {
+    provider?: EmailProvider;
+    host?: string;
+    port?: number;
+    secure?: boolean;
+    username?: string;
+    password?: string;
+    /**
+     * Explicitly allow SMTP `AUTH LOGIN` over a plaintext session. Defaults to
+     * `false`: credentials are only sent after implicit TLS or a STARTTLS upgrade.
+     */
+    allowPlaintextAuth?: boolean;
+    from?: string;
+    graphBaseUrl?: string;
+    token?: string;
+}
+/**
+ * @description Result of a successful email send
+ * @summary Carries the generated RFC 5322 `Message-ID`, the resolved sender,
+ * the flattened recipient list, and the provider that delivered it.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailSendResult {
+    /** @description Generated `Message-ID` (also present in the raw MIME headers) */
+    messageId: string;
+    /** @description Sender address used for delivery */
+    from: string;
+    /** @description All To/Cc/Bcc recipients, in that order */
+    recipients: string[];
+    /** @description Provider that performed the delivery */
+    provider: EmailProvider;
+}
+/**
+ * @description Filter for inbox reads
+ * @summary Applies to both {@link EmailService.listInbox} (Graph) and
+ * {@link EmailService.listImapMessages} (IMAP): mailbox path, page size, a
+ * lower received-date bound, and a subject filter.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailInboxQuery {
+    /** @description Mailbox path to read (default `me` on Graph, `INBOX` on IMAP) */
+    mailbox?: string;
+    /** @description Maximum messages returned (default 25) */
+    limit?: number;
+    /** @description Only messages received after this date (Graph `$filter`); must be an ISO 8601 date or timestamp */
+    since?: string;
+    /** @description Subject `contains` filter (Graph only) */
+    subject?: string;
+}
+/**
+ * @description Multi-provider email send/inbox service
+ * @summary Resolves the delivery provider from config (`provider`, or inferred
+ * from the presence of `host` vs `token`), builds RFC 5322 MIME with
+ * UTF-8-encoded headers via {@link buildEmail}, then delivers through SMTP or
+ * posts to Graph. Inbox reads go through Graph `messages` (with `$top`,
+ * `$filter`, `$orderby`) or the optional `imapflow` package.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export declare class EmailService extends HttpApiService<EmailServiceConfig> {
+    protected readonly serviceName = "Email";
+    /**
+     * @description Default Microsoft Graph base URL used when no override is configured
+     * @returns The Graph v1.0 endpoint URL
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Authorization headers for Graph requests
+     * @param config - Resolved service config
+     * @returns A bearer-token `Authorization` header map, empty when no `token` is configured
+     */
+    protected authHeaders(config: EmailServiceConfig): Record<string, string>;
+    /**
+     * @description Pins the SMTP plaintext-AUTH default on top of the base initialization
+     * @summary Runs the {@link HttpApiService} initialization (explicit config
+     * merged over the `comms.email` environment slice) and then defaults an
+     * unresolved `allowPlaintextAuth` to `false`, so credentials are only sent
+     * over a TLS-protected session unless the config explicitly opts in. This
+     * closes the F1 residual where an environment-only `allowPlaintextAuth`
+     * opt-in would otherwise reach a boot whose explicit config omits the key
+     * (defense in depth on top of {@link bootWithoutEnvironment}, which disables
+     * the environment slice entirely on the node path).
+     * @param {...any[]} args - An optional `Partial<EmailServiceConfig>`, optionally followed by a decaf `Context`.
+     * @returns {Promise<{config: EmailServiceConfig, client: AxiosInstance}>} The merged configuration, with `allowPlaintextAuth` defaulted to `false` when unset, and the configured Axios instance.
+     */
+    initialize(...args: any[]): Promise<{
+        config: EmailServiceConfig;
+        client: import("axios").AxiosInstance;
+    }>;
+    /**
+     * @description Builds service config from the `comms.email` environment slice
+     * @returns A partial config when either an SMTP `host` or a Graph `token` is present, otherwise `undefined`
+     */
+    protected configFromEnvironment(): Partial<EmailServiceConfig> | undefined;
+    /**
+     * @description Selects the delivery provider
+     * @summary Prefers an explicit `provider`, then infers `smtp` from a
+     * configured `host` and `graph` from a configured `token`.
+     * @param config - Resolved service config
+     * @returns The resolved provider
+     * @throws {InternalError} when neither an SMTP host nor a Graph token is configured
+     */
+    protected resolveProvider(config: EmailServiceConfig): EmailProvider;
+    /**
+     * @description Resolves the fallback sender address
+     * @summary Uses `from`, then `username`, then the `From` header override.
+     * @param config - Resolved service config
+     * @returns The resolved sender address
+     * @throws {InternalError} when no sender address can be resolved
+     */
+    protected resolveFrom(config: EmailServiceConfig): string;
+    /**
+     * @description Sends an email through the resolved provider
+     * @summary Builds the raw MIME message (honouring `input.from`, else the
+     * resolved config sender), then delivers via SMTP or Graph. SMTP config
+     * passes `allowPlaintextAuth` through unchanged, so the plaintext-AUTH
+     * opt-out is inherited from the service config.
+     * @param input - Message input (recipients, subject, text/html body, attachments)
+     * @returns The send result with the generated `Message-ID` and provider
+     * @throws {BadRequestError} when an address, attachment filename, or content type fails validation (via {@link buildEmail})
+     * @throws {InternalError} when the provider cannot be resolved, the SMTP host is missing, plaintext AUTH is refused, or SMTP delivery fails
+     */
+    send(input: EmailMessageInput): Promise<EmailSendResult>;
+    /**
+     * @description Posts a raw MIME message to the Microsoft Graph `sendMail` endpoint
+     * @summary Sends the base64-encoded raw message to
+     * `/users/<from>/sendMail` (or `/me/sendMail` when no sender is resolved)
+     * with the configured `graphBaseUrl`/`baseUrl`.
+     * @param raw - Raw RFC 5322 message text
+     * @param from - Sender mailbox (UPN) for the Graph path
+     * @throws {Error} Graph error mapped through {@link httpError}
+     */
+    protected sendViaGraph(raw: string, from: string): Promise<void>;
+    /**
+     * @description Lists messages from a Graph mailbox
+     * @summary Queries `<mailbox>/messages` with `$top`, an optional
+     * subject/since `$filter`, and `receivedDateTime desc` ordering. The mailbox
+     * is URL-encoded as a single path segment, quotes in the subject are escaped
+     * for the OData string literal, and `since` must be an ISO 8601 date.
+     * @param query - Inbox filter (mailbox, limit, since, subject)
+     * @returns The raw Graph message records
+     * @throws {BadRequestError} when `since` is not an ISO 8601 date
+     * @throws {InternalError} when no `token` is configured; Graph errors mapped through {@link httpError}
+     */
+    listInbox(query?: EmailInboxQuery): Promise<Array<Record<string, unknown>>>;
+    /**
+     * @description Lists messages directly over IMAP
+     * @summary Dynamically imports the optional `imapflow` package, connects to
+     * `host` (default port 993, implicit TLS), and fetches the newest messages
+     * from `INBOX`.
+     *
+     * R2 direct-library-wrap justification: IMAP is a stateful protocol
+     * (mailbox locks, sequence/UID state, IDLE) whose correct implementation is
+     * large and security-sensitive. `imapflow` is the maintained n8n-vetted
+     * client for exactly this surface, so wrapping it is deliberate; a local
+     * reimplementation would add risk without changing the node contract. The
+     * package stays optional so SMTP/Graph-only consumers do not install it.
+     * @param query - Inbox filter (limit only is honoured by IMAP)
+     * @returns The fetched IMAP message records
+     * @throws {InternalError} when `imapflow` is not installed, no `host` is configured, or the IMAP session fails
+     */
+    listImapMessages(query?: EmailInboxQuery): Promise<Array<Record<string, unknown>>>;
+}

package/lib/types/comms/email/EmailService.d.mts

@@ -0,0 +1,184 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+import { type EmailMessageInput } from "./mime.d.mts";
+/**
+ * @description Delivery provider selected for a send
+ * @summary `smtp` delivers through the built-in raw-MIME client; `graph`
+ * posts to the Microsoft Graph `sendMail` endpoint.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export type EmailProvider = "smtp" | "graph";
+/**
+ * @description Configuration for the Email service
+ * @summary Extends {@link HttpApiServiceConfig} with the SMTP connection
+ * settings and the Microsoft Graph token/base URL. Every field falls back to
+ * the `comms.email` environment slice when omitted. A `host` selects the SMTP
+ * provider; a `token` (without `host`) selects Graph.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailServiceConfig extends HttpApiServiceConfig {
+    provider?: EmailProvider;
+    host?: string;
+    port?: number;
+    secure?: boolean;
+    username?: string;
+    password?: string;
+    /**
+     * Explicitly allow SMTP `AUTH LOGIN` over a plaintext session. Defaults to
+     * `false`: credentials are only sent after implicit TLS or a STARTTLS upgrade.
+     */
+    allowPlaintextAuth?: boolean;
+    from?: string;
+    graphBaseUrl?: string;
+    token?: string;
+}
+/**
+ * @description Result of a successful email send
+ * @summary Carries the generated RFC 5322 `Message-ID`, the resolved sender,
+ * the flattened recipient list, and the provider that delivered it.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailSendResult {
+    /** @description Generated `Message-ID` (also present in the raw MIME headers) */
+    messageId: string;
+    /** @description Sender address used for delivery */
+    from: string;
+    /** @description All To/Cc/Bcc recipients, in that order */
+    recipients: string[];
+    /** @description Provider that performed the delivery */
+    provider: EmailProvider;
+}
+/**
+ * @description Filter for inbox reads
+ * @summary Applies to both {@link EmailService.listInbox} (Graph) and
+ * {@link EmailService.listImapMessages} (IMAP): mailbox path, page size, a
+ * lower received-date bound, and a subject filter.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export interface EmailInboxQuery {
+    /** @description Mailbox path to read (default `me` on Graph, `INBOX` on IMAP) */
+    mailbox?: string;
+    /** @description Maximum messages returned (default 25) */
+    limit?: number;
+    /** @description Only messages received after this date (Graph `$filter`); must be an ISO 8601 date or timestamp */
+    since?: string;
+    /** @description Subject `contains` filter (Graph only) */
+    subject?: string;
+}
+/**
+ * @description Multi-provider email send/inbox service
+ * @summary Resolves the delivery provider from config (`provider`, or inferred
+ * from the presence of `host` vs `token`), builds RFC 5322 MIME with
+ * UTF-8-encoded headers via {@link buildEmail}, then delivers through SMTP or
+ * posts to Graph. Inbox reads go through Graph `messages` (with `$top`,
+ * `$filter`, `$orderby`) or the optional `imapflow` package.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/service
+ */
+export declare class EmailService extends HttpApiService<EmailServiceConfig> {
+    protected readonly serviceName = "Email";
+    /**
+     * @description Default Microsoft Graph base URL used when no override is configured
+     * @returns The Graph v1.0 endpoint URL
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Authorization headers for Graph requests
+     * @param config - Resolved service config
+     * @returns A bearer-token `Authorization` header map, empty when no `token` is configured
+     */
+    protected authHeaders(config: EmailServiceConfig): Record<string, string>;
+    /**
+     * @description Pins the SMTP plaintext-AUTH default on top of the base initialization
+     * @summary Runs the {@link HttpApiService} initialization (explicit config
+     * merged over the `comms.email` environment slice) and then defaults an
+     * unresolved `allowPlaintextAuth` to `false`, so credentials are only sent
+     * over a TLS-protected session unless the config explicitly opts in. This
+     * closes the F1 residual where an environment-only `allowPlaintextAuth`
+     * opt-in would otherwise reach a boot whose explicit config omits the key
+     * (defense in depth on top of {@link bootWithoutEnvironment}, which disables
+     * the environment slice entirely on the node path).
+     * @param {...any[]} args - An optional `Partial<EmailServiceConfig>`, optionally followed by a decaf `Context`.
+     * @returns {Promise<{config: EmailServiceConfig, client: AxiosInstance}>} The merged configuration, with `allowPlaintextAuth` defaulted to `false` when unset, and the configured Axios instance.
+     */
+    initialize(...args: any[]): Promise<{
+        config: EmailServiceConfig;
+        client: import("axios").AxiosInstance;
+    }>;
+    /**
+     * @description Builds service config from the `comms.email` environment slice
+     * @returns A partial config when either an SMTP `host` or a Graph `token` is present, otherwise `undefined`
+     */
+    protected configFromEnvironment(): Partial<EmailServiceConfig> | undefined;
+    /**
+     * @description Selects the delivery provider
+     * @summary Prefers an explicit `provider`, then infers `smtp` from a
+     * configured `host` and `graph` from a configured `token`.
+     * @param config - Resolved service config
+     * @returns The resolved provider
+     * @throws {InternalError} when neither an SMTP host nor a Graph token is configured
+     */
+    protected resolveProvider(config: EmailServiceConfig): EmailProvider;
+    /**
+     * @description Resolves the fallback sender address
+     * @summary Uses `from`, then `username`, then the `From` header override.
+     * @param config - Resolved service config
+     * @returns The resolved sender address
+     * @throws {InternalError} when no sender address can be resolved
+     */
+    protected resolveFrom(config: EmailServiceConfig): string;
+    /**
+     * @description Sends an email through the resolved provider
+     * @summary Builds the raw MIME message (honouring `input.from`, else the
+     * resolved config sender), then delivers via SMTP or Graph. SMTP config
+     * passes `allowPlaintextAuth` through unchanged, so the plaintext-AUTH
+     * opt-out is inherited from the service config.
+     * @param input - Message input (recipients, subject, text/html body, attachments)
+     * @returns The send result with the generated `Message-ID` and provider
+     * @throws {BadRequestError} when an address, attachment filename, or content type fails validation (via {@link buildEmail})
+     * @throws {InternalError} when the provider cannot be resolved, the SMTP host is missing, plaintext AUTH is refused, or SMTP delivery fails
+     */
+    send(input: EmailMessageInput): Promise<EmailSendResult>;
+    /**
+     * @description Posts a raw MIME message to the Microsoft Graph `sendMail` endpoint
+     * @summary Sends the base64-encoded raw message to
+     * `/users/<from>/sendMail` (or `/me/sendMail` when no sender is resolved)
+     * with the configured `graphBaseUrl`/`baseUrl`.
+     * @param raw - Raw RFC 5322 message text
+     * @param from - Sender mailbox (UPN) for the Graph path
+     * @throws {Error} Graph error mapped through {@link httpError}
+     */
+    protected sendViaGraph(raw: string, from: string): Promise<void>;
+    /**
+     * @description Lists messages from a Graph mailbox
+     * @summary Queries `<mailbox>/messages` with `$top`, an optional
+     * subject/since `$filter`, and `receivedDateTime desc` ordering. The mailbox
+     * is URL-encoded as a single path segment, quotes in the subject are escaped
+     * for the OData string literal, and `since` must be an ISO 8601 date.
+     * @param query - Inbox filter (mailbox, limit, since, subject)
+     * @returns The raw Graph message records
+     * @throws {BadRequestError} when `since` is not an ISO 8601 date
+     * @throws {InternalError} when no `token` is configured; Graph errors mapped through {@link httpError}
+     */
+    listInbox(query?: EmailInboxQuery): Promise<Array<Record<string, unknown>>>;
+    /**
+     * @description Lists messages directly over IMAP
+     * @summary Dynamically imports the optional `imapflow` package, connects to
+     * `host` (default port 993, implicit TLS), and fetches the newest messages
+     * from `INBOX`.
+     *
+     * R2 direct-library-wrap justification: IMAP is a stateful protocol
+     * (mailbox locks, sequence/UID state, IDLE) whose correct implementation is
+     * large and security-sensitive. `imapflow` is the maintained n8n-vetted
+     * client for exactly this surface, so wrapping it is deliberate; a local
+     * reimplementation would add risk without changing the node contract. The
+     * package stays optional so SMTP/Graph-only consumers do not install it.
+     * @param query - Inbox filter (limit only is honoured by IMAP)
+     * @returns The fetched IMAP message records
+     * @throws {InternalError} when `imapflow` is not installed, no `host` is configured, or the IMAP session fails
+     */
+    listImapMessages(query?: EmailInboxQuery): Promise<Array<Record<string, unknown>>>;
+}

package/lib/types/comms/email/index.d.cts

@@ -0,0 +1,11 @@
+/**
+ * @module integrations/comms/email
+ * @summary Email service (SMTP + Microsoft Graph send, Graph/IMAP inbox reads).
+ * @description Re-exports the {@link EmailService} and its config/result
+ * types, the raw MIME builder, and the nodemailer-backed {@link SmtpClient}
+ * with its {@link SmtpConfig}
+ * (also available directly from the `./smtp` subpath).
+ */
+export * from "./EmailService.d.cts";
+export * from "./mime.d.cts";
+export * from "./smtp.d.cts";