@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/esm/comms/gmail/GmailService.js

@@ -0,0 +1,230 @@
+/**
+ * @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}.
+ */
+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";
+import { buildEmail } from "./../email/mime.js";
+/**
+ * @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
+ */
+export class GmailService extends 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 = CommsEnvironment.comms.gmail;
+        const token = envString(env?.token);
+        if (!token)
+            return undefined;
+        return {
+            token,
+            userId: envString(env.userId),
+            baseUrl: envString(env.baseUrl),
+            timeout: 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 InternalError("Gmail send requires a sender address");
+        }
+        const built = 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 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 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 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 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 httpError("Gmail", "list labels", error);
+        }
+    }
+}
+//# sourceMappingURL=GmailService.js.map

package/lib/esm/comms/gmail/GmailService.js.map

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

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

@@ -0,0 +1,7 @@
+/**
+ * @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.
+ */
+export * from "./GmailService.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/comms/gmail/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,kCAA+B"}

package/lib/esm/comms/index.js

@@ -0,0 +1,14 @@
+/**
+ * @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.
+ */
+export * from "./email/index.js";
+export * from "./gmail/index.js";
+export * from "./slack/index.js";
+export * from "./teams/index.js";
+export * from "./telegram/index.js";
+export * from "./environment.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/comms/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,iCAAwB;AACxB,iCAAwB;AACxB,iCAAwB;AACxB,iCAAwB;AACxB,oCAA2B;AAC3B,iCAA8B"}

package/lib/esm/comms/slack/SlackService.js

