@omnizap-system/omnizap 2.6.1 → 2.6.3

package/app/configParts/messagePersistenceService.js

@@ -1,21 +1,196 @@
 import { now as __timeNow, nowIso as __timeNowIso, toUnixMs as __timeNowMs } from '#time';
 import { baileysConnectionLogger as logger } from './loggerConfig.js';
 import { queueMessageInsert } from '../services/infra/dbWriteQueue.js';
-import { parseEnvBool, parseEnvInt, normalizeJid, isGroupJid, isStatusJid, isBroadcastJid, isNewsletterJid, normalizeWAPresence } from './baileysConfig.js';
+import { parseEnvBool, parseEnvInt, normalizeJid, isGroupJid, isStatusJid, isBroadcastJid, isNewsletterJid, normalizeWAPresence, isLidJid, isWhatsAppJid, normalizePnToJid, resolveUserId } from './baileysConfig.js';
+import { getOwner as getGroupOwner, tryAcquire as tryAcquireGroupOwner } from '../services/multiSession/groupOwnershipService.js';
 
+/**
+ * Número máximo de tentativas de envio.
+ * @type {number}
+ */
 const BAILEYS_SEND_RETRY_ATTEMPTS = parseEnvInt(process.env.BAILEYS_SEND_RETRY_ATTEMPTS, 2, 1, 5);
+/**
+ * Atraso base (ms) para backoff exponencial entre retries.
+ * @type {number}
+ */
 const BAILEYS_SEND_RETRY_BASE_DELAY_MS = parseEnvInt(process.env.BAILEYS_SEND_RETRY_BASE_DELAY_MS, 600, 100, 10_000);
+/**
+ * Timeout de upload de mídia repassado ao Baileys.
+ * @type {number}
+ */
 const BAILEYS_SEND_MEDIA_UPLOAD_TIMEOUT_MS = parseEnvInt(process.env.BAILEYS_SEND_MEDIA_UPLOAD_TIMEOUT_MS, 0, 0, 120_000);
+/**
+ * Habilita presença automática durante replies.
+ * @type {boolean}
+ */
 const BAILEYS_REPLY_PRESENCE_ENABLED = parseEnvBool(process.env.BAILEYS_REPLY_PRESENCE_ENABLED, true);
+/**
+ * Define se deve assinar presença antes de enviar update.
+ * @type {boolean}
+ */
 const BAILEYS_REPLY_PRESENCE_SUBSCRIBE = parseEnvBool(process.env.BAILEYS_REPLY_PRESENCE_SUBSCRIBE, true);
+/**
+ * Delay entre presença "before" e envio (ms).
+ * @type {number}
+ */
 const BAILEYS_REPLY_PRESENCE_DELAY_MS = parseEnvInt(process.env.BAILEYS_REPLY_PRESENCE_DELAY_MS, 280, 0, 3_000);
+/**
+ * Presença enviada antes do envio.
+ * @type {import('@whiskeysockets/baileys').WAPresence}
+ */
 const BAILEYS_REPLY_PRESENCE_BEFORE = normalizeWAPresence(process.env.BAILEYS_REPLY_PRESENCE_BEFORE, 'composing');
+/**
+ * Presença enviada após o envio.
+ * @type {import('@whiskeysockets/baileys').WAPresence}
+ */
 const BAILEYS_REPLY_PRESENCE_AFTER = normalizeWAPresence(process.env.BAILEYS_REPLY_PRESENCE_AFTER, 'paused');
+/**
+ * Prefere enviar para PN quando o destino original for LID.
+ * @type {boolean}
+ */
+const BAILEYS_SEND_PREFER_PN_FOR_LID = parseEnvBool(process.env.BAILEYS_SEND_PREFER_PN_FOR_LID, true);
+/**
+ * TTL do cache de permissão de escrita em grupo (ms).
+ * @type {number}
+ */
+const GROUP_WRITE_PERMISSION_CACHE_TTL_MS = parseEnvInt(process.env.GROUP_OWNER_WRITE_CACHE_TTL_MS, 8_000, 1_000, 60_000);
 
