@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/types/comms/slack/SlackService.d.mts

@@ -0,0 +1,259 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+/**
+ * @description Configuration for the Slack service
+ * @summary Extends {@link HttpApiServiceConfig} with the Slack Bot User OAuth
+ * token used as a bearer token. When omitted, the `comms.slack` environment
+ * slice supplies the token (and optional `baseUrl`/`timeout`).
+ * @category Comms
+ * @memberOf module:integrations/comms/slack/service
+ */
+export interface SlackServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Slack Bot User OAuth token
+     * @summary Sent as `Authorization: Bearer <token>` with every API call.
+     */
+    token?: string;
+}
+/**
+ * @description Input for posting a message to a Slack channel or thread
+ * @summary Carries the destination `channel` (ID or `#channel`/`@user` style
+ * name), the plain-text fallback `text`, optional Block Kit `blocks`, and the
+ * posting options (thread reply, broadcast reply, unfurling).
+ * @category Comms
+ * @memberOf module:integrations/comms/slack/service
+ */
+export interface SlackPostMessageInput {
+    /**
+     * @description Destination channel ID, `#channel`, or `@user` mention
+     */
+    channel: string;
+    /**
+     * @description Plain-text message body (also the fallback for `blocks`)
+     */
+    text: string;
+    /**
+     * @description Optional Block Kit layout blocks replacing plain text
+     */
+    blocks?: unknown[];
+    /**
+     * @description Message timestamp to reply in-thread to
+     */
+    threadTs?: string;
+    /**
+     * @description Whether to also notify the channel when replying in a thread
+     */
+    replyBroadcast?: boolean;
+    /**
+     * @description Whether link previews are enabled
+     */
+    unfurlLinks?: boolean;
+    /**
+     * @description Whether media unfurls are enabled
+     */
+    unfurlMedia?: boolean;
+}
+/**
+ * @description Result of a posted Slack message
+ * @summary Echoes the destination `channel` and the message timestamp `ts`
+ * (usable as `threadTs` for follow-up replies), with the posted `text` and the
+ * raw `message` payload when Slack returns them.
+ * @category Comms
+ * @memberOf module:integrations/comms/slack/service
+ */
+export interface SlackPostMessageResult {
+    channel: string;
+    ts: string;
+    text?: string;
+    message?: unknown;
+}
+/**
+ * @description Normalized Slack conversation (channel) descriptor
+ * @summary Maps the raw `conversations.*` payload onto camelCase fields:
+ * identity (`id`, `name`), visibility (`isPrivate`, `isArchived`),
+ * `memberCount`, and topic/purpose summaries.
+ * @category Comms
+ * @memberOf module:integrations/comms/slack/service
+ */
+export interface SlackChannel {
+    id: string;
+    name?: string;
+    isPrivate?: boolean;
+    isArchived?: boolean;
+    memberCount?: number;
+    topic?: string;
+    purpose?: string;
+}
+interface SlackApiResponse {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * @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 declare class SlackService extends HttpApiService<SlackServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Slack";
+    /**
+     * @description The Slack Web API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://slack.com/api"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @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).
+     */
+    protected authHeaders(config: SlackServiceConfig): Record<string, string>;
+    /**
+     * @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.
+     */
+    protected configFromEnvironment(): Partial<SlackServiceConfig> | undefined;
+    /**
+     * @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.
+     */
+    protected call<T extends SlackApiResponse>(method: string, payload: Record<string, unknown>): Promise<T>;
+    /**
+     * @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,
+     * });
+     * ```
+     */
+    postMessage(input: SlackPostMessageInput): Promise<SlackPostMessageResult>;
+    /**
+     * @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);
+     * ```
+     */
+    listConversations(options?: {
+        limit?: number;
+        cursor?: string;
+        types?: string;
+        excludeArchived?: boolean;
+    }): Promise<{
+        channels: SlackChannel[];
+        nextCursor?: string;
+    }>;
+    /**
+     * @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.
+     */
+    getConversation(channel: string): Promise<SlackChannel>;
+    /**
+     * @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.
+     */
+    getUser(userId: string): Promise<Record<string, unknown> | undefined>;
+}
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * @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.d.cts";

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

