core-services-sdk 1.3.49 → 1.3.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.49",
+  "version": "1.3.50",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",

package/src/instant-messages/index.js

@@ -2,3 +2,5 @@ export * from './im-platform.js'
 export * from './message-type.js'
 export * from './message-types.js'
 export * from './message-unified-mapper.js'
+export * from './telegram-apis/telegram-apis.js'
+export * from './whatsapp-apis/whatsapp-apis.js'

package/src/instant-messages/telegram-apis/telegram-apis.js

@@ -0,0 +1,301 @@
+import { post } from '../../http/http.js'
+
+const TELEGRAM_API_BASE_URL = 'https://api.telegram.org'
+
+/**
+ * Builds a full set of Telegram Bot API endpoint URLs
+ * based on the provided bot token and an optional base URL.
+ *
+ * This helper centralizes all Telegram endpoints used by the system,
+ * making it easier to mock, override, or customize for testing environments.
+ *
+ * @typedef {Object} TelegramApiUrls
+ * @property {string} SEND_MESSAGE
+ *   URL to send a text message to a chat using the Telegram Bot API.
+ *
+ * @property {string} FORWARD_MESSAGE
+ *   URL to forward an existing message from one chat to another.
+ *
+ * @property {string} SEND_PHOTO
+ *   URL to send a photo to a chat.
+ *
+ * @property {string} SEND_AUDIO
+ *   URL to send an audio file.
+ *
+ * @property {string} SEND_DOCUMENT
+ *   URL to send files such as PDF, DOC, ZIP, and others supported by Telegram.
+ *
+ * @property {string} SEND_STICKER
+ *   URL to send a sticker.
+ *
+ * @property {string} SEND_VIDEO
+ *   URL to send a video file.
+ *
+ * @property {string} SEND_VOICE
+ *   URL to send a voice note.
+ *
+ * @property {string} SEND_LOCATION
+ *   URL to send a geolocation point.
+ *
+ * @property {string} SEND_CHAT_ACTION
+ *   URL to send a chat action (typing, uploading photo, etc).
+ *
+ * @property {string} GET_USER_PROFILE_PHOTOS
+ *   URL to retrieve the profile photos of a specific user.
+ *
+ * @property {string} GET_UPDATES
+ *   URL to poll for new updates (not used when using webhooks).
+ *
+ * @property {string} GET_FILE
+ *   URL to fetch a file path for downloading a file uploaded to Telegram servers.
+ */
+
+/**
+ * Generates Telegram Bot API endpoint URLs for the given bot token.
+ *
+ * @param {Object} params
+ * @param {string} params.token
+ *   The bot token obtained from BotFather.
+ *
+ * @param {string} [params.telegramBaseUrl=TELEGRAM_API_BASE_URL]
+ *   Optional override for the Telegram API base URL.
+ *   Useful for testing or for proxying requests.
+ *
+ * @returns {TelegramApiUrls}
+ *   A dictionary of fully resolved Telegram API endpoint URLs.
+ */
+export const getTelegramApiUrls = ({
+  token,
+  telegramBaseUrl = TELEGRAM_API_BASE_URL,
+}) => ({
+  SEND_MESSAGE: `${telegramBaseUrl}/bot${token}/sendMessage`,
+  FORWARD_MESSAGE: `${telegramBaseUrl}/bot${token}/forwardMessage`,
+  SEND_PHOTO: `${telegramBaseUrl}/bot${token}/sendPhoto`,
+  SEND_AUDIO: `${telegramBaseUrl}/bot${token}/sendAudio`,
+  SEND_DOCUMENT: `${telegramBaseUrl}/bot${token}/sendDocument`,
+  SEND_STICKER: `${telegramBaseUrl}/bot${token}/sendSticker`,
+  SEND_VIDEO: `${telegramBaseUrl}/bot${token}/sendVideo`,
+  SEND_VOICE: `${telegramBaseUrl}/bot${token}/sendVoice`,
+  SEND_LOCATION: `${telegramBaseUrl}/bot${token}/sendLocation`,
+  SEND_CHAT_ACTION: `${telegramBaseUrl}/bot${token}/sendChatAction`,
+  GET_USER_PROFILE_PHOTOS: `${telegramBaseUrl}/bot${token}/getUserProfilePhotos`,
+  GET_UPDATES: `${telegramBaseUrl}/bot${token}/getUpdates`,
+  GET_FILE: `${telegramBaseUrl}/bot${token}/getFile`,
+})
+
+/**
+ * Factory that creates a set of high level Telegram Bot API helper methods.
+ *
+ * Each method sends a specific type of message (text, photo, video, document)
+ * through the Telegram Bot API using the provided bot token.
+ *
+ * This abstraction wraps the raw URL generation logic and HTTP calls,
+ * allowing higher level services to use clean method calls instead of
+ * managing endpoint URLs manually.
+ *
+ * @typedef {Object} TelegramApis
+ *
+ * @property {Function} sendMessage
+ *   Sends a text message to a specific chat.
+ *
+ * @property {Function} sendButtonsGroup
+ *   Sends a text message with an inline keyboard button group.
+ *
+ * @property {Function} sendPhoto
+ *   Sends a photo with an optional caption.
+ *
+ * @property {Function} sendVideo
+ *   Sends a video with an optional caption.
+ *
+ * @property {Function} sendAudio
+ *   Sends an audio file with an optional caption.
+ *
+ * @property {Function} sendDocument
+ *   Sends a document file with an optional caption.
+ */
+
+/**
+ * Creates Telegram API methods bound to a specific bot token.
+ *
+ * @param {Object} params
+ * @param {string} params.token
+ *   Telegram bot token obtained from BotFather.
+ *
+ * @returns {TelegramApis}
+ *   An object containing all supported Telegram message sending functions.
+ */
+export const telegramApis = ({ token }) => {
+  const APIS = getTelegramApiUrls({ token })
+
+  return {
+    /**
+     * Sends a text message to a Telegram chat.
+     *
+     * @param {Object} params
+     * @param {string} params.text
+     *   The message content.
+     *
+     * @param {number|string} params.chatId
+     *   Chat identifier where the message should be sent.
+     *
+     * @param {Array<Object>} [params.entities]
+     *   Optional entities for formatting (bold, URL, etc).
+     *
+     * @returns {Promise<import('../../http/http.js').HttpResponse>}
+     *   Telegram API response.
+     */
+    async sendMessage({ text, chatId, entities }) {
+      const res = await post({
+        url: APIS.SEND_MESSAGE,
+        body: {
+          chat_id: chatId,
+          text,
+          entities,
+        },
+      })
+      return res
+    },
+
+    /**
+     * Sends a text message with inline keyboard buttons.
+     *
+     * @param {Object} params
+     * @param {string} params.text
+     *   The message content.
+     *
+     * @param {number|string} params.chatId
+     *   Chat identifier.
+     *
+     * @param {Array<Array<Object>>} params.options
+     *   Two dimensional array of inline keyboard button objects.
+     *
+     * @returns {Promise<import('../../http/http.js').HttpResponse>}
+     *   Telegram API response.
+     */
+    async sendButtonsGroup({ text, chatId, options }) {
+      const res = await post({
+        url: APIS.SEND_MESSAGE,
+        body: {
+          chat_id: chatId,
+          text,
+          reply_markup: {
+            inline_keyboard: options,
+          },
+        },
+      })
+      return res
+    },
+
+    /**
+     * Sends a photo message using an HTTP URL.
+     *
+     * @param {Object} params
+     * @param {number|string} params.chatId
+     *   Chat identifier.
+     *
+     * @param {string} params.photo
+     *   Publicly accessible HTTP URL of the photo.
+     *
+     * @param {string} [params.caption]
+     *   Optional caption for the photo.
+     *
+     * @returns {Promise<import('../../http/http.js').HttpResponse>}
+     *   Telegram API response.
+     */
+    async sendPhoto({ caption, photo, chatId }) {
+      const res = await post({
+        url: APIS.SEND_PHOTO,
+        body: {
+          chat_id: chatId,
+          caption,
+          photo,
+        },
+      })
+      return res
+    },
+
+    /**
+     * Sends a video message using an HTTP URL.
+     *
+     * @param {Object} params
+     * @param {number|string} params.chatId
+     *   Chat identifier.
+     *
+     * @param {string} params.video
+     *   Public video URL.
+     *
+     * @param {string} [params.caption]
+     *   Optional caption.
+     *
+     * @returns {Promise<import('../../http/http.js').HttpResponse>}
+     *   Telegram API response.
+     */
+    async sendVideo({ caption, video, chatId }) {
+      const res = await post({
+        url: APIS.SEND_VIDEO,
+        body: {
+          chat_id: chatId,
+          caption,
+          video,
+        },
+      })
+      return res
+    },
+
+    /**
+     * Sends an audio message using an HTTP URL.
+     *
+     * @param {Object} params
+     * @param {number|string} params.chatId
+     *   Chat identifier.
+     *
+     * @param {string} params.audio
+     *   Public audio URL.
+     *
+     * @param {string} [params.caption]
+     *   Optional caption.
+     *
+     * @returns {Promise<import('../../http/http.js').HttpResponse>}
+     *   Telegram API response.
+     */
+    async sendAudio({ caption, audio, chatId }) {
+      const res = await post({
+        url: APIS.SEND_AUDIO,
+        body: {
+          chat_id: chatId,
+          caption,
+          audio,
+        },
+      })
+      return res
+    },
+
+    /**
+     * Sends a document file using an HTTP URL.
+     *
+     * @param {Object} params
+     * @param {number|string} params.chatId
+     *   Chat identifier.
+     *
+     * @param {string} params.document
+     *   URL to the document file.
+     *
+     * @param {string} [params.caption]
+     *   Optional caption.
+     *
+     * @returns {Promise<import('../../http/http.js').HttpResponse>}
+     *   Telegram API response.
+     */
+    async sendDocument({ caption, document, chatId }) {
+      const res = await post({
+        url: APIS.SEND_DOCUMENT,
+        body: {
+          chat_id: chatId,
+          caption,
+          document,
+        },
+      })
+      return res
+    },
+  }
+}

