@decaf-ts/integrations 0.11.0 → 0.14.0

package/lib/esm/comms/discord/DiscordService.js

@@ -0,0 +1,313 @@
+/**
+ * @module integrations/comms/discord/service
+ * @summary Discord Bot API integration service for messages, channels, and reactions.
+ * @description Exposes the Discord Bot REST API (v10) as an undecorated
+ * client-based service built on {@link HttpApiService}. Configuration comes
+ * from an explicit `DiscordServiceConfig` or the `comms.discord` environment
+ * slice, and the bot token is sent as `Authorization: Bot <token>` on every
+ * call. Credentials are referenced from configuration (and, from as-graph
+ * nodes, from the resolved `discord` credential secret) and are never embedded
+ * in source. Failures are mapped to decaf errors via {@link httpError}.
+ *
+ * `core.comms.discord` is a callable messaging service/node. It is distinct
+ * from the mastra agent channel kinds `core.agent.trigger.discord` and
+ * `core.agent.response.discord`, which receive inbound conversations and post
+ * agent replies through host-supplied channel adapters.
+ */
+import { InternalError } from "@decaf-ts/db-decorators";
+import { CommsEnvironment } from "./../environment.js";
+import { envNumber, envString } from "./../../shared/environmentValue.js";
+import { HttpApiService, httpError, } from "./../../shared/http/index.js";
+const DEFAULT_CHANNEL_TYPE = 0;
+/**
+ * @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 class DiscordService extends HttpApiService {
+    constructor() {
+        super(...arguments);
+        /**
+         * @description The provider name used in error messages
+         */
+        this.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"`.
+     */
+    defaultBaseUrl() {
+        return "https://discord.com/api/v10";
+    }
+    /**
+     * @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).
+     */
+    authHeaders(config) {
+        return config.token ? { Authorization: `Bot ${config.token}` } : {};
+    }
+    /**
+     * @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.
+     */
+    configFromEnvironment() {
+        const env = CommsEnvironment.comms.discord;
+        const token = envString(env?.token);
+        if (!token)
+            return undefined;
+        return {
+            token,
+            baseUrl: envString(env.baseUrl),
+            timeout: envNumber(env.timeout),
+        };
+    }
+    /**
+     * @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`.
+     */
+    requireBotToken() {
+        if (!this.config.token) {
+            throw new InternalError("Discord requires a bot token");
+        }
+    }
+    /**
+     * @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.
+     */
+    channelPath(channelId) {
+        if (!channelId) {
+            throw new InternalError("Discord requires a channel id");
+        }
+        return `/channels/${encodeURIComponent(channelId)}`;
+    }
+    /**
+     * @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" });
+     * ```
+     */
+    async sendMessage(input) {
+        this.requireBotToken();
+        try {
+            const response = await this.client.post(`${this.channelPath(input.channelId)}/messages`, {
+                content: input.content,
+                tts: input.tts ?? false,
+                ...(input.embeds ? { embeds: input.embeds } : {}),
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Discord", "send message", error);
+        }
+    }
+    /**
+     * @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.
+     */
+    async getMessage(channelId, messageId) {
+        this.requireBotToken();
+        if (!messageId) {
+            throw new InternalError("Discord requires a message id");
+        }
+        try {
+            const response = await this.client.get(`${this.channelPath(channelId)}/messages/${encodeURIComponent(messageId)}`);
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Discord", "get message", error);
+        }
+    }
+    /**
+     * @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.
+     */
+    async listMessages(input) {
+        this.requireBotToken();
+        try {
+            const response = await this.client.get(`${this.channelPath(input.channelId)}/messages`, {
+                params: {
+                    ...(input.limit !== undefined ? { limit: input.limit } : {}),
+                    ...(input.before ? { before: input.before } : {}),
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Discord", "list messages", error);
+        }
+    }
+    /**
+     * @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.
+     */
+    async getChannel(channelId) {
+        this.requireBotToken();
+        try {
+            const response = await this.client.get(this.channelPath(channelId));
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Discord", "get channel", error);
+        }
+    }
+    /**
+     * @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.
+     */
+    async listChannels(guildId) {
+        this.requireBotToken();
+        if (!guildId) {
+            throw new InternalError("Discord requires a guild id");
+        }
+        try {
+            const response = await this.client.get(`/guilds/${encodeURIComponent(guildId)}/channels`);
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Discord", "list channels", error);
+        }
+    }
+    /**
+     * @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.
+     */
+    async createChannel(input) {
+        this.requireBotToken();
+        try {
+            const response = await this.client.post(`/guilds/${encodeURIComponent(input.guildId)}/channels`, {
+                name: input.name,
+                type: input.type ?? DEFAULT_CHANNEL_TYPE,
+                ...(input.topic ? { topic: input.topic } : {}),
+                ...(input.parentId ? { parent_id: input.parentId } : {}),
+            });
+            return response.data;
+        }
+        catch (error) {
+            throw httpError("Discord", "create channel", error);
+        }
+    }
+    /**
+     * @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.
+     */
+    async deleteChannel(channelId) {
+        this.requireBotToken();
+        try {
+            const response = await this.client.delete(this.channelPath(channelId));
+            return response.data ?? { deleted: true, channelId };
+        }
+        catch (error) {
+            throw httpError("Discord", "delete channel", error);
+        }
+    }
+    /**
+     * @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.
+     */
+    async addReaction(input) {
+        this.requireBotToken();
+        if (!input.messageId || !input.emoji) {
+            throw new InternalError("Discord requires a message id and emoji");
+        }
+        try {
+            await this.client.put(`${this.channelPath(input.channelId)}/messages/${encodeURIComponent(input.messageId)}/reactions/${encodeURIComponent(input.emoji)}/@me`);
+            return { channelId: input.channelId, messageId: input.messageId };
+        }
+        catch (error) {
+            throw httpError("Discord", "add reaction", error);
+        }
+    }
+}
+//# sourceMappingURL=DiscordService.js.map

package/lib/esm/comms/discord/DiscordService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiscordService.js","sourceRoot":"","sources":["../../../../src/comms/discord/DiscordService.ts"],"names":[],"mappings":"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"}

package/lib/esm/comms/discord/index.js

@@ -0,0 +1,2 @@
+export * from "./DiscordService.js";
+//# sourceMappingURL=index.js.map

package/lib/esm/comms/discord/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/comms/discord/index.ts"],"names":[],"mappings":"AAAA,oCAAiC"}

package/lib/esm/comms/email/EmailService.js

@@ -0,0 +1,338 @@
+/**
+ * @module integrations/comms/email/service
+ * @summary Email integration service for sending mail and reading inboxes across SMTP, Microsoft Graph, and IMAP.
+ * @description Exposes an undecorated client-based service that
+ * multiplexes three delivery surfaces behind one config: SMTP delivery through
+ * the built-in {@link SmtpClient} (raw MIME built by {@link buildEmail}), and
+ * Microsoft Graph (`sendMail`, message listing) through {@link HttpApiService}
+ * with a bearer token. `listInbox` reads via Graph while `listImapMessages`
+ * dynamically imports the optional `imapflow` package for direct IMAP reads.
+ * Configuration comes from an explicit {@link EmailServiceConfig} or the
+ * `comms.email` environment slice; failures are mapped to decaf errors via
+ * {@link httpError} (Graph) or wrapped `InternalError`s (SMTP).
+ */
+import { BadRequestError, InternalError } from "@decaf-ts/db-decorators";
+import { CommsEnvironment } from "./../environment.js";
+import { envBoolean, envNumber, envString, } from "./../../shared/environmentValue.js";
+import { HttpApiService, httpError, } from "./../../shared/http/index.js";
+import { SmtpClient } from "./smtp.js";
+import { buildEmail } from "./mime.js";
+/**
+ * ISO 8601 date shapes accepted by the Graph `receivedDateTime` filter.
+ * Date-only values and full timestamps (with optional fractional seconds and
+ * `Z`/offset) are allowed; anything else is rejected before it can reach
+ * `$filter`.
+ */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})?)?$/;
+/**
+ * Validates and returns an ISO 8601 date for a Graph `$filter` literal.
+ *
+ * @param value - Caller-supplied `since` value.
+ * @returns The validated ISO date string.
+ * @throws {BadRequestError} when the value is not a parseable ISO 8601 date.
+ */
+function assertIsoDate(value) {
+    if (!ISO_DATE.test(value) || Number.isNaN(Date.parse(value))) {
+        throw new BadRequestError("Email inbox 'since' filter must be an ISO 8601 date");
+    }
+    return value;
+}
+/**
+ * Escapes a value for use inside an OData single-quoted string literal.
+ *
+ * @param value - Raw filter value.
+ * @returns The value with embedded single quotes doubled per OData rules.
+ */
+function escapeODataString(value) {
+    return value.replace(/'/g, "''");
+}
+/**
+ * @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 class EmailService extends HttpApiService {
+    constructor() {
+        super(...arguments);
+        this.serviceName = "Email";
+    }
+    /**
+     * @description Default Microsoft Graph base URL used when no override is configured
+     * @returns The Graph v1.0 endpoint URL
+     */
+    defaultBaseUrl() {
+        return "https://graph.microsoft.com/v1.0";
+    }
+    /**
+     * @description Authorization headers for Graph requests
+     * @param config - Resolved service config
+     * @returns A bearer-token `Authorization` header map, empty when no `token` is configured
+     */
+    authHeaders(config) {
+        return config.token ? { Authorization: `Bearer ${config.token}` } : {};
+    }
+    /**
+     * @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.
+     */
+    async initialize(...args) {
+        const initialized = await super.initialize(...args);
+        initialized.config.allowPlaintextAuth =
+            initialized.config.allowPlaintextAuth ?? false;
+        return initialized;
+    }
+    /**
+     * @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`
+     */
+    configFromEnvironment() {
+        const env = CommsEnvironment.comms.email;
+        const host = envString(env?.host);
+        const token = envString(env?.token);
+        if (!host && !token)
+            return undefined;
+        const provider = envString(env.provider);
+        return {
+            provider: provider ?? (host ? "smtp" : "graph"),
+            host,
+            port: envNumber(env.port),
+            secure: envBoolean(env.secure),
+            username: envString(env.username),
+            password: envString(env.password),
+            allowPlaintextAuth: envBoolean(env.allowPlaintextAuth),
+            from: envString(env.from),
+            token,
+            graphBaseUrl: envString(env.graphBaseUrl),
+            timeout: envNumber(env.timeout),
+        };
+    }
+    /**
+     * @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
+     */
+    resolveProvider(config) {
+        if (config.provider)
+            return config.provider;
+        if (config.host)
+            return "smtp";
+        if (config.token)
+            return "graph";
+        throw new InternalError("Email requires either an SMTP host or a Microsoft Graph token");
+    }
+    /**
+     * @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
+     */
+    resolveFrom(config) {
+        const from = config.from ?? config.username ?? config.headers?.["From"] ?? undefined;
+        if (!from)
+            throw new InternalError("Email requires a sender address");
+        return from;
+    }
+    /**
+     * @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
+     */
+    async send(input) {
+        const config = this.config;
+        const provider = this.resolveProvider(config);
+        const from = input.from || this.resolveFrom(config);
+        const built = buildEmail({ ...input, from });
+        if (provider === "graph") {
+            await this.sendViaGraph(built.raw, from);
+            return {
+                messageId: built.messageId,
+                from,
+                recipients: built.recipients,
+                provider,
+            };
+        }
+        if (!config.host) {
+            throw new InternalError("Email SMTP provider requires a host");
+        }
+        const client = new SmtpClient({
+            host: config.host,
+            port: config.port,
+            secure: config.secure,
+            username: config.username,
+            password: config.password,
+            timeout: config.timeout,
+            allowPlaintextAuth: config.allowPlaintextAuth,
+        });
+        try {
+            await client.connect();
+            await client.send(built.from, built.recipients, built.raw);
+            return {
+                messageId: built.messageId,
+                from,
+                recipients: built.recipients,
+                provider,
+            };
+        }
+        catch (error) {
+            if (error instanceof InternalError)
+                throw error;
+            throw new InternalError(`Email SMTP delivery failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            await client.close().catch(() => undefined);
+        }
+    }
+    /**
+     * @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}
+     */
+    async sendViaGraph(raw, from) {
+        const config = this.config;
+        this.requireToken(config);
+        const baseUrl = config.graphBaseUrl ??
+            config.baseUrl ??
+            "https://graph.microsoft.com/v1.0";
+        const path = from
+            ? `/users/${encodeURIComponent(from)}/sendMail`
+            : "/me/sendMail";
+        try {
+            await this.client.post(`${baseUrl}${path}`, Buffer.from(raw, "utf8").toString("base64"), {
+                headers: { "Content-Type": "text/plain" },
+            });
+        }
+        catch (error) {
+            throw httpError("Microsoft Graph", "sendMail", error);
+        }
+    }
+    /**
+     * @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}
+     */
+    async listInbox(query = {}) {
+        const config = this.config;
+        this.requireToken(config);
+        const baseUrl = config.graphBaseUrl ??
+            config.baseUrl ??
+            "https://graph.microsoft.com/v1.0";
+        const mailbox = encodeURIComponent(query.mailbox ?? "me");
+        const filters = [
+            query.subject
+                ? `contains(subject,'${escapeODataString(query.subject)}')`
+                : undefined,
+            query.since
+                ? `receivedDateTime ge ${assertIsoDate(query.since)}`
+                : undefined,
+        ].filter(Boolean);
+        try {
+            const response = await this.client.get(`${baseUrl}/${mailbox}/messages`, {
+                params: {
+                    $top: query.limit ?? 25,
+                    $filter: filters.length ? filters.join(" and ") : undefined,
+                    $orderby: "receivedDateTime desc",
+                },
+            });
+            return response.data.value ?? [];
+        }
+        catch (error) {
+            throw httpError("Microsoft Graph", "list messages", error);
+        }
+    }
+    /**
+     * @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
+     */
+    async listImapMessages(query = {}) {
+        let ImapFlow;
+        try {
+            const moduleName = "imapflow";
+            const imported = (await import(moduleName));
+            ImapFlow = imported.ImapFlow;
+            if (!ImapFlow)
+                throw new Error("imapflow did not export ImapFlow");
+        }
+        catch {
+            throw new InternalError("IMAP reads require the optional 'imapflow' package; install it to use this surface");
+        }
+        const config = this.config;
+        if (!config.host)
+            throw new InternalError("IMAP requires a host");
+        const client = new ImapFlow({
+            host: config.host,
+            port: config.port ?? 993,
+            secure: config.secure ?? true,
+            auth: {
+                user: config.username,
+                pass: config.password,
+            },
+        });
+        const messages = [];
+        await client.connect();
+        try {
+            const lock = await client.getMailboxLock("INBOX");
+            try {
+                const limit = query.limit ?? 25;
+                for await (const message of client.fetch(`${Math.max(1, limit)}:*`, { envelope: true, source: false }, { uid: false })) {
+                    messages.push(message);
+                    if (messages.length >= limit)
+                        break;
+                }
+            }
+            finally {
+                lock.release();
+            }
+        }
+        finally {
+            await client.logout().catch(() => undefined);
+        }
+        return messages;
+    }
+}
+//# sourceMappingURL=EmailService.js.map