@decaf-ts/integrations 0.11.0 → 0.12.0

package/lib/cjs/comms/email/smtp.cjs

@@ -0,0 +1,204 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SmtpClient = void 0;
+/**
+ * @module integrations/comms/email/smtp
+ * @summary SMTP client used by the Email service for direct SMTP delivery.
+ * @description Delegates the SMTP protocol to the optional `nodemailer`
+ * library (the same library n8n uses) instead of hand-rolling the wire
+ * protocol: the transport performs EHLO, STARTTLS/implicit TLS, AUTH LOGIN,
+ * and the `MAIL FROM`/`RCPT TO`/`DATA` transaction for a pre-built raw MIME
+ * message. The public {@link SmtpClient} surface is unchanged. Envelope
+ * addresses are validated through {@link assertEmailAddress} (decaf
+ * `BadRequestError`s) before they reach any SMTP command, and credentials are
+ * never sent over a plaintext session unless `SmtpConfig.allowPlaintextAuth`
+ * opts in.
+ */
+const db_decorators_1 = require("@decaf-ts/db-decorators");
+const mime_js_1 = require("./mime.cjs");
+/**
+ * @description SMTP client for raw MIME delivery
+ * @summary Connects and authenticates through a nodemailer SMTP transport
+ * (implicit TLS on `secure`, STARTTLS otherwise), then delivers a pre-built
+ * message with the envelope sender/recipients and the raw RFC 5322 source.
+ * Credentials are never sent over a plaintext session unless
+ * `allowPlaintextAuth` is set, and every envelope address is validated before
+ * it reaches the transport.
+ * @category Comms
+ * @memberOf module:integrations/comms/email/smtp
+ * @example
+ * ```ts
+ * import { SmtpClient, buildEmail } from "@decaf-ts/integrations/comms/email";
+ *
+ * const client = new SmtpClient({
+ *   host: "smtp.example.com",
+ *   port: 587,
+ *   username: "noreply@example.com",
+ *   password: process.env.SMTP_PASSWORD,
+ * });
+ * await client.connect();
+ * const mail = buildEmail({
+ *   from: "noreply@example.com",
+ *   to: ["ops@example.com"],
+ *   subject: "Nightly report",
+ *   text: "All systems nominal.",
+ * });
+ * await client.send(mail.from, mail.recipients, mail.raw);
+ * await client.close();
+ * ```
+ */
+class SmtpClient {
+    /**
+     * @description Creates an SMTP client
+     * @summary Stores the config; the nodemailer transport is only created and
+     * verified by {@link SmtpClient.connect}.
+     * @param config - Server address, optional credentials, and TLS/timeout options
+     */
+    constructor(config) {
+        this.config = config;
+    }
+    transportOptions() {
+        const secure = this.config.secure ?? false;
+        const hasCredentials = Boolean(this.config.username && this.config.password);
+        const timeout = this.config.timeout ?? 30000;
+        return {
+            host: this.config.host,
+            port: this.config.port ?? (secure ? 465 : 587),
+            secure,
+            name: this.config.clientHostname ?? "as-graph",
+            requireTLS: !secure && hasCredentials && !this.config.allowPlaintextAuth,
+            auth: hasCredentials
+                ? {
+                    user: this.config.username,
+                    pass: this.config.password,
+                    method: "LOGIN",
+                }
+                : undefined,
+            tls: this.config.allowUnauthorizedCerts
+                ? { rejectUnauthorized: false }
+                : undefined,
+            connectionTimeout: timeout,
+            greetingTimeout: timeout,
+            socketTimeout: timeout,
+        };
+    }
+    transportError(prefix, error) {
+        if (error instanceof db_decorators_1.InternalError)
+            return error;
+        return new db_decorators_1.InternalError(`${prefix}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    /**
+     * @description Opens the SMTP session
+     * @summary Lazily loads the optional `nodemailer` peer, builds the SMTP
+     * transport for the configured host/credentials, and verifies it
+     * (`EHLO` + TLS upgrade + `AUTH LOGIN` when credentials are configured).
+     * Authentication fails closed: with credentials configured and no encrypted
+     * session, the transport requires STARTTLS and verification fails unless
+     * `allowPlaintextAuth` was set on the config.
+     * @throws {InternalError} when `nodemailer` is not installed, or on
+     * connection, TLS, or auth failures
+     */
+    async connect() {
+        if (this.transporter)
+            return;
+        const moduleName = "nodemailer";
+        let module;
+        try {
+            module = (await Promise.resolve(`${moduleName}`).then(s => __importStar(require(s))));
+        }
+        catch {
+            throw new db_decorators_1.InternalError("SMTP delivery requires the optional 'nodemailer' package; install it to use this surface");
+        }
+        if (typeof module.createTransport !== "function") {
+            throw new db_decorators_1.InternalError("The optional 'nodemailer' package did not export createTransport");
+        }
+        const transporter = module.createTransport(this.transportOptions(), {
+            disableFileAccess: true,
+            disableUrlAccess: true,
+        });
+        try {
+            await transporter.verify();
+        }
+        catch (error) {
+            transporter.close();
+            throw this.transportError("SMTP connection failed", error);
+        }
+        this.transporter = transporter;
+    }
+    /**
+     * @description Delivers a raw message over the established session
+     * @summary Validates the envelope, then hands the sender, recipients, and
+     * raw RFC 5322 source to nodemailer's `sendMail` (the transport performs
+     * queueing, dot-stuffing, and CRLF normalization).
+     * @param from - Envelope sender address
+     * @param recipients - Envelope recipient addresses
+     * @param raw - Raw RFC 5322 message text
+     * @throws {InternalError} when not connected or the server rejects delivery
+     * @throws {BadRequestError} when the envelope sender or a recipient is not an allowlisted mailbox
+     */
+    async send(from, recipients, raw) {
+        if (!this.transporter) {
+            throw new db_decorators_1.InternalError("SMTP client is not connected");
+        }
+        const sender = (0, mime_js_1.assertEmailAddress)(from, "envelope sender");
+        const envelopes = recipients.map((recipient) => (0, mime_js_1.assertEmailAddress)(recipient, "envelope recipient"));
+        const message = {
+            envelope: { from: sender, to: envelopes },
+            raw,
+        };
+        try {
+            await this.transporter.sendMail(message);
+        }
+        catch (error) {
+            throw this.transportError("SMTP delivery failed", error);
+        }
+    }
+    /**
+     * @description Closes the session gracefully
+     * @summary Closes the nodemailer transport, ignoring shutdown failures.
+     */
+    async close() {
+        try {
+            this.transporter?.close();
+        }
+        finally {
+            this.transporter = undefined;
+        }
+    }
+}
+exports.SmtpClient = SmtpClient;
+//# sourceMappingURL=smtp.js.map
+//# sourceMappingURL=smtp.cjs.map

package/lib/cjs/comms/email/smtp.cjs.map

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

package/lib/cjs/comms/environment.cjs

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommsEnvironment = void 0;
+const logging_1 = require("@decaf-ts/logging");
+/**
+ * @description Accumulated comms environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `CommsEnvironmentShape` contract. Comms services read their provider slice
+ * (e.g. `CommsEnvironment.comms.slack`) inside `configFromEnvironment()` and
+ * translate it into an `HttpApiServiceConfig`-derived config. Credentials come
+ * from environment variables; for as-graph node usage those are provided as
+ * `GRAPH_CREDENTIAL_*` values (placeholders in this example).
+ * @example
+ * ```ts
+ * import { SlackService } from "@decaf-ts/integrations/comms/slack";
+ *
+ * // with comms.slack.token / comms.slack.baseUrl configured in the environment
+ * const slack = new SlackService();
+ * await slack.initialize();
+ * ```
+ * @constant {LoggedEnvironment} CommsEnvironment
+ * @memberOf module:integrations/comms/environment
+ */
+exports.CommsEnvironment = logging_1.LoggedEnvironment.accumulate({
+    comms: {
+        slack: {
+            token: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+        telegram: {
+            token: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+        teams: {
+            token: "",
+            webhookUrl: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+        email: {
+            provider: "",
+            host: "",
+            port: undefined,
+            secure: undefined,
+            username: "",
+            password: "",
+            from: "",
+            token: "",
+            graphBaseUrl: "",
+            timeout: undefined,
+        },
+        gmail: {
+            token: "",
+            userId: "",
+            baseUrl: "",
+            timeout: undefined,
+        },
+    },
+});
+//# sourceMappingURL=environment.js.map
+//# sourceMappingURL=environment.cjs.map

package/lib/cjs/comms/environment.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms/environment.cjs","sourceRoot":"","sources":["comms/environment.js"],"names":[],"mappings":";;;AAAA,+CAAsD;AACtD;;;;;;;;;;;;;;;;;;GAkBG;AACU,QAAA,gBAAgB,GAAG,2BAAiB,CAAC,UAAU,CAAC;IACzD,KAAK,EAAE;QACH,KAAK,EAAE;YACH,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAAS;SACrB;QACD,QAAQ,EAAE;YACN,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAAS;SACrB;QACD,KAAK,EAAE;YACH,KAAK,EAAE,EAAE;YACT,UAAU,EAAE,EAAE;YACd,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAAS;SACrB;QACD,KAAK,EAAE;YACH,QAAQ,EAAE,EAAE;YACZ,IAAI,EAAE,EAAE;YACR,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,SAAS;YACjB,QAAQ,EAAE,EAAE;YACZ,QAAQ,EAAE,EAAE;YACZ,IAAI,EAAE,EAAE;YACR,KAAK,EAAE,EAAE;YACT,YAAY,EAAE,EAAE;YAChB,OAAO,EAAE,SAAS;SACrB;QACD,KAAK,EAAE;YACH,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,EAAE;YACV,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,SAAS;SACrB;KACJ;CACJ,CAAC,CAAC;AACH,uCAAuC"}

package/lib/cjs/comms/gmail/GmailService.cjs

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GmailService = void 0;
+/**
+ * @module integrations/comms/gmail/service
+ * @summary Gmail API integration service for sending and listing messages.
+ * @description Exposes the Gmail REST API (`users.messages.send`,
+ * `users.messages.list`, `users.messages.get`, `users.labels.list`) as an
+ * undecorated client-based service built on {@link HttpApiService}.
+ * Message sending reuses the shared MIME builder from the email integration
+ * (`buildEmail`) and posts the raw MIME message as base64url. Configuration
+ * comes from an explicit `GmailServiceConfig` or the `comms.gmail` environment
+ * slice, and failures are mapped to decaf errors via {@link httpError}.
+ */
+const db_decorators_1 = require("@decaf-ts/db-decorators");
+const environment_js_1 = require("./../environment.cjs");
+const environmentValue_js_1 = require("./../../shared/environmentValue.cjs");
+const index_js_1 = require("./../../shared/http/index.cjs");
+const mime_js_1 = require("./../email/mime.cjs");
+/**
+ * @description Gmail API integration service
+ * @summary An undecorated HTTP service for sending MIME-built
+ * emails, listing messages with Gmail query syntax and page tokens, fetching
+ * a single message in a chosen format, and listing labels. All operations
+ * require an OAuth token (`requireToken()`) and operate on the configured
+ * `userId` mailbox (default `"me"`); transport failures are mapped to decaf
+ * errors via {@link httpError}.
+ * @class GmailService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { GmailService } from "@decaf-ts/integrations/comms/gmail";
+ *
+ * const gmail = new GmailService();
+ * await gmail.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_GMAIL_TOKEN,
+ * });
+ * await gmail.send({
+ *   from: "bot@example.com",
+ *   to: "ops@example.com",
+ *   subject: "Deploy",
+ *   text: "Release 1.2.0 is live",
+ * });
+ * ```
+ * @memberOf module:integrations/comms/gmail/service
+ */
+class GmailService extends index_js_1.HttpApiService {
+    constructor() {
+        super(...arguments);
+        /**
+         * @description The provider name used in error messages
+         */
+        this.serviceName = "Gmail";
+    }
+    /**
+     * @description The Gmail REST API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://gmail.googleapis.com/gmail/v1"`.
+     */
+    defaultBaseUrl() {
+        return "https://gmail.googleapis.com/gmail/v1";
+    }
+    /**
+     * @description Builds the Gmail OAuth bearer authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries a token, and no headers otherwise.
+     * @param {GmailServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    authHeaders(config) {
+        return config.token ? { Authorization: `Bearer ${config.token}` } : {};
+    }
+    /**
+     * @description Reads the Gmail credentials and defaults from the environment
+     * @summary Reads the `comms.gmail` environment slice and returns a partial
+     * config when a token is configured, `undefined` otherwise. Values pass
+     * through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<GmailServiceConfig> | undefined} A partial config, or `undefined` when no Gmail token is configured.
+     */
+    configFromEnvironment() {
+        const env = environment_js_1.CommsEnvironment.comms.gmail;
+        const token = (0, environmentValue_js_1.envString)(env?.token);
+        if (!token)
+            return undefined;
+        return {
+            token,
+            userId: (0, environmentValue_js_1.envString)(env.userId),
+            baseUrl: (0, environmentValue_js_1.envString)(env.baseUrl),
+            timeout: (0, environmentValue_js_1.envNumber)(env.timeout),
+        };
+    }
+    /**
+     * @description Builds the mailbox-scoped API path
+     * @summary Returns `/users/<userId>` with the configured `userId` (or
+     * `"me"` when unset) URL-encoded; all message and label operations are
+     * relative to this path.
+     * @returns {string} The URL-encoded mailbox path.
+     */
+    userPath() {
+        return `/users/${encodeURIComponent(this.config.userId ?? "me")}`;
+    }
+    /**
+     * @description Sends an email through the Gmail API
+     * @summary Builds a raw MIME message from the input with the shared email
+     * MIME builder (`buildEmail`), base64url-encodes it, and `POST`s it to
+     * `users.messages.send`. Requires a token and a `from` sender address.
+     * @param {EmailMessageInput} input - The message envelope and body (`from`, `to`, `subject`, and optional `cc`/`bcc`/`text`/`html`/`replyTo`/`attachments`).
+     * @returns {Promise<GmailSendResult>} Gmail's identifiers for the sent message.
+     * @throws {InternalError} When no token is configured or the sender address is missing.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status (e.g. invalid recipients).
+     */
+    async send(input) {
+        this.requireToken();
+        if (!input.from) {
+            throw new db_decorators_1.InternalError("Gmail send requires a sender address");
+        }
+        const built = (0, mime_js_1.buildEmail)(input);
+        try {
+            const response = await this.client.post(`${this.userPath()}/messages/send`, {
+                raw: Buffer.from(built.raw, "utf8").toString("base64url"),
+            });
+            return {
+                id: String(response.data.id ?? built.messageId),
+                threadId: response.data.threadId,
+                labelIds: response.data.labelIds,
+            };
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Gmail", "send message", error);
+        }
+    }
+    /**
+     * @description Lists mailbox messages with Gmail query paging
+     * @summary `GET`s `users.messages.list` with an optional Gmail `query`
+     * (`q` parameter, e.g. `"from:user@example.com is:unread"`), a page size
+     * (default `25`), a `pageToken` from the previous page, and `labelIds`
+     * filtering. Returns the message references and the `nextPageToken` to pass
+     * back as `pageToken` for the next page.
+     * @param {object} [options] - Query and paging options.
+     * @param {string} [options.query] - Gmail search query (`q` parameter).
+     * @param {number} [options.maxResults] - Page size; defaults to `25`.
+     * @param {string} [options.pageToken] - The `nextPageToken` from the previous page.
+     * @param {string[]} [options.labelIds] - Label IDs the messages must carry.
+     * @returns {Promise<GmailListResult>} One page of message references with the next page token when more pages exist.
+     * @throws {InternalError} When no token is configured.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status (e.g. invalid query).
+     * @example
+     * ```ts
+     * let pageToken: string | undefined;
+     * do {
+     *   const page = await gmail.listMessages({
+     *     query: "is:unread",
+     *     maxResults: 100,
+     *     pageToken,
+     *   });
+     *   console.log(page.messages);
+     *   pageToken = page.nextPageToken;
+     * } while (pageToken);
+     * ```
+     */
+    async listMessages(options = {}) {
+        this.requireToken();
+        try {
+            const response = await this.client.get(`${this.userPath()}/messages`, {
+                params: {
+                    q: options.query,
+                    maxResults: options.maxResults ?? 25,
+                    pageToken: options.pageToken,
+                    labelIds: options.labelIds,
+                },
+            });
+            return {
+                messages: response.data.messages ?? [],
+                nextPageToken: response.data.nextPageToken,
+                resultSizeEstimate: response.data.resultSizeEstimate,
+            };
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Gmail", "list messages", error);
+        }
+    }
+    /**
+     * @description Fetches a single Gmail message
+     * @summary `GET`s `users.messages.get` for the given message ID with the
+     * requested `format`. With `"full"` (the default) the payload includes the
+     * parsed body parts; `"metadata"` limits it to headers and labels,
+     * `"minimal"` to identifiers only, and `"raw"` returns the raw MIME string.
+     * @param {string} id - The Gmail message ID.
+     * @param {"full" | "metadata" | "minimal" | "raw"} [format] - The message format to request; defaults to `"full"`.
+     * @returns {Promise<Record<string, unknown>>} The raw Gmail message payload in the requested format.
+     * @throws {InternalError} When no token is configured or the message ID is empty.
+     * @throws {NotFoundError} When the message does not exist (HTTP 404).
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status.
+     */
+    async getMessage(id, format = "full") {
+        this.requireToken();
+        if (!id)
+            throw new db_decorators_1.InternalError("Gmail getMessage requires a message ID");
+        try {
+            const response = await this.client.get(`${this.userPath()}/messages/${encodeURIComponent(id)}`, { params: { format } });
+            return response.data;
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Gmail", "get message", error);
+        }
+    }
+    /**
+     * @description Lists the mailbox's Gmail labels
+     * @summary `GET`s `users.labels.list` and returns the raw label payloads
+     * (including `id`, `name`, and `type`).
+     * @returns {Promise<Array<Record<string, unknown>>>} The raw Gmail label payloads.
+     * @throws {InternalError} When no token is configured.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When Gmail answers with HTTP 409.
+     * @throws {BadRequestError} When Gmail answers with any other HTTP error status.
+     */
+    async listLabels() {
+        this.requireToken();
+        try {
+            const response = await this.client.get(`${this.userPath()}/labels`);
+            return response.data.labels ?? [];
+        }
+        catch (error) {
+            throw (0, index_js_1.httpError)("Gmail", "list labels", error);
+        }
+    }
+}
+exports.GmailService = GmailService;
+//# sourceMappingURL=GmailService.js.map
+//# sourceMappingURL=GmailService.cjs.map

package/lib/cjs/comms/gmail/GmailService.cjs.map

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

package/lib/cjs/comms/gmail/index.cjs

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @module integrations/comms/gmail
+ * @summary Gmail service (REST v1 message send/list/get and label listing).
+ * @description Re-exports the Gmail client-based service and its types.
+ */
+__exportStar(require("./GmailService.cjs"), exports);
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map

package/lib/cjs/comms/gmail/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms/gmail/index.cjs","sourceRoot":"","sources":["comms/gmail/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;GAIG;AACH,oDAAkC;AAClC,iCAAiC"}

package/lib/cjs/comms/index.cjs

@@ -0,0 +1,31 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @module integrations/comms
+ * @summary Comms integration services (Slack, Telegram, Teams, Gmail, Email).
+ * @description Re-exports the messaging/email services, their per-service
+ * modules, and the shared `comms` environment slice. Each sub-module is also
+ * available through its own package subpath export.
+ */
+__exportStar(require("./email/index.cjs"), exports);
+__exportStar(require("./gmail/index.cjs"), exports);
+__exportStar(require("./slack/index.cjs"), exports);
+__exportStar(require("./teams/index.cjs"), exports);
+__exportStar(require("./telegram/index.cjs"), exports);
+__exportStar(require("./environment.cjs"), exports);
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map

package/lib/cjs/comms/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"comms/index.cjs","sourceRoot":"","sources":["comms/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;GAMG;AACH,mDAAiC;AACjC,mDAAiC;AACjC,mDAAiC;AACjC,mDAAiC;AACjC,sDAAoC;AACpC,mDAAiC;AACjC,iCAAiC"}