core-services-sdk 1.3.49 → 1.3.51

package/tests/ids/generators.unit.test.js

@@ -29,12 +29,25 @@ import {
   generateDeviceId,
   generateAlertId,
   generateResourceId,
+  generateRoleId,
+  generateAssetId,
+  generateAssetUploadId,
+  generateSupplierId,
+  generateInvoiceId,
+  generateInvoiceItemId,
+  generateInvoiceCorrectionId,
+  generateDocumentDataId,
+  generateEmailId,
+  generateIncomingEmailId,
+  generateImId,
+  generateBotFlowId,
 } from '../../src/ids/generators.js'
 import { ID_PREFIXES } from '../../src/ids/prefixes.js'
 
 // ULID is a 26-character Base32 string (no I, L, O, U).
 const ULID_REGEX = /^[0-9A-HJKMNP-TV-Z]{26}$/
 
+// @ts-ignore
 const testPrefixFunction = (fn, expectedPrefix) => {
   const id = fn()
   expect(typeof id).toBe('string')
@@ -91,7 +104,7 @@ describe('generate*Id functions', () => {
   })
 
   it('generateRolePermissionsId returns ID with role_ prefix', () => {
-    testPrefixFunction(generateRolePermissionsId, ID_PREFIXES.ROLE_PERMISSIONS)
+    testPrefixFunction(generateRolePermissionsId, ID_PREFIXES.ROLE_PERMISSION)
   })
 
   it('generateSessionId returns ID with sess_ prefix', () => {
@@ -169,4 +182,55 @@ describe('generate*Id functions', () => {
   it('generateResourceId returns ID with res_ prefix', () => {
     testPrefixFunction(generateResourceId, ID_PREFIXES.RESOURCE)
   })
+
+  it('generateRoleId returns ID with role_ prefix', () => {
+    testPrefixFunction(generateRoleId, ID_PREFIXES.ROLE)
+  })
+
+  it('generateAssetId returns ID with ast_ prefix', () => {
+    testPrefixFunction(generateAssetId, ID_PREFIXES.ASSET)
+  })
+
+  it('generateAssetUploadId returns ID with aupl_ prefix', () => {
+    testPrefixFunction(generateAssetUploadId, ID_PREFIXES.ASSET_UPLOAD)
+  })
+
+  it('generateSupplierId returns ID with sup_ prefix', () => {
+    testPrefixFunction(generateSupplierId, ID_PREFIXES.SUPPLIER)
+  })
+
+  it('generateInvoiceId returns ID with inv_ prefix', () => {
+    testPrefixFunction(generateInvoiceId, ID_PREFIXES.INVOICE)
+  })
+
+  it('generateInvoiceItemId returns ID with invi_ prefix', () => {
+    testPrefixFunction(generateInvoiceItemId, ID_PREFIXES.INVOICE_ITEM)
+  })
+
+  it('generateInvoiceCorrectionId returns ID with invc_ prefix', () => {
+    testPrefixFunction(
+      generateInvoiceCorrectionId,
+      ID_PREFIXES.INVOICE_CORRECTION,
+    )
+  })
+
+  it('generateDocumentDataId returns ID with docd_ prefix', () => {
+    testPrefixFunction(generateDocumentDataId, ID_PREFIXES.DOCUMENT_DATA)
+  })
+
+  it('generateEmailId returns ID with eml_ prefix', () => {
+    testPrefixFunction(generateEmailId, ID_PREFIXES.EMAIL)
+  })
+
+  it('generateIncomingEmailId returns ID with ieml_ prefix', () => {
+    testPrefixFunction(generateIncomingEmailId, ID_PREFIXES.INCOMING_EMAIL)
+  })
+
+  it('generateImId returns ID with im_ prefix', () => {
+    testPrefixFunction(generateImId, ID_PREFIXES.IM)
+  })
+
+  it('generateBotFlowId returns ID with botf_ prefix', () => {
+    testPrefixFunction(generateBotFlowId, ID_PREFIXES.BOT_FLOW)
+  })
 })

package/tests/ids/prefixes.unit.test.js

@@ -5,35 +5,44 @@ import { ID_PREFIXES } from '../../src/ids/prefixes.js'
 describe('ID_PREFIXES', () => {
   it('contains expected keys and values', () => {
     expect(ID_PREFIXES).toEqual({
-      USER: 'usr',
-      TENANT: 'tnt',
-      PERMISSION: 'prm',
+      ALERT: 'alr',
+      ASSET: 'ast',
+      ASSET_UPLOAD: 'aupl',
+      AUDIT: 'adt',
+      BOT_FLOW: 'botf',
+      CONFIG: 'cfg',
       CORRELATION: 'crln',
-      VERIFICATION: 'vrf',
-      ROLE_PERMISSIONS: 'role',
-      ONBOARDING: 'onb',
-      SESSION: 'sess',
-      FILE: 'fil',
+      DEVICE: 'dev',
+      DOCUMENT_DATA: 'docd',
+      EMAIL: 'eml',
       EVENT: 'evt',
+      FILE: 'fil',
+      IM: 'im',
+      INCOMING_EMAIL: 'ieml',
+      INVOICE: 'inv',
+      INVOICE_CORRECTION: 'invc',
+      INVOICE_ITEM: 'invi',
       JOB: 'job',
-      TASK: 'task',
-      QUEUE: 'que',
-      MESSAGE: 'msg',
-      NOTIFICATION: 'ntf',
-      LOG: 'log',
-      AUDIT: 'adt',
-      CONFIG: 'cfg',
       KEY: 'key',
+      LOG: 'log',
+      MESSAGE: 'msg',
       METRIC: 'met',
-      TAG: 'tag',
+      NOTIFICATION: 'ntf',
+      ONBOARDING: 'onb',
+      PERMISSION: 'prm',
       POLICY: 'plc',
       PROFILE: 'prf',
-      DEVICE: 'dev',
-      ALERT: 'alr',
+      QUEUE: 'que',
       RESOURCE: 'res',
-      INCOMING_EMAIL: 'ieml',
-      EMAIL: 'eml',
-      IM: 'im',
+      ROLE: 'role',
+      ROLE_PERMISSION: 'rprm',
+      SESSION: 'sess',
+      SUPPLIER: 'sup',
+      TAG: 'tag',
+      TASK: 'task',
+      TENANT: 'tnt',
+      USER: 'usr',
+      VERIFICATION: 'vrf',
     })
   })
 

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