package/src/instant-messages/whatsapp-apis/whatsapp-apis.js

@@ -0,0 +1,401 @@
+import { post } from '../../http/http.js'
+
+const WHATSAPP_API_BASE_URL = 'https://graph.facebook.com'
+
+/**
+ * Retrieves metadata for a WhatsApp media object.
+ *
+ * WhatsApp Cloud API does not provide the media file directly via mediaId.
+ * Instead, you must first request the metadata for the media item, which
+ * includes a temporary download URL. This URL can then be used to retrieve
+ * the actual binary content of the file.
+ *
+ * The returned metadata object typically includes:
+ * - `url`        A temporary URL that allows downloading the media file
+ * - `mime_type`  The detected MIME type of the media
+ * - `id`         The mediaId itself
+ *
+ * Example output from WhatsApp:
+ * {
+ *   "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=...",
+ *   "mime_type": "image/jpeg",
+ *   "id": "MEDIA_ID"
+ * }
+ *
+ * Note:
+ * The temporary download URL is short-lived and must be accessed quickly.
+ *
+ * @param {Object} params
+ * @param {string} params.mediaId
+ *   The media identifier received in an incoming WhatsApp webhook message.
+ *
+ * @param {string} params.token
+ *   WhatsApp Cloud API access token used for authorization.
+ *
+ * @param {string} [params.version='v21.0']
+ *   The WhatsApp Cloud API Graph version to use.
+ *
+ * @returns {Promise<Object>}
+ *   Resolves with the media metadata object containing `url`, `mime_type`, and `id`.
+ *
+ * @throws {Error}
+ *   If the metadata request fails or WhatsApp responds with a non successful status code.
+ */
+export const getWhatsAppMediaInfo = async ({
+  token,
+  mediaId,
+  version = 'v21.0',
+  baseUrl = WHATSAPP_API_BASE_URL,
+}) => {
+  const url = `${baseUrl}/${version}/${mediaId}`
+
+  const res = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+  })
+
+  if (!res.ok) {
+    throw new Error(`Failed to retrieve media info: ${res.status}`)
+  }
+
+  return res.json()
+}
+
+/**
+ * Downloads WhatsApp media and returns either a Buffer or a Stream,
+ * depending on mode.
+ *
+ * @param {Object} params
+ * @param {string} params.mediaId
+ * @param {string} params.token
+ * @param {'buffer' | 'stream'} params.mode
+ * @returns {Promise<Buffer|ReadableStream>}
+ */
+export const downloadWhatsAppMedia = async ({
+  token,
+  mediaId,
+  mode = 'buffer',
+}) => {
+  const info = await getWhatsAppMediaInfo({ mediaId, token })
+  const { url: downloadUrl } = info
+
+  const res = await fetch(downloadUrl, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+  })
+
+  if (!res.ok) {
+    throw new Error(`Failed to download media: ${res.status}`)
+  }
+
+  if (mode === 'stream') {
+    return res.body
+  }
+
+  const buffer = Buffer.from(await res.arrayBuffer())
+  return buffer
+}
+
+/**
+ * Builds the WhatsApp Cloud API messages endpoint URL.
+ *
+ * This function generates the full URL required to send messages
+ * through the WhatsApp Cloud API. It concatenates the base Graph API URL,
+ * the selected API version, and the phone number ID to produce:
+ *
+ *   https://graph.facebook.com/{version}/{phoneNumberId}/messages
+ *
+ * The returned URL can then be used for POST requests to send text,
+ * media, interactive messages, and more.
+ *
+ * @param {Object} params
+ * @param {string} params.phoneNumberId
+ *   The WhatsApp phone number ID associated with the business account.
+ *
+ * @param {string} [params.version='v21.0']
+ *   The WhatsApp Cloud API version to use. Defaults to the current stable.
+ *
+ * @param {string} [params.baseUrl=WHATSAPP_API_BASE_URL]
+ *   Optional override for the Graph API base URL (useful for testing or proxying).
+ *
+ * @returns {string}
+ *   Fully resolved WhatsApp Cloud API endpoint URL for sending messages.
+ */
+export const getWhatsAppApiUrls = ({
+  phoneNumberId,
+  version = 'v21.0',
+  baseUrl = WHATSAPP_API_BASE_URL,
+}) => `${baseUrl}/${version}/${phoneNumberId}/messages`
+
+/**
+ * Factory that creates WhatsApp Cloud API helper methods.
+ *
+ * This module wraps the WhatsApp Graph API endpoints and exposes
+ * high level functions for sending text messages, interactive buttons,
+ * images, videos, documents, and audio files.
+ *
+ * Each returned method builds the correct request format according
+ * to the WhatsApp Cloud API specification.
+ *
+ * @typedef {Object} WhatsAppApis
+ *
+ * @property {Function} sendMessage
+ *   Sends a plain text message to an individual WhatsApp user.
+ *
+ * @property {Function} sendButtonsGroup
+ *   Sends an interactive message containing buttons.
+ *
+ * @property {Function} sendPhoto
+ *   Sends an image message using a public URL.
+ *
+ * @property {Function} sendVideo
+ *   Sends a video file using a public URL.
+ *
+ * @property {Function} sendDocument
+ *   Sends a document message using a public URL.
+ *
+ * @property {Function} sendAudio
+ *   Sends an audio file using a public URL.
+ */
+
+/**
+ * Creates a WhatsApp API client bound to a specific token, phone number ID,
+ * and Graph API version.
+ *
+ * @param {Object} params
+ * @param {string} params.token
+ *   WhatsApp Cloud API access token.
+ *
+ * @param {string} params.phoneNumberId
+ *   The phone number ID from Meta Business Manager used for sending messages.
+ *
+ * @param {string} [params.version='v21.0']
+ *   WhatsApp Graph API version to use.
+ *
+ * @returns {WhatsAppApis}
+ *   A set of helper functions for interacting with the WhatsApp Cloud API.
+ */
+export const whatsappApis = ({ token, phoneNumberId, version = 'v21.0' }) => {
+  const url = getWhatsAppApiUrls({ phoneNumberId, version })
+
+  const headers = {
+    Authorization: `Bearer ${token}`,
+  }
+
+  const bodyBase = {
+    recipient_type: 'individual',
+    messaging_product: 'whatsapp',
+  }
+
+  return {
+    /**
+     * Sends a text message to an individual WhatsApp user.
+     *
+     * @param {Object} params
+     * @param {string} params.chatId
+     *   The WhatsApp number (in international format) of the recipient.
+     *
+     * @param {string} params.text
+     *   The message content to send.
+     *
+     * @param {boolean} [params.preview_url=true]
+     *   Whether URL previews should be generated automatically.
+     *
+     * @returns {Promise<import('bot-services-libs-shared').HttpResponse>}
+     *   The API response from the WhatsApp Cloud API.
+     */
+    async sendMessage({ chatId, text, preview_url = true }) {
+      const textMessage = {
+        to: chatId,
+        type: 'text',
+        text: {
+          preview_url,
+          body: text,
+        },
+      }
+
+      const res = await post({
+        url,
+        headers,
+        body: {
+          ...bodyBase,
+          ...textMessage,
+        },
+      })
+
+      return res
+    },
+
+    /**
+     * Sends an interactive buttons message to a WhatsApp user.
+     *
+     * @param {Object} params
+     * @param {string} params.chatId
+     *   The recipient phone number.
+     *
+     * @param {Object} params.buttonsBody
+     *   The full interactive object containing button definitions.
+     *   The caller is expected to pass a structure matching
+     *   WhatsApp's interactive message schema.
+     *
+     * @returns {Promise<import('bot-services-libs-shared').HttpResponse>}
+     *   The API response.
+     */
+    async sendButtonsGroup({ chatId, buttonsBody }) {
+      const res = await post({
+        url,
+        headers,
+        body: {
+          ...bodyBase,
+          to: chatId,
+          type: 'interactive',
+          ...buttonsBody,
+        },
+      })
+
+      return res
+    },
+
+    /**
+     * Sends an image message using a public URL.
+     *
+     * @param {Object} params
+     * @param {string} params.chatId
+     *   The phone number of the recipient.
+     *
+     * @param {string} params.photo
+     *   Public URL of the image.
+     *
+     * @param {string} [params.caption]
+     *   Optional caption added to the image.
+     *
+     * @returns {Promise<import('bot-services-libs-shared').HttpResponse>}
+     *   The API response.
+     */
+    async sendPhoto({ caption, photo, chatId }) {
+      const res = await post({
+        url,
+        headers,
+        body: {
+          ...bodyBase,
+          to: chatId,
+          type: 'image',
+          image: {
+            link: photo,
+            caption,
+          },
+        },
+      })
+
+      return res
+    },
+
+    /**
+     * Sends a video message using a public URL.
+     *
+     * @param {Object} params
+     * @param {string} params.chatId
+     *   Recipient phone number.
+     *
+     * @param {string} params.video
+     *   Public URL to the video file.
+     *
+     * @param {string} [params.caption]
+     *   Optional caption added to the video.
+     *
+     * @param {string} [params.filename]
+     *   Optional filename displayed to the user.
+     *
+     * @returns {Promise<import('bot-services-libs-shared').HttpResponse>}
+     *   The API response.
+     */
+    async sendVideo({ caption, video, filename, chatId }) {
+      const res = await post({
+        url,
+        headers,
+        body: {
+          ...bodyBase,
+          to: chatId,
+          type: 'video',
+          video: {
+            link: video,
+            caption,
+            ...(filename ? { filename } : null),
+          },
+        },
+      })
+
+      return res
+    },
+
+    /**
+     * Sends a document file using a public URL.
+     *
+     * @param {Object} params
+     * @param {string} params.chatId
+     *   Recipient WhatsApp number.
+     *
+     * @param {string} params.document
+     *   Public URL to the document.
+     *
+     * @param {string} [params.caption]
+     *   Optional text caption.
+     *
+     * @param {string} [params.filename]
+     *   Optional filename shown to the user.
+     *
+     * @returns {Promise<import('bot-services-libs-shared').HttpResponse>}
+     *   The API response.
+     */
+    async sendDocument({ caption, document, filename, chatId }) {
+      const res = await post({
+        url,
+        headers,
+        body: {
+          ...bodyBase,
+          to: chatId,
+          type: 'document',
+          document: {
+            link: document,
+            caption,
+            ...(filename ? { filename } : null),
+          },
+        },
+      })
+
+      return res
+    },
+
+    /**
+     * Sends an audio message using a public URL.
+     *
+     * @param {Object} params
+     * @param {string} params.chatId
+     *   The phone number of the recipient.
+     *
+     * @param {string} params.audio
+     *   Public URL to the audio file.
+     *
+     * @returns {Promise<import('bot-services-libs-shared').HttpResponse>}
+     *   The API response.
+     */
+    async sendAudio({ audio, chatId }) {
+      const res = await post({
+        url,
+        headers,
+        body: {
+          ...bodyBase,
+          to: chatId,
+          type: 'audio',
+          audio: {
+            link: audio,
+          },
+        },
+      })
+
+      return res
+    },
+  }
+}

