@omnizap-system/omnizap 2.6.1 → 2.6.3

package/app/configParts/baileysConfig.js

@@ -13,20 +13,177 @@ import path from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { Readable } from 'node:stream';
 import { fileURLToPath } from 'node:url';
-
+import { getMultiSessionRuntimeConfig } from './sessionConfig.js';
+
+/**
+ * Utilitários centrais de integração com Baileys.
+ *
+ * Responsabilidades deste módulo:
+ * - validar/normalizar JIDs e tipos de presença;
+ * - encapsular chamadas seguras no socket ativo;
+ * - extrair/detectar mídia em mensagens;
+ * - resolver mapeamento LID <-> JID com cache e persistência.
+ */
+
+/**
+ * @typedef {import('@whiskeysockets/baileys').WASocket} BaileysSocket
+ * @typedef {import('@whiskeysockets/baileys').WAMessage} BaileysMessage
+ * @typedef {import('@whiskeysockets/baileys').WAProto.IMessage} BaileysProtoMessage
+ * @typedef {'lid'|'pn'} AddressingMode
+ * @typedef {{includeAllTypes?: boolean, includeQuoted?: boolean, includeUnknown?: boolean}} MediaExtractionOptions
+ * @typedef {{
+ *   mediaType: string,
+ *   mediaKey: Record<string, any>,
+ *   messageKey: string,
+ *   isQuoted: boolean,
+ *   isBinary: boolean,
+ *   isUnknownType?: boolean,
+ *   hasUrl: boolean,
+ *   hasDirectPath: boolean,
+ *   hasMediaKey: boolean,
+ *   hasFileEncSha256: boolean,
+ *   mimetype: string|null,
+ *   fileLength: number|string|null,
+ *   fileName: string|null,
+ *   caption: string|null
+ * }} MediaEntry
+ * @typedef {{
+ *   mediaType: string,
+ *   mediaKey: Record<string, any>,
+ *   isQuoted: boolean,
+ *   details: {
+ *     messageKey: string,
+ *     isBinary: boolean,
+ *     isUnknownType?: boolean,
+ *     hasUrl: boolean,
+ *     hasDirectPath: boolean,
+ *     hasMediaKey: boolean,
+ *     hasFileEncSha256: boolean,
+ *     mimetype: string|null,
+ *     fileLength: number|string|null,
+ *     fileName: string|null,
+ *     caption: string|null,
+ *     allMediaFound: MediaEntry[]|null
+ *   }
+ * }} MediaExtractionResult
+ * @typedef {{lid?: string|null, jid?: string|null, participantAlt?: string|null}} IdentityParams
+ * @typedef {{jid: string|null, expiresAt: number, lastStoredAt: number|null}} LidCacheEntry
+ * @typedef {{
+ *   lid: string|null,
+ *   jid: string|null,
+ *   participantAlt: string|null,
+ *   remoteJid: string|null,
+ *   remoteJidAlt: string|null,
+ *   groupMessage: boolean
+ * }} SenderInfo
+ */
+
+/**
+ * Versão local de fallback do Baileys.
+ * @type {number[]}
+ */
 const DEFAULT_BAILEYS_VERSION = [7, 0, 0];
+const multiSessionRuntimeConfig = getMultiSessionRuntimeConfig();
+const PRIMARY_BAILEYS_SESSION_ID = String(multiSessionRuntimeConfig?.primarySessionId || process.env.BAILEYS_AUTH_SESSION_ID || 'default').trim() || 'default';
+
+/**
+ * Normaliza ID de sessão com fallback para sessão primária.
+ * @param {string|null|undefined} sessionId
+ * @returns {string}
+ */
+const normalizeSessionId = (sessionId) => {
+  const normalized = String(sessionId || '').trim();
+  return normalized || PRIMARY_BAILEYS_SESSION_ID;
+};
 
+/**
+ * Mapa de sockets ativos por sessão.
+ * @type {Map<string, BaileysSocket>}
+ */
+const sessionSocketMap = new Map();
 let activeSocket = null;
 
