core-services-sdk 1.3.48 → 1.3.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.48",
+  "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/message-types.js

@@ -7,54 +7,24 @@
  *
  * @readonly
  * @enum {string}
+ * @type {{ [key: string]: string }}
  *
  * @property {"text"} TEXT
- *   Represents plain text content.
- *
  * @property {"poll"} POLL
- *   Represents a Telegram poll (multiple-choice question).
- *
  * @property {"video"} VIDEO
- *   Represents a standard video file.
- *
  * @property {"photo"} PHOTO
- *   Represents a Telegram “photo” array (before mapping to IMAGE).
- *
  * @property {"image"} IMAGE
- *   Represents an image file (after normalization).
- *
  * @property {"voice"} VOICE
- *   Represents Telegram's "voice" messages (OGG encoded voice notes).
- *
  * @property {"audio"} AUDIO
- *   Represents general audio files (WhatsApp voice notes, audio uploads).
- *
  * @property {"sticker"} STICKER
- *   Represents sticker messages (Telegram or WhatsApp).
- *
  * @property {"contact"} CONTACT
- *   Represents a shared contact card.
- *
  * @property {"reaction"} REACTION
- *   Represents WhatsApp/Telegram reactions (emojis on messages).
- *
  * @property {"document"} DOCUMENT
- *   Represents generic uploaded files, including PDFs.
- *
  * @property {"location"} LOCATION
- *   Represents geographic coordinates.
- *
  * @property {"contacts"} CONTACTS
- *   Represents WhatsApp contacts array (before mapping to CONTACT).
- *
  * @property {"video_note"} VIDEO_NOTE
- *   Represents Telegram's circular "video note".
- *
  * @property {"button_click"} BUTTON_CLICK
- *   Represents a button press (interactive replies).
- *
  * @property {"button_click_multiple"} BUTTON_CLICK_MULTIPLE
- *   Represents list/menu selection (e.g., WhatsApp list_reply).
  */
 export const MESSAGE_MEDIA_TYPE = {
   TEXT: 'text',
@@ -75,7 +45,6 @@ export const MESSAGE_MEDIA_TYPE = {
   BUTTON_CLICK: 'button_click',
   BUTTON_CLICK_MULTIPLE: 'button_click_multiple',
 }
-
 /**
  * Additional high-level message categories.
  *
@@ -83,6 +52,7 @@ export const MESSAGE_MEDIA_TYPE = {
  *
  * @readonly
  * @enum {string}
+ * @type {{ [key: string]: string }}
  *
  * @property {"message"} MESSAGE
  *   Regular message container (base type in some providers).
@@ -125,3 +95,27 @@ export const MESSAGE_MEDIA_TYPE_MAPPER = {
   [MESSAGE_MEDIA_TYPE.PHOTO]: MESSAGE_MEDIA_TYPE.IMAGE,
   [MESSAGE_MEDIA_TYPE.CONTACTS]: MESSAGE_MEDIA_TYPE.CONTACT,
 }
+
+/**
+ * Unified message media types based on existing MESSAGE_MEDIA_TYPE and MESSAGE_TYPE.
+ *
+ * This enum flattens and merges all raw message media types
+ * into a single canonical type list.
+ *
+ * VOICE → AUDIO
+ * PHOTO → IMAGE
+ * CONTACTS → CONTACT
+ *
+ * @readonly
+ * @enum {string}
+ * @type {{ [key: string]: string }}
+ */
+export const UNIFIED_MESSAGE_MEDIA_TYPE = {
+  ...MESSAGE_MEDIA_TYPE,
+  ...MESSAGE_TYPE,
+
+  // Normalized equivalents
+  AUDIO: MESSAGE_MEDIA_TYPE.AUDIO,
+  IMAGE: MESSAGE_MEDIA_TYPE.IMAGE,
+  CONTACT: MESSAGE_MEDIA_TYPE.CONTACT,
+}

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
+    },
+  }
+}