@decaf-ts/integrations 0.11.0 → 0.14.0

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/comms/whatsapp/WhatsAppService.d.cts

@@ -0,0 +1,258 @@
+import { HttpApiService, type HttpApiServiceConfig } from "../../shared/http/index.d.cts";
+/**
+ * @description Configuration for the WhatsApp service
+ * @summary Extends {@link HttpApiServiceConfig} with the Meta access token
+ * (sent as a bearer token) and the sender `phoneNumberId` used in the
+ * `/messages` path. When omitted, the `comms.whatsApp` environment slice
+ * supplies both (plus optional `baseUrl`/`timeout`). Both values are
+ * credential references, never literals in source.
+ * @category Comms
+ * @memberOf module:integrations/comms/whatsapp/service
+ */
+export interface WhatsAppServiceConfig extends HttpApiServiceConfig {
+    /**
+     * @description Meta WhatsApp Cloud API access token
+     * @summary Sent as `Authorization: Bearer <token>` with every API call.
+     */
+    token?: string;
+    /**
+     * @description Sender phone number ID used in the messages path
+     */
+    phoneNumberId?: string;
+}
+/**
+ * @description Input for sending a WhatsApp text message
+ * @summary Carries the recipient (`to`, E.164 digits without `+`), the text
+ * body, and whether link previews are generated.
+ * @category Comms
+ * @memberOf module:integrations/comms/whatsapp/service
+ */
+export interface WhatsAppTextInput {
+    /**
+     * @description Recipient phone number in international format
+     */
+    to: string;
+    /**
+     * @description Text message body
+     */
+    text: string;
+    /**
+     * @description Whether WhatsApp generates a link preview
+     */
+    previewUrl?: boolean;
+}
+/**
+ * @description Input for sending a WhatsApp template message
+ * @summary Carries the recipient, the approved `templateName`, its
+ * `languageCode`, and optional template `components`.
+ * @category Comms
+ * @memberOf module:integrations/comms/whatsapp/service
+ */
+export interface WhatsAppTemplateInput {
+    /**
+     * @description Recipient phone number in international format
+     */
+    to: string;
+    /**
+     * @description Name of the approved message template
+     */
+    templateName: string;
+    /**
+     * @description Template language code (e.g. `"en_US"`)
+     */
+    languageCode: string;
+    /**
+     * @description Optional template components (header/body/button parameters)
+     */
+    components?: unknown[];
+}
+/**
+ * @description Supported WhatsApp media message types
+ * @summary The media kinds the Cloud API accepts in the message `type` field.
+ * @category Comms
+ * @memberOf module:integrations/comms/whatsapp/service
+ */
+export type WhatsAppMediaType = "image" | "audio" | "video" | "document";
+/**
+ * @description Input for sending a WhatsApp media message
+ * @summary Carries the recipient, the media `type`, and either a previously
+ * uploaded `mediaId` or a public `link` (one is required), plus an optional
+ * `caption` and `filename`.
+ * @category Comms
+ * @memberOf module:integrations/comms/whatsapp/service
+ */
+export interface WhatsAppMediaInput {
+    /**
+     * @description Recipient phone number in international format
+     */
+    to: string;
+    /**
+     * @description Media kind sent in the message `type` field
+     */
+    type: WhatsAppMediaType;
+    /**
+     * @description ID of previously uploaded WhatsApp media
+     */
+    mediaId?: string;
+    /**
+     * @description Public URL of the media (alternative to `mediaId`)
+     */
+    link?: string;
+    /**
+     * @description Optional caption (images, videos, documents)
+     */
+    caption?: string;
+    /**
+     * @description Optional filename (documents)
+     */
+    filename?: string;
+}
+/**
+ * @description Input for marking a WhatsApp message as read
+ * @summary Carries the inbound `messageId` to acknowledge.
+ * @category Comms
+ * @memberOf module:integrations/comms/whatsapp/service
+ */
+export interface WhatsAppReadInput {
+    /**
+     * @description ID of the inbound message to mark read
+     */
+    messageId: string;
+}
+/**
+ * @description WhatsApp Cloud API integration service
+ * @summary An undecorated HTTP service for text, template, and media
+ * messages, read receipts, and media metadata. Every message operation needs
+ * both the access token and the sender phone number ID; missing credentials or
+ * identifiers raise `InternalError`, and transport failures are mapped to decaf
+ * errors via {@link httpError}.
+ * @class WhatsAppService
+ * @extends HttpApiService
+ * @category Comms
+ * @example
+ * ```ts
+ * import { WhatsAppService } from "@decaf-ts/integrations/comms/whatsapp";
+ *
+ * const whatsapp = new WhatsAppService();
+ * await whatsapp.initialize({
+ *   token: process.env.GRAPH_CREDENTIAL_WHATSAPP_TOKEN,
+ *   phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID,
+ * });
+ * await whatsapp.sendText({ to: "15551234567", text: "Hello" });
+ * ```
+ * @mermaid
+ * sequenceDiagram
+ *   autonumber
+ *   participant Caller
+ *   participant Service as WhatsAppService
+ *   participant Graph as WhatsApp Cloud API
+ *   Caller->>Service: sendText(input)
+ *   activate Service
+ *   Service->>Service: requireTokenAndPhone()
+ *   Service->>Graph: POST /{phoneNumberId}/messages
+ *   activate Graph
+ *   Graph-->>Service: message payload
+ *   deactivate Graph
+ *   Service-->>Caller: message payload
+ *   deactivate Service
+ * @memberOf module:integrations/comms/whatsapp/service
+ */
+export declare class WhatsAppService extends HttpApiService<WhatsAppServiceConfig> {
+    /**
+     * @description The provider name used in error messages
+     */
+    protected readonly serviceName = "WhatsApp";
+    /**
+     * @description The WhatsApp Cloud API base URL
+     * @summary Used when the resolved config carries no `baseUrl`.
+     * @returns {string} `"https://graph.facebook.com/v19.0"`.
+     */
+    protected defaultBaseUrl(): string;
+    /**
+     * @description Builds the WhatsApp bearer authorization headers
+     * @summary Returns `Authorization: Bearer <token>` when configured, and no
+     * headers otherwise.
+     * @param {WhatsAppServiceConfig} config - The resolved service configuration.
+     * @returns {Record<string, string>} The authorization headers (empty without a token).
+     */
+    protected authHeaders(config: WhatsAppServiceConfig): Record<string, string>;
+    /**
+     * @description Reads the WhatsApp credentials and defaults from the environment
+     * @summary Reads the `comms.whatsApp` slice and returns a partial config
+     * when a token or phone number ID is configured, `undefined` otherwise.
+     * Values pass through `envString`/`envNumber` to reject unset-leaf proxies.
+     * @returns {Partial<WhatsAppServiceConfig> | undefined} A partial config, or `undefined` when neither credential is configured.
+     */
+    protected configFromEnvironment(): Partial<WhatsAppServiceConfig> | undefined;
+    /**
+     * @description Asserts the access token and sender phone number ID
+     * @summary Calls `requireToken()` and returns the configured
+     * `phoneNumberId` used to build the messages path.
+     * @returns {string} The configured sender phone number ID.
+     * @throws {InternalError} When no token or phone number ID is configured.
+     */
+    protected requireTokenAndPhone(): string;
+    /**
+     * @description Builds the encoded messages path for a sender
+     * @summary Encodes the phone number ID into `/<id>/messages`.
+     * @param {string} phoneNumberId - The sender phone number ID.
+     * @returns {string} The messages API path.
+     */
+    private messagesPath;
+    /**
+     * @description Sends a WhatsApp text message
+     * @summary `POST`s a `text` message to the sender's `/messages` endpoint
+     * and returns the WhatsApp message payload.
+     * @param {WhatsAppTextInput} input - The recipient, text, and preview flag.
+     * @returns {Promise<unknown>} The WhatsApp message payload.
+     * @throws {InternalError} When credentials or the phone number ID are missing.
+     * @throws {BadRequestError} When WhatsApp rejects the message.
+     * @example
+     * ```ts
+     * await whatsapp.sendText({ to: "15551234567", text: "Deployment finished" });
+     * ```
+     */
+    sendText(input: WhatsAppTextInput): Promise<unknown>;
+    /**
+     * @description Sends a WhatsApp template message
+     * @summary `POST`s a `template` message referencing an approved template
+     * name and language, with optional components.
+     * @param {WhatsAppTemplateInput} input - The recipient and template definition.
+     * @returns {Promise<unknown>} The WhatsApp message payload.
+     * @throws {InternalError} When credentials or the phone number ID are missing.
+     * @throws {BadRequestError} When WhatsApp rejects the template message.
+     */
+    sendTemplate(input: WhatsAppTemplateInput): Promise<unknown>;
+    /**
+     * @description Sends a WhatsApp media message
+     * @summary `POST`s an `image`/`audio`/`video`/`document` message using
+     * either an uploaded `mediaId` or a public `link`, with optional caption and
+     * filename.
+     * @param {WhatsAppMediaInput} input - The recipient and media reference.
+     * @returns {Promise<unknown>} The WhatsApp message payload.
+     * @throws {InternalError} When credentials or the phone number ID are missing, or neither `mediaId` nor `link` is provided.
+     * @throws {BadRequestError} When WhatsApp rejects the media message.
+     */
+    sendMedia(input: WhatsAppMediaInput): Promise<unknown>;
+    /**
+     * @description Marks an inbound WhatsApp message as read
+     * @summary `POST`s a `read` status for the message to the sender's
+     * `/messages` endpoint.
+     * @param {WhatsAppReadInput} input - The inbound message ID to acknowledge.
+     * @returns {Promise<unknown>} The WhatsApp status payload.
+     * @throws {InternalError} When credentials, the phone number ID, or the message ID are missing.
+     * @throws {BadRequestError} When WhatsApp rejects the request.
+     */
+    markAsRead(input: WhatsAppReadInput): Promise<unknown>;
+    /**
+     * @description Fetches WhatsApp media metadata
+     * @summary `GET`s the media descriptor (URL, MIME type, size) by media ID;
+     * the descriptor's URL is then used to download the binary.
+     * @param {string} mediaId - The WhatsApp media ID.
+     * @returns {Promise<unknown>} The media metadata payload.
+     * @throws {InternalError} When no token is configured or the media ID is empty.
+     * @throws {NotFoundError} When the media does not exist (HTTP 404).
+     * @throws {BadRequestError} When WhatsApp rejects the request.
+     */
+    getMedia(mediaId: string): Promise<unknown>;
+}