@zervonex/baileys 3.0.8 → 4.0.0

package/lib/Socket/zervonex-handler.js

@@ -1,6 +1,6 @@
 import crypto from 'crypto'
 import * as Builders from '../Builders/index.js'
-import { buildDispatch, buildPlugins, norm, handleGroupStatus, handleStatusMention, handlePollResult, PRIMITIVE_SHORTCUTS, HANDLER_SHORTCUTS, attachAIRich } from '../Builders/index.js'
+import { buildDispatch, buildPlugins, norm, handleGroupStatus, handleStatusMention, handlePollResult, handleNativeFlow, PRIMITIVE_SHORTCUTS, HANDLER_SHORTCUTS, attachAIRich } from '../Builders/index.js'
 import { makeUsernameSocket } from './username.js'
 
 export const makeMessageBuilderSocket = (config) => {
@@ -23,24 +23,19 @@ export const makeMessageBuilderSocket = (config) => {
 
     result.sendMessage = async (jid, content, options = {}) => {
         // aiRich shorthand — multiple aliases supported
-        const aiData = content.aiRich ?? content.airich ?? content.richResponse ?? content.AIRich
-        if (aiData) return result.sendRichFromObject(jid, aiData, options)
+        const aiData = content.aiRich ?? content.airich ?? content.richResponse ?? content.AIRich ?? content.richMessage
+        if (aiData) return result.sendRichFromObject(jid, Array.isArray(aiData) ? { ...content, parts: aiData } : { ...content, ...aiData }, options)
 
         // dispatch to registered builder handlers
         for (const [key, handler] of Object.entries(DISPATCH)) {
             if (key in content) return handler(result, jid, content, options, config)
         }
-
-        // bare nativeFlow array/object — wrap into interactiveMessage before sending
-        if (content.nativeFlow && !content.interactiveMessage) {
-            const buttons = Array.isArray(content.nativeFlow) ? content.nativeFlow : [content.nativeFlow]
-            const { generateWAMessageFromContent } = await import('../Utils/index.js')
-            const msg = await await generateWAMessageFromContent(jid, {
-                interactiveMessage: { body: { text: content.text || '' }, footer: { text: content.footer || '' }, header: { hasMediaAttachment: false }, nativeFlowMessage: { buttons } }
-            }, { userJid: sock.user?.id })
-            await result.relayMessage(jid, msg.message, { messageId: msg.key.id, aiLabel: !!(content.ai ?? content.aiLabel ?? options.aiLabel ?? options.ai ?? config.aiLabel ?? config.ai) })
-            return msg
-        }
+        // templateButtons check
+        if (content.templateButtons) return result.sendMessage(jid, { text: content.text ?? content.caption ?? '', footer: content.footer, ...(content.image ? { image: content.image } : {}), nativeFlow: content.templateButtons.map(b => b.url ? { text: b.text, url: b.url } : b.call ? { text: b.text, call: b.call } : { text: b.text, id: b.id }) }, options)
+        // carousel && card message check
+        if (content.cards && !content.carouselMessage) return result.sendMessage(jid, { carouselMessage: { caption: content.text ?? content.caption ?? '', footer: content.footer, cards: content.cards } }, options)
+        // bare nativeFlow array/object
+        if (content.nativeFlow && !content.interactiveMessage) return handleNativeFlow(result, jid, content, options)
 
         const { ai, aiLabel: contentAiLabel, ...cleanContent } = content
         const isAi = !!(ai ?? contentAiLabel ?? options.aiLabel ?? options.ai ?? config.aiLabel)

package/lib/Store/make-cache-manager-store.js

@@ -1,7 +1,6 @@
 import * as cacheManager from 'cache-manager';
 import * as WAProto from '../../WAProto/index.js';
-import { BufferJSON, initAuthCreds } from '../Utils/index.js';
-import logger from '../Utils/logger.js';
+import { BufferJSON, initAuthCreds, logger } from '../Utils/index.js';
 
 const makeCacheManagerAuthState = async (store, sessionKey) => {
   const defaultKey = (file) => `${sessionKey}:${file}`;
@@ -40,7 +39,7 @@ const makeCacheManagerAuthState = async (store, sessionKey) => {
     try {
       const result = await databaseConn.store.keys(`${sessionKey}*`);
       await Promise.all(result.map(async (key) => await databaseConn.del(key)));
-    } catch {}
+    } catch { }
   };
 
   const creds = (await readData('creds')) || initAuthCreds();

package/lib/Store/make-in-memory-store.js

@@ -43,6 +43,7 @@ const makeInMemoryStore = (config) => {
     const contactsUpsert = (newContacts) => {
         const oldContacts = new Set(Object.keys(contacts))
         for (const contact of newContacts) {
+            if (!contact || typeof contact.id !== 'string') continue
             oldContacts.delete(contact.id)
             contacts[contact.id] = Object.assign(contacts[contact.id] || {}, contact)
         }

package/lib/Utils/auth-utils.js

@@ -6,8 +6,9 @@ import PQueue from 'p-queue'
 import { v4 } from 'uuid'
 import { DEFAULT_CACHE_TTLS } from '../Defaults/index.js'
 import { Curve, signedKeyPair } from './crypto.js'
-import { delay, generateRegistrationId } from './generics.js'
+import { delay, generateRegistrationId, BufferJSON } from './generics.js'
 import { PreKeyManager } from './pre-key-manager.js'
+import { proto } from '../../WAProto/index.js'
 
 export function makeCacheableSignalKeyStore(store, logger, _cache) {
     const cache = _cache || new NodeCache({ stdTTL: DEFAULT_CACHE_TTLS.SIGNAL_STORE, useClones: false, deleteOnExpire: true })
@@ -139,4 +140,20 @@ export const initAuthCreds = () => {
         routingInfo: undefined,
         additionalData: undefined
     }
-}
+}
+
+
+export const bootstrapCreds = raw => raw ?? initAuthCreds()
+export const patchAppStateKey = (type, v) => type === 'app-state-sync-key' && v ? proto.Message.AppStateSyncKeyData.fromObject(v) : v
+export const ser = v => v == null ? null : JSON.parse(JSON.stringify(v, BufferJSON.replacer))
+export const deser = raw => {
+    if (raw == null) return null
+    let p = typeof raw === 'string'
+        ? (() => { try { return JSON.parse(raw) } catch { return raw } })()
+        : raw
+    let depth = 0
+    while (depth++ < 3 && p && typeof p === 'object' && !Array.isArray(p) && Object.keys(p).length === 1 && 'value' in p) p = p.value
+    if (p == null) return null
+    if (typeof p === 'object' && '__checksum' in p && 'data' in p) p = p.data
+    return JSON.parse(JSON.stringify(p), BufferJSON.reviver)
+}

package/lib/Utils/bot-capabilities.js

@@ -2,6 +2,7 @@ import { proto } from '../../WAProto/index.js'
 import { BOT_RENDERING_CONFIG_METADATA } from '../Defaults/index.js'
 
 export const BotCapabilityType = proto.BotCapabilityMetadata.BotCapabilityType
+export const RichSubMessageType = proto.AIRichResponseSubMessageType
 
 const capabilityNames = new Set(Object.keys(BotCapabilityType).filter(n => Number.isNaN(Number(n))))
 

package/lib/Utils/crypto.js

@@ -28,7 +28,7 @@ export const aesEncryptGCM = (plaintext, key, iv, additionalData) => {
 }
 
 export const aesDecryptGCM = (ciphertext, key, iv, additionalData) => {
-    const decipher = createDecipheriv('aes-256-gcm', key, iv)
+    const decipher = createDecipheriv('aes-256-gcm', key, iv, { authTagLength: GCM_TAG_LENGTH })
     decipher.setAAD(additionalData)
     decipher.setAuthTag(ciphertext.subarray(-GCM_TAG_LENGTH))
     return Buffer.concat([decipher.update(ciphertext.subarray(0, -GCM_TAG_LENGTH)), decipher.final()])
@@ -37,6 +37,7 @@ export const aesDecryptGCM = (ciphertext, key, iv, additionalData) => {
 export const aesEncryptCTR = (plaintext, key, iv) => { const c = createCipheriv('aes-256-ctr', key, iv); return Buffer.concat([c.update(plaintext), c.final()]) }
 export const aesDecryptCTR = (ciphertext, key, iv) => { const d = createDecipheriv('aes-256-ctr', key, iv); return Buffer.concat([d.update(ciphertext), d.final()]) }
 
+// aes-256-cbc is required by the WhatsApp media encryption spec (CBC + HMAC-SHA256)
 export const aesDecryptWithIV = (buffer, key, IV) => { const d = createDecipheriv('aes-256-cbc', key, IV); return Buffer.concat([d.update(buffer), d.final()]) }
 export const aesDecrypt = (buffer, key) => aesDecryptWithIV(buffer.subarray(16), key, buffer.subarray(0, 16))
 

package/lib/Utils/extras.js

@@ -25,7 +25,7 @@ export const decryptWithRevealKey = (encPayload, encIv, revealKey) => {
     const key = Buffer.from(revealKey)
     const payload = Buffer.from(encPayload)
     if (payload.length < SCHEDULED_MSG_TAG_BYTES) throw new TypeError('encrypted payload is too short to carry an auth tag')
-    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(encIv))
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(encIv), { authTagLength: SCHEDULED_MSG_TAG_BYTES })
     decipher.setAuthTag(payload.subarray(payload.length - SCHEDULED_MSG_TAG_BYTES))
     return Buffer.concat([decipher.update(payload.subarray(0, payload.length - SCHEDULED_MSG_TAG_BYTES)), decipher.final()])
 }

package/lib/Utils/generics.js

@@ -44,7 +44,7 @@ export const generateRegistrationId = () => Uint16Array.from(randomBytes(2))[0]
 
 export const encodeBigEndian = (e, t = 4) => { let r = e; const a = new Uint8Array(t); for (let i = t - 1; i >= 0; i--) { a[i] = 255 & r; r >>>= 8 }; return a }
 
-export const toNumber = t => typeof t === 'object' && t ? ('toNumber' in t ? t.toNumber() : t.low) : t || 0
+export const toNumber = t => { if (typeof t === 'bigint') return Number(t); if (typeof t === 'object' && t) return 'toNumber' in t ? t.toNumber() : (t.low ?? 0); return t || 0 }
 export const unixTimestampSeconds = (date = new Date()) => Math.floor(date.getTime() / 1000)
 
 export const debouncedTimeout = (intervalMs = 1000, task) => {

package/lib/Utils/index.js

@@ -14,6 +14,7 @@ export * from './lt-hash.js'
 export * from './auth-utils.js'
 export * from './baileys-event-stream.js'
 export * from './use-multi-file-auth-state.js'
+export * from './use-keyv-auth-state.js'
 export * from './link-preview.js'
 export * from './event-buffer.js'
 export * from './process-message.js'

package/lib/Utils/message-composer.js

@@ -1,4 +1,6 @@
 import { generateMessageIDV2, tokenizeCode } from './generics.js'
+import { RichSubMessageType } from './bot-capabilities.js'
+import { proto } from '../../WAProto/index.js'
 
 const buildRichContextInfo = (quoted, options = {}) => {
     const ctx = { forwardingScore: 1, isForwarded: true, forwardedAiBotMessageInfo: { botJid: options.botJid || '867051314767696@bot' }, forwardOrigin: 4, ...(options.mentions ? { mentionedJid: options.mentions } : {}) }
@@ -7,14 +9,14 @@ const buildRichContextInfo = (quoted, options = {}) => {
 }
 
 const buildBotForwardedMessage = (submessages, contextInfo, unifiedResponse) => {
-    const rich = { messageType: 1, submessages, contextInfo }
+    const rich = { messageType: proto.AIRichResponseMessageType.AI_RICH_RESPONSE_TYPE_STANDARD, submessages, contextInfo }
     if (unifiedResponse) rich.unifiedResponse = unifiedResponse
     return { botForwardedMessage: { message: { richResponseMessage: rich } } }
 }
 
 const wrap = (sub, quoted, options) => ({ message: buildBotForwardedMessage(sub, buildRichContextInfo(quoted, options)), messageId: generateMessageIDV2() })
-const text = msg => ({ messageType: 2, messageText: msg })
-const table = (title, rows) => ({ messageType: 4, tableMetadata: { title, rows } })
+const text = msg => ({ messageType: RichSubMessageType.AI_RICH_RESPONSE_TEXT, messageText: msg })
+const table = (title, rows) => ({ messageType: RichSubMessageType.AI_RICH_RESPONSE_TABLE, tableMetadata: { title, rows } })
 
 export const generateTableContent = (title, headers, rows, quoted, options = {}) => {
     const { footer, headerText } = options
@@ -30,7 +32,8 @@ export const generateListContent = (title, items, quoted, options = {}) => {
 
 export const generateCodeBlockContent = (code, quoted, options = {}) => {
     const { title, footer, language = 'javascript' } = options
-    const sub = [...(title ? [text(title)] : []), { messageType: 5, codeMetadata: { codeLanguage: language, codeBlocks: tokenizeCode(code, language) } }, ...(footer ? [text(footer)] : [])]
+    const { codeBlocks } = tokenizeCode(code, language)
+    const sub = [...(title ? [text(title)] : []), { messageType: RichSubMessageType.AI_RICH_RESPONSE_CODE, codeMetadata: { codeLanguage: language, codeBlocks } }, ...(footer ? [text(footer)] : [])]
     return wrap(sub, quoted, options)
 }
 
@@ -45,7 +48,7 @@ export const generateLatexContent = (quoted, options = {}) => {
         if (imageTrailingPadding !== undefined) e.imageTrailingPadding = imageTrailingPadding
         return e
     })
-    const sub = [...(headerText ? [text(headerText)] : []), { messageType: 8, latexMetadata: { text: txt || '', expressions: latexExpressions } }, ...(footer ? [text(footer)] : [])]
+    const sub = [...(headerText ? [text(headerText)] : []), { messageType: RichSubMessageType.AI_RICH_RESPONSE_LATEX, latexMetadata: { text: txt || '', expressions: latexExpressions } }, ...(footer ? [text(footer)] : [])]
     return wrap(sub, quoted, options)
 }
 

package/lib/Utils/messages.js

@@ -16,6 +16,7 @@ import { CALL_AUDIO_PREFIX, CALL_VIDEO_PREFIX, MEDIA_KEYS, URL_REGEX, WA_DEFAULT
 import { WAMessageStatus, WAProto } from '../Types/index.js'
 import { isJidGroup, isJidNewsletter, isJidStatusBroadcast, jidNormalizedUser } from '../WABinary/index.js'
 import { sha256 } from './crypto.js'
+import { resolveNativeFlowButtons } from './native-flow.js'
 import { generateMessageIDV2, getKeyAuthor, unixTimestampSeconds } from './generics.js'
 import { downloadContentFromMessage, encryptedStream, prepareStream, generateThumbnail, getAudioDuration, getAudioWaveform, getStream, toBuffer, normalizeToBuffer } from './messages-media.js'
 import { shouldIncludeReportingToken } from './reporting-utils.js'
@@ -546,9 +547,9 @@ const applyContextInfoAndMentions = async (interactive, msg) => {
 
 const OVERLAY_HANDLERS = {
     buttons: async (m, msg) => {
-        const hasNativeFlow = msg.buttons.some(b => b.nativeFlowInfo || b.name || b.buttonParamsJson)
+        const hasNativeFlow = msg.buttons.some(b => b.nativeFlowInfo || b.name || b.buttonParamsJson || b.url || b.call || b.sections)
         if (hasNativeFlow) {
-            const interactive = { body: { text: msg.text || msg.caption || msg.contentText || '' }, footer: { text: msg.footer || msg.footerText || '' }, nativeFlowMessage: { buttons: msg.buttons.map(b => b.name && b.buttonParamsJson ? b : b.nativeFlowInfo ? { name: b.nativeFlowInfo.name, buttonParamsJson: b.nativeFlowInfo.paramsJson } : { name: 'quick_reply', buttonParamsJson: JSON.stringify({ display_text: b.buttonText?.displayText || b.displayText || '', id: b.buttonId || b.id || '' }) }) } }
+            const interactive = { body: { text: msg.text || msg.caption || msg.contentText || '' }, footer: { text: msg.footer || msg.footerText || '' }, nativeFlowMessage: { buttons: resolveNativeFlowButtons(msg.buttons) } }
             if (msg.title) interactive.header = { title: msg.title, subtitle: msg.subtitle || '', hasMediaAttachment: msg.hasMediaAttachment || false }
             if (Object.keys(m).length) { interactive.header ??= { title: msg.title || '', hasMediaAttachment: true }; Object.assign(interactive.header, m) }
             await applyContextInfoAndMentions(interactive, msg)
@@ -575,6 +576,11 @@ const OVERLAY_HANDLERS = {
         if (msg.mentions?.length) ht.contextInfo = { ...(ht.contextInfo || {}), mentionedJid: msg.mentions }
         return { templateMessage: { fourRowTemplate: ht, hydratedTemplate: ht } }
     },
+    audioFooter: async (m, msg, opts) => {
+        const audio = await prepareWAMessageMedia({ audio: msg.audioFooter }, { upload: opts.upload ?? opts.waUploadToServer })
+        const buttons = resolveNativeFlowButtons(Array.isArray(msg.nativeFlow) ? msg.nativeFlow : [msg.nativeFlow])
+        return { interactiveMessage: { body: { text: msg.text || '' }, footer: { text: msg.footer || '' }, header: { hasMediaAttachment: false }, nativeFlowMessage: { buttons }, footerColumns: [{ audioMessage: audio.audioMessage }] } }
+    },
     interactiveButtons: async (m, msg) => {
         const interactive = { nativeFlowMessage: WAProto.Message.InteractiveMessage.NativeFlowMessage.fromObject({ buttons: msg.interactiveButtons }) }
         if ('text' in msg) { interactive.body = { text: msg.text }; interactive.header = { title: msg.title || '', subtitle: msg.subtitle || '', hasMediaAttachment: false } }
@@ -628,7 +634,7 @@ export const generateWAMessageContent = async (message, options = {}) => {
     }
 
     // Apply overlays: any overlay key present in message replaces m
-    for (const key of overlayKeys) { if (key in message && message[key]) { m = await OVERLAY_HANDLERS[key](m, message); break } }
+    for (const key of overlayKeys) { if (key in message && message[key]) { m = await OVERLAY_HANDLERS[key](m, message, options); break } }
 
     // Merge contextInfo / mentions onto the primary content key — deep-merges externalAdReply to prevent thumbnail/field loss
     const finalKey = Object.keys(m)[0]

package/lib/Utils/native-flow.js

@@ -49,6 +49,32 @@ export const buildWhatsAppFlowButton = ({ flowId, flowToken, cta = 'Open form',
     }
 }
 
+export const resolveNativeFlowButtons = (rawButtons) => {
+    const buttons = Array.isArray(rawButtons) ? rawButtons : [rawButtons]
+    return buttons.map(b => {
+        if (b.name && b.buttonParamsJson) return b  // already formatted
+        const text = b.text ?? b.display_text ?? ''
+        if (b.sections) return { name: 'single_select', buttonParamsJson: JSON.stringify({ title: text, sections: b.sections }) }
+        if (b.url && b.useWebview) return { name: 'cta_open_webview', buttonParamsJson: JSON.stringify({ display_text: text, url: b.url }) }
+        if (b.url) return { name: 'cta_url', buttonParamsJson: JSON.stringify({ display_text: text, url: b.url, merchant_url: b.merchantUrl ?? b.url }) }
+        if (b.call) return { name: 'cta_call', buttonParamsJson: JSON.stringify({ display_text: text, phone_number: b.call }) }
+        if (b.copy) return { name: 'cta_copy', buttonParamsJson: JSON.stringify({ display_text: text, copy_code: b.copy }) }
+        if (b.flow_id ?? b.flowId) return { name: 'flow', buttonParamsJson: JSON.stringify({ display_text: text, flow_id: b.flow_id ?? b.flowId, flow_token: b.flow_token ?? b.flowToken ?? crypto.randomUUID() }) }
+        if (b.remind) return { name: 'cta_reminder', buttonParamsJson: JSON.stringify({ display_text: text, ...b.remind }) }
+        if (b.cancelReminder) return { name: 'cta_cancel_reminder', buttonParamsJson: JSON.stringify({ display_text: text }) }
+        if (b.location) return { name: 'send_location', buttonParamsJson: JSON.stringify({ display_text: text }) }
+        if (b.address) return { name: 'address_message', buttonParamsJson: JSON.stringify({ display_text: text }) }
+        if (b.catalog) return { name: 'catalog_message', buttonParamsJson: JSON.stringify({ display_text: text, ...b.catalog }) }
+        if (b.reviewAndPay) return { name: 'review_and_pay', buttonParamsJson: JSON.stringify({ display_text: text, ...b.reviewAndPay }) }
+        if (b.reviewOrder) return { name: 'review_order', buttonParamsJson: JSON.stringify({ display_text: text, ...b.reviewOrder }) }
+        if (b.orderDetails) return { name: 'order_details', buttonParamsJson: JSON.stringify({ display_text: text, ...b.orderDetails }) }
+        if (b.paymentStatus) return { name: 'payment_status', buttonParamsJson: JSON.stringify({ display_text: text, ...b.paymentStatus }) }
+        if (b.transactionDetails) return { name: 'transaction_details', buttonParamsJson: JSON.stringify({ display_text: text, ...b.transactionDetails }) }
+        // default: quick_reply
+        return { name: 'quick_reply', buttonParamsJson: JSON.stringify({ display_text: text, id: b.id ?? text }) }
+    })
+}
+
 export const makeWhatsAppFlowButton = flow => ({
     name: flow?.nativeFlowName || 'galaxy_message',
     buttonParamsJson: JSON.stringify(buildWhatsAppFlowButton(flow)),

package/lib/Utils/spam-report-utils.js

@@ -1,14 +1,31 @@
-import { getBinaryNodeChild, getBinaryNodeChildString, isLidUser, isHostedLidUser, S_WHATSAPP_NET } from '../WABinary/index.js'
+import { getBinaryNodeChild, getBinaryNodeChildString, isLidUser, isHostedLidUser, isJidGroup, S_WHATSAPP_NET } from '../WABinary/index.js'
 import { extractMessageContent } from './messages.js'
 
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+// Controls how WA routes the report internally — pass via options.spamFlow to override auto-selection.
+// ACCOUNT_INFO_REPORT       → tag-based 1:1 contact report (default)
+// ACCOUNT_INFO_BLOCK        → tag-based contact report signalling intent to block
+// GROUP_INFO_REPORT         → tag-based group report (auto-selected for group JIDs)
+// CONTACT_INFO_REPORT       → legacy lightweight report, no reporting_tag needed
+// ONE_TO_ONE_SPAM_BANNER_REPORT → from the in-chat spam banner
+// MESSAGE_MENU              → from long-press message context menu
+// OVERFLOW_MENU_REPORT      → from the chat overflow (⋮) menu
 export const SPAM_FLOWS = {
     ACCOUNT_INFO_REPORT: 'account_info_report',
     ACCOUNT_INFO_BLOCK: 'account_info_block',
+    GROUP_INFO_REPORT: 'group_info_report',
+    CONTACT_INFO_REPORT: 'contact_info_report',
     ONE_TO_ONE_SPAM_BANNER_REPORT: '1_1_spam_banner_report',
     MESSAGE_MENU: 'message_menu',
     OVERFLOW_MENU_REPORT: 'overflow_menu_report',
 }
 
+// Numeric reason codes for the w:report IQ endpoint — used by reportUser() and reportMessage().
+export const REPORT_REASON_CODES = { spam: 1, harassment: 2, impersonation: 3, scam: 4, other: 5 }
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
 const toBuffer = data => {
     if (!data) return null
     if (Buffer.isBuffer(data)) return data
@@ -17,32 +34,44 @@ const toBuffer = data => {
     return null
 }
 
+// ─── JID resolution ───────────────────────────────────────────────────────────
+
+// Resolves a PN JID to its LID equivalent for tag-based spam IQs.
+// Groups and already-LID/hosted-LID JIDs pass through unchanged.
 export const resolveReportJid = async (jid, lidMapping) => {
-    if (!jid) throw new Error('reportSpam: jid required')
-    if (isLidUser(jid) || isHostedLidUser(jid)) return jid
-    if (lidMapping?.getLIDForPN) {
-        const lid = await lidMapping.getLIDForPN(jid)
-        if (lid) return lid
-    }
-    return jid
+    if (!jid) throw new Error('resolveReportJid: jid required')
+    if (isJidGroup(jid) || isLidUser(jid) || isHostedLidUser(jid)) return jid
+    const lid = lidMapping?.getLIDForPN ? await lidMapping.getLIDForPN(jid) : null
+    return lid ?? jid
+}
+
+// Auto-detects JID type and returns the resolved JID + correct spam_flow for reportSpam().
+// Returns { reportJid, spamFlow, isGroup }.
+export const resolveReportContext = async (jid, lidMapping) => {
+    if (!jid) throw new Error('resolveReportContext: jid required')
+    if (isJidGroup(jid)) return { reportJid: jid, spamFlow: SPAM_FLOWS.GROUP_INFO_REPORT, isGroup: true }
+    return { reportJid: await resolveReportJid(jid, lidMapping), spamFlow: SPAM_FLOWS.ACCOUNT_INFO_REPORT, isGroup: false }
 }
 
+// ─── Tag / text extraction ────────────────────────────────────────────────────
+
+// Normalizes a raw reporting_tag to a Buffer — returns null if invalid or empty.
 export const normalizeReportingTag = tag => {
     const buf = toBuffer(tag)
     return buf?.length ? buf : null
 }
 
+// Extracts plain text from a WAMessage across common message types.
 export const extractMessageText = msg => {
     if (!msg?.message) return ''
-    const content = extractMessageContent(msg.message)
-    if (!content) return ''
-    if (typeof content.conversation === 'string') return content.conversation
-    if (content.extendedTextMessage?.text) return content.extendedTextMessage.text
-    if (content.imageMessage?.caption) return content.imageMessage.caption
-    if (content.videoMessage?.caption) return content.videoMessage.caption
-    return ''
+    const c = extractMessageContent(msg.message)
+    if (!c) return ''
+    return c.conversation ?? c.extendedTextMessage?.text ?? c.imageMessage?.caption ?? c.videoMessage?.caption ?? ''
 }
 
+// Extracts { stanzaId, timestamp, reportingTag, reportingToken, tokenVersion, validationPolicy }
+// from a raw incoming binary stanza. Call inside messages.upsert and persist via reportingInfoStore
+// so reportSpam() can use the tags later.
 export const extractReportingInfoFromStanza = stanza => {
     const reporting = getBinaryNodeChild(stanza, 'reporting')
     if (!reporting) return null
@@ -56,60 +85,71 @@ export const extractReportingInfoFromStanza = stanza => {
     const stanzaId = tagNode.attrs?.id || stanza.attrs?.id
     if (!stanzaId) return null
     const tsRaw = tagNode.attrs?.ts_s || stanza.attrs?.t
-    const reportingToken = tokenNode?.content ? toBuffer(tokenNode.content) : null
-    const tokenVersion = tokenNode?.attrs?.v ? parseInt(tokenNode.attrs.v) : null
-    const validationPolicy = reporting.attrs?.validation_policy || null
-    return { stanzaId, timestamp: tsRaw ? Number(tsRaw) : 0, reportingTag, reportingToken, tokenVersion, validationPolicy }
+    return {
+        stanzaId,
+        timestamp: tsRaw ? Number(tsRaw) : 0,
+        reportingTag,
+        reportingToken: tokenNode?.content ? toBuffer(tokenNode.content) : null,
+        tokenVersion: tokenNode?.attrs?.v ? parseInt(tokenNode.attrs.v) : null,
+        validationPolicy: reporting.attrs?.validation_policy || null,
+    }
 }
 
-export const buildSpamReportMessageNodes = messages => messages.slice(0, 5).map(m => {
-    const reportingTag = normalizeReportingTag(m.reportingTag)
-    if (!reportingTag) throw new Error(`reportSpam: missing reportingTag for ${m.stanzaId}`)
-    return {
-        tag: 'message',
-        attrs: {
-            t: String(m.timestamp),
-            id: m.stanzaId,
-            reported_push_name: m.pushName || '',
-            type: m.messageType || 'text',
-            from: m.fromJid,
-        },
-        content: [
-            {
-                tag: 'raw',
-                attrs: { local_message_type: '0', v: '2' },
-                content: m.text ?? '',
-            },
-            {
-                tag: 'reporting',
-                attrs: {},
-                content: [{
-                    tag: 'reporting_validation',
-                    attrs: {},
-                    content: [{
-                        tag: 'reporting_tag',
-                        attrs: { id: m.stanzaId, ts_s: String(m.timestamp) },
-                        content: reportingTag,
-                    }],
-                }],
-            },
-        ],
+// ─── Node builders ────────────────────────────────────────────────────────────
+
+// Builds <message> child nodes for a spam_list IQ.
+// Skips messages missing a reportingTag (warn) — throws only if all are filtered (error).
+export const buildSpamReportMessageNodes = (messages, logger) => {
+    const ts = () => Math.floor(Date.now() / 1000)
+    const nodes = messages.slice(0, 5).reduce((acc, m) => {
+        const reportingTag = normalizeReportingTag(m.reportingTag)
+        if (!reportingTag) {
+            logger?.warn?.({ stanzaId: m.stanzaId }, 'buildSpamReportMessageNodes: skipping — missing reportingTag')
+            return acc
+        }
+        const t = String(m.timestamp || ts())
+        acc.push({
+            tag: 'message',
+            attrs: { t, id: m.stanzaId, reported_push_name: m.pushName || '', type: m.messageType || 'text', from: m.fromJid },
+            content: [
+                { tag: 'raw', attrs: { local_message_type: '0', v: '2' }, content: m.text != null ? String(m.text) : '' },
+                { tag: 'reporting', attrs: {}, content: [{ tag: 'reporting_validation', attrs: {}, content: [{ tag: 'reporting_tag', attrs: { id: m.stanzaId, ts_s: t }, content: reportingTag }] }] },
+            ],
+        })
+        return acc
+    }, [])
+    if (!nodes.length) {
+        logger?.error?.({}, 'buildSpamReportMessageNodes: all messages filtered — none had a valid reportingTag')
+        throw new Error('reportSpam: no valid messages with reportingTag after filtering')
     }
-})
+    return nodes
+}
 
-export const buildSpamReportIq = (jid, messages, spamFlow = SPAM_FLOWS.ACCOUNT_INFO_REPORT) => {
-    if (!messages?.length) throw new Error('reportSpam: at least one message with reporting_tag required')
+// Builds the full xmlns="spam" IQ stanza for tag-based reporting — used by reportSpam().
+export const buildSpamReportIq = (jid, messages, spamFlow = SPAM_FLOWS.ACCOUNT_INFO_REPORT, logger) => {
+    if (!messages?.length) {
+        logger?.error?.({ jid, spamFlow }, 'buildSpamReportIq: called with empty messages array')
+        throw new Error('reportSpam: at least one message with reporting_tag required')
+    }
     return {
         tag: 'iq',
         attrs: { type: 'set', xmlns: 'spam', to: S_WHATSAPP_NET },
-        content: [{
-            tag: 'spam_list',
-            attrs: { jid, spam_flow: spamFlow },
-            content: buildSpamReportMessageNodes(messages),
-        }],
+        content: [{ tag: 'spam_list', attrs: { jid, spam_flow: spamFlow }, content: buildSpamReportMessageNodes(messages, logger) }],
     }
 }
 
+// Builds the simpler xmlns="spam" <report> node — used by reportContact() and reportGroup().
+// Does NOT require reporting_tags, only message key ids or bare id strings.
+export const buildSimpleReportNode = (jid, messageKeys) => ({
+    tag: 'report',
+    attrs: { jid, type: 'spam' },
+    content: (messageKeys || []).map(key => ({ tag: 'message', attrs: { id: key.id || key, ...(key.fromMe ? {} : { from: jid }) } })),
+})
+
+// ─── Response parser ──────────────────────────────────────────────────────────
+
+// Parses the IQ result node from any spam report query.
+// Returns { success: true, reportId? } on success or { success: false, error } on failure.
 export const parseSpamReportResponse = result => {
     if (!result) return { success: false, error: 'empty response' }
     if (result.attrs?.type === 'error') {
@@ -123,13 +163,4 @@ export const parseSpamReportResponse = result => {
     if (reportId) return { success: true, reportId: String(reportId) }
     if (result.attrs?.type === 'result') return { success: true }
     return { success: false, error: 'unexpected spam IQ response' }
-}
-
-export const buildSimpleReportNode = (jid, messageKeys) => ({
-    tag: 'report',
-    attrs: { jid, type: 'spam' },
-    content: (messageKeys || []).map(key => ({
-        tag: 'message',
-        attrs: { id: key.id || key, from: key.fromMe ? undefined : jid },
-    })),
-})
+}