package/tests/instant-messages/telegram-apis.unit.test.js

@@ -0,0 +1,157 @@
+// @ts-nocheck
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import {
+  getTelegramApiUrls,
+  telegramApis,
+} from '../../src/instant-messages/telegram-apis/telegram-apis.js'
+import * as httpModule from '../../src/http/http.js'
+
+describe('getTelegramApiUrls', () => {
+  it('builds correct Telegram API URLs', () => {
+    const token = 'TEST_TOKEN'
+    const urls = getTelegramApiUrls({ token })
+
+    expect(urls.SEND_MESSAGE).toBe(
+      `https://api.telegram.org/bot${token}/sendMessage`,
+    )
+    expect(urls.FORWARD_MESSAGE).toBe(
+      `https://api.telegram.org/bot${token}/forwardMessage`,
+    )
+    expect(urls.SEND_PHOTO).toBe(
+      `https://api.telegram.org/bot${token}/sendPhoto`,
+    )
+    expect(urls.GET_FILE).toBe(`https://api.telegram.org/bot${token}/getFile`)
+  })
+
+  it('supports custom base URL', () => {
+    const token = 'X'
+    const baseUrl = 'http://localhost:9999'
+    const urls = getTelegramApiUrls({ token, telegramBaseUrl: baseUrl })
+
+    expect(urls.SEND_MESSAGE).toBe(`${baseUrl}/bot${token}/sendMessage`)
+  })
+})
+
+describe('telegramApis', () => {
+  const token = 'MOCK_TOKEN'
+  let postMock
+
+  beforeEach(() => {
+    postMock = vi.spyOn(httpModule, 'post').mockResolvedValue({
+      ok: true,
+      result: 'mock-response',
+    })
+  })
+
+  it('sends text message with correct body', async () => {
+    const api = telegramApis({ token })
+    await api.sendMessage({ text: 'hello', chatId: 123 })
+
+    expect(postMock).toHaveBeenCalledWith({
+      url: `https://api.telegram.org/bot${token}/sendMessage`,
+      body: {
+        chat_id: 123,
+        text: 'hello',
+        entities: undefined,
+      },
+    })
+  })
+
+  it('sends inline keyboard buttons', async () => {
+    const api = telegramApis({ token })
+    const options = [[{ text: 'A', callback_data: '1' }]]
+
+    await api.sendButtonsGroup({
+      text: 'Choose',
+      chatId: 10,
+      options,
+    })
+
+    expect(postMock).toHaveBeenCalledWith({
+      url: `https://api.telegram.org/bot${token}/sendMessage`,
+      body: {
+        chat_id: 10,
+        text: 'Choose',
+        reply_markup: {
+          inline_keyboard: options,
+        },
+      },
+    })
+  })
+
+  it('sends a photo with caption', async () => {
+    const api = telegramApis({ token })
+
+    await api.sendPhoto({
+      chatId: 77,
+      photo: 'http://photo.jpg',
+      caption: 'hi',
+    })
+
+    expect(postMock).toHaveBeenCalledWith({
+      url: `https://api.telegram.org/bot${token}/sendPhoto`,
+      body: {
+        chat_id: 77,
+        caption: 'hi',
+        photo: 'http://photo.jpg',
+      },
+    })
+  })
+
+  it('sends a video', async () => {
+    const api = telegramApis({ token })
+
+    await api.sendVideo({
+      chatId: 55,
+      video: 'http://video.mp4',
+      caption: 'watch this',
+    })
+
+    expect(postMock).toHaveBeenCalledWith({
+      url: `https://api.telegram.org/bot${token}/sendVideo`,
+      body: {
+        chat_id: 55,
+        caption: 'watch this',
+        video: 'http://video.mp4',
+      },
+    })
+  })
+
+  it('sends an audio file', async () => {
+    const api = telegramApis({ token })
+
+    await api.sendAudio({
+      chatId: 200,
+      audio: 'http://audio.mp3',
+      caption: 'listen',
+    })
+
+    expect(postMock).toHaveBeenCalledWith({
+      url: `https://api.telegram.org/bot${token}/sendAudio`,
+      body: {
+        chat_id: 200,
+        caption: 'listen',
+        audio: 'http://audio.mp3',
+      },
+    })
+  })
+
+  it('sends a document', async () => {
+    const api = telegramApis({ token })
+
+    await api.sendDocument({
+      chatId: 999,
+      document: 'http://file.pdf',
+      caption: 'file',
+    })
+
+    expect(postMock).toHaveBeenCalledWith({
+      url: `https://api.telegram.org/bot${token}/sendDocument`,
+      body: {
+        chat_id: 999,
+        caption: 'file',
+        document: 'http://file.pdf',
+      },
+    })
+  })
+})

