@decaf-ts/integrations 0.11.0 → 0.12.0

package/lib/types/comms/telegram/TelegramService.d.cts

@@ -0,0 +1,202 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+/**
+ * @description Configuration for the Telegram service
+ * @summary Extends {@link HttpApiServiceConfig} with the Telegram bot token
+ * used to build the `/bot<token>` request path. When omitted, the
+ * `comms.telegram` environment slice supplies the token (and optional
+ * `baseUrl`/`timeout`).
+ * @category Comms
+ * @memberOf module:integrations/comms/telegram/service
+ */
+export interface TelegramServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Telegram bot token
+     * @summary Issued by BotFather; embedded in the request path for every call.
+     */
+    token?: string;
+}
+/**
+ * @description Input for sending a Telegram message
+ * @summary Carries the destination `chatId`, the message `text`, the optional
+ * parse mode (`Markdown`, `MarkdownV2`, or `HTML`), and the notification,
+ * preview, reply, and forum-thread options.
+ * @category Comms
+ * @memberOf module:integrations/comms/telegram/service
+ */
+export interface TelegramSendMessageInput {
+    /**
+     * @description Destination chat ID or `@channelusername`
+     */
+    chatId: string | number;
+    /**
+     * @description Message text (up to 4096 characters)
+     */
+    text: string;
+    /**
+     * @description Parse mode for entity recognition in `text`
+     */
+    parseMode?: "Markdown" | "MarkdownV2" | "HTML";
+    /**
+     * @description Whether the message is sent silently
+     */
+    disableNotification?: boolean;
+    /**
+     * @description Whether link previews are disabled
+     */
+    disablePreview?: boolean;
+    /**
+     * @description Message to reply to
+     */
+    replyToMessageId?: number;
+    /**
+     * @description Forum thread to post into
+     */
+    messageThreadId?: number;
+}
+/**
+ * @description Normalized Telegram message descriptor
+ * @summary The relevant subset of the Telegram `Message` object: identifiers
+ * (`message_id`, `date`), the sending `chat`, and the message `text`.
+ * @category Comms
+ * @memberOf module:integrations/comms/telegram/service
+ */
+export interface TelegramMessage {
+    message_id: number;
+    date: number;
+    chat: {
+        id: number;
+        type?: string;
+        title?: string;
+        username?: string;
+    };
+    text?: string;
+}
+/**
+ * @description Telegram Bot API integration service
+ * @summary An undecorated HTTP service for verifying the bot
+ * identity, sending messages with parse modes and reply/thread options, long
+ * or short polling `getUpdates`, and posting chat actions. The bot token is
+ * required (`requireToken()`) and embedded in the request path; non-`ok` Bot
+ * API responses raise `InternalError`, and transport failures are mapped to
+ * decaf errors via {@link httpError}.
+ * @class TelegramService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { TelegramService } from "@decaf-ts/integrations/comms/telegram";
+ *
+ * const telegram = new TelegramService();
+ * await telegram.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_TELEGRAM_TOKEN,
+ * });
+ * await telegram.sendMessage({
+ *   chatId: "@mychannel",
+ *   text: "Release 1.2.0 is live",
+ *   parseMode: "HTML",
+ * });
+ * ```
+ * @memberOf module:integrations/comms/telegram/service
+ */
+export declare class TelegramService extends HttpApiService<TelegramServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Telegram";
+    /**
+     * @description The Telegram Bot API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://api.telegram.org"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Reads the Telegram credentials and defaults from the environment
+     * @summary Reads the `comms.telegram` 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<TelegramServiceConfig> | undefined} A partial config, or `undefined` when no Telegram token is configured.
+     */
+    protected configFromEnvironment(): Partial<TelegramServiceConfig> | undefined;
+    /**
+     * @description Calls a Telegram Bot API method with the configured bot token
+     * @summary Shared request path for all Telegram operations: resolves the
+     * token (`requireToken()`), `POST`s the payload to
+     * `/bot<token>/<method>`, rejects non-`ok` Bot API responses with an
+     * `InternalError`, and maps transport failures through {@link httpError}.
+     * @template T - The expected `result` payload type of the Bot API response.
+     * @param {string} method - The Bot API method name (e.g. `"sendMessage"`).
+     * @param {Record<string, unknown>} [payload] - The JSON body for the method; defaults to an empty object.
+     * @returns {Promise<T>} The `result` payload of the Bot API response.
+     * @throws {InternalError} When no token is configured or the Bot API answers with `ok: false`.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    protected call<T>(method: string, payload?: Record<string, unknown>): Promise<T>;
+    /**
+     * @description Fetches the authenticated bot's identity
+     * @summary Calls the `getMe` method and returns the raw bot descriptor
+     * (including `id`, `username`, and `can_join_groups` flags).
+     * @returns {Promise<Record<string, unknown>>} The raw `User` payload describing the bot.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the call.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    getMe(): Promise<Record<string, unknown>>;
+    /**
+     * @description Sends a message to a Telegram chat
+     * @summary Calls the `sendMessage` method with the destination chat, text,
+     * and the requested parse/notification/reply/thread options, returning the
+     * sent message descriptor.
+     * @param {TelegramSendMessageInput} input - The message destination, content, and options.
+     * @returns {Promise<TelegramMessage>} The sent message descriptor.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the message.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     * @example
+     * ```ts
+     * await telegram.sendMessage({
+     *   chatId: "-1001234567890",
+     *   text: "*Release* 1.2.0 is live",
+     *   parseMode: "MarkdownV2",
+     *   disableNotification: true,
+     * });
+     * ```
+     */
+    sendMessage(input: TelegramSendMessageInput): Promise<TelegramMessage>;
+    /**
+     * @description Polls pending bot updates
+     * @summary Calls the `getUpdates` method, optionally with an `offset`
+     * (confirmation of processed updates), a `limit` on returned updates, and a
+     * long-polling `timeoutSeconds`. Advance `offset` past each handled
+     * update's `update_id` to avoid re-reading them.
+     * @param {object} [options] - Polling options.
+     * @param {number} [options.offset] - The first update ID to return (previous ID + 1).
+     * @param {number} [options.limit] - Maximum number of updates to return (1-100).
+     * @param {number} [options.timeoutSeconds] - Long-polling timeout in seconds.
+     * @returns {Promise<Array<Record<string, unknown>>>} The raw `Update` payloads.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the call.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409 (e.g. another `getUpdates` call is in flight).
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    getUpdates(options?: {
+        offset?: number;
+        limit?: number;
+        timeoutSeconds?: number;
+    }): Promise<Array<Record<string, unknown>>>;
+    /**
+     * @description Posts a chat action (typing indicator)
+     * @summary Calls the `sendChatAction` method so clients display the given
+     * action (e.g. `"typing"`) for up to five seconds.
+     * @param {string | number} chatId - The destination chat ID or `@channelusername`.
+     * @param {string} [action] - The action to display; defaults to `"typing"`.
+     * @returns {Promise<boolean>} Whether the action was accepted.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the call.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    sendChatAction(chatId: string | number, action?: string): Promise<boolean>;
+}

package/lib/types/comms/telegram/TelegramService.d.mts

@@ -0,0 +1,202 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.mts";
+/**
+ * @description Configuration for the Telegram service
+ * @summary Extends {@link HttpApiServiceConfig} with the Telegram bot token
+ * used to build the `/bot<token>` request path. When omitted, the
+ * `comms.telegram` environment slice supplies the token (and optional
+ * `baseUrl`/`timeout`).
+ * @category Comms
+ * @memberOf module:integrations/comms/telegram/service
+ */
+export interface TelegramServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Telegram bot token
+     * @summary Issued by BotFather; embedded in the request path for every call.
+     */
+    token?: string;
+}
+/**
+ * @description Input for sending a Telegram message
+ * @summary Carries the destination `chatId`, the message `text`, the optional
+ * parse mode (`Markdown`, `MarkdownV2`, or `HTML`), and the notification,
+ * preview, reply, and forum-thread options.
+ * @category Comms
+ * @memberOf module:integrations/comms/telegram/service
+ */
+export interface TelegramSendMessageInput {
+    /**
+     * @description Destination chat ID or `@channelusername`
+     */
+    chatId: string | number;
+    /**
+     * @description Message text (up to 4096 characters)
+     */
+    text: string;
+    /**
+     * @description Parse mode for entity recognition in `text`
+     */
+    parseMode?: "Markdown" | "MarkdownV2" | "HTML";
+    /**
+     * @description Whether the message is sent silently
+     */
+    disableNotification?: boolean;
+    /**
+     * @description Whether link previews are disabled
+     */
+    disablePreview?: boolean;
+    /**
+     * @description Message to reply to
+     */
+    replyToMessageId?: number;
+    /**
+     * @description Forum thread to post into
+     */
+    messageThreadId?: number;
+}
+/**
+ * @description Normalized Telegram message descriptor
+ * @summary The relevant subset of the Telegram `Message` object: identifiers
+ * (`message_id`, `date`), the sending `chat`, and the message `text`.
+ * @category Comms
+ * @memberOf module:integrations/comms/telegram/service
+ */
+export interface TelegramMessage {
+    message_id: number;
+    date: number;
+    chat: {
+        id: number;
+        type?: string;
+        title?: string;
+        username?: string;
+    };
+    text?: string;
+}
+/**
+ * @description Telegram Bot API integration service
+ * @summary An undecorated HTTP service for verifying the bot
+ * identity, sending messages with parse modes and reply/thread options, long
+ * or short polling `getUpdates`, and posting chat actions. The bot token is
+ * required (`requireToken()`) and embedded in the request path; non-`ok` Bot
+ * API responses raise `InternalError`, and transport failures are mapped to
+ * decaf errors via {@link httpError}.
+ * @class TelegramService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { TelegramService } from "@decaf-ts/integrations/comms/telegram";
+ *
+ * const telegram = new TelegramService();
+ * await telegram.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_TELEGRAM_TOKEN,
+ * });
+ * await telegram.sendMessage({
+ *   chatId: "@mychannel",
+ *   text: "Release 1.2.0 is live",
+ *   parseMode: "HTML",
+ * });
+ * ```
+ * @memberOf module:integrations/comms/telegram/service
+ */
+export declare class TelegramService extends HttpApiService<TelegramServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "Telegram";
+    /**
+     * @description The Telegram Bot API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://api.telegram.org"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Reads the Telegram credentials and defaults from the environment
+     * @summary Reads the `comms.telegram` 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<TelegramServiceConfig> | undefined} A partial config, or `undefined` when no Telegram token is configured.
+     */
+    protected configFromEnvironment(): Partial<TelegramServiceConfig> | undefined;
+    /**
+     * @description Calls a Telegram Bot API method with the configured bot token
+     * @summary Shared request path for all Telegram operations: resolves the
+     * token (`requireToken()`), `POST`s the payload to
+     * `/bot<token>/<method>`, rejects non-`ok` Bot API responses with an
+     * `InternalError`, and maps transport failures through {@link httpError}.
+     * @template T - The expected `result` payload type of the Bot API response.
+     * @param {string} method - The Bot API method name (e.g. `"sendMessage"`).
+     * @param {Record<string, unknown>} [payload] - The JSON body for the method; defaults to an empty object.
+     * @returns {Promise<T>} The `result` payload of the Bot API response.
+     * @throws {InternalError} When no token is configured or the Bot API answers with `ok: false`.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    protected call<T>(method: string, payload?: Record<string, unknown>): Promise<T>;
+    /**
+     * @description Fetches the authenticated bot's identity
+     * @summary Calls the `getMe` method and returns the raw bot descriptor
+     * (including `id`, `username`, and `can_join_groups` flags).
+     * @returns {Promise<Record<string, unknown>>} The raw `User` payload describing the bot.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the call.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    getMe(): Promise<Record<string, unknown>>;
+    /**
+     * @description Sends a message to a Telegram chat
+     * @summary Calls the `sendMessage` method with the destination chat, text,
+     * and the requested parse/notification/reply/thread options, returning the
+     * sent message descriptor.
+     * @param {TelegramSendMessageInput} input - The message destination, content, and options.
+     * @returns {Promise<TelegramMessage>} The sent message descriptor.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the message.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     * @example
+     * ```ts
+     * await telegram.sendMessage({
+     *   chatId: "-1001234567890",
+     *   text: "*Release* 1.2.0 is live",
+     *   parseMode: "MarkdownV2",
+     *   disableNotification: true,
+     * });
+     * ```
+     */
+    sendMessage(input: TelegramSendMessageInput): Promise<TelegramMessage>;
+    /**
+     * @description Polls pending bot updates
+     * @summary Calls the `getUpdates` method, optionally with an `offset`
+     * (confirmation of processed updates), a `limit` on returned updates, and a
+     * long-polling `timeoutSeconds`. Advance `offset` past each handled
+     * update's `update_id` to avoid re-reading them.
+     * @param {object} [options] - Polling options.
+     * @param {number} [options.offset] - The first update ID to return (previous ID + 1).
+     * @param {number} [options.limit] - Maximum number of updates to return (1-100).
+     * @param {number} [options.timeoutSeconds] - Long-polling timeout in seconds.
+     * @returns {Promise<Array<Record<string, unknown>>>} The raw `Update` payloads.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the call.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409 (e.g. another `getUpdates` call is in flight).
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    getUpdates(options?: {
+        offset?: number;
+        limit?: number;
+        timeoutSeconds?: number;
+    }): Promise<Array<Record<string, unknown>>>;
+    /**
+     * @description Posts a chat action (typing indicator)
+     * @summary Calls the `sendChatAction` method so clients display the given
+     * action (e.g. `"typing"`) for up to five seconds.
+     * @param {string | number} chatId - The destination chat ID or `@channelusername`.
+     * @param {string} [action] - The action to display; defaults to `"typing"`.
+     * @returns {Promise<boolean>} Whether the action was accepted.
+     * @throws {InternalError} When no token is configured or the Bot API rejects the call.
+     * @throws {NotFoundError} When the endpoint answers with HTTP 404.
+     * @throws {ConflictError} When the endpoint answers with HTTP 409.
+     * @throws {BadRequestError} When the endpoint answers with any other HTTP error status.
+     */
+    sendChatAction(chatId: string | number, action?: string): Promise<boolean>;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/comms/telegram
+ * @summary Telegram Bot API service (messaging, updates, chat actions).
+ * @description Re-exports the Telegram client-based service and its types.
+ */
+export * from "./TelegramService.d.cts";

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/comms/telegram
+ * @summary Telegram Bot API service (messaging, updates, chat actions).
+ * @description Re-exports the Telegram client-based service and its types.
+ */
+export * from "./TelegramService.d.mts";