+/**
+ * Verifica se o valor é um objeto plano.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
 const isPlainObject = (value) => Object.prototype.toString.call(value) === '[object Object]';
 
+/**
+ * Chaves primárias conhecidas de `AnyMessageContent`.
+ * @type {Set<string>}
+ */
 const ANY_MESSAGE_CONTENT_PRIMARY_KEYS = new Set(['text', 'image', 'video', 'audio', 'sticker', 'stickerPack', 'stickerPackMessage', 'document', 'event', 'poll', 'contacts', 'location', 'react', 'buttonReply', 'groupInvite', 'listReply', 'pin', 'product', 'sharePhoneNumber', 'requestPhoneNumber', 'forward', 'delete', 'disappearingMessagesInChat', 'limitSharing']);
+/**
+ * Conteúdos que não disparam presença de resposta.
+ * @type {Set<string>}
+ */
 const PRESENCE_NON_REPLY_CONTENT_KEYS = new Set(['react', 'delete', 'pin', 'disappearingMessagesInChat']);
+/**
+ * Cache local de permissão de escrita por `sessionId+groupJid`.
+ * @type {Map<string, {allowed: boolean, ownerSessionId: string | null, expiresAtMs: number}>}
+ */
+const groupWritePermissionCache = new Map();
+
+/**
+ * Normaliza um ID de sessão.
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+const normalizeSessionId = (value) => {
+  const normalized = String(value || '').trim();
+  return normalized || null;
+};
+
+/**
+ * Recupera permissão de escrita de grupo no cache.
+ * @param {string} groupJid
+ * @param {string} sessionId
+ * @returns {{allowed: boolean, ownerSessionId: string | null, expiresAtMs: number} | null}
+ */
+const getCachedGroupWritePermission = (groupJid, sessionId) => {
+  const key = `${sessionId}:${groupJid}`;
+  const cached = groupWritePermissionCache.get(key);
+  if (!cached) return null;
+  if (cached.expiresAtMs <= __timeNowMs()) {
+    groupWritePermissionCache.delete(key);
+    return null;
+  }
+  return cached;
+};
+
+/**
+ * Salva permissão de escrita de grupo no cache.
+ * @param {string} groupJid
+ * @param {string} sessionId
+ * @param {boolean} allowed
+ * @param {string|null} [ownerSessionId=null]
+ * @returns {void}
+ */
+const setCachedGroupWritePermission = (groupJid, sessionId, allowed, ownerSessionId = null) => {
+  const key = `${sessionId}:${groupJid}`;
+  groupWritePermissionCache.set(key, {
+    allowed: Boolean(allowed),
+    ownerSessionId: normalizeSessionId(ownerSessionId),
+    expiresAtMs: __timeNowMs() + GROUP_WRITE_PERMISSION_CACHE_TTL_MS,
+  });
+};
+
+/**
+ * Resolve se a sessão atual pode escrever em um grupo.
+ * @param {string} groupJid
+ * @param {string|null} sessionId
+ * @returns {Promise<{allowed: boolean, ownerSessionId: string | null, reason: string}>}
+ */
+const resolveGroupWritePermission = async (groupJid, sessionId) => {
+  if (!isGroupJid(groupJid) || !sessionId) {
+    return {
+      allowed: true,
+      ownerSessionId: null,
+      reason: 'not_group_or_missing_session',
+    };
+  }
+
+  const cached = getCachedGroupWritePermission(groupJid, sessionId);
+  if (cached) {
+    return {
+      allowed: cached.allowed,
+      ownerSessionId: cached.ownerSessionId,
+      reason: 'cache_hit',
+    };
+  }
+
+  try {
+    const ownerState = await getGroupOwner(groupJid);
+    let ownerSessionId = normalizeSessionId(ownerState?.ownerSessionId);
+    let allowed = false;
+    let reason = 'owned_by_other';
+
+    if (!ownerSessionId) {
+      const claimOutcome = await tryAcquireGroupOwner({
+        groupJid,
+        sessionId,
+        reason: 'send_store_claim',
+        changedBy: sessionId,
+        metadata: {
+          source: 'message_persistence_service',
+          gate: 'group_write',
+        },
+      });
+      ownerSessionId = normalizeSessionId(claimOutcome?.owner?.ownerSessionId);
+      allowed = Boolean(claimOutcome?.acquired && ownerSessionId === sessionId);
+      reason = claimOutcome?.reason || 'claim_attempt';
+    } else {
+      allowed = ownerSessionId === sessionId;
+      reason = allowed ? 'owner_match' : 'owned_by_other';
+    }
+
+    setCachedGroupWritePermission(groupJid, sessionId, allowed, ownerSessionId);
+    return {
+      allowed,
+      ownerSessionId,
+      reason,
+    };
+  } catch (error) {
+    logger.warn('Falha ao validar ownership para persistência de saída em grupo.', {
+      action: 'group_write_permission_resolution_failed',
+      groupJid,
+      sessionId,
+      error: error?.message,
+    });
+    return {
+      allowed: false,
+      ownerSessionId: null,
+      reason: 'resolution_failed',
+    };
+  }
+};
 
 /**
  * Verifica se o payload se parece com AnyMessageContent do Baileys.
@@ -62,6 +237,8 @@ const normalizeSendOptions = (options) => {
  * @param {unknown} options
  * @returns {{
  *   sendOptions: import('@whiskeysockets/baileys').MiscMessageGenerationOptions|undefined,
+ *   sessionId: string | null,
+ *   allowGroupWrite: boolean | undefined,
  *   skipPresenceUpdate: boolean,
  *   presenceBefore: import('@whiskeysockets/baileys').WAPresence,
  *   presenceAfter: import('@whiskeysockets/baileys').WAPresence,
@@ -73,6 +250,8 @@ const resolveRuntimeSendOptions = (options) => {
   if (!isPlainObject(options)) {
     return {
       sendOptions: undefined,
+      sessionId: null,
+      allowGroupWrite: undefined,
       skipPresenceUpdate: false,
       presenceBefore: BAILEYS_REPLY_PRESENCE_BEFORE,
       presenceAfter: BAILEYS_REPLY_PRESENCE_AFTER,
@@ -81,10 +260,12 @@ const resolveRuntimeSendOptions = (options) => {
     };
   }
 
-  const { skipPresenceUpdate, presenceBefore, presenceAfter, presenceDelayMs, presenceSubscribe, ...sendOptions } = options;
+  const { skipPresenceUpdate, presenceBefore, presenceAfter, presenceDelayMs, presenceSubscribe, sessionId, allowGroupWrite, ...sendOptions } = options;
   const normalizedDelay = parseEnvInt(presenceDelayMs, BAILEYS_REPLY_PRESENCE_DELAY_MS, 0, 3_000);
   return {
     sendOptions: Object.keys(sendOptions).length > 0 ? sendOptions : undefined,
+    sessionId: normalizeSessionId(sessionId),
+    allowGroupWrite: typeof allowGroupWrite === 'boolean' ? allowGroupWrite : undefined,
     skipPresenceUpdate: Boolean(skipPresenceUpdate),
     presenceBefore: normalizeWAPresence(presenceBefore, BAILEYS_REPLY_PRESENCE_BEFORE),
     presenceAfter: normalizeWAPresence(presenceAfter, BAILEYS_REPLY_PRESENCE_AFTER),
@@ -127,6 +308,60 @@ const shouldSendReplyPresence = (jid, content, runtimeOptions) => {
   return true;
 };
 
+/**
+ * Verifica se o JID é de usuário direto (não grupo/broadcast/status/newsletter).
+ * @param {string} jid
+ * @returns {boolean}
+ */
+const isDirectUserJid = (jid) => {
+  if (!jid) return false;
+  if (isGroupJid(jid)) return false;
+  if (isStatusJid(jid)) return false;
+  if (isBroadcastJid(jid)) return false;
+  if (isNewsletterJid(jid)) return false;
+  return true;
+};
+
+/**
+ * Resolve JID preferencial de envio, convertendo LID para PN quando possível.
+ * @param {string} normalizedJid
+ * @returns {Promise<string>}
+ */
+const resolvePreferredSendJid = async (normalizedJid) => {
+  if (!normalizedJid) return normalizedJid;
+  if (!BAILEYS_SEND_PREFER_PN_FOR_LID) return normalizedJid;
+  if (!isDirectUserJid(normalizedJid)) return normalizedJid;
+  if (!isLidJid(normalizedJid)) return normalizedJid;
+
+  try {
+    const resolvedIdentity = await resolveUserId({
+      lid: normalizedJid,
+      jid: normalizedJid,
+    });
+    const normalizedResolved = normalizeJid(String(resolvedIdentity || '').trim());
+    const candidatePnJid = normalizePnToJid(normalizedResolved || String(resolvedIdentity || '').trim());
+    if (candidatePnJid && isWhatsAppJid(candidatePnJid)) {
+      return candidatePnJid;
+    }
+  } catch (error) {
+    logger.debug('Falha ao resolver PN para envio com destino LID. Mantendo destino original.', {
+      action: 'resolve_preferred_send_jid_failed',
+      jid: normalizedJid,
+      error: error?.message,
+    });
+  }
+
+  return normalizedJid;
+};
+
+/**
+ * Envia presença no Baileys sem interromper o fluxo principal em caso de erro.
+ * @param {import('@whiskeysockets/baileys').WASocket} sock
+ * @param {import('@whiskeysockets/baileys').WAPresence} type
+ * @param {string} jid
+ * @param {boolean} [subscribeFirst=false]
+ * @returns {Promise<void>}
+ */
 const sendPresenceSilently = async (sock, type, jid, subscribeFirst = false) => {
   if (!sock || typeof sock.sendPresenceUpdate !== 'function') return;
   try {
@@ -163,9 +398,11 @@ const resolveMessageTimestampMs = (msg) => {
  * Normaliza uma mensagem do Baileys para o formato persistido no banco.
  * @param {import('@whiskeysockets/baileys').WAMessage} msg - Mensagem recebida/enviada.
  * @param {string} [senderId] - ID do remetente (opcional).
+ * @param {string|null} [sessionId] - Sessão lógica para persistência.
  * @returns {Object} Objeto com dados prontos para persistencia.
  */
-export const buildMessageData = (msg, senderId) => ({
+export const buildMessageData = (msg, senderId, sessionId = null) => ({
+  session_id: normalizeSessionId(sessionId),
   message_id: msg?.key?.id,
   chat_id: msg?.key?.remoteJid,
   sender_id: senderId || msg?.key?.participant || msg?.key?.remoteJid,
@@ -174,8 +411,18 @@ export const buildMessageData = (msg, senderId) => ({
   timestamp: new Date(resolveMessageTimestampMs(msg)),
 });
 
+/**
+ * Atrasa execução por `ms`.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, Number(ms) || 0)));
 
+/**
+ * Detecta se um erro de envio é potencialmente transitório.
+ * @param {any} error
+ * @returns {boolean}
+ */
 const isTransientSendError = (error) => {
   const statusCode = Number(error?.output?.statusCode || error?.statusCode || 0);
   if ([408, 409, 425, 429, 500, 502, 503, 504].includes(statusCode)) return true;
@@ -192,6 +439,11 @@ const isTransientSendError = (error) => {
   return transientFragments.some((fragment) => rawMessage.includes(fragment));
 };
 
+/**
+ * Indica se o erro sugere refresh explícito de media connection.
+ * @param {any} error
+ * @returns {boolean}
+ */
 const shouldRefreshMediaConnection = (error) => {
   const rawMessage = `${error?.message || ''} ${error?.data?.message || ''}`.toLowerCase();
   return rawMessage.includes('media') || rawMessage.includes('directpath') || rawMessage.includes('upload');
@@ -225,8 +477,52 @@ export async function sendAndStore(sock, jid, content, options) {
     throw new TypeError(`Payload de mensagem inválido. Chaves recebidas: ${payloadKeys.join(', ') || 'nenhuma'}`);
   }
 
-  const normalizedJid = normalizeJid(jid) || String(jid).trim();
+  const normalizedInputJid = normalizeJid(jid) || String(jid).trim();
   const runtimeOptions = resolveRuntimeSendOptions(options);
+  const runtimeSessionId = runtimeOptions.sessionId || normalizeSessionId(sock?.__omnizapSessionId);
+  let resolvedGroupWritePermission = null;
+
+  if (isGroupJid(normalizedInputJid)) {
+    if (runtimeOptions.allowGroupWrite === false) {
+      logger.debug('Envio para grupo ignorado por bloqueio explícito de escrita.', {
+        action: 'send_group_blocked_explicit',
+        groupJid: normalizedInputJid,
+        sessionId: runtimeSessionId,
+      });
+      return undefined;
+    }
+
+    if (runtimeOptions.allowGroupWrite === true) {
+      resolvedGroupWritePermission = {
+        allowed: true,
+        ownerSessionId: runtimeSessionId,
+        reason: 'explicit_allow',
+      };
+    } else {
+      resolvedGroupWritePermission = await resolveGroupWritePermission(normalizedInputJid, runtimeSessionId);
+      if (!resolvedGroupWritePermission.allowed) {
+        logger.info('Envio para grupo bloqueado por sessão não-owner.', {
+          action: 'send_group_blocked_non_owner',
+          groupJid: normalizedInputJid,
+          sessionId: runtimeSessionId,
+          ownerSessionId: resolvedGroupWritePermission.ownerSessionId,
+          reason: resolvedGroupWritePermission.reason,
+        });
+        return undefined;
+      }
+    }
+  }
+
+  const normalizedJid = await resolvePreferredSendJid(normalizedInputJid);
+  if (normalizedJid !== normalizedInputJid) {
+    logger.debug('Destino LID convertido para PN antes do envio.', {
+      action: 'send_target_lid_to_pn',
+      from: normalizedInputJid,
+      to: normalizedJid,
+      sessionId: runtimeSessionId,
+    });
+  }
+
   const normalizedOptions = normalizeSendOptions(runtimeOptions.sendOptions);
   const shouldSendPresence = shouldSendReplyPresence(normalizedJid, content, runtimeOptions);
 
@@ -292,7 +588,13 @@ export async function sendAndStore(sock, jid, content, options) {
   const senderId = sock?.user?.id || sent?.key?.participant;
   if (sent?.key?.id) {
     try {
-      queueMessageInsert(buildMessageData(sent, senderId));
+      const messageData = buildMessageData(sent, senderId, runtimeSessionId);
+      const targetGroupJid = normalizeJid(messageData.chat_id || normalizedInputJid);
+      if (isGroupJid(targetGroupJid)) {
+        const allowGroupWrite = runtimeOptions.allowGroupWrite === true || resolvedGroupWritePermission?.allowed === true;
+        messageData.allow_group_write = allowGroupWrite;
+      }
+      queueMessageInsert(messageData);
     } catch (error) {
       logger.warn('Falha ao enfileirar mensagem enviada para persistencia.', {
         error: error.message,

package/app/configParts/sessionConfig.js

@@ -0,0 +1,242 @@
+/**
+ * Sessão padrão usada como fallback.
+ * @type {string}
+ */
+const DEFAULT_SESSION_ID = 'default';
+/**
+ * Tamanho máximo permitido para IDs de sessão.
+ * @type {number}
+ */
+const SESSION_ID_MAX_LENGTH = 64;
+/**
+ * Regex de validação para IDs de sessão.
+ * @type {RegExp}
+ */
+const SESSION_ID_PATTERN = /^[a-zA-Z0-9:_-]+$/;
+/**
+ * Modos de enforcement válidos para ownership de grupo.
+ * @type {Set<string>}
+ */
+const OWNER_ENFORCEMENT_MODES = new Set(['off', 'shadow', 'enforce']);
+
+/**
+ * Converte um valor de ambiente para boolean com fallback.
+ * @param {unknown} value
+ * @param {boolean} fallback
+ * @returns {boolean}
+ */
+const parseEnvBool = (value, fallback) => {
+  if (value === undefined || value === null || value === '') return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) return false;
+  return fallback;
+};
+
+/**
+ * Converte um valor em inteiro com limites.
+ * @param {unknown} value
+ * @param {number} fallback
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+const parseEnvInt = (value, fallback, min, max) => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(parsed)));
+};
+
+/**
+ * Faz parse de entradas separadas por vírgula, quebra de linha ou `;`.
+ * @param {unknown} value
+ * @returns {string[]}
+ */
+const parseFlexibleEntries = (value) =>
+  String(value || '')
+    .split(/[,\n;]+/g)
+    .map((entry) => String(entry || '').trim())
+    .filter(Boolean);
+
+/**
+ * Normaliza um ID de sessão.
+ * @param {unknown} value
+ * @returns {string}
+ */
+const normalizeSessionId = (value) => String(value || '').trim();
+
+/**
+ * Valida formato e tamanho de ID de sessão.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+const isValidSessionId = (value) => {
+  const normalized = normalizeSessionId(value);
+  if (!normalized) return false;
+  if (normalized.length > SESSION_ID_MAX_LENGTH) return false;
+  return SESSION_ID_PATTERN.test(normalized);
+};
+
+/**
+ * @typedef {{sessionIds: string[], warnings: string[]}} ParsedSessionIds
+ */
+/**
+ * Interpreta lista de sessões do ambiente e aplica fallback legado.
+ * @param {{sessionIdsRaw?: string, legacySessionIdRaw?: string}} [params]
+ * @returns {ParsedSessionIds}
+ */
+const parseSessionIds = ({ sessionIdsRaw = '', legacySessionIdRaw = '' } = {}) => {
+  const warnings = [];
+  const validSessionIds = [];
+  const seen = new Set();
+
+  const legacySessionId = normalizeSessionId(legacySessionIdRaw) || DEFAULT_SESSION_ID;
+  const requestedSessionIds = parseFlexibleEntries(sessionIdsRaw);
+  const sourceSessionIds = requestedSessionIds.length > 0 ? requestedSessionIds : [legacySessionId];
+
+  for (const candidate of sourceSessionIds) {
+    const sessionId = normalizeSessionId(candidate);
+    if (!isValidSessionId(sessionId)) {
+      warnings.push(`session_id invalido ignorado: "${candidate}"`);
+      continue;
+    }
+    if (seen.has(sessionId)) continue;
+    seen.add(sessionId);
+    validSessionIds.push(sessionId);
+  }
+
+  if (validSessionIds.length === 0) {
+    validSessionIds.push(DEFAULT_SESSION_ID);
+    warnings.push(`nenhum session_id valido encontrado; usando fallback "${DEFAULT_SESSION_ID}"`);
+  }
+
+  return {
+    sessionIds: validSessionIds,
+    warnings,
+  };
+};
+
+/**
+ * Resolve pesos por sessão com validação e defaults.
+ * @param {unknown} rawValue
+ * @param {string[]} sessionIds
+ * @param {string[]} warnings
+ * @returns {Record<string, number>}
+ */
+const parseSessionWeights = (rawValue, sessionIds, warnings) => {
+  const allowedSessions = new Set(sessionIds);
+  const weights = {};
+  for (const sessionId of sessionIds) {
+    weights[sessionId] = 1;
+  }
+
+  const entries = parseFlexibleEntries(rawValue);
+  if (entries.length === 0) return weights;
+
+  for (const entry of entries) {
+    const separator = entry.includes('=') ? '=' : entry.includes(':') ? ':' : '';
+    if (!separator) {
+      warnings.push(`peso de sessao invalido (faltando separador "=" ou ":"): "${entry}"`);
+      continue;
+    }
+
+    const [rawSessionId, rawWeight] = entry.split(separator, 2);
+    const sessionId = normalizeSessionId(rawSessionId);
+    if (!isValidSessionId(sessionId)) {
+      warnings.push(`peso ignorado para session_id invalido: "${rawSessionId}"`);
+      continue;
+    }
+    if (!allowedSessions.has(sessionId)) {
+      warnings.push(`peso ignorado para session_id nao listado em BAILEYS_SESSION_IDS: "${sessionId}"`);
+      continue;
+    }
+
+    const weight = parseEnvInt(rawWeight, Number.NaN, 1, 1000);
+    if (!Number.isFinite(weight)) {
+      warnings.push(`peso invalido para "${sessionId}": "${rawWeight}"`);
+      continue;
+    }
+    weights[sessionId] = weight;
+  }
+
+  return weights;
+};
+
+/**
+ * @typedef {{
+ *   sessionIds: readonly string[],
+ *   primarySessionId: string,
+ *   sessionWeights: Readonly<Record<string, number>>,
+ *   ownerEnforcementMode: 'off'|'shadow'|'enforce',
+ *   ownerLeaseMs: number,
+ *   ownerHeartbeatMs: number,
+ *   balancerEnabled: boolean,
+ *   warnings: readonly string[]
+ * }} MultiSessionRuntimeConfig
+ */
+/**
+ * Resolve a configuração de runtime para múltiplas sessões.
+ * @param {Record<string, any>} [env=process.env]
+ * @returns {MultiSessionRuntimeConfig}
+ */
+export const resolveMultiSessionRuntimeConfig = (env = process.env) => {
+  const warnings = [];
+  const legacySessionId = normalizeSessionId(env.BAILEYS_AUTH_SESSION_ID) || DEFAULT_SESSION_ID;
+  const { sessionIds, warnings: parseWarnings } = parseSessionIds({
+    sessionIdsRaw: env.BAILEYS_SESSION_IDS,
+    legacySessionIdRaw: legacySessionId,
+  });
+  warnings.push(...parseWarnings);
+
+  const requestedPrimary = normalizeSessionId(env.BAILEYS_PRIMARY_SESSION_ID);
+  let primarySessionId = requestedPrimary || sessionIds[0];
+
+  if (requestedPrimary && !isValidSessionId(requestedPrimary)) {
+    warnings.push(`BAILEYS_PRIMARY_SESSION_ID invalido: "${requestedPrimary}"`);
+    primarySessionId = sessionIds[0];
+  } else if (requestedPrimary && !sessionIds.includes(requestedPrimary)) {
+    warnings.push(`BAILEYS_PRIMARY_SESSION_ID fora da lista de sessoes: "${requestedPrimary}"`);
+    primarySessionId = sessionIds[0];
+  }
+
+  const ownerEnforcementModeRaw = String(env.GROUP_OWNER_ENFORCEMENT_MODE || 'off')
+    .trim()
+    .toLowerCase();
+  const ownerEnforcementMode = OWNER_ENFORCEMENT_MODES.has(ownerEnforcementModeRaw) ? ownerEnforcementModeRaw : 'off';
+  if (!OWNER_ENFORCEMENT_MODES.has(ownerEnforcementModeRaw)) {
+    warnings.push(`GROUP_OWNER_ENFORCEMENT_MODE invalido: "${ownerEnforcementModeRaw}"`);
+  }
+
+  const ownerLeaseMs = parseEnvInt(env.GROUP_OWNER_LEASE_MS, 120_000, 5_000, 15 * 60 * 1000);
+  let ownerHeartbeatMs = parseEnvInt(env.GROUP_OWNER_HEARTBEAT_MS, 30_000, 1_000, 5 * 60 * 1000);
+  if (ownerHeartbeatMs >= ownerLeaseMs) {
+    ownerHeartbeatMs = Math.max(1_000, Math.floor(ownerLeaseMs / 2));
+    warnings.push(`GROUP_OWNER_HEARTBEAT_MS ajustado automaticamente para ${ownerHeartbeatMs}ms (precisa ser menor que lease)`);
+  }
+
+  const balancerEnabled = parseEnvBool(env.GROUP_BALANCER_ENABLED, false);
+  const sessionWeights = parseSessionWeights(env.BAILEYS_SESSION_WEIGHTS, sessionIds, warnings);
+
+  return Object.freeze({
+    sessionIds: Object.freeze([...sessionIds]),
+    primarySessionId,
+    sessionWeights: Object.freeze({ ...sessionWeights }),
+    ownerEnforcementMode,
+    ownerLeaseMs,
+    ownerHeartbeatMs,
+    balancerEnabled,
+    warnings: Object.freeze([...warnings]),
+  });
+};
+
+/**
+ * Configuração resolvida uma única vez por processo.
+ * @type {MultiSessionRuntimeConfig}
+ */
+export const multiSessionRuntimeConfig = resolveMultiSessionRuntimeConfig();
+
+/**
+ * Retorna a configuração de runtime multi-sessão.
+ * @returns {MultiSessionRuntimeConfig}
+ */
+export const getMultiSessionRuntimeConfig = () => multiSessionRuntimeConfig;

package/app/connection/baileysCompatibility.test.js

@@ -6,12 +6,21 @@ import test from 'node:test';
 
 import { initAuthCreds, proto } from '@whiskeysockets/baileys';
 
-const PINNED_BAILEYS_REF = 'github:jlucaso1/Baileys#be89465e07afa871cf3f0e19cabfec9780db6be7';
+/**
+ * Referência do fork/branch do Baileys validada pelos testes.
+ * @type {string}
+ */
+const PINNED_BAILEYS_REF = 'github:jlucaso1/Baileys#feat-add-stickerpack-support';
 
 const require = createRequire(import.meta.url);
 const baileysPackageJsonPath = require.resolve('@whiskeysockets/baileys/package.json');
 const baileysPackageDir = path.dirname(baileysPackageJsonPath);
 
+/**
+ * Lê um arquivo de tipos dentro do pacote instalado do Baileys.
+ * @param {string} relativePath
+ * @returns {Promise<string>}
+ */
 const readBaileysTypeFile = async (relativePath) => readFile(path.join(baileysPackageDir, relativePath), 'utf8');
 
 test('Auth.d.ts expõe AuthenticationState compatível com SocketConfig.auth', async () => {