@@ -0,0 +1,259 @@
+/**
+ * @module integrations/comms/slack/service
+ * @summary Slack Web API integration service for posting messages and reading conversations and users.
+ * @description Exposes the Slack Web API (`chat.postMessage`, `conversations.*`, `users.info`)
+ * as an undecorated client-based service built on {@link HttpApiService}.
+ * Configuration comes from an explicit `SlackServiceConfig` or the `comms.slack`
+ * environment slice; every response is normalized and failures are mapped to decaf
+ * errors via {@link httpError}.
+ */
+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";
+/**
+ * @description Slack Web API integration service
+ * @summary An undecorated HTTP service for posting messages,
+ * listing conversations with cursor paging, fetching a single conversation,
+ * and looking up users. The Slack Bot token is sent as a bearer token, every
+ * call requires it (`requireToken()`), non-`ok` Slack responses raise
+ * `InternalError`, and transport failures are mapped to decaf errors via
+ * {@link httpError}.
+ * @class SlackService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { SlackService } from "@decaf-ts/integrations/comms/slack";
+ *
+ * const slack = new SlackService();
+ * await slack.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_SLACK_TOKEN,
+ * });
+ * await slack.postMessage({
+ *   channel: "#general",
+ *   text: "Deployment finished",
+ * });
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as SlackService
+ *   participant Slack as Slack Web API
+ *   Caller->>Service: postMessage(input)
+ *   activate Service
+ *   Service->>Service: requireToken()
+ *   Service->>Slack: POST /chat.postMessage
+ *   activate Slack
+ *   Slack-->>Service: { ok, channel, ts }
+ *   deactivate Slack
+ *   alt ok
+ *     Service-->>Caller: SlackPostMessageResult
+ *   else error
+ *     Service--xCaller: InternalError / mapped decaf error
+ *   end
+ *   deactivate Service
+ * @memberOf module:integrations/comms/slack/service
+ */
+export class SlackService extends HttpApiService {
+    constructor() {
+        super(...arguments);
+        /**
+         * @description The provider name used in error messages
+         */
+        this.serviceName = "Slack";
+    }
+    /**
+     * @description The Slack Web API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://slack.com/api"`.
+     */
+    defaultBaseUrl() {
+        return "https://slack.com/api";
+    }
+    /**
+     * @description Builds the Slack bearer authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries a token, and no headers otherwise.
+     * @param {SlackServiceConfig} 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 Slack credentials and defaults from the environment
+     * @summary Reads the `comms.slack` 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<SlackServiceConfig> | undefined} A partial config, or `undefined` when no Slack token is configured.
+     */
+    configFromEnvironment() {
+        const env = CommsEnvironment.comms.slack;
+        const token = envString(env?.token);
+        if (!token)
+            return undefined;
+        return {
+            token,
+            baseUrl: envString(env.baseUrl),
+            timeout: envNumber(env.timeout),
+        };
+    }
+    /**
+     * @description Posts a request to a Slack Web API method
+     * @summary Shared request path for all Slack operations: asserts a token is
+     * configured, `POST`s the payload to `/<method>`, rejects non-`ok` Slack
+     * responses with an `InternalError`, and maps transport failures through
+     * {@link httpError}.
+     * @template T - The expected Slack response shape, extending `SlackApiResponse`.
+     * @param {string} method - The Slack Web API method name (e.g. `"chat.postMessage"`).
+     * @param {Record<string, unknown>} payload - The JSON body for the method.
+     * @returns {Promise<T>} The parsed Slack response payload.
+     * @throws {InternalError} When no token is configured or Slack answers with `ok: false`.
+     * @throws {NotFoundError} When Slack answers with HTTP 404.
+     * @throws {ConflictError} When Slack answers with HTTP 409.
+     * @throws {BadRequestError} When Slack answers with any other HTTP error status.
+     */
+    async call(method, payload) {
+        this.requireToken();
+        try {
+            const response = await this.client.post(`/${method}`, payload);
+            const data = response.data;
+            if (!data || data.ok !== true) {
+                throw new InternalError(`Slack API ${method} failed: ${data?.error ?? "unknown error"}`);
+            }
+            return data;
+        }
+        catch (error) {
+            throw httpError("Slack", `API ${method}`, error);
+        }
+    }
+    /**
+     * @description Posts a message to a Slack channel or thread
+     * @summary Sends the input to Slack's `chat.postMessage` method and returns
+     * the destination channel and message timestamp; use the returned `ts` as
+     * `threadTs` to reply in the same thread. Provide `blocks` for Block Kit
+     * layouts (with `text` as the fallback), or plain text alone.
+     * @param {SlackPostMessageInput} input - The message destination and content.
+     * @returns {Promise<SlackPostMessageResult>} The posted message's channel, timestamp, text, and raw payload.
+     * @throws {InternalError} When no token is configured or Slack rejects the message.
+     * @throws {NotFoundError} When the channel cannot be found (HTTP 404).
+     * @throws {ConflictError} When Slack answers with HTTP 409.
+     * @throws {BadRequestError} When Slack answers with any other HTTP error status.
+     * @example
+     * ```ts
+     * await slack.postMessage({
+     *   channel: "#deploys",
+     *   text: "Release 1.2.0 is live",
+     *   unfurlLinks: false,
+     * });
+     * ```
+     */
+    async postMessage(input) {
+        const data = await this.call("chat.postMessage", {
+            channel: input.channel,
+            text: input.text,
+            blocks: input.blocks,
+            thread_ts: input.threadTs,
+            reply_broadcast: input.replyBroadcast,
+            unfurl_links: input.unfurlLinks,
+            unfurl_media: input.unfurlMedia,
+        });
+        return {
+            channel: data.channel,
+            ts: data.ts,
+            text: data.text,
+            message: data.message,
+        };
+    }
+    /**
+     * @description Lists Slack conversations with cursor paging
+     * @summary Calls `conversations.list` with a page size (default `100`),
+     * conversation `types` (default public and private channels), and archived
+     * exclusion (default `true`), returning normalized channels and the
+     * `nextCursor` to pass back as `cursor` for the next page.
+     * @param {object} [options] - Paging and filter options.
+     * @param {number} [options.limit] - Page size; defaults to `100`.
+     * @param {string} [options.cursor] - The `nextCursor` from the previous page.
+     * @param {string} [options.types] - Comma-separated conversation types (e.g. `"public_channel,private_channel"`); defaults to `"public_channel,private_channel"`.
+     * @param {boolean} [options.excludeArchived] - Whether archived channels are excluded; defaults to `true`.
+     * @returns {Promise<{channels: SlackChannel[], nextCursor?: string}>} The page of channels and the cursor for the next page, when more pages exist.
+     * @throws {InternalError} When no token is configured or Slack rejects the call.
+     * @throws {NotFoundError} When Slack answers with HTTP 404.
+     * @throws {ConflictError} When Slack answers with HTTP 409.
+     * @throws {BadRequestError} When Slack answers with any other HTTP error status.
+     * @example
+     * ```ts
+     * let cursor: string | undefined;
+     * do {
+     *   const page = await slack.listConversations({ limit: 200, cursor });
+     *   console.log(page.channels.map((channel) => channel.name));
+     *   cursor = page.nextCursor;
+     * } while (cursor);
+     * ```
+     */
+    async listConversations(options = {}) {
+        const data = await this.call("conversations.list", {
+            limit: options.limit ?? 100,
+            cursor: options.cursor,
+            types: options.types ?? "public_channel,private_channel",
+            exclude_archived: options.excludeArchived ?? true,
+        });
+        return {
+            channels: (data.channels ?? []).map((channel) => ({
+                id: String(channel["id"] ?? ""),
+                name: envString(channel["name"]),
+                isPrivate: channel["is_private"] === true,
+                isArchived: channel["is_archived"] === true,
+                memberCount: typeof channel["num_members"] === "number"
+                    ? channel["num_members"]
+                    : undefined,
+                topic: channel["topic"]?.value,
+                purpose: channel["purpose"]?.value,
+            })),
+            nextCursor: envString(data.response_metadata?.next_cursor),
+        };
+    }
+    /**
+     * @description Fetches a single Slack conversation
+     * @summary Calls `conversations.info` for the given channel ID (or
+     * `#name`) and returns the normalized channel descriptor.
+     * @param {string} channel - The channel ID or `#name` to look up.
+     * @returns {Promise<SlackChannel>} The normalized conversation descriptor.
+     * @throws {InternalError} When no token is configured or Slack rejects the call.
+     * @throws {NotFoundError} When the channel does not exist (HTTP 404).
+     * @throws {ConflictError} When Slack answers with HTTP 409.
+     * @throws {BadRequestError} When Slack answers with any other HTTP error status.
+     */
+    async getConversation(channel) {
+        const data = await this.call("conversations.info", { channel });
+        const found = data.channel ?? {};
+        return {
+            id: String(found["id"] ?? channel),
+            name: envString(found["name"]),
+            isPrivate: found["is_private"] === true,
+            isArchived: found["is_archived"] === true,
+            memberCount: typeof found["num_members"] === "number"
+                ? found["num_members"]
+                : undefined,
+            topic: found["topic"]?.value,
+            purpose: found["purpose"]?.value,
+        };
+    }
+    /**
+     * @description Fetches a Slack user profile
+     * @summary Calls `users.info` for the given user ID and returns the raw
+     * user payload, or `undefined` when Slack reports no user.
+     * @param {string} userId - The Slack user ID to look up (e.g. `"U12345678"`).
+     * @returns {Promise<Record<string, unknown> | undefined>} The raw user payload, or `undefined` when the user is not found.
+     * @throws {InternalError} When no token is configured or Slack rejects the call.
+     * @throws {NotFoundError} When the user does not exist (HTTP 404).
+     * @throws {ConflictError} When Slack answers with HTTP 409.
+     * @throws {BadRequestError} When Slack answers with any other HTTP error status.
+     */
+    async getUser(userId) {
+        const data = await this.call("users.info", { user: userId });
+        return data.user;
+    }
+}
+//# sourceMappingURL=SlackService.js.map

package/lib/esm/comms/slack/SlackService.js.map

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

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

@@ -0,0 +1,7 @@
+/**
+ * @module integrations/comms/slack
+ * @summary Slack Web API service (posting, conversations, users).
+ * @description Re-exports the Slack client-based service and its types.
+ */
+export * from "./SlackService.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/comms/slack/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,kCAA+B"}