package/tests/instant-messages/whatsapp-apis.unit.test.js

@@ -0,0 +1,277 @@
+// @ts-nocheck
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+
+import {
+  whatsappApis,
+  getWhatsAppApiUrls,
+  getWhatsAppMediaInfo,
+  downloadWhatsAppMedia,
+} from '../../src/instant-messages/whatsapp-apis/whatsapp-apis.js'
+
+import * as httpModule from '../../src/http/http.js'
+
+global.fetch = vi.fn()
+
+describe('getWhatsAppMediaInfo', () => {
+  beforeEach(() => {
+    fetch.mockReset()
+  })
+
+  it('returns media metadata correctly', async () => {
+    const mockResponse = {
+      url: 'https://cdn.whatsapp.com/file.jpg',
+      mime_type: 'image/jpeg',
+      id: 'ABC123',
+    }
+
+    fetch.mockResolvedValue({
+      ok: true,
+      json: async () => mockResponse,
+    })
+
+    const result = await getWhatsAppMediaInfo({
+      mediaId: 'ABC123',
+      token: 'TOKEN',
+    })
+
+    expect(fetch).toHaveBeenCalledWith(
+      'https://graph.facebook.com/v21.0/ABC123',
+      {
+        headers: {
+          Authorization: 'Bearer TOKEN',
+        },
+      },
+    )
+
+    expect(result).toEqual(mockResponse)
+  })
+
+  it('throws on non successful response', async () => {
+    fetch.mockResolvedValue({
+      ok: false,
+      status: 403,
+    })
+
+    await expect(
+      getWhatsAppMediaInfo({
+        mediaId: 'MEDIA_ID',
+        token: 'TOKEN',
+      }),
+    ).rejects.toThrow('Failed to retrieve media info: 403')
+  })
+})
+
+describe('downloadWhatsAppMedia', () => {
+  beforeEach(() => {
+    fetch.mockReset()
+  })
+
+  it('downloads media as buffer', async () => {
+    const mockMetadata = {
+      url: 'https://cdn.whatsapp.com/file.jpg',
+    }
+
+    const mockBinary = new Uint8Array([10, 20, 30])
+
+    fetch
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => mockMetadata,
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        arrayBuffer: async () => mockBinary.buffer,
+      })
+
+    const buffer = await downloadWhatsAppMedia({
+      token: 'TOKEN',
+      mediaId: 'MEDIA_ID',
+      mode: 'buffer',
+    })
+
+    expect(Buffer.isBuffer(buffer)).toBe(true)
+    expect(buffer.equals(Buffer.from(mockBinary))).toBe(true)
+  })
+
+  it('returns stream when mode=stream', async () => {
+    const mockStream = { fake: 'stream' }
+
+    fetch
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ url: 'http://cdn.com/x' }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        body: mockStream,
+      })
+
+    const stream = await downloadWhatsAppMedia({
+      token: 'TOKEN',
+      mediaId: 'ID',
+      mode: 'stream',
+    })
+
+    expect(stream).toBe(mockStream)
+  })
+})
+
+describe('getWhatsAppApiUrls', () => {
+  it('generates correct messages URL', () => {
+    const url = getWhatsAppApiUrls({
+      phoneNumberId: '12345',
+      version: 'v21.0',
+    })
+
+    expect(url).toBe('https://graph.facebook.com/v21.0/12345/messages')
+  })
+
+  it('supports custom base URL', () => {
+    const url = getWhatsAppApiUrls({
+      phoneNumberId: '99',
+      baseUrl: 'http://localhost:3000',
+      version: 'v21.0',
+    })
+
+    expect(url).toBe('http://localhost:3000/v21.0/99/messages')
+  })
+})
+
+describe('whatsappApis', () => {
+  let postMock
+
+  beforeEach(() => {
+    postMock = vi
+      .spyOn(httpModule, 'post')
+      .mockResolvedValue({ ok: true, data: 'mock-response' })
+  })
+
+  const token = 'TOKEN'
+  const phoneNumberId = '111'
+
+  const baseUrl = 'https://graph.facebook.com/v21.0/111/messages'
+
+  it('sendMessage sends correct payload', async () => {
+    const api = whatsappApis({ token, phoneNumberId })
+
+    await api.sendMessage({
+      chatId: '9725000000',
+      text: 'Hello',
+    })
+
+    expect(postMock).toHaveBeenCalledWith({
+      url: baseUrl,
+      headers: { Authorization: 'Bearer TOKEN' },
+      body: {
+        recipient_type: 'individual',
+        messaging_product: 'whatsapp',
+        to: '9725000000',
+        type: 'text',
+        text: {
+          preview_url: true,
+          body: 'Hello',
+        },
+      },
+    })
+  })
+
+  it('sendPhoto sends correct body', async () => {
+    const api = whatsappApis({ token, phoneNumberId })
+
+    await api.sendPhoto({
+      chatId: '1',
+      photo: 'http://img.jpg',
+      caption: 'Hi',
+    })
+
+    expect(postMock).toHaveBeenCalledWith({
+      url: baseUrl,
+      headers: { Authorization: 'Bearer TOKEN' },
+      body: {
+        recipient_type: 'individual',
+        messaging_product: 'whatsapp',
+        to: '1',
+        type: 'image',
+        image: {
+          link: 'http://img.jpg',
+          caption: 'Hi',
+        },
+      },
+    })
+  })
+
+  it('sendVideo sends filename when provided', async () => {
+    const api = whatsappApis({ token, phoneNumberId })
+
+    await api.sendVideo({
+      chatId: '77',
+      video: 'http://video.mp4',
+      caption: 'watch',
+      filename: 'clip.mp4',
+    })
+
+    expect(postMock).toHaveBeenCalledWith({
+      url: baseUrl,
+      headers: { Authorization: 'Bearer TOKEN' },
+      body: {
+        recipient_type: 'individual',
+        messaging_product: 'whatsapp',
+        to: '77',
+        type: 'video',
+        video: {
+          link: 'http://video.mp4',
+          caption: 'watch',
+          filename: 'clip.mp4',
+        },
+      },
+    })
+  })
+
+  it('sendDocument works without filename', async () => {
+    const api = whatsappApis({ token, phoneNumberId })
+
+    await api.sendDocument({
+      chatId: '33',
+      document: 'http://file.pdf',
+      caption: 'doc',
+    })
+
+    expect(postMock).toHaveBeenCalledWith({
+      url: baseUrl,
+      headers: { Authorization: 'Bearer TOKEN' },
+      body: {
+        recipient_type: 'individual',
+        messaging_product: 'whatsapp',
+        to: '33',
+        type: 'document',
+        document: {
+          link: 'http://file.pdf',
+          caption: 'doc',
+        },
+      },
+    })
+  })
+
+  it('sendAudio sends correct structure', async () => {
+    const api = whatsappApis({ token, phoneNumberId })
+
+    await api.sendAudio({
+      chatId: '555',
+      audio: 'http://a.mp3',
+    })
+
+    expect(postMock).toHaveBeenCalledWith({
+      url: baseUrl,
+      headers: { Authorization: 'Bearer TOKEN' },
+      body: {
+        recipient_type: 'individual',
+        messaging_product: 'whatsapp',
+        to: '555',
+        type: 'audio',
+        audio: {
+          link: 'http://a.mp3',
+        },
+      },
+    })
+  })
+})