package/lib/types/devops/environment.d.cts

@@ -0,0 +1,62 @@
+/**
+ * @module integrations/devops/environment
+ * @summary Environment contract and accumulated environment for the devops integration services.
+ * @description Declares the `DevopsEnvironmentShape` consumed by the GitHub and
+ * GitLab services' `configFromEnvironment()` implementations and the
+ * `DevopsEnvironment` singleton created via `LoggedEnvironment.accumulate`.
+ * Services read their credentials and defaults from the matching
+ * `devops.<provider>` slice, using the `envString`/`envNumber` helpers from
+ * `shared/environmentValue` to reject unset-leaf proxies.
+ */
+/**
+ * @description Environment shape for the devops integration services
+ * @summary Defines the `devops` root with one slice per provider (`github`,
+ * `gitlab`). Each slice carries the provider's required `token` and defaults
+ * (`owner`/`repo` for GitHub, `projectId` for GitLab) plus an optional
+ * `baseUrl` override and `timeout`. Fields are typed as required here so
+ * `LoggedEnvironment.accumulate` registers them; absent values resolve to
+ * proxy placeholders at runtime and must pass through `envString`/`envNumber`.
+ * @memberOf module:integrations/devops/environment
+ */
+export interface DevopsEnvironmentShape {
+    devops: {
+        github: {
+            token: string;
+            baseUrl: string;
+            owner: string;
+            repo: string;
+            timeout?: number;
+        };
+        gitlab: {
+            token: string;
+            baseUrl: string;
+            projectId: string;
+            timeout?: number;
+        };
+    };
+}
+/**
+ * @description Accumulated devops environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `DevopsEnvironmentShape` contract. Devops services read their provider
+ * slice (e.g. `DevopsEnvironment.devops.github`) 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 { GithubService } from "@decaf-ts/integrations/devops/github";
+ *
+ * // with devops.github.token / devops.github.owner / devops.github.repo configured
+ * const github = new GithubService();
+ * await github.initialize();
+ * ```
+ * @constant {LoggedEnvironment} DevopsEnvironment
+ * @memberOf module:integrations/devops/environment
+ */
+export declare const DevopsEnvironment: import("@decaf-ts/logging").AccumulatedEnvironment<{
+    app: string | undefined;
+} & import("@decaf-ts/logging").LoggingConfig<object> & {
+    env: any;
+} & DevopsEnvironmentShape>;