@@ -0,0 +1,6 @@
+/**
+ * @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.d.mts";

package/lib/types/comms/teams/TeamsService.d.cts

@@ -0,0 +1,172 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+/**
+ * @description Configuration for the Teams service
+ * @summary Extends {@link HttpApiServiceConfig} with the Microsoft Graph
+ * access token (required for channel messaging and listings, optional when
+ * only webhooks are used) and the incoming-webhook URL. When omitted, the
+ * `comms.teams` environment slice supplies both (and optional
+ * `baseUrl`/`timeout`).
+ * @category Comms
+ * @memberOf module:integrations/comms/teams/service
+ */
+export interface TeamsServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Microsoft Graph access token
+     * @summary Sent as `Authorization: Bearer <token>` for Graph requests.
+     */
+    token?: string;
+    /**
+     * @description Incoming webhook URL for `sendWebhook`
+     * @summary Typically an Office 365 connector URL; required only for webhook delivery.
+     */
+    webhookUrl?: string;
+}
+/**
+ * @description Input for Teams incoming-webhook delivery
+ * @summary Carries the plain-text `text`, an optional card `title`, and
+ * whether the text is rendered as markdown (default `true`). Delivered as an
+ * Office 365 `MessageCard` to the configured webhook URL.
+ * @category Comms
+ * @memberOf module:integrations/comms/teams/service
+ */
+export interface TeamsWebhookMessage {
+    /**
+     * @description Message body text
+     */
+    text: string;
+    /**
+     * @description Optional card title
+     */
+    title?: string;
+    /**
+     * @description Whether `text` is rendered as markdown; defaults to `true`
+     */
+    markdown?: boolean;
+}
+/**
+ * @description Input for sending a message into a Teams channel via Microsoft Graph
+ * @summary Carries the target `teamId` and `channelId`, the message
+ * `content`, and its content type (`text` by default, or `html`).
+ * @category Comms
+ * @memberOf module:integrations/comms/teams/service
+ */
+export interface TeamsChannelMessage {
+    teamId: string;
+    channelId: string;
+    content: string;
+    contentType?: "text" | "html";
+}
+/**
+ * @description Microsoft Teams integration service
+ * @summary An undecorated HTTP service combining incoming-webhook
+ * delivery (needs only `webhookUrl`) with Microsoft Graph operations — channel
+ * messaging, team listing, and channel listing (need a Graph `token`).
+ * Webhook delivery posts an Office 365 `MessageCard` directly to the
+ * configured URL; Graph operations go through the service client with bearer
+ * auth, require a token (`requireToken()`), and map transport failures to
+ * decaf errors via {@link httpError}.
+ * @class TeamsService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { TeamsService } from "@decaf-ts/integrations/comms/teams";
+ *
+ * const teams = new TeamsService();
+ * await teams.initialize({
+ *   webhookUrl: process.env.GRAPH_CREDENTIAL_TEAMS_WEBHOOK_URL,
+ *   token: process.env.GRAPH_CREDENTIAL_TEAMS_TOKEN,
+ * });
+ * await teams.sendWebhook({ title: "Deploy", text: "Release 1.2.0 is live" });
+ * ```
+ * @memberOf module:integrations/comms/teams/service
+ */
+export declare class TeamsService extends HttpApiService<TeamsServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Microsoft Teams";
+    /**
+     * @description The Microsoft Graph v1.0 base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://graph.microsoft.com/v1.0"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Microsoft Graph bearer authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries a token, and no headers otherwise.
+     * @param {TeamsServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: TeamsServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Teams credentials and defaults from the environment
+     * @summary Reads the `comms.teams` environment slice and returns a partial
+     * config when a Graph token or webhook URL is configured, `undefined`
+     * otherwise. Values pass through `envString`/`envNumber` to reject
+     * unset-leaf proxies.
+     * @returns {Partial<TeamsServiceConfig> | undefined} A partial config, or `undefined` when neither token nor webhook URL is configured.
+     */
+    protected configFromEnvironment(): Partial<TeamsServiceConfig> | undefined;
+    /**
+     * @description Delivers a MessageCard through the configured incoming webhook
+     * @summary Posts an Office 365 `MessageCard` (`@type: "MessageCard"`) with
+     * the title, text, and markdown flag directly to `config.webhookUrl` using
+     * a standalone Axios call (no Graph token involved). Requires a configured
+     * webhook URL.
+     * @param {TeamsWebhookMessage} input - The card title, text, and markdown flag.
+     * @returns {Promise<unknown>} The raw webhook response payload.
+     * @throws {InternalError} When no webhook URL is configured.
+     * @throws {NotFoundError} When the webhook endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the webhook endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the webhook endpoint answers with any other HTTP error status.
+     */
+    sendWebhook(input: TeamsWebhookMessage): Promise<unknown>;
+    /**
+     * @description Sends a message into a Teams channel through Microsoft Graph
+     * @summary `POST`s a chat message to
+     * `/teams/<teamId>/channels/<channelId>/messages` with the given content
+     * type (`text` by default, or `html`). Requires a Graph token and both a
+     * team and channel ID; IDs are URL-encoded.
+     * @param {TeamsChannelMessage} input - The target team/channel and the message content.
+     * @returns {Promise<unknown>} The raw Graph message payload.
+     * @throws {InternalError} When no token is configured or the team/channel IDs are missing.
+     * @throws {NotFoundError} When the team or channel does not exist (HTTP 404).
+     * @throws {ConflictError} When Graph answers with HTTP 409.
+     * @throws {BadRequestError} When Graph answers with any other HTTP error status.
+     * @example
+     * ```ts
+     * await teams.sendChannelMessage({
+     *   teamId: "team-id",
+     *   channelId: "channel-id",
+     *   content: "<b>Release</b> 1.2.0 is live",
+     *   contentType: "html",
+     * });
+     * ```
+     */
+    sendChannelMessage(input: TeamsChannelMessage): Promise<unknown>;
+    /**
+     * @description Lists Teams accessible to the authenticated identity
+     * @summary `GET`s `/teams` with a `$top` page size (default `50`) and
+     * returns the raw Graph `team` payloads.
+     * @param {number} [limit] - Maximum number of teams to return; defaults to `50`.
+     * @returns {Promise<Array<Record<string, unknown>>>} The raw Graph `team` payloads.
+     * @throws {InternalError} When no token is configured.
+     * @throws {NotFoundError} When Graph answers with HTTP 404.
+     * @throws {ConflictError} When Graph answers with HTTP 409.
+     * @throws {BadRequestError} When Graph answers with any other HTTP error status.
+     */
+    listTeams(limit?: number): Promise<Array<Record<string, unknown>>>;
+    /**
+     * @description Lists channels of a Teams team
+     * @summary `GET`s `/teams/<teamId>/channels` and returns the raw Graph
+     * `channel` payloads; the team ID is URL-encoded.
+     * @param {string} teamId - The ID of the team whose channels are listed.
+     * @returns {Promise<Array<Record<string, unknown>>>} The raw Graph `channel` payloads.
+     * @throws {InternalError} When no token is configured.
+     * @throws {NotFoundError} When the team does not exist (HTTP 404).
+     * @throws {ConflictError} When Graph answers with HTTP 409.
+     * @throws {BadRequestError} When Graph answers with any other HTTP error status.
+     */
+    listChannels(teamId: string): Promise<Array<Record<string, unknown>>>;
+}