package/types/instant-messages/index.d.ts

@@ -2,3 +2,5 @@ export * from './im-platform.js'
 export * from './message-type.js'
 export * from './message-types.js'
 export * from './message-unified-mapper.js'
+export * from './telegram-apis/telegram-apis.js'
+export * from './whatsapp-apis/whatsapp-apis.js'

package/types/instant-messages/telegram-apis/telegram-apis.d.ts

@@ -0,0 +1,105 @@
+export function getTelegramApiUrls({
+  token,
+  telegramBaseUrl,
+}: {
+  token: string
+  telegramBaseUrl?: string
+}): TelegramApiUrls
+export function telegramApis({ token }: { token: string }): TelegramApis
+/**
+ * Builds a full set of Telegram Bot API endpoint URLs
+ * based on the provided bot token and an optional base URL.
+ *
+ * This helper centralizes all Telegram endpoints used by the system,
+ * making it easier to mock, override, or customize for testing environments.
+ */
+export type TelegramApiUrls = {
+  /**
+   *   URL to send a text message to a chat using the Telegram Bot API.
+   */
+  SEND_MESSAGE: string
+  /**
+   *   URL to forward an existing message from one chat to another.
+   */
+  FORWARD_MESSAGE: string
+  /**
+   *   URL to send a photo to a chat.
+   */
+  SEND_PHOTO: string
+  /**
+   *   URL to send an audio file.
+   */
+  SEND_AUDIO: string
+  /**
+   *   URL to send files such as PDF, DOC, ZIP, and others supported by Telegram.
+   */
+  SEND_DOCUMENT: string
+  /**
+   *   URL to send a sticker.
+   */
+  SEND_STICKER: string
+  /**
+   *   URL to send a video file.
+   */
+  SEND_VIDEO: string
+  /**
+   *   URL to send a voice note.
+   */
+  SEND_VOICE: string
+  /**
+   *   URL to send a geolocation point.
+   */
+  SEND_LOCATION: string
+  /**
+   *   URL to send a chat action (typing, uploading photo, etc).
+   */
+  SEND_CHAT_ACTION: string
+  /**
+   *   URL to retrieve the profile photos of a specific user.
+   */
+  GET_USER_PROFILE_PHOTOS: string
+  /**
+   *   URL to poll for new updates (not used when using webhooks).
+   */
+  GET_UPDATES: string
+  /**
+   *   URL to fetch a file path for downloading a file uploaded to Telegram servers.
+   */
+  GET_FILE: string
+}
+/**
+ * Factory that creates a set of high level Telegram Bot API helper methods.
+ *
+ * Each method sends a specific type of message (text, photo, video, document)
+ * through the Telegram Bot API using the provided bot token.
+ *
+ * This abstraction wraps the raw URL generation logic and HTTP calls,
+ * allowing higher level services to use clean method calls instead of
+ * managing endpoint URLs manually.
+ */
+export type TelegramApis = {
+  /**
+   *   Sends a text message to a specific chat.
+   */
+  sendMessage: Function
+  /**
+   *   Sends a text message with an inline keyboard button group.
+   */
+  sendButtonsGroup: Function
+  /**
+   *   Sends a photo with an optional caption.
+   */
+  sendPhoto: Function
+  /**
+   *   Sends a video with an optional caption.
+   */
+  sendVideo: Function
+  /**
+   *   Sends an audio file with an optional caption.
+   */
+  sendAudio: Function
+  /**
+   *   Sends a document file with an optional caption.
+   */
+  sendDocument: Function
+}