package/lib/types/devops/environment.d.mts

@@ -0,0 +1,62 @@
+/**
+ * @module integrations/devops/environment
+ * @summary Environment contract and accumulated environment for the devops integration services.
+ * @description Declares the `DevopsEnvironmentShape` consumed by the GitHub and
+ * GitLab services' `configFromEnvironment()` implementations and the
+ * `DevopsEnvironment` singleton created via `LoggedEnvironment.accumulate`.
+ * Services read their credentials and defaults from the matching
+ * `devops.<provider>` slice, using the `envString`/`envNumber` helpers from
+ * `shared/environmentValue` to reject unset-leaf proxies.
+ */
+/**
+ * @description Environment shape for the devops integration services
+ * @summary Defines the `devops` root with one slice per provider (`github`,
+ * `gitlab`). Each slice carries the provider's required `token` and defaults
+ * (`owner`/`repo` for GitHub, `projectId` for GitLab) plus an optional
+ * `baseUrl` override and `timeout`. Fields are typed as required here so
+ * `LoggedEnvironment.accumulate` registers them; absent values resolve to
+ * proxy placeholders at runtime and must pass through `envString`/`envNumber`.
+ * @memberOf module:integrations/devops/environment
+ */
+export interface DevopsEnvironmentShape {
+    devops: {
+        github: {
+            token: string;
+            baseUrl: string;
+            owner: string;
+            repo: string;
+            timeout?: number;
+        };
+        gitlab: {
+            token: string;
+            baseUrl: string;
+            projectId: string;
+            timeout?: number;
+        };
+    };
+}
+/**
+ * @description Accumulated devops environment singleton
+ * @summary The `LoggedEnvironment.accumulate`-registered instance backing the
+ * `DevopsEnvironmentShape` contract. Devops services read their provider
+ * slice (e.g. `DevopsEnvironment.devops.github`) 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 { GithubService } from "@decaf-ts/integrations/devops/github";
+ *
+ * // with devops.github.token / devops.github.owner / devops.github.repo configured
+ * const github = new GithubService();
+ * await github.initialize();
+ * ```
+ * @constant {LoggedEnvironment} DevopsEnvironment
+ * @memberOf module:integrations/devops/environment
+ */
+export declare const DevopsEnvironment: import("@decaf-ts/logging").AccumulatedEnvironment<{
+    app: string | undefined;
+} & import("@decaf-ts/logging").LoggingConfig<object> & {
+    env: any;
+} & DevopsEnvironmentShape>;