package/lib/types/comms/teams/TeamsService.d.mts

@@ -0,0 +1,172 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+/**
+ * @description Configuration for the Teams service
+ * @summary Extends {@link HttpApiServiceConfig} with the Microsoft Graph
+ * access token (required for channel messaging and listings, optional when
+ * only webhooks are used) and the incoming-webhook URL. When omitted, the
+ * `comms.teams` environment slice supplies both (and optional
+ * `baseUrl`/`timeout`).
+ * @category Comms
+ * @memberOf module:integrations/comms/teams/service
+ */
+export interface TeamsServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Microsoft Graph access token
+     * @summary Sent as `Authorization: Bearer <token>` for Graph requests.
+     */
+    token?: string;
+    /**
+     * @description Incoming webhook URL for `sendWebhook`
+     * @summary Typically an Office 365 connector URL; required only for webhook delivery.
+     */
+    webhookUrl?: string;
+}
+/**
+ * @description Input for Teams incoming-webhook delivery
+ * @summary Carries the plain-text `text`, an optional card `title`, and
+ * whether the text is rendered as markdown (default `true`). Delivered as an
+ * Office 365 `MessageCard` to the configured webhook URL.
+ * @category Comms
+ * @memberOf module:integrations/comms/teams/service
+ */
+export interface TeamsWebhookMessage {
+    /**
+     * @description Message body text
+     */
+    text: string;
+    /**
+     * @description Optional card title
+     */
+    title?: string;
+    /**
+     * @description Whether `text` is rendered as markdown; defaults to `true`
+     */
+    markdown?: boolean;
+}
+/**
+ * @description Input for sending a message into a Teams channel via Microsoft Graph
+ * @summary Carries the target `teamId` and `channelId`, the message
+ * `content`, and its content type (`text` by default, or `html`).
+ * @category Comms
+ * @memberOf module:integrations/comms/teams/service
+ */
+export interface TeamsChannelMessage {
+    teamId: string;
+    channelId: string;
+    content: string;
+    contentType?: "text" | "html";
+}
+/**
+ * @description Microsoft Teams integration service
+ * @summary An undecorated HTTP service combining incoming-webhook
+ * delivery (needs only `webhookUrl`) with Microsoft Graph operations — channel
+ * messaging, team listing, and channel listing (need a Graph `token`).
+ * Webhook delivery posts an Office 365 `MessageCard` directly to the
+ * configured URL; Graph operations go through the service client with bearer
+ * auth, require a token (`requireToken()`), and map transport failures to
+ * decaf errors via {@link httpError}.
+ * @class TeamsService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { TeamsService } from "@decaf-ts/integrations/comms/teams";
+ *
+ * const teams = new TeamsService();
+ * await teams.initialize({
+ *   webhookUrl: process.env.GRAPH_CREDENTIAL_TEAMS_WEBHOOK_URL,
+ *   token: process.env.GRAPH_CREDENTIAL_TEAMS_TOKEN,
+ * });
+ * await teams.sendWebhook({ title: "Deploy", text: "Release 1.2.0 is live" });
+ * ```
+ * @memberOf module:integrations/comms/teams/service
+ */
+export declare class TeamsService extends HttpApiService<TeamsServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Microsoft Teams";
+    /**
+     * @description The Microsoft Graph v1.0 base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://graph.microsoft.com/v1.0"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the Microsoft Graph bearer authorization headers
+     * @summary Returns the `Authorization: Bearer <token>` header when the
+     * config carries a token, and no headers otherwise.
+     * @param {TeamsServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: TeamsServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the Teams credentials and defaults from the environment
+     * @summary Reads the `comms.teams` environment slice and returns a partial
+     * config when a Graph token or webhook URL is configured, `undefined`
+     * otherwise. Values pass through `envString`/`envNumber` to reject
+     * unset-leaf proxies.
+     * @returns {Partial<TeamsServiceConfig> | undefined} A partial config, or `undefined` when neither token nor webhook URL is configured.
+     */
+    protected configFromEnvironment(): Partial<TeamsServiceConfig> | undefined;
+    /**
+     * @description Delivers a MessageCard through the configured incoming webhook
+     * @summary Posts an Office 365 `MessageCard` (`@type: "MessageCard"`) with
+     * the title, text, and markdown flag directly to `config.webhookUrl` using
+     * a standalone Axios call (no Graph token involved). Requires a configured
+     * webhook URL.
+     * @param {TeamsWebhookMessage} input - The card title, text, and markdown flag.
+     * @returns {Promise<unknown>} The raw webhook response payload.
+     * @throws {InternalError} When no webhook URL is configured.
+     * @throws {NotFoundError} When the webhook endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the webhook endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the webhook endpoint answers with any other HTTP error status.
+     */
+    sendWebhook(input: TeamsWebhookMessage): Promise<unknown>;
+    /**
+     * @description Sends a message into a Teams channel through Microsoft Graph
+     * @summary `POST`s a chat message to
+     * `/teams/<teamId>/channels/<channelId>/messages` with the given content
+     * type (`text` by default, or `html`). Requires a Graph token and both a
+     * team and channel ID; IDs are URL-encoded.
+     * @param {TeamsChannelMessage} input - The target team/channel and the message content.
+     * @returns {Promise<unknown>} The raw Graph message payload.
+     * @throws {InternalError} When no token is configured or the team/channel IDs are missing.
+     * @throws {NotFoundError} When the team or channel does not exist (HTTP 404).
+     * @throws {ConflictError} When Graph answers with HTTP 409.
+     * @throws {BadRequestError} When Graph answers with any other HTTP error status.
+     * @example
+     * ```ts
+     * await teams.sendChannelMessage({
+     *   teamId: "team-id",
+     *   channelId: "channel-id",
+     *   content: "<b>Release</b> 1.2.0 is live",
+     *   contentType: "html",
+     * });
+     * ```
+     */
+    sendChannelMessage(input: TeamsChannelMessage): Promise<unknown>;
+    /**
+     * @description Lists Teams accessible to the authenticated identity
+     * @summary `GET`s `/teams` with a `$top` page size (default `50`) and
+     * returns the raw Graph `team` payloads.
+     * @param {number} [limit] - Maximum number of teams to return; defaults to `50`.
+     * @returns {Promise<Array<Record<string, unknown>>>} The raw Graph `team` payloads.
+     * @throws {InternalError} When no token is configured.
+     * @throws {NotFoundError} When Graph answers with HTTP 404.
+     * @throws {ConflictError} When Graph answers with HTTP 409.
+     * @throws {BadRequestError} When Graph answers with any other HTTP error status.
+     */
+    listTeams(limit?: number): Promise<Array<Record<string, unknown>>>;
+    /**
+     * @description Lists channels of a Teams team
+     * @summary `GET`s `/teams/<teamId>/channels` and returns the raw Graph
+     * `channel` payloads; the team ID is URL-encoded.
+     * @param {string} teamId - The ID of the team whose channels are listed.
+     * @returns {Promise<Array<Record<string, unknown>>>} The raw Graph `channel` payloads.
+     * @throws {InternalError} When no token is configured.
+     * @throws {NotFoundError} When the team does not exist (HTTP 404).
+     * @throws {ConflictError} When Graph answers with HTTP 409.
+     * @throws {BadRequestError} When Graph answers with any other HTTP error status.
+     */
+    listChannels(teamId: string): Promise<Array<Record<string, unknown>>>;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/comms/teams
+ * @summary Microsoft Teams service (webhook posts and Graph channel messaging).
+ * @description Re-exports the Teams client-based service and its types.
+ */
+export * from "./TeamsService.d.cts";

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/comms/teams
+ * @summary Microsoft Teams service (webhook posts and Graph channel messaging).
+ * @description Re-exports the Teams client-based service and its types.
+ */
+export * from "./TeamsService.d.mts";