package/types/instant-messages/whatsapp-apis/whatsapp-apis.d.ts

@@ -0,0 +1,73 @@
+export function getWhatsAppMediaInfo({
+  token,
+  mediaId,
+  version,
+  baseUrl,
+}: {
+  mediaId: string
+  token: string
+  version?: string
+}): Promise<any>
+export function downloadWhatsAppMedia({
+  token,
+  mediaId,
+  mode,
+}: {
+  mediaId: string
+  token: string
+  mode: 'buffer' | 'stream'
+}): Promise<Buffer | ReadableStream>
+export function getWhatsAppApiUrls({
+  phoneNumberId,
+  version,
+  baseUrl,
+}: {
+  phoneNumberId: string
+  version?: string
+  baseUrl?: string
+}): string
+export function whatsappApis({
+  token,
+  phoneNumberId,
+  version,
+}: {
+  token: string
+  phoneNumberId: string
+  version?: string
+}): WhatsAppApis
+/**
+ * Factory that creates WhatsApp Cloud API helper methods.
+ *
+ * This module wraps the WhatsApp Graph API endpoints and exposes
+ * high level functions for sending text messages, interactive buttons,
+ * images, videos, documents, and audio files.
+ *
+ * Each returned method builds the correct request format according
+ * to the WhatsApp Cloud API specification.
+ */
+export type WhatsAppApis = {
+  /**
+   *   Sends a plain text message to an individual WhatsApp user.
+   */
+  sendMessage: Function
+  /**
+   *   Sends an interactive message containing buttons.
+   */
+  sendButtonsGroup: Function
+  /**
+   *   Sends an image message using a public URL.
+   */
+  sendPhoto: Function
+  /**
+   *   Sends a video file using a public URL.
+   */
+  sendVideo: Function
+  /**
+   *   Sends a document message using a public URL.
+   */
+  sendDocument: Function
+  /**
+   *   Sends an audio file using a public URL.
+   */
+  sendAudio: Function
+}