core-services-sdk 1.3.48 → 1.3.50

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/message-types.d.ts

@@ -2,37 +2,64 @@
  * *
  */
 export type MESSAGE_MEDIA_TYPE = string
-export namespace MESSAGE_MEDIA_TYPE {
-  let TEXT: string
-  let POLL: string
-  let VIDEO: string
-  let PHOTO: string
-  let IMAGE: string
-  let VOICE: string
-  let AUDIO: string
-  let STICKER: string
-  let CONTACT: string
-  let MESSAGE: string
-  let REACTION: string
-  let DOCUMENT: string
-  let LOCATION: string
-  let CONTACTS: string
-  let VIDEO_NOTE: string
-  let BUTTON_CLICK: string
-  let BUTTON_CLICK_MULTIPLE: string
+/**
+ * Enumerates all supported incoming media/content types
+ * across messaging platforms (Telegram, WhatsApp, etc).
+ *
+ * This is the unified taxonomy used inside the system
+ * after normalization of the raw message payload.
+ *
+ * @readonly
+ * @enum {string}
+ * @type {{ [key: string]: string }}
+ *
+ * @property {"text"} TEXT
+ * @property {"poll"} POLL
+ * @property {"video"} VIDEO
+ * @property {"photo"} PHOTO
+ * @property {"image"} IMAGE
+ * @property {"voice"} VOICE
+ * @property {"audio"} AUDIO
+ * @property {"sticker"} STICKER
+ * @property {"contact"} CONTACT
+ * @property {"reaction"} REACTION
+ * @property {"document"} DOCUMENT
+ * @property {"location"} LOCATION
+ * @property {"contacts"} CONTACTS
+ * @property {"video_note"} VIDEO_NOTE
+ * @property {"button_click"} BUTTON_CLICK
+ * @property {"button_click_multiple"} BUTTON_CLICK_MULTIPLE
+ */
+export const MESSAGE_MEDIA_TYPE: {
+  [key: string]: string
 }
 /**
  * *
  */
 export type MESSAGE_TYPE = string
-export namespace MESSAGE_TYPE {
-  let MESSAGE_1: string
-  export { MESSAGE_1 as MESSAGE }
-  import BUTTON_CLICK_1 = MESSAGE_MEDIA_TYPE.BUTTON_CLICK
-  export { BUTTON_CLICK_1 as BUTTON_CLICK }
-  import BUTTON_CLICK_MULTIPLE_1 = MESSAGE_MEDIA_TYPE.BUTTON_CLICK_MULTIPLE
-  export { BUTTON_CLICK_MULTIPLE_1 as BUTTON_CLICK_MULTIPLE }
-  export let UNKNOWN_MESSAGE_TYPE: string
+/**
+ * Additional high-level message categories.
+ *
+ * These represent logical groupings rather than raw media types.
+ *
+ * @readonly
+ * @enum {string}
+ * @type {{ [key: string]: string }}
+ *
+ * @property {"message"} MESSAGE
+ *   Regular message container (base type in some providers).
+ *
+ * @property {"button_click"} BUTTON_CLICK
+ *   A click on a single interactive button.
+ *
+ * @property {"button_click_multiple"} BUTTON_CLICK_MULTIPLE
+ *   A selection from a list of interactive reply choices.
+ *
+ * @property {"unknown_message_type"} UNKNOWN_MESSAGE_TYPE
+ *   Used when the system cannot identify or normalize the message type.
+ */
+export const MESSAGE_TYPE: {
+  [key: string]: string
 }
 /**
  * *
@@ -60,3 +87,24 @@ export const MESSAGE_MEDIA_TYPE_MAPPER: {
   [MESSAGE_MEDIA_TYPE.PHOTO]: string
   [MESSAGE_MEDIA_TYPE.CONTACTS]: string
 }
+/**
+ * *
+ */
+export type UNIFIED_MESSAGE_MEDIA_TYPE = string
+/**
+ * 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: {
+  [key: string]: string
+}

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