-export const setActiveSocket = (socket) => {
-  activeSocket = socket;
+/**
+ * Atualiza a referência global do socket ativo e o registro por sessão.
+ * Mantém compatibilidade com chamadas legadas que não informam `sessionId`.
+ * @param {BaileysSocket|null} socket Instância conectada ou `null` para limpar.
+ * @param {string} [sessionId=PRIMARY_BAILEYS_SESSION_ID] Sessão da conexão.
+ * @returns {void}
+ */
+export const setActiveSocket = (socket, sessionId = PRIMARY_BAILEYS_SESSION_ID) => {
+  const safeSessionId = normalizeSessionId(sessionId);
+  const previousSocket = sessionSocketMap.get(safeSessionId) || null;
+
+  if (socket) {
+    sessionSocketMap.set(safeSessionId, socket);
+  } else {
+    sessionSocketMap.delete(safeSessionId);
+  }
+
+  if (safeSessionId === PRIMARY_BAILEYS_SESSION_ID) {
+    activeSocket = socket || null;
+  } else if (!socket && previousSocket && activeSocket === previousSocket) {
+    activeSocket = null;
+  }
+
+  if (!activeSocket) {
+    activeSocket = sessionSocketMap.get(PRIMARY_BAILEYS_SESSION_ID) || sessionSocketMap.values().next()?.value || null;
+  }
+};
+
+/**
+ * Atualiza o socket ativo de uma sessão específica.
+ * @param {string} sessionId Sessão alvo.
+ * @param {BaileysSocket|null} socket Instância conectada ou `null`.
+ * @returns {void}
+ */
+export const setSocketBySession = (sessionId, socket) => {
+  setActiveSocket(socket, sessionId);
+};
+
+/**
+ * Retorna a instância de socket ativa no processo.
+ * @returns {BaileysSocket|null}
+ */
+export const getActiveSocket = () => {
+  if (isSocketOpen(activeSocket)) return activeSocket;
+
+  const primarySocket = sessionSocketMap.get(PRIMARY_BAILEYS_SESSION_ID) || null;
+  if (isSocketOpen(primarySocket)) {
+    activeSocket = primarySocket;
+    return activeSocket;
+  }
+
+  for (const socket of sessionSocketMap.values()) {
+    if (isSocketOpen(socket)) {
+      activeSocket = socket;
+      return activeSocket;
+    }
+  }
+
+  activeSocket = null;
+  return activeSocket;
+};
+
+/**
+ * Retorna o socket ativo associado a uma sessão.
+ * @param {string} [sessionId=PRIMARY_BAILEYS_SESSION_ID]
+ * @returns {BaileysSocket|null}
+ */
+export const getSocketBySession = (sessionId = PRIMARY_BAILEYS_SESSION_ID) => {
+  const safeSessionId = normalizeSessionId(sessionId);
+  return sessionSocketMap.get(safeSessionId) || null;
 };
 
-export const getActiveSocket = () => activeSocket;
+/**
+ * Snapshot dos sockets ativos por sessão.
+ * @returns {Map<string, BaileysSocket>}
+ */
+export const getActiveSocketsBySession = () => new Map(sessionSocketMap);
 
 /**
  * Indica se uma instância de socket está aberta para operações.
- * @param {object|null|undefined} socket Instância de socket.
+ * @param {BaileysSocket|null|undefined} socket Instância de socket.
  * @returns {boolean}
  */
 export const isSocketOpen = (socket) => {
@@ -43,7 +200,7 @@ export const isActiveSocketOpen = () => isSocketOpen(activeSocket);
 
 /**
  * Executa um método em uma instância de socket validando disponibilidade.
- * @param {object|null|undefined} socket Instância de socket.
+ * @param {BaileysSocket|null|undefined} socket Instância de socket.
  * @param {string} methodName Nome do método no socket.
  * @param {...any} args Argumentos do método.
  * @returns {Promise<any>}
@@ -69,9 +226,18 @@ export const runSocketMethod = async (socket, methodName, ...args) => {
  */
 export const runActiveSocketMethod = async (methodName, ...args) => runSocketMethod(activeSocket, methodName, ...args);
 
+/**
+ * Executa um método no socket de uma sessão específica.
+ * @param {string} sessionId Sessão alvo.
+ * @param {string} methodName Nome do método no socket.
+ * @param {...any} args Argumentos do método.
+ * @returns {Promise<any>}
+ */
+export const runSessionSocketMethod = async (sessionId, methodName, ...args) => runSocketMethod(getSocketBySession(sessionId), methodName, ...args);
+
 /**
  * Recupera a blocklist da conta conectada.
- * @returns {Promise<(string|undefined)[]>}
+ * @returns {Promise<string[]>}
  */
 export const fetchBlocklistFromActiveSocket = async () => runActiveSocketMethod('fetchBlocklist');
 
@@ -112,6 +278,10 @@ export const WHATSAPP_USER_JID_SERVERS = new Set(['s.whatsapp.net', 'c.us', 'hos
  */
 export const LID_USER_JID_SERVERS = new Set(['lid', 'hosted.lid']);
 
+/**
+ * Decode de JID com cache simples do último valor.
+ * @type {(jid: string) => ({user?: string, server?: string, domainType?: number, device?: number}|null)}
+ */
 const decodeJidParts = (() => {
   let lastJid = null;
   let lastDecoded = null;
@@ -128,7 +298,8 @@ const decodeJidParts = (() => {
 
 /**
  * Tipos de mensagem conhecidos do Baileys
- * Mapeamento de chaves do proto.Message para tipos normalizados
+ * (mapeamento de chaves do proto.Message para tipos normalizados).
+ * @type {Record<string, string>}
  */
 export const MEDIA_TYPE_MAPPING = {
   conversation: 'text',
@@ -182,14 +353,25 @@ export const MEDIA_TYPE_MAPPING = {
 };
 
 /**
- * Tipos de midia que contem conteudo binario/arquivo
+ * Tipos de mídia que carregam conteúdo binário/arquivo.
+ * @type {Set<string>}
  */
 export const BINARY_MEDIA_TYPES = new Set(['image', 'video', 'videoNote', 'audio', 'voice', 'document', 'sticker']);
 
+/**
+ * Aplica normalização nativa do Baileys no payload de mensagem.
+ * @param {Record<string, any>} message
+ * @returns {Record<string, any>}
+ */
 const normalizeMessage = (message) => normalizeMessageContent(message) || message;
 
 const MESSAGE_CONTENT_WRAPPER_KEYS = ['ephemeralMessage', 'viewOnceMessage', 'viewOnceMessageV2', 'viewOnceMessageV2Extension', 'deviceSentMessage', 'documentWithCaptionMessage', 'botInvokeMessage', 'editedMessage', 'keepInChatMessage'];
 
+/**
+ * Resolve wrapper de mensagem de um nó com chave única.
+ * @param {Record<string, any>} node
+ * @returns {Record<string, any>|null}
+ */
 const resolveSingleWrapperMessage = (node) => {
   if (!node || typeof node !== 'object') return null;
 
@@ -204,6 +386,12 @@ const resolveSingleWrapperMessage = (node) => {
   return null;
 };
 
+/**
+ * Remove camadas de wrappers (`ephemeral`, `viewOnce`, etc.) até o payload real.
+ * @param {Record<string, any>} message
+ * @param {number} [maxDepth=8]
+ * @returns {Record<string, any>}
+ */
 const unwrapMessageContent = (message, maxDepth = 8) => {
   let current = normalizeMessage(message);
   const visited = new Set();
@@ -237,6 +425,11 @@ const unwrapMessageContent = (message, maxDepth = 8) => {
   return current || message;
 };
 
+/**
+ * Verifica se uma mediaKey está presente e não vazia.
+ * @param {unknown} mediaKey
+ * @returns {boolean}
+ */
 const hasNonEmptyMediaKey = (mediaKey) => {
   if (!mediaKey) return false;
 
@@ -262,6 +455,15 @@ const hasNonEmptyMediaKey = (mediaKey) => {
   return Boolean(mediaKey);
 };
 
+/**
+ * Constrói entrada padronizada de mídia detectada.
+ * @param {string} mediaType
+ * @param {string} messageKey
+ * @param {Record<string, any>} value
+ * @param {boolean} isQuoted
+ * @param {Partial<MediaEntry>} [overrides={}]
+ * @returns {MediaEntry}
+ */
 const buildMediaEntry = (mediaType, messageKey, value, isQuoted, overrides = {}) => ({
   mediaType,
   mediaKey: value,
@@ -279,6 +481,12 @@ const buildMediaEntry = (mediaType, messageKey, value, isQuoted, overrides = {})
   ...overrides,
 });
 
+/**
+ * Coleta mídias do corpo principal e, opcionalmente, de mensagem citada.
+ * @param {BaileysMessage|{message?: Record<string, any>}|Record<string, any>} message
+ * @param {{includeQuoted?: boolean}} [options]
+ * @returns {MediaEntry[]}
+ */
 const collectMediaFromMessage = (message, { includeQuoted = true } = {}) => {
   if (!message || !message.message) {
     return [];
@@ -297,6 +505,12 @@ const collectMediaFromMessage = (message, { includeQuoted = true } = {}) => {
   return allMedia;
 };
 
+/**
+ * Filtra lista de mídia por tipo binário e inclusão de tipos desconhecidos.
+ * @param {MediaEntry[]} media
+ * @param {{includeAllTypes?: boolean, includeUnknown?: boolean}} [options]
+ * @returns {MediaEntry[]}
+ */
 const filterMedia = (media, { includeAllTypes = false, includeUnknown = false } = {}) => {
   let filtered = media;
 
@@ -311,6 +525,11 @@ const filterMedia = (media, { includeAllTypes = false, includeUnknown = false }
   return filtered;
 };
 
+/**
+ * Procura o campo `contextInfo.expiration` de forma recursiva no payload.
+ * @param {Record<string, any>} root
+ * @returns {number|null}
+ */
 const findExpiration = (root) => {
   if (!root || typeof root !== 'object') return null;
 
@@ -336,6 +555,11 @@ const findExpiration = (root) => {
   return null;
 };
 
+/**
+ * Resolve extensão padrão por tipo de mídia.
+ * @param {string} type
+ * @returns {string}
+ */
 const getMediaExtension = (type) => {
   if (type === 'image') return 'jpeg';
   if (type === 'video') return 'mp4';
@@ -343,6 +567,11 @@ const getMediaExtension = (type) => {
   return 'bin';
 };
 
+/**
+ * Detecta erros de decrypt inválido (OpenSSL).
+ * @param {any} error
+ * @returns {boolean}
+ */
 const isBadDecryptError = (error) => {
   if (!error || typeof error !== 'object') return false;
   if (error.code === 'ERR_OSSL_BAD_DECRYPT') return true;
@@ -521,13 +750,22 @@ export function isWhatsAppJid(jid) {
   return Boolean(server && WHATSAPP_USER_JID_SERVERS.has(server));
 }
 
+/**
+ * Modo de endereçamento por LID.
+ * @type {'lid'}
+ */
 export const ADDRESSING_MODE_LID = 'lid';
+
+/**
+ * Modo de endereçamento por PN/JID canônico.
+ * @type {'pn'}
+ */
 export const ADDRESSING_MODE_PN = 'pn';
 
 /**
  * Normaliza um modo de endereçamento (lid/pn).
  * @param {unknown} value
- * @returns {'lid'|'pn'|undefined}
+ * @returns {AddressingMode|undefined}
  */
 export const normalizeAddressingMode = (value) => {
   if (value === undefined || value === null) return undefined;
@@ -540,8 +778,8 @@ export const normalizeAddressingMode = (value) => {
 /**
  * Resolve modo de endereçamento a partir da chave da mensagem.
  * @param {object} [key={}]
- * @param {object} [senderInfo={}]
- * @returns {'lid'|'pn'|undefined}
+ * @param {SenderInfo|Record<string, any>} [senderInfo={}]
+ * @returns {AddressingMode|undefined}
  */
 export const resolveAddressingModeFromMessageKey = (key = {}, senderInfo = {}) => {
   const explicit = normalizeAddressingMode(key?.addressingMode);
@@ -560,7 +798,7 @@ export const resolveAddressingModeFromMessageKey = (key = {}, senderInfo = {}) =
 
 /**
  * Resolve JID canônico de usuário WhatsApp a partir de candidatos.
- * @param {...string} candidates
+ * @param {...(string|null|undefined)} candidates
  * @returns {string}
  */
 export const resolveCanonicalWhatsAppJid = (...candidates) => {
@@ -716,7 +954,7 @@ export async function resolveBaileysVersion() {
 
 /**
  * Baixa a foto de perfil associada à mensagem recebida.
- * @param {import('@whiskeysockets/baileys').WASocket} sock - Instância conectada do socket.
+ * @param {BaileysSocket} sock - Instância conectada do socket.
  * @param {import('@whiskeysockets/baileys').proto.IWebMessageInfo} msg - Mensagem usada para resolver o JID.
  * @returns {Promise<Buffer|null>} Buffer da imagem ou `null` se indisponível.
  */
@@ -740,17 +978,17 @@ export async function getProfilePicBuffer(sock, msg) {
 
 /**
  * Extrai o valor de expiração de uma mensagem do WhatsApp, ou retorna 24 horas (em segundos) por padrão.
- * @param {{message?: object}|null|undefined} sock - Estrutura contendo a propriedade `message`.
+ * @param {{message?: Record<string, any>}|null|undefined} messageInfo - Estrutura contendo a propriedade `message`.
  * @returns {number} Tempo de expiração em segundos.
  */
-export function getExpiration(sock) {
+export function getExpiration(messageInfo) {
   const DEFAULT_EXPIRATION_SECONDS = 24 * 60 * 60;
 
-  if (!sock || typeof sock !== 'object' || !sock.message) {
+  if (!messageInfo || typeof messageInfo !== 'object' || !messageInfo.message) {
     return DEFAULT_EXPIRATION_SECONDS;
   }
 
-  const normalizedMessage = normalizeMessage(sock.message);
+  const normalizedMessage = normalizeMessage(messageInfo.message);
   const expiration = findExpiration(normalizedMessage);
 
   return typeof expiration === 'number' ? expiration : DEFAULT_EXPIRATION_SECONDS;
@@ -758,7 +996,7 @@ export function getExpiration(sock) {
 
 /**
  * Extrai o conteúdo de texto de uma mensagem do WhatsApp.
- * @param {{message?: object}} messageInfo - Objeto que contém o payload da mensagem.
+ * @param {{message?: Record<string, any>}} messageInfo - Objeto que contém o payload da mensagem.
  * @returns {string} Conteúdo textual extraído ou descrição do tipo de mensagem.
  */
 export const extractMessageContent = ({ message }) => {
@@ -810,7 +1048,7 @@ export const extractMessageContent = ({ message }) => {
 
 /**
  * Faz o download de mídia a partir de uma mensagem do Baileys.
- * @param {import('@whiskeysockets/baileys').WAProto.IMessage} message - Objeto da mídia a ser baixada.
+ * @param {BaileysProtoMessage} message - Objeto da mídia a ser baixada.
  * @param {string} type - Tipo de mídia (ex.: `image`, `video`, `audio`, `document`).
  * @param {string} outputPath - Diretório onde o arquivo será salvo.
  * @returns {Promise<string|null>} Caminho do arquivo salvo ou `null` em caso de falha.
@@ -867,10 +1105,10 @@ export const downloadMediaMessage = async (message, type, outputPath) => {
 };
 
 /**
- * Detecta dinamicamente todos os tipos de midia em um objeto de mensagem
- * @param {object} messageContent - Conteudo da mensagem
- * @param {boolean} isQuoted - Se e de uma mensagem citada
- * @returns {Array} Array de objetos com detalhes da midia encontrada
+ * Detecta dinamicamente os tipos de mídia presentes em um payload de mensagem.
+ * @param {Record<string, any>} messageContent Conteúdo da mensagem (normal ou quoted).
+ * @param {boolean} [isQuoted=false] Sinaliza se o payload veio de uma citação.
+ * @returns {MediaEntry[]} Lista de mídias detectadas (pode estar vazia).
  */
 export function detectAllMediaTypes(messageContent, isQuoted = false) {
   if (!messageContent || typeof messageContent !== 'object') {
@@ -914,13 +1152,10 @@ export function detectAllMediaTypes(messageContent, isQuoted = false) {
 }
 
 /**
- * Extrai detalhes da midia da mensagem de forma dinamica
- * @param {object} message - O objeto da mensagem
- * @param {object} options - Opcoes de configuracao
- * @param {boolean} options.includeAllTypes - Se deve incluir todos os tipos, nao apenas binarios
- * @param {boolean} options.includeQuoted - Se deve incluir midia de mensagens citadas
- * @param {boolean} options.includeUnknown - Se deve incluir tipos desconhecidos
- * @returns {{mediaType: string, mediaKey: object, details: object}|null} - Detalhes da midia ou null se nao encontrada
+ * Extrai a mídia primária de uma mensagem com filtros configuráveis.
+ * @param {BaileysMessage|{message?: Record<string, any>}|Record<string, any>} message Objeto da mensagem.
+ * @param {MediaExtractionOptions} [options={}] Opções de filtragem.
+ * @returns {MediaExtractionResult|null} Estrutura da mídia primária ou `null` quando não houver mídia.
  */
 export function extractMediaDetails(message, options = {}) {
   const { includeAllTypes = false, includeQuoted = true, includeUnknown = false } = options;
@@ -955,10 +1190,10 @@ export function extractMediaDetails(message, options = {}) {
 }
 
 /**
- * Extrai todos os tipos de midia de uma mensagem
- * @param {object} message - O objeto da mensagem
- * @param {object} options - Opcoes de configuracao
- * @returns {Array} Array com todos os tipos de midia encontrados
+ * Extrai todas as mídias detectadas de uma mensagem.
+ * @param {BaileysMessage|{message?: Record<string, any>}|Record<string, any>} message Objeto da mensagem.
+ * @param {MediaExtractionOptions} [options={}] Opções de filtragem.
+ * @returns {MediaEntry[]} Array com todas as mídias encontradas.
  */
 export function extractAllMediaDetails(message, options = {}) {
   const { includeAllTypes = true, includeQuoted = true, includeUnknown = true } = options;
@@ -968,10 +1203,10 @@ export function extractAllMediaDetails(message, options = {}) {
 }
 
 /**
- * Verifica se uma mensagem contem midia
- * @param {object} message - O objeto da mensagem
- * @param {string} specificType - Tipo especifico para verificar (opcional)
- * @returns {boolean} True se contem midia
+ * Verifica se uma mensagem contém mídia.
+ * @param {BaileysMessage|{message?: Record<string, any>}|Record<string, any>} message Objeto da mensagem.
+ * @param {string|null} [specificType=null] Tipo específico para filtrar (ex.: `image`).
+ * @returns {boolean} `true` quando ao menos uma mídia compatível é encontrada.
  */
 export function hasMedia(message, specificType = null) {
   const allMedia = collectMediaFromMessage(message, { includeQuoted: true });
@@ -989,8 +1224,13 @@ export function hasMedia(message, specificType = null) {
 }
 
 /**
- * Obtem informacoes sobre os tipos de midia suportados
- * @returns {object} Informacoes sobre tipos de midia
+ * Obtém metadados dos tipos de mídia suportados.
+ * @returns {{
+ *   knownTypes: string[],
+ *   binaryTypes: string[],
+ *   typeMapping: Record<string, string>,
+ *   totalKnownTypes: number
+ * }}
  */
 export function getMediaTypeInfo() {
   return {
@@ -1002,9 +1242,9 @@ export function getMediaTypeInfo() {
 }
 
 /**
- * ===============================
+ * ===========================
  * LID Map Utilities
- * ===============================
+ * ===========================
  */
 const CACHE_TTL_MS = 20 * 60 * 1000;
 const NEGATIVE_TTL_MS = 5 * 60 * 1000;
@@ -1015,10 +1255,7 @@ const BACKFILL_SOURCE = 'backfill';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const BAILEYS_AUTH_DIR = path.resolve(__dirname, '../connection/auth');
-const BAILEYS_AUTH_SESSION_ID = (() => {
-  const raw = String(process.env.BAILEYS_AUTH_SESSION_ID || '').trim();
-  return raw || 'default';
-})();
+const BAILEYS_AUTH_SESSION_ID = PRIMARY_BAILEYS_SESSION_ID;
 
 const lidCache = new Map();
 const lidWriteBuffer = new Map();
@@ -1026,6 +1263,10 @@ const authReverseLidCache = new Map();
 
 let backfillPromise = null;
 
+/**
+ * Atualiza métrica de profundidade da fila `lid_map`.
+ * @returns {void}
+ */
 const updateLidQueueMetric = () => {
   setQueueDepth('lid_map', lidWriteBuffer.size);
 };
@@ -1036,20 +1277,40 @@ const updateLidQueueMetric = () => {
  */
 const now = () => __timeNowMs();
 
+/**
+ * Normaliza um identificador LID.
+ * @param {string|null|undefined} lid
+ * @returns {string|null}
+ */
 const normalizeLid = (lid) => {
   if (!lid || !isLidJid(lid)) return null;
   const normalized = normalizeJid(lid);
   return normalized || null;
 };
 
+/**
+ * Normaliza JID de usuário WhatsApp.
+ * @param {string|null|undefined} jid
+ * @returns {string|null}
+ */
 const normalizeWhatsAppJid = (jid) => {
   if (!jid || !isWhatsAppJid(jid)) return null;
   const normalized = normalizeJid(jid);
   return normalized || null;
 };
 
+/**
+ * Mantém apenas dígitos de um valor.
+ * @param {unknown} value
+ * @returns {string}
+ */
 const toDigits = (value) => String(value || '').replace(/\D+/g, '');
 
+/**
+ * Extrai telefone (dígitos) de payload reverso LID.
+ * @param {unknown} content
+ * @returns {string}
+ */
 const parseReverseMappingPhoneDigits = (content) => {
   const raw = String(content || '').trim();
   if (!raw) return '';
@@ -1065,6 +1326,11 @@ const parseReverseMappingPhoneDigits = (content) => {
   return digits.length >= 10 && digits.length <= 15 ? digits : '';
 };
 
+/**
+ * Resolve JID a partir de LID consultando auth state (MySQL/arquivos).
+ * @param {string} lid
+ * @returns {Promise<string|null>}
+ */
 const resolveAuthStoreJidByLid = async (lid) => {
   const normalizedLid = normalizeLid(lid);
   if (!normalizedLid) return null;
@@ -1132,7 +1398,7 @@ const maskJid = (jid) => {
 /**
  * Busca entrada do cache (com expiração).
  * @param {string|null|undefined} lid
- * @returns {{jid: string|null, expiresAt: number, lastStoredAt: number|null}|null}
+ * @returns {LidCacheEntry|null}
  */
 const getCacheEntry = (lid) => {
   if (!lid) return null;
@@ -1194,9 +1460,10 @@ export const getCachedJidForLid = (lid) => {
 
 /**
  * Divide lista em batches.
- * @param {Array<any>} items
+ * @template T
+ * @param {T[]} items
  * @param {number} [limit=BATCH_LIMIT]
- * @returns {Array<Array<any>>}
+ * @returns {T[][]}
  */
 const buildChunks = (items, limit = BATCH_LIMIT) => {
   const chunks = [];
@@ -1326,7 +1593,7 @@ const buildServerLikeFilter = (column, servers) => {
 /**
  * Resolve candidatos principais de identidade de usuário.
  * Centraliza regra usada por `resolveUserIdCached` e `resolveUserId`.
- * @param {{lid?: string|null, jid?: string|null, participantAlt?: string|null}} [params]
+ * @param {IdentityParams} [params]
  * @returns {{directJid: string|null, lidValue: string|null, fallback: string|null}}
  */
 const resolveIdentityCandidates = ({ lid, jid, participantAlt } = {}) => {
@@ -1355,6 +1622,11 @@ const resolveIdentityCandidates = ({ lid, jid, participantAlt } = {}) => {
   };
 };
 
+/**
+ * Monta SQL de upsert para lote do `lid_map`.
+ * @param {number} rows
+ * @returns {string}
+ */
 const buildLidUpsertSql = (rows) => {
   const placeholders = buildRowPlaceholders(rows, '(?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP, ?)');
   return `
@@ -1431,7 +1703,7 @@ export const queueLidUpdate = (lid, jid, source = 'message') => {
 
 /**
  * Resolve ID canônico usando apenas cache.
- * @param {{lid?: string|null, jid?: string|null, participantAlt?: string|null}} [params]
+ * @param {IdentityParams} [params]
  * @returns {string|null}
  */
 export const resolveUserIdCached = ({ lid, jid, participantAlt } = {}) => {
@@ -1445,9 +1717,9 @@ export const resolveUserIdCached = ({ lid, jid, participantAlt } = {}) => {
 };
 
 /**
- * Extrai informacoes do remetente a partir de uma mensagem do Baileys.
- * @param {import('@whiskeysockets/baileys').WAMessage} msg
- * @returns {{lid: string|null, jid: string|null, participantAlt: string|null, remoteJid: string|null, remoteJidAlt: string|null, groupMessage: boolean}}
+ * Extrai informações de identidade do remetente a partir da mensagem.
+ * @param {BaileysMessage} msg
+ * @returns {SenderInfo}
  */
 export const extractSenderInfoFromMessage = (msg) => {
   const remoteJid = normalizeJid(msg?.key?.remoteJid || '') || null;
@@ -1556,7 +1828,7 @@ const fetchJidByLid = async (lid) => {
 
 /**
  * Resolve ID canônico consultando banco se necessário.
- * @param {{lid?: string|null, jid?: string|null, participantAlt?: string|null}} [params]
+ * @param {IdentityParams} [params]
  * @returns {Promise<string|null>}
  */
 export const resolveUserId = async ({ lid, jid, participantAlt } = {}) => {
@@ -1604,6 +1876,10 @@ export const reconcileLidToJid = async ({ lid, jid, source = 'map' } = {}) => {
   return { updated };
 };
 
+/**
+ * Executa flush em lote do buffer de atualizações LID->JID.
+ * @returns {Promise<void>}
+ */
 const flushLidQueueCore = async () => {
   if (lidWriteBuffer.size === 0) return;
   const entries = Array.from(lidWriteBuffer.values());
@@ -1669,6 +1945,13 @@ export const flushLidQueue = async () => {
   await lidFlushRunner.run();
 };
 
+/**
+ * Enfileira atualização de mapa LID/JID e retorna estado simplificado.
+ * @param {string} lid
+ * @param {string|null} jid
+ * @param {string} [source='message']
+ * @returns {Promise<{stored: boolean, reconciled: boolean}>}
+ */
 export const maybeStoreLidMap = async (lid, jid, source = 'message') => {
   const result = queueLidUpdate(lid, jid, source);
   return { stored: result.queued, reconciled: result.reconciled };
@@ -1690,6 +1973,10 @@ export const extractUserIdInfo = (value) => {
     };
   }
 
+  /**
+   * @param {unknown} entry
+   * @returns {string|null}
+   */
   const readJid = (entry) => (typeof entry === 'string' ? normalizeJid(entry) || null : null);
 
   const participantAlt = readJid(value.participantAlt);