core-services-sdk 1.3.44 → 1.3.46

package/package.json

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

package/src/ids/generators.js

@@ -223,3 +223,17 @@ export const generateResourceId = () => generatePrefixedId(ID_PREFIXES.RESOURCE)
  */
 export const generateIncomingEmailId = () =>
   generatePrefixedId(ID_PREFIXES.INCOMING_EMAIL)
+
+/**
+ * Generates a resource ID with a `eml_` prefix.
+ *
+ * @returns {string} An Email ID.
+ */
+export const generateEmailId = () => generatePrefixedId(ID_PREFIXES.EMAIL)
+
+/**
+ * Generates a resource ID with a `im_` prefix.
+ *
+ * @returns {string} An Instant Message ID.
+ */
+export const generateImId = () => generatePrefixedId(ID_PREFIXES.IM)

package/src/ids/prefixes.js

@@ -88,4 +88,10 @@ export const ID_PREFIXES = Object.freeze({
 
   /** Incoming email ID prefix */
   INCOMING_EMAIL: 'ieml',
+
+  /** Email ID prefix */
+  EMAIL: 'eml',
+
+  /** Instant Message ID prefix */
+  IM: 'im',
 })

package/src/index.js

@@ -9,3 +9,4 @@ export * from './mailer/index.js'
 export * from './rabbit-mq/index.js'
 export * from './templates/index.js'
 export * from './util/index.js'
+export * from './instant-messages/index.js'

package/src/instant-messages/im-platform.js

@@ -0,0 +1,18 @@
+/**
+
+Supported instant-messaging application identifiers.
+
+Used across the system to determine which message-mapper,
+
+parser, and processing logic to apply (Telegram vs WhatsApp).
+
+@enum {string}
+
+@property {"telegram"} TELEGRAM - Telegram Bot API messages
+
+@property {"whatsapp"} WHATSAPP - WhatsApp Business API messages
+*/
+export const IM_PLATFORM = {
+  TELEGRAM: 'telegram',
+  WHATSAPP: 'whatsapp',
+}

package/src/instant-messages/index.js

@@ -0,0 +1,4 @@
+export * from './im-platform.js'
+export * from './message-type.js'
+export * from './message-types.js'
+export * from './message-unified-mapper.js'

package/src/instant-messages/message-type.js

@@ -0,0 +1,153 @@
+import { MESSAGE_MEDIA_TYPE, MESSAGE_TYPE } from './message-types.js'
+
+/**
+ * Creates a predicate that checks whether a given media type exists
+ * inside the platform-original message object.
+ *
+ * @param {string} mediaType - One of MESSAGE_MEDIA_TYPE.*
+ * @returns {(params: { originalMessage: any }) => boolean}
+ */
+export const isItMediaType =
+  (mediaType) =>
+  ({ originalMessage }) => {
+    const message = originalMessage?.message
+    if (!message || typeof message !== 'object') {
+      return false
+    }
+    return mediaType in message
+  }
+
+/**
+ * Creates a predicate that checks whether the normalized `type`
+ * of the incoming platform message equals a given expected type.
+ *
+ * @function isMessageTypeof
+ * @param {string} typeOfMessage - One of the MESSAGE_TYPE.* values.
+ * @returns {(params: { originalMessage: any }) => boolean}
+ * A function that accepts an object containing `originalMessage`
+ * and returns true if its `type` matches the expected type.
+ */
+export const isMessageTypeof =
+  (typeOfMessage) =>
+  ({ originalMessage }) => {
+    const type = originalMessage?.type
+    return type === typeOfMessage
+  }
+
+/**
+ * Detects Telegram interactive "callback_query" messages.
+ *
+ * These represent button clicks on inline keyboards.
+ *
+ * @function isCallbackQuery
+ * @param {Object} params
+ * @param {Object} params.originalMessage - Raw Telegram update
+ * @returns {boolean}
+ */
+export const isCallbackQuery = ({ originalMessage }) => {
+  return 'callback_query' in originalMessage
+}
+
+// Media-type detectors for each supported message detail section.
+// Telegram/WhatsApp provide different fields; these predicate utilities
+// allow consistent detection used inside getTelegramMessageType().
+
+export const isItPoll = isItMediaType(MESSAGE_MEDIA_TYPE.POLL)
+export const isItMessage = isMessageTypeof(MESSAGE_TYPE.MESSAGE)
+export const isItVoice = isItMediaType(MESSAGE_MEDIA_TYPE.VOICE)
+export const isItVideo = isItMediaType(MESSAGE_MEDIA_TYPE.VIDEO)
+export const isItPhoto = isItMediaType(MESSAGE_MEDIA_TYPE.PHOTO)
+export const isItFreeText = isItMediaType(MESSAGE_MEDIA_TYPE.TEXT)
+export const isItSticker = isItMediaType(MESSAGE_MEDIA_TYPE.STICKER)
+export const isItContact = isItMediaType(MESSAGE_MEDIA_TYPE.CONTACT)
+export const isItLocation = isItMediaType(MESSAGE_MEDIA_TYPE.LOCATION)
+export const isItDocument = isItMediaType(MESSAGE_MEDIA_TYPE.DOCUMENT)
+export const isItVideoNote = isItMediaType(MESSAGE_MEDIA_TYPE.VIDEO_NOTE)
+export const isItButtonClick = isMessageTypeof(MESSAGE_TYPE.BUTTON_CLICK)
+
+/**
+ * Determines a normalized unified message type based on the raw platform update
+ * structure received from Telegram or WhatsApp.
+ *
+ * The resolution order:
+ * 1. Callback button click (Telegram inline keyboard)
+ * 2. Standard media checks (text, photo, video, etc.)
+ * 3. Special formats (polls, video notes, contacts, forwarded messages)
+ * 4. Fallback to UNKNOWN_MESSAGE_TYPE
+ *
+ * @function getTelegramMessageType
+ * @param {Object} params
+ * @param {Object} params.originalMessage - Raw update object from Telegram or WhatsApp.
+ *   For Telegram:
+ *     - May contain: message, callback_query, poll, etc.
+ *   For WhatsApp:
+ *     - Normalized structure after base extraction: { type, message, ... }
+ * @returns {string}
+ *   Returns one of:
+ *   - MESSAGE_MEDIA_TYPE.* (text, photo, video, document, ...)
+ *   - MESSAGE_TYPE.BUTTON_CLICK
+ *   - MESSAGE_TYPE.UNKNOWN_MESSAGE_TYPE
+ *
+ * @example
+ * getTelegramMessageType({ originalMessage: telegramUpdate })
+ * // → "text"
+ *
+ * @example
+ * getTelegramMessageType({ originalMessage: whatsappPayload })
+ * // → "image"
+ */
+export const getTelegramMessageType = ({ originalMessage }) => {
+  switch (true) {
+    case isCallbackQuery({ originalMessage }): {
+      return MESSAGE_TYPE.BUTTON_CLICK
+    }
+
+    case isItFreeText({ originalMessage }): {
+      return MESSAGE_MEDIA_TYPE.TEXT
+    }
+
+    case isItVideo({ originalMessage }): {
+      return MESSAGE_MEDIA_TYPE.VIDEO
+    }
+
+    case isItPhoto({ originalMessage }): {
+      return MESSAGE_MEDIA_TYPE.PHOTO
+    }
+
+    case isItDocument({ originalMessage }): {
+      return MESSAGE_MEDIA_TYPE.DOCUMENT
+    }
+
+    case isItLocation({ originalMessage }): {
+      return MESSAGE_MEDIA_TYPE.LOCATION
+    }
+
+    case isItVoice({ originalMessage }): {
+      return MESSAGE_MEDIA_TYPE.VOICE
+    }
+
+    case isItVideoNote({ originalMessage }): {
+      return MESSAGE_MEDIA_TYPE.VIDEO_NOTE
+    }
+
+    case isItPoll({ originalMessage }): {
+      return MESSAGE_MEDIA_TYPE.POLL
+    }
+
+    case isItSticker({ originalMessage }): {
+      return MESSAGE_MEDIA_TYPE.STICKER
+    }
+
+    case isItMessage({ originalMessage }): {
+      return MESSAGE_MEDIA_TYPE.MESSAGE
+    }
+
+    case isItContact({ originalMessage }): {
+      return MESSAGE_MEDIA_TYPE.CONTACT
+    }
+
+    default: {
+      return MESSAGE_TYPE.UNKNOWN_MESSAGE_TYPE
+    }
+  }
+}

package/src/instant-messages/message-types.js

@@ -0,0 +1,127 @@
+/**
+ * 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}
+ *
+ * @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',
+  POLL: 'poll',
+  VIDEO: 'video',
+  PHOTO: 'photo',
+  IMAGE: 'image',
+  VOICE: 'voice',
+  AUDIO: 'audio',
+  STICKER: 'sticker',
+  CONTACT: 'contact',
+  MESSAGE: 'message',
+  REACTION: 'reaction',
+  DOCUMENT: 'document',
+  LOCATION: 'location',
+  CONTACTS: 'contacts',
+  VIDEO_NOTE: 'video_note',
+  BUTTON_CLICK: 'button_click',
+  BUTTON_CLICK_MULTIPLE: 'button_click_multiple',
+}
+
+/**
+ * Additional high-level message categories.
+ *
+ * These represent logical groupings rather than raw media types.
+ *
+ * @readonly
+ * @enum {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 = {
+  MESSAGE: 'message',
+  BUTTON_CLICK: MESSAGE_MEDIA_TYPE.BUTTON_CLICK,
+  BUTTON_CLICK_MULTIPLE: MESSAGE_MEDIA_TYPE.BUTTON_CLICK_MULTIPLE,
+  UNKNOWN_MESSAGE_TYPE: 'unknown_message_type',
+}
+
+/**
+ * Maps platform-specific message types into the unified equivalents.
+ *
+ * This is used to convert raw provider terminology into internal naming.
+ *
+ * @readonly
+ * @enum {string}
+ *
+ * @property {"audio"} VOICE
+ *   Telegram's "voice" is normalized into the system's AUDIO type.
+ *
+ * @property {"image"} PHOTO
+ *   Telegram's "photo" array is normalized into IMAGE.
+ *
+ * @property {"contact"} CONTACTS
+ *   WhatsApp's "contacts" array is normalized into CONTACT.
+ */
+export const MESSAGE_MEDIA_TYPE_MAPPER = {
+  [MESSAGE_MEDIA_TYPE.VOICE]: MESSAGE_MEDIA_TYPE.AUDIO,
+  [MESSAGE_MEDIA_TYPE.PHOTO]: MESSAGE_MEDIA_TYPE.IMAGE,
+  [MESSAGE_MEDIA_TYPE.CONTACTS]: MESSAGE_MEDIA_TYPE.CONTACT,
+}

package/src/instant-messages/message-unified-mapper.js

@@ -0,0 +1,251 @@
+import { IM_PLATFORM } from './im-platform.js'
+import { getTelegramMessageType } from './message-type.js'
+import {
+  MESSAGE_TYPE,
+  MESSAGE_MEDIA_TYPE,
+  MESSAGE_MEDIA_TYPE_MAPPER,
+} from './message-types.js'
+
+const INTERACTIVE_MAPPER = {
+  button_reply: MESSAGE_TYPE.BUTTON_CLICK,
+  list_reply: MESSAGE_TYPE.BUTTON_CLICK_MULTIPLE,
+}
+/**
+ * Universal message type resolver.
+ *
+ * Detects whether the message is Telegram or WhatsApp automatically,
+ * and delegates to the correct internal resolver.
+ *
+ * @param {Object} params
+ * @param {Object} params.originalMessage - Raw message payload
+ * @returns {string} Unified message type
+ */
+export const getMessageType = ({ originalMessage }) => {
+  if (!originalMessage || typeof originalMessage !== 'object') {
+    return MESSAGE_TYPE.UNKNOWN_MESSAGE_TYPE
+  }
+
+  // Telegram format
+  if (
+    'update_id' in originalMessage ||
+    'message' in originalMessage ||
+    'callback_query' in originalMessage
+  ) {
+    return getTelegramMessageType({ originalMessage })
+  }
+
+  // WhatsApp format
+  const entry = originalMessage?.entry?.[0]
+  const change = entry?.changes?.[0]
+  const message = change?.value?.messages?.[0]
+
+  if (message) {
+    return getWhatsAppMessageType({ message })
+  }
+
+  return MESSAGE_TYPE.UNKNOWN_MESSAGE_TYPE
+}
+
+export const mapMessageTelegramBase = ({ originalMessage }) => {
+  const { callback_query, message, update_id } = originalMessage
+  const messageData = callback_query?.message || message
+  const { chat, date, from, message_id } = messageData
+  const type = getTelegramMessageType({ originalMessage })
+  const typeMapped = MESSAGE_MEDIA_TYPE_MAPPER[type] || type
+  const { forward_date, forward_from } = messageData
+  const itIsForward = !!(forward_date && forward_from)
+
+  const messageBase = {
+    id: update_id,
+    imExtraInfo: {
+      tmId: message_id,
+    },
+    chatId: chat.id,
+    type: typeMapped,
+    chatter: {
+      ...from,
+      id: chat.id,
+      name: `${chat.first_name} ${chat.last_name}`,
+      username: chat.username,
+    },
+    itIsForward,
+    ...(itIsForward ? { forwardInfo: { forward_date, forward_from } } : null),
+    timestamp: `${date}`,
+  }
+  return { messageBase, message: messageData, type }
+}
+
+export const mapMessageWhatsAppContent = ({ message, type }) => {
+  switch (type) {
+    case MESSAGE_MEDIA_TYPE.TEXT:
+      return {
+        text: message.text?.body,
+      }
+    case MESSAGE_MEDIA_TYPE.IMAGE:
+    case MESSAGE_MEDIA_TYPE.VIDEO:
+    case MESSAGE_MEDIA_TYPE.AUDIO:
+    case MESSAGE_MEDIA_TYPE.STICKER:
+    case MESSAGE_MEDIA_TYPE.LOCATION:
+    case MESSAGE_MEDIA_TYPE.REACTION:
+      return {
+        [type]: message[type],
+      }
+    case MESSAGE_MEDIA_TYPE.DOCUMENT:
+      return {
+        [type]: message[type],
+      }
+    case MESSAGE_MEDIA_TYPE.CONTACTS:
+      return {
+        [MESSAGE_MEDIA_TYPE.CONTACT]: message[type],
+      }
+    case MESSAGE_MEDIA_TYPE.BUTTON_CLICK:
+      const { interactive } = message
+      const { button_reply } = interactive
+      return {
+        reply: button_reply,
+      }
+    case MESSAGE_MEDIA_TYPE.BUTTON_CLICK_MULTIPLE:
+      const { interactive: interactiveMultiple } = message
+      const { list_reply } = interactiveMultiple
+      return {
+        reply: list_reply,
+      }
+    default:
+      return {}
+  }
+}
+
+export const mapMessageTelegram = ({ originalMessage }) => {
+  const { messageBase, type, message } = mapMessageTelegramBase({
+    originalMessage,
+  })
+  const messageContent = mapMessageTelegramContent({
+    type,
+    message,
+    originalMessage,
+  })
+  const messageMapped = { ...messageBase, ...messageContent }
+  return messageMapped
+}
+
+export const getWhatsAppMessageType = ({ message }) => {
+  const { type } = message
+  switch (type) {
+    case 'interactive': {
+      const { interactive } = message
+      return INTERACTIVE_MAPPER[interactive.type] || interactive.type
+    }
+    default:
+      return type
+  }
+}
+
+export const extractReply = ({ originalMessage }) => {
+  const { callback_query } = originalMessage
+  const { data: id, message } = callback_query
+  const {
+    reply_markup: { inline_keyboard },
+  } = message
+  const buttonsFlat = inline_keyboard.reduce((buttons, button) => {
+    return buttons.concat(button.flat())
+  }, [])
+  const { text: title } = buttonsFlat.find(
+    (button) => button.callback_data === id,
+  )
+
+  return { id, title }
+}
+export const whatsappBaseExtraction = ({ originalMessage }) => {
+  const {
+    entry: [{ changes, id }],
+  } = originalMessage
+  const [change] = changes
+  const { field, value } = change
+  return { field, value, wbaid: id }
+}
+
+export const mapMessageWhatsAppBase = ({ originalMessage }) => {
+  const { field, value, wbaid } = whatsappBaseExtraction({ originalMessage })
+  const { [field]: messages, contacts } = value
+  const [message] = messages
+  const [contact] = contacts
+  const { id, from, timestamp, context } = message
+  const type = getWhatsAppMessageType({ message })
+  const messageBase = {
+    id: id,
+    chatId: from,
+    imExtraInfo: {
+      wbaid,
+    },
+    type,
+    chatter: {
+      id: from,
+      name: contacts[0].profile.name,
+      username: contact.wa_id,
+    },
+    itIsForward: !!context?.forwarded,
+    timestamp: timestamp,
+  }
+
+  return { messageBase, message, contact, context }
+}
+
+export const mapMessageTelegramContent = ({
+  type,
+  message,
+  originalMessage,
+}) => {
+  switch (type) {
+    case MESSAGE_MEDIA_TYPE.TEXT:
+      return {
+        text: message.text,
+      }
+    case MESSAGE_MEDIA_TYPE.PHOTO:
+    case MESSAGE_MEDIA_TYPE.VOICE:
+      return {
+        [MESSAGE_MEDIA_TYPE_MAPPER[type] || type]: message[type],
+      }
+    case MESSAGE_MEDIA_TYPE.POLL:
+    case MESSAGE_MEDIA_TYPE.VIDEO:
+    case MESSAGE_MEDIA_TYPE.STICKER:
+    case MESSAGE_MEDIA_TYPE.CONTACT:
+    case MESSAGE_MEDIA_TYPE.LOCATION:
+    case MESSAGE_MEDIA_TYPE.VIDEO_NOTE:
+      return {
+        [type]: message[type],
+      }
+    case MESSAGE_MEDIA_TYPE.DOCUMENT:
+      const { animation } = message
+      return {
+        [type]: message[type],
+        ...(animation ? { animation } : null),
+        ...(animation ? { attachment: 'animation' } : null),
+      }
+    case MESSAGE_MEDIA_TYPE.BUTTON_CLICK:
+      const reply = extractReply({ originalMessage })
+      return {
+        reply,
+      }
+    default:
+      return {}
+  }
+}
+
+export const mapMessageWhatsApp = ({ originalMessage }) => {
+  const { messageBase, message, context } = mapMessageWhatsAppBase({
+    originalMessage,
+  })
+  const { type } = messageBase
+  const messageContent = mapMessageWhatsAppContent({
+    type,
+    message,
+    context,
+  })
+
+  return { ...messageBase, ...messageContent }
+}
+
+export const messageUnifiedMapper = {
+  [IM_PLATFORM.TELEGRAM]: mapMessageTelegram,
+  [IM_PLATFORM.WHATSAPP]: mapMessageWhatsApp,
+}

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

@@ -31,7 +31,9 @@ describe('ID_PREFIXES', () => {
       DEVICE: 'dev',
       ALERT: 'alr',
       RESOURCE: 'res',
-      INCOMING_EMAIL: 'ieml', // ✅ added
+      INCOMING_EMAIL: 'ieml',
+      EMAIL: 'eml',
+      IM: 'im',
     })
   })
 

package/tests/instant-messages/applications.unit.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest'
+import { IM_PLATFORM } from '../../src/instant-messages/im-platform.js'
+
+describe('IM_PLATFORM enum', () => {
+  it('should expose the expected keys', () => {
+    expect(IM_PLATFORM).toHaveProperty('TELEGRAM')
+    expect(IM_PLATFORM).toHaveProperty('WHATSAPP')
+  })
+
+  it('should map keys to correct string values', () => {
+    expect(IM_PLATFORM.TELEGRAM).toBe('telegram')
+    expect(IM_PLATFORM.WHATSAPP).toBe('whatsapp')
+  })
+
+  it('should contain exactly two entries and nothing else', () => {
+    expect(Object.keys(IM_PLATFORM).length).toBe(2)
+    expect(Object.values(IM_PLATFORM)).toContain('telegram')
+    expect(Object.values(IM_PLATFORM)).toContain('whatsapp')
+  })
+
+  it('should not allow undefined application identifiers', () => {
+    const allowed = Object.values(IM_PLATFORM)
+    expect(allowed.includes('signal')).toBe(false)
+    expect(allowed.includes('viber')).toBe(false)
+    expect(allowed.includes('sms')).toBe(false)
+  })
+})