@nexustechpro/baileys 2.0.1 → 2.0.2

package/lib/Socket/messages-send.js

@@ -34,7 +34,10 @@ export const makeMessagesSocket = (config) => {
     } = config
 
     const sock = makeNewsletterSocket(config)
-    const { ev, authState, processingMutex, signalRepository, upsertMessage, query, fetchPrivacySettings, sendNode, groupMetadata, groupToggleEphemeral } = sock
+    const {
+        ev, authState, processingMutex, signalRepository, upsertMessage, query,
+        fetchPrivacySettings, sendNode, groupMetadata, groupToggleEphemeral
+    } = sock
 
     const userDevicesCache = config.userDevicesCache || new NodeCache({ stdTTL: DEFAULT_CACHE_TTLS.USER_DEVICES, useClones: false })
     const peerSessionsCache = new NodeCache({ stdTTL: DEFAULT_CACHE_TTLS.USER_DEVICES, useClones: false })
@@ -42,7 +45,11 @@ export const makeMessagesSocket = (config) => {
     const encryptionMutex = makeKeyedMutex()
     let mediaConn
 
-    // ===== MEDIA CONNECTION =====
+    // ─────────────────────────────────────────────
+    // MEDIA CONNECTION
+    // Fetches and caches the WhatsApp media upload connection.
+    // Refreshes automatically when TTL expires or forced.
+    // ─────────────────────────────────────────────
     const refreshMediaConn = async (forceGet = false) => {
         const media = await mediaConn
         if (!media || forceGet || Date.now() - media.fetchDate.getTime() > media.ttl * 1000) {
@@ -51,7 +58,9 @@ export const makeMessagesSocket = (config) => {
                 const mediaConnNode = getBinaryNodeChild(result, 'media_conn')
                 return {
                     hosts: getBinaryNodeChildren(mediaConnNode, 'host').map(({ attrs }) => ({ hostname: attrs.hostname, maxContentLengthBytes: +attrs.maxContentLengthBytes })),
-                    auth: mediaConnNode.attrs.auth, ttl: +mediaConnNode.attrs.ttl, fetchDate: new Date()
+                    auth: mediaConnNode.attrs.auth,
+                    ttl: +mediaConnNode.attrs.ttl,
+                    fetchDate: new Date()
                 }
             })()
             logger.debug('fetched media conn')
@@ -59,23 +68,35 @@ export const makeMessagesSocket = (config) => {
         return mediaConn
     }
 
-    // ===== RECEIPTS =====
+    // ─────────────────────────────────────────────
+    // RECEIPTS
+    // Sends read receipts and delivery confirmations.
+    // ─────────────────────────────────────────────
     const sendReceipt = async (jid, participant, messageIds, type) => {
         if (!messageIds?.length) throw new Boom('missing ids in receipt')
         const node = { tag: 'receipt', attrs: { id: messageIds[0] } }
         const isReadReceipt = type === 'read' || type === 'read-self'
         if (isReadReceipt) node.attrs.t = unixTimestampSeconds().toString()
-        if (type === 'sender' && (isPnUser(jid) || isLidUser(jid))) { node.attrs.recipient = jid; node.attrs.to = participant } 
-        else { node.attrs.to = jid; if (participant) node.attrs.participant = participant }
+        if (type === 'sender' && (isPnUser(jid) || isLidUser(jid))) {
+            node.attrs.recipient = jid
+            node.attrs.to = participant
+        } else {
+            node.attrs.to = jid
+            if (participant) node.attrs.participant = participant
+        }
         if (type) node.attrs.type = type
-        if (messageIds.length > 1) node.content = [{ tag: 'list', attrs: {}, content: messageIds.slice(1).map(id => ({ tag: 'item', attrs: { id } })) }]
+        if (messageIds.length > 1) {
+            node.content = [{ tag: 'list', attrs: {}, content: messageIds.slice(1).map(id => ({ tag: 'item', attrs: { id } })) }]
+        }
         logger.debug({ attrs: node.attrs, messageIds }, 'sending receipt')
         await sendNode(node)
     }
 
     const sendReceipts = async (keys, type) => {
         const recps = aggregateMessageKeysNotFromMe(keys)
-        for (const { jid, participant, messageIds } of recps) await sendReceipt(jid, participant, messageIds, type)
+        for (const { jid, participant, messageIds } of recps) {
+            await sendReceipt(jid, participant, messageIds, type)
+        }
     }
 
     const readMessages = async (keys) => {
@@ -83,7 +104,11 @@ export const makeMessagesSocket = (config) => {
         await sendReceipts(keys, privacySettings.readreceipts === 'all' ? 'read' : 'read-self')
     }
 
-    // ===== DEVICES & SESSIONS =====
+    // ─────────────────────────────────────────────
+    // DEVICE & SESSION MANAGEMENT
+    // Fetches participant devices via USync and manages
+    // Signal protocol sessions for encryption.
+    // ─────────────────────────────────────────────
     const getUSyncDevices = async (jids, useCache, ignoreZeroDevices) => {
         const deviceResults = []
         if (!useCache) logger.debug('not using cache for devices')
@@ -92,26 +117,41 @@ export const makeMessagesSocket = (config) => {
             const decoded = jidDecode(jid)
             const user = decoded?.user
             const device = decoded?.device
+            // Already has a device number — push directly
             if (typeof device === 'number' && device >= 0 && user) { deviceResults.push({ user, device, jid }); return null }
             return { jid: jidNormalizedUser(jid), user }
         }).filter(Boolean)
 
         let mgetDevices
-        if (useCache && userDevicesCache.mget) mgetDevices = await userDevicesCache.mget(jidsWithUser.map(j => j?.user).filter(Boolean))
+        if (useCache && userDevicesCache.mget) {
+            mgetDevices = await userDevicesCache.mget(jidsWithUser.map(j => j?.user).filter(Boolean))
+        }
 
         const toFetch = []
         for (const { jid, user } of jidsWithUser) {
             if (useCache) {
                 const devices = mgetDevices?.[user] || (userDevicesCache.mget ? undefined : await userDevicesCache.get(user))
-                if (devices) { deviceResults.push(...devices.map(d => ({ ...d, jid: jidEncode(d.user, d.server, d.device) }))); logger.trace({ user }, 'using cache for devices') } 
-                else toFetch.push(jid)
-            } else toFetch.push(jid)
+                if (devices) {
+                    deviceResults.push(...devices.map(d => ({ ...d, jid: jidEncode(d.user, d.server, d.device) })))
+                    logger.trace({ user }, 'using cache for devices')
+                } else {
+                    toFetch.push(jid)
+                }
+            } else {
+                toFetch.push(jid)
+            }
         }
 
         if (!toFetch.length) return deviceResults
 
+        // Track which JIDs are LID-based so we can encode them correctly
         const requestedLidUsers = new Set()
-        for (const jid of toFetch) if (isLidUser(jid) || isHostedLidUser(jid)) { const user = jidDecode(jid)?.user; if (user) requestedLidUsers.add(user) }
+        for (const jid of toFetch) {
+            if (isLidUser(jid) || isHostedLidUser(jid)) {
+                const user = jidDecode(jid)?.user
+                if (user) requestedLidUsers.add(user)
+            }
+        }
 
         const query = new USyncQuery().withContext('message').withDeviceProtocol().withLIDProtocol()
         for (const jid of toFetch) query.withUser(new USyncUser().withId(jid))
@@ -119,10 +159,14 @@ export const makeMessagesSocket = (config) => {
         const result = await sock.executeUSyncQuery(query)
         if (result) {
             const lidResults = result.list.filter(a => !!a.lid)
-            if (lidResults.length > 0) { logger.trace('Storing LID maps from device call'); await signalRepository.lidMapping.storeLIDPNMappings(lidResults.map(a => ({ lid: a.lid, pn: a.id }))) }
+            if (lidResults.length > 0) {
+                logger.trace('Storing LID maps from device call')
+                await signalRepository.lidMapping.storeLIDPNMappings(lidResults.map(a => ({ lid: a.lid, pn: a.id })))
+            }
+
+            // Pre-assert sessions for newly discovered LID users
             try {
                 const lids = lidResults.map(a => a.lid)
-                // Re-fetch sessions during device lookup to ensure fresh state
                 if (lids.length) await assertSessions(lids, false)
             } catch (e) {
                 logger.warn({ error: e, count: lidResults.length }, 'failed to assert sessions for newly mapped LIDs')
@@ -130,62 +174,90 @@ export const makeMessagesSocket = (config) => {
 
             const extracted = extractDeviceJids(result?.list, authState.creds.me.id, authState.creds.me.lid, ignoreZeroDevices)
             const deviceMap = {}
-            for (const item of extracted) { deviceMap[item.user] = deviceMap[item.user] || []; deviceMap[item.user]?.push(item) }
+            for (const item of extracted) {
+                deviceMap[item.user] = deviceMap[item.user] || []
+                deviceMap[item.user]?.push(item)
+            }
 
             for (const [user, userDevices] of Object.entries(deviceMap)) {
-                const isLidUser = requestedLidUsers.has(user)
+                const isLid = requestedLidUsers.has(user)
                 for (const item of userDevices) {
-                    const finalJid = isLidUser ? jidEncode(user, item.server, item.device) : jidEncode(item.user, item.server, item.device)
+                    const finalJid = isLid ? jidEncode(user, item.server, item.device) : jidEncode(item.user, item.server, item.device)
                     deviceResults.push({ ...item, jid: finalJid })
                 }
             }
 
-            if (userDevicesCache.mset) await userDevicesCache.mset(Object.entries(deviceMap).map(([key, value]) => ({ key, value })))
-            else for (const key in deviceMap) if (deviceMap[key]) await userDevicesCache.set(key, deviceMap[key])
+            // Cache results
+            if (userDevicesCache.mset) {
+                await userDevicesCache.mset(Object.entries(deviceMap).map(([key, value]) => ({ key, value })))
+            } else {
+                for (const key in deviceMap) if (deviceMap[key]) await userDevicesCache.set(key, deviceMap[key])
+            }
 
+            // Persist device lists for session migration support (capped at 500 users)
             const userDeviceUpdates = {}
-            for (const [userId, devices] of Object.entries(deviceMap)) if (devices?.length > 0) userDeviceUpdates[userId] = devices.map(d => d.device?.toString() || '0')
-
+            for (const [userId, devices] of Object.entries(deviceMap)) {
+                if (devices?.length > 0) userDeviceUpdates[userId] = devices.map(d => d.device?.toString() || '0')
+            }
             if (Object.keys(userDeviceUpdates).length > 0) {
                 try {
                     const existingData = await authState.keys.get('device-list', ['_index'])
                     const currentBatch = existingData?.['_index'] || {}
                     const mergedBatch = { ...currentBatch, ...userDeviceUpdates }
-                    const userKeys = Object.keys(mergedBatch).sort()
                     const trimmedBatch = {}
-                    userKeys.slice(-500).forEach(userId => { trimmedBatch[userId] = mergedBatch[userId] })
+                    Object.keys(mergedBatch).sort().slice(-500).forEach(userId => { trimmedBatch[userId] = mergedBatch[userId] })
                     await authState.keys.set({ 'device-list': { '_index': trimmedBatch } })
                     logger.debug({ userCount: Object.keys(userDeviceUpdates).length, batchSize: Object.keys(trimmedBatch).length }, 'stored user device lists')
-                } catch (error) { logger.warn({ error }, 'failed to store user device lists') }
+                } catch (error) {
+                    logger.warn({ error }, 'failed to store user device lists')
+                }
             }
         }
         return deviceResults
     }
 
     const assertSessions = async (jids, force) => {
-    let didFetchNewSession = false
-    const uniqueJids = [...new Set(jids)]
-    const jidsRequiringFetch = []
-
-    for (const jid of uniqueJids) {
-        const signalId = signalRepository.jidToSignalProtocolAddress(jid)
-        const cachedSession = peerSessionsCache.get(signalId)
-        if (cachedSession !== undefined) { if (cachedSession && !force) continue }  // ← Add && !force
-        else { const sessionValidation = await signalRepository.validateSession(jid); peerSessionsCache.set(signalId, sessionValidation.exists); if (sessionValidation.exists && !force) continue }  // ← Add && !force
-        jidsRequiringFetch.push(jid)
-    }
+        const uniqueJids = [...new Set(jids)]
+        const jidsRequiringFetch = []
+
+        for (const jid of uniqueJids) {
+            const signalId = signalRepository.jidToSignalProtocolAddress(jid)
+            const cachedSession = peerSessionsCache.get(signalId)
+            if (cachedSession !== undefined) {
+                if (cachedSession && !force) continue
+            } else {
+                const sessionValidation = await signalRepository.validateSession(jid)
+                peerSessionsCache.set(signalId, sessionValidation.exists)
+                if (sessionValidation.exists && !force) continue
+            }
+            jidsRequiringFetch.push(jid)
+        }
+
+        if (!jidsRequiringFetch.length) return false
+
+        // Resolve LID JIDs for wire-level session fetch
+        const wireJids = [
+            ...jidsRequiringFetch.filter(jid => isLidUser(jid) || isHostedLidUser(jid)),
+            ...(await signalRepository.lidMapping.getLIDsForPNs(
+                jidsRequiringFetch.filter(jid => isPnUser(jid) || isHostedPnUser(jid))
+            ) || []).map(a => a.lid)
+        ]
 
-    if (jidsRequiringFetch.length) {
-        const wireJids = [...jidsRequiringFetch.filter(jid => isLidUser(jid) || isHostedLidUser(jid)), ...(await signalRepository.lidMapping.getLIDsForPNs(jidsRequiringFetch.filter(jid => isPnUser(jid) || isHostedPnUser(jid))) || []).map(a => a.lid)]
         logger.debug({ jidsRequiringFetch, wireJids }, 'fetching sessions')
-        const result = await query({ tag: 'iq', attrs: { xmlns: 'encrypt', type: 'get', to: S_WHATSAPP_NET }, content: [{ tag: 'key', attrs: {}, content: wireJids.map(jid => { const attrs = { jid }; if (force) attrs.reason = 'identity'; return { tag: 'user', attrs } }) }] })
+        const result = await query({
+            tag: 'iq',
+            attrs: { xmlns: 'encrypt', type: 'get', to: S_WHATSAPP_NET },
+            content: [{ tag: 'key', attrs: {}, content: wireJids.map(jid => { const attrs = { jid }; if (force) attrs.reason = 'identity'; return { tag: 'user', attrs } }) }]
+        })
         await parseAndInjectE2ESessions(result, signalRepository)
-        didFetchNewSession = true
         for (const wireJid of wireJids) peerSessionsCache.set(signalRepository.jidToSignalProtocolAddress(wireJid), true)
+        return true
     }
-    return didFetchNewSession
-}
 
+    // ─────────────────────────────────────────────
+    // PEER DATA OPERATIONS
+    // Used for history sync requests and placeholder resends.
+    // ─────────────────────────────────────────────
     const sendPeerDataOperationMessage = async (pdoMessage) => {
         if (!authState.creds.me?.id) throw new Boom('Not authenticated')
         return await relayMessage(jidNormalizedUser(authState.creds.me.id), {
@@ -193,62 +265,60 @@ export const makeMessagesSocket = (config) => {
         }, { additionalAttributes: { category: 'peer', push_priority: 'high_force' }, additionalNodes: [{ tag: 'meta', attrs: { appdata: 'default' } }] })
     }
 
-    const parseTCTokens = (result) => {
-    const tokens = {}
-    const tokenList = getBinaryNodeChild(result, 'tokens')
-    if (tokenList) {
-        const tokenNodes = getBinaryNodeChildren(tokenList, 'token')
-        for (const node of tokenNodes) {
-            const jid = node.attrs.jid
-            const token = node.content
-            if (jid && token) tokens[jid] = { token, timestamp: Number(unixTimestampSeconds()) }
-        }
-    }
-    return tokens
-}
-    const updateMemberLabel = (jid, memberLabel) => {
-         if (!memberLabel || typeof memberLabel !== 'string') throw new Error('Member label must be a non-empty string')
-         if (!isJidGroup(jid)) throw new Error('Member labels can only be set in groups')
-         return relayMessage(jid, { protocolMessage: { type: proto.Message.ProtocolMessage.Type.GROUP_MEMBER_LABEL_CHANGE, memberLabel: { label: memberLabel.slice(0, 30), labelTimestamp: unixTimestampSeconds() } } }, { additionalNodes: [{ tag: 'meta', attrs: { tag_reason: 'user_update', appdata: 'member_tag' }, content: undefined }] })
-    }
+    // ─────────────────────────────────────────────
+    // TC TOKEN (Trusted Contact Token)
+    // Used for end-to-end privacy verification with contacts.
+    // ─────────────────────────────────────────────
+    const TOKEN_EXPIRY_TTL = 24 * 60 * 60 // 24 hours in seconds
 
-    const createParticipantNodes = async (recipientJids, message, extraAttrs, dsmMessage) => {
-        if (!recipientJids.length) return { nodes: [], shouldIncludeDeviceIdentity: false }
-        const patched = await patchMessageBeforeSending(message, recipientJids)
-        const patchedMessages = Array.isArray(patched) ? patched : recipientJids.map(jid => ({ recipientJid: jid, message: patched }))
-        let shouldIncludeDeviceIdentity = false
-        const meId = authState.creds.me.id
-        const meLid = authState.creds.me?.lid
-        const meLidUser = meLid ? jidDecode(meLid)?.user : null
+    const isTokenExpired = (tokenData) => {
+        if (!tokenData || !tokenData.timestamp) return true
+        return unixTimestampSeconds() - Number(tokenData.timestamp) > TOKEN_EXPIRY_TTL
+    }
 
-        const encryptionPromises = patchedMessages.map(async ({ recipientJid: jid, message: patchedMessage }) => {
-            try {
-            if (!jid) return null
-            let msgToEncrypt = patchedMessage
-            if (dsmMessage) {
-                const { user: targetUser } = jidDecode(jid)
-                const { user: ownPnUser } = jidDecode(meId)
-                const isOwnUser = targetUser === ownPnUser || (meLidUser && targetUser === meLidUser)
-                const isExactSenderDevice = jid === meId || (meLid && jid === meLid)
-                if (isOwnUser && !isExactSenderDevice) { msgToEncrypt = dsmMessage; logger.debug({ jid, targetUser }, 'Using DSM for own device') }
+    const parseTCTokens = (result) => {
+        const tokens = {}
+        const tokenList = getBinaryNodeChild(result, 'tokens')
+        if (tokenList) {
+            for (const node of getBinaryNodeChildren(tokenList, 'token')) {
+                const { jid, content } = { jid: node.attrs.jid, content: node.content }
+                if (jid && content) tokens[jid] = { token: content, timestamp: Number(unixTimestampSeconds()) }
             }
-            const bytes = encodeWAMessage(msgToEncrypt)
-            return await encryptionMutex.mutex(jid, async () => {
-                const { type, ciphertext } = await signalRepository.encryptMessage({ jid, data: bytes })
-                if (type === 'pkmsg') shouldIncludeDeviceIdentity = true
-                return { tag: 'to', attrs: { jid }, content: [{ tag: 'enc', attrs: { v: '2', type, ...(extraAttrs || {}) }, content: ciphertext }] }
-            })
-        } catch (err) {
-            logger.error({jid, err }, 'Failed to encrypt for recipient')
-            return null
         }
+        return tokens
+    }
+
+    const getPrivacyTokens = async (jids) => {
+        const t = unixTimestampSeconds().toString()
+        const result = await query({
+            tag: 'iq',
+            attrs: { to: S_WHATSAPP_NET, type: 'set', xmlns: 'privacy' },
+            content: [{ tag: 'tokens', attrs: {}, content: jids.map(jid => ({ tag: 'token', attrs: { jid: jidNormalizedUser(jid), t, type: 'trusted_contact' } })) }]
         })
+        const tokens = parseTCTokens(result)
+        if (Object.keys(tokens).length > 0) await authState.keys.set({ 'tctoken': tokens })
+        return tokens
+    }
 
-        const nodes = (await Promise.all(encryptionPromises)).filter(Boolean)
-        return { nodes, shouldIncludeDeviceIdentity }
+    // ─────────────────────────────────────────────
+    // GROUP MEMBER LABEL
+    // Sets a custom label for a member in a group.
+    // ─────────────────────────────────────────────
+    const updateMemberLabel = (jid, memberLabel) => {
+        if (!memberLabel || typeof memberLabel !== 'string') throw new Error('Member label must be a non-empty string')
+        if (!isJidGroup(jid)) throw new Error('Member labels can only be set in groups')
+        return relayMessage(jid, {
+            protocolMessage: {
+                type: proto.Message.ProtocolMessage.Type.GROUP_MEMBER_LABEL_CHANGE,
+                memberLabel: { label: memberLabel.slice(0, 30), labelTimestamp: unixTimestampSeconds() }
+            }
+        }, { additionalNodes: [{ tag: 'meta', attrs: { tag_reason: 'user_update', appdata: 'member_tag' }, content: undefined }] })
     }
 
-    // ===== MESSAGE HELPERS =====
+    // ─────────────────────────────────────────────
+    // MESSAGE TYPE DETECTION
+    // Classifies messages for proper stanza type attribute.
+    // ─────────────────────────────────────────────
     const getMessageType = (msg) => {
         const message = normalizeMessageContent(msg)
         if (message.pollCreationMessage || message.pollCreationMessageV2 || message.pollCreationMessageV3) return 'poll'
@@ -282,266 +352,375 @@ export const makeMessagesSocket = (config) => {
         if (message.extendedTextMessage?.matchedText || message.groupInviteMessage) return 'url'
     }
 
-    // ===== RELAY MESSAGE =====
-const relayMessage = async (jid, message, { messageId: msgId, participant, additionalAttributes, additionalNodes, useUserDevicesCache, useCachedGroupMetadata, statusJidList, quoted } = {}) => {
-    const meId = authState.creds.me.id
-    const meLid = authState.creds.me?.lid
-    const isRetryResend = Boolean(participant?.jid)
-    let shouldIncludeDeviceIdentity = isRetryResend
-    let finalMsgId = msgId
-
-    // Check if message is already in proper WAMessage format
-    const hasProtoMessageType = Object.keys(message).some(key => key.endsWith('Message') || key === 'conversation')
-    
-    if (!hasProtoMessageType) {
-        logger.debug({ jid }, 'relayMessage: auto-generating message from raw content')
-        const generatedMsg = await generateWAMessage(jid, message, { logger, userJid: meId, getUrlInfo: text => getUrlInfo(text, { thumbnailWidth: linkPreviewImageThumbnailWidth, fetchOpts: { timeout: 3000, ...(httpRequestOptions || {}) }, logger, uploadImage: generateHighQualityLinkPreview ? waUploadToServer : undefined }), getProfilePicUrl: sock.profilePictureUrl, getCallLink: sock.createCallLink, upload: waUploadToServer, mediaCache: config.mediaCache, options: config.options, messageId: finalMsgId || generateMessageIDV2(meId), quoted: quoted })
-        message = generatedMsg.message
-        if (!finalMsgId) finalMsgId = generatedMsg.key.id
-        logger.debug({ msgId: finalMsgId, jid }, 'message auto-generated successfully')
-    }
+    // ─────────────────────────────────────────────
+    // PARTICIPANT NODE CREATION
+    // Encrypts a message for each recipient JID and
+    // wraps it in a binary <to> node for the stanza.
+    // ─────────────────────────────────────────────
+    const createParticipantNodes = async (recipientJids, message, extraAttrs, dsmMessage) => {
+        if (!recipientJids.length) return { nodes: [], shouldIncludeDeviceIdentity: false }
 
-    const { user, server } = jidDecode(jid)
-    const isGroup = server === 'g.us'
-    const isStatus = jid === 'status@broadcast'
-    const isLid = server === 'lid'
-    const isNewsletter = server === 'newsletter'
-
-    finalMsgId = finalMsgId || generateMessageIDV2(meId)
-    useUserDevicesCache = useUserDevicesCache !== false
-    useCachedGroupMetadata = useCachedGroupMetadata !== false && !isStatus
-
-    const participants = []
-    const destinationJid = !isStatus ? jid : 'status@broadcast'
-    const binaryNodeContent = []
-    const devices = []
-
-    const meMsg = { deviceSentMessage: { destinationJid, message }, messageContextInfo: message.messageContextInfo }
-    const extraAttrs = {}
-    const messages = normalizeMessageContent(message)
-    const buttonType = getButtonType(messages)
-
-    if (participant) {
-        if (!isGroup && !isStatus) additionalAttributes = { ...additionalAttributes, device_fanout: 'false' }
-        const { user, device } = jidDecode(participant.jid)
-        devices.push({ user, device, jid: participant.jid })
+        const patched = await patchMessageBeforeSending(message, recipientJids)
+        const patchedMessages = Array.isArray(patched) ? patched : recipientJids.map(jid => ({ recipientJid: jid, message: patched }))
+        let shouldIncludeDeviceIdentity = false
+
+        const meId = authState.creds.me.id
+        const meLid = authState.creds.me?.lid
+        const meLidUser = meLid ? jidDecode(meLid)?.user : null
+
+        const encryptionPromises = patchedMessages.map(async ({ recipientJid: jid, message: patchedMessage }) => {
+            try {
+                if (!jid) return null
+                let msgToEncrypt = patchedMessage
+
+                // Use Device Sent Message (DSM) for own linked devices so they can read the message
+                if (dsmMessage) {
+                    const { user: targetUser } = jidDecode(jid)
+                    const { user: ownPnUser } = jidDecode(meId)
+                    const isOwnUser = targetUser === ownPnUser || (meLidUser && targetUser === meLidUser)
+                    const isExactSenderDevice = jid === meId || (meLid && jid === meLid)
+                    if (isOwnUser && !isExactSenderDevice) { msgToEncrypt = dsmMessage; logger.debug({ jid, targetUser }, 'Using DSM for own device') }
+                }
+
+                const bytes = encodeWAMessage(msgToEncrypt)
+                return await encryptionMutex.mutex(jid, async () => {
+                    const { type, ciphertext } = await signalRepository.encryptMessage({ jid, data: bytes })
+                    if (type === 'pkmsg') shouldIncludeDeviceIdentity = true
+                    return { tag: 'to', attrs: { jid }, content: [{ tag: 'enc', attrs: { v: '2', type, ...(extraAttrs || {}) }, content: ciphertext }] }
+                })
+            } catch (err) {
+                logger.error({ jid, err }, 'Failed to encrypt for recipient')
+                return null
+            }
+        })
+
+        const nodes = (await Promise.all(encryptionPromises)).filter(Boolean)
+        return { nodes, shouldIncludeDeviceIdentity }
     }
 
-    await authState.keys.transaction(async () => {
-        const mediaType = getMediaType(message)
-        if (mediaType) extraAttrs.mediatype = mediaType
+    // ─────────────────────────────────────────────
+    // RELAY MESSAGE
+    // Core message sending function. Handles groups, DMs,
+    // newsletters, status broadcasts, and retries.
+    //
+    // Key design decisions:
+    // - senderKeyMap always starts empty (Promise.resolve({})) so
+    //   SKDM is always sent fresh — prevents "waiting for message"
+    //   errors caused by stale persisted sender key memory.
+    // - LID vs PN identity is resolved per group's addressingMode.
+    // ─────────────────────────────────────────────
+    const relayMessage = async (jid, message, { messageId: msgId, participant, additionalAttributes, additionalNodes, useUserDevicesCache, useCachedGroupMetadata, statusJidList, quoted } = {}) => {
+        const meId = authState.creds.me.id
+        const meLid = authState.creds.me?.lid
+        const { user, server } = jidDecode(jid)
+        const isGroup = server === 'g.us'
+        const isStatus = jid === 'status@broadcast'
+        const isLid = server === 'lid'
+        const isNewsletter = server === 'newsletter'
+
+        // Choose sender identity (PN or LID) based on destination
+        let activeSender = meId
+        let groupAddressingMode = 'pn'
+        if (isGroup && !isStatus) {
+            const groupData = useCachedGroupMetadata && cachedGroupMetadata ? await cachedGroupMetadata(jid) : undefined
+            groupAddressingMode = additionalAttributes?.addressing_mode || groupData?.addressingMode || 'lid'
+            if (groupAddressingMode === 'lid' && meLid) activeSender = meLid
+        } else if (isLid && meLid) {
+            activeSender = meLid
+        }
+
+        const isRetryResend = Boolean(participant?.jid)
+        let shouldIncludeDeviceIdentity = isRetryResend
+        let finalMsgId = msgId
 
-        if (isNewsletter) {
-            const patched = patchMessageBeforeSending ? await patchMessageBeforeSending(message, []) : message
-            const bytes = encodeNewsletterMessage(patched)
-            binaryNodeContent.push({ tag: 'plaintext', attrs: {}, content: bytes })
-            const stanza = { tag: 'message', attrs: { to: jid, id: finalMsgId, type: getMessageType(message), ...(additionalAttributes || {}) }, content: binaryNodeContent }
-            logger.debug({ msgId: finalMsgId }, `sending newsletter message to ${jid}`)
-            await sendNode(stanza)
-            return
+        // Auto-generate WAMessage from raw content if needed
+        const hasProtoMessageType = Object.keys(message).some(key => key.endsWith('Message') || key === 'conversation')
+        if (!hasProtoMessageType) {
+            logger.debug({ jid }, 'relayMessage: auto-generating message from raw content')
+            const generatedMsg = await generateWAMessage(jid, message, {
+                logger, userJid: jidNormalizedUser(activeSender),
+                getUrlInfo: text => getUrlInfo(text, { thumbnailWidth: linkPreviewImageThumbnailWidth, fetchOpts: { timeout: 3000, ...(httpRequestOptions || {}) }, logger, uploadImage: generateHighQualityLinkPreview ? waUploadToServer : undefined }),
+                getProfilePicUrl: sock.profilePictureUrl, getCallLink: sock.createCallLink,
+                upload: waUploadToServer, mediaCache: config.mediaCache, options: config.options,
+                messageId: finalMsgId || generateMessageIDV2(activeSender), quoted
+            })
+            message = generatedMsg.message
+            if (!finalMsgId) finalMsgId = generatedMsg.key.id
+            logger.debug({ msgId: finalMsgId, jid }, 'message auto-generated successfully')
         }
 
-        if (messages.pinInChatMessage || messages.keepInChatMessage || message.reactionMessage || message.protocolMessage?.editedMessage) extraAttrs['decrypt-fail'] = 'hide'
+        finalMsgId = finalMsgId || generateMessageIDV2(activeSender)
+        useUserDevicesCache = useUserDevicesCache !== false
+        useCachedGroupMetadata = useCachedGroupMetadata !== false && !isStatus
+
+        const participants = []
+        const destinationJid = !isStatus ? jid : 'status@broadcast'
+        const binaryNodeContent = []
+        const devices = []
+        const meMsg = { deviceSentMessage: { destinationJid, message }, messageContextInfo: message.messageContextInfo }
+        const extraAttrs = {}
+        const messages = normalizeMessageContent(message)
+        const buttonType = getButtonType(messages)
+
+        let hasDeviceFanoutFalse = false
+        if (participant) {
+            if (!isGroup && !isStatus) hasDeviceFanoutFalse = true
+            const { user, device } = jidDecode(participant.jid)
+            devices.push({ user, device, jid: participant.jid })
+        }
 
-        if (isGroup || isStatus) {
-            const [groupData, senderKeyMap] = await Promise.all([
-                (async () => {
-                    let groupData = useCachedGroupMetadata && cachedGroupMetadata ? await cachedGroupMetadata(jid) : undefined
-                    if (groupData?.participants) logger.trace({ jid, participants: groupData.participants.length }, 'using cached group metadata')
-                    else if (!isStatus) groupData = await groupMetadata(jid)
-                    return groupData
-                })(),
-                (async () => !participant && !isStatus ? (await authState.keys.get('sender-key-memory', [jid]))[jid] || {} : {})()
-            ])
+        await authState.keys.transaction(async () => {
+            const mediaType = getMediaType(message)
+            if (mediaType) extraAttrs.mediatype = mediaType
+
+            // ── Newsletter: plaintext encoding, no encryption ──
+            if (isNewsletter) {
+                const patched = patchMessageBeforeSending ? await patchMessageBeforeSending(message, []) : message
+                binaryNodeContent.push({ tag: 'plaintext', attrs: {}, content: encodeNewsletterMessage(patched) })
+                await sendNode({ tag: 'message', attrs: { to: jid, id: finalMsgId, type: getMessageType(message), ...(additionalAttributes || {}) }, content: binaryNodeContent })
+                logger.debug({ msgId: finalMsgId }, `sending newsletter message to ${jid}`)
+                return
+            }
+
+            if (messages.pinInChatMessage || messages.keepInChatMessage || message.reactionMessage || message.protocolMessage?.editedMessage) {
+                extraAttrs['decrypt-fail'] = 'hide'
+            }
 
-            if (!participant) {
+            // ── Group / Status: sender key (SKDM + skmsg) ──
+            if ((isGroup || isStatus) && !isRetryResend) {
+                const [groupData] = await Promise.all([
+                    (async () => {
+                        let groupData = useCachedGroupMetadata && cachedGroupMetadata ? await cachedGroupMetadata(jid) : undefined
+                        if (groupData?.participants) logger.trace({ jid, participants: groupData.participants.length }, 'using cached group metadata')
+                        else if (!isStatus) groupData = await groupMetadata(jid)
+                        return groupData
+                    })(),
+                    Promise.resolve({}) // senderKeyMap intentionally always empty — forces fresh SKDM every send
+                ])
+
+                // Build participant list
                 const participantsList = []
-                if (isStatus) { if (statusJidList?.length) participantsList.push(...statusJidList) } 
-                else {
+                if (isStatus) {
+                    if (statusJidList?.length) participantsList.push(...statusJidList)
+                } else {
                     let groupAddressingMode = 'lid'
                     if (groupData) { participantsList.push(...groupData.participants.map(p => p.id)); groupAddressingMode = groupData?.addressingMode || groupAddressingMode }
                     additionalAttributes = { ...additionalAttributes, addressing_mode: groupAddressingMode }
                 }
-                
-                // DEVICE 0 PRESERVATION FOR GROUPS: Initialize device 0 for all participants
-                const device0EntriesGroup = []
-                for (const jid of participantsList) {
-                    const { user, server } = jidDecode(jid)
-                    if (user) {
-                        device0EntriesGroup.push({ user, device: 0, jid: jidEncode(user, server, 0) })
-                    }
+
+                if (groupData?.ephemeralDuration > 0) {
+                    additionalAttributes = { ...additionalAttributes, expiration: groupData.ephemeralDuration.toString() }
                 }
-                
+
                 const additionalDevices = await getUSyncDevices(participantsList, !!useUserDevicesCache, false)
-                // Combine device 0 entries with fetched devices, avoiding duplicates
-                const deviceMap = new Map()
-                for (const d of device0EntriesGroup) deviceMap.set(`${d.user}:${d.device}`, d)
-                for (const d of additionalDevices) {
-                    const key = `${d.user}:${d.device}`
-                    if (!deviceMap.has(key)) deviceMap.set(key, d)
+                devices.push(...additionalDevices)
+
+                // Ensure Device 0 (primary phone) is always included for every participant.
+                // USync sometimes omits Device 0 for LID groups to save bandwidth,
+                // which would cause recipients to miss the SKDM on first send.
+                for (const pJid of participantsList) {
+                    const decoded = jidDecode(pJid)
+                    if (decoded?.user && !devices.some(d => d.user === decoded.user && d.device === 0)) {
+                        devices.push({ user: decoded.user, device: 0, server: decoded.server, domainType: decoded.domainType, jid: jidEncode(decoded.user, decoded.server, 0) })
+                    }
                 }
-                devices.push(...Array.from(deviceMap.values()))
-            }
 
-            if (groupData?.ephemeralDuration > 0) additionalAttributes = { ...additionalAttributes, expiration: groupData.ephemeralDuration.toString() }
+                const patched = await patchMessageBeforeSending(message)
+                if (Array.isArray(patched)) throw new Boom('Per-jid patching not supported in groups')
+
+                const bytes = encodeWAMessage(patched)
+                const gAddressingMode = additionalAttributes?.addressing_mode || groupData?.addressingMode || 'lid'
+                const groupSenderIdentity = gAddressingMode === 'lid' && meLid ? meLid : meId
+                const { ciphertext, senderKeyDistributionMessage } = await signalRepository.encryptGroupMessage({ group: destinationJid, data: bytes, meId: groupSenderIdentity })
+
+                // Send SKDM to ALL devices every time (senderKeyMap is always {})
+                const senderKeyRecipients = devices
+                    .filter(d => !isHostedLidUser(d.jid) && !isHostedPnUser(d.jid) && d.device !== 99)
+                    .map(d => d.jid)
+
+                if (senderKeyRecipients.length) {
+                    logger.debug({ senderKeyJids: senderKeyRecipients }, 'sending sender key')
+                    const senderKeyMsg = { senderKeyDistributionMessage: { axolotlSenderKeyDistributionMessage: senderKeyDistributionMessage, groupId: destinationJid } }
+                    await assertSessions(senderKeyRecipients)
+                    const result = await createParticipantNodes(senderKeyRecipients, senderKeyMsg, {})
+                    shouldIncludeDeviceIdentity = shouldIncludeDeviceIdentity || result.shouldIncludeDeviceIdentity
+                    participants.push(...result.nodes)
+                }
 
-            const patched = await patchMessageBeforeSending(message)
-            if (Array.isArray(patched)) throw new Boom('Per-jid patching not supported in groups')
+                binaryNodeContent.push({ tag: 'enc', attrs: { v: '2', type: 'skmsg', ...extraAttrs }, content: ciphertext })
 
-            const bytes = encodeWAMessage(patched)
-            const groupAddressingMode = additionalAttributes?.addressing_mode || groupData?.addressingMode || 'lid'
-            const groupSenderIdentity = groupAddressingMode === 'lid' && meLid ? meLid : meId
+                // ── Group Retry: direct pairwise re-encrypt for specific participant ──
+            } else if ((isGroup || isStatus) && isRetryResend) {
+                const groupData = useCachedGroupMetadata && cachedGroupMetadata ? await cachedGroupMetadata(jid) : undefined
+                if (!groupData && !isStatus) await groupMetadata(jid)
 
-            const { ciphertext, senderKeyDistributionMessage } = await signalRepository.encryptGroupMessage({ group: destinationJid, data: bytes, meId: groupSenderIdentity })
+                if (groupData?.ephemeralDuration > 0) additionalAttributes = { ...additionalAttributes, expiration: groupData.ephemeralDuration.toString() }
+                additionalAttributes = { ...additionalAttributes, addressing_mode: groupData?.addressingMode || 'lid' }
 
-            const senderKeyRecipients = []
-            for (const device of devices) {
-                const deviceJid = device.jid
-                const hasKey = !!senderKeyMap[deviceJid]
-                if ((!hasKey || !!participant) && !isHostedLidUser(deviceJid) && !isHostedPnUser(deviceJid) && device.device !== 99) { senderKeyRecipients.push(deviceJid); senderKeyMap[deviceJid] = true }
-            }
+                const patched = await patchMessageBeforeSending(message)
+                if (Array.isArray(patched)) throw new Boom('Per-jid patching not supported in groups')
 
-            // Assert sessions once for sender key recipients ONLY to avoid concurrent conflicts
-            if (senderKeyRecipients.length) {
-                logger.debug({ senderKeyJids: senderKeyRecipients }, 'sending sender key')
+                const bytes = encodeWAMessage(patched)
+                const gAddressingMode = additionalAttributes?.addressing_mode || groupData?.addressingMode || 'lid'
+                const groupSenderIdentity = gAddressingMode === 'lid' && meLid ? meLid : meId
+                const { ciphertext, senderKeyDistributionMessage } = await signalRepository.encryptGroupMessage({ group: destinationJid, data: bytes, meId: groupSenderIdentity })
+
+                // Send fresh SKDM directly to the requesting participant
                 const senderKeyMsg = { senderKeyDistributionMessage: { axolotlSenderKeyDistributionMessage: senderKeyDistributionMessage, groupId: destinationJid } }
-                await assertSessions(senderKeyRecipients)
-                const result = await createParticipantNodes(senderKeyRecipients, senderKeyMsg, extraAttrs)
-                shouldIncludeDeviceIdentity = shouldIncludeDeviceIdentity || result.shouldIncludeDeviceIdentity
-                participants.push(...result.nodes)
-            }
+                await assertSessions([participant.jid])
+                const skResult = await createParticipantNodes([participant.jid], senderKeyMsg, {})
+                shouldIncludeDeviceIdentity = shouldIncludeDeviceIdentity || skResult.shouldIncludeDeviceIdentity
+                participants.push(...skResult.nodes)
 
-            if (isRetryResend) {
                 const { type, ciphertext: encryptedContent } = await signalRepository.encryptMessage({ data: bytes, jid: participant?.jid })
                 binaryNodeContent.push({ tag: 'enc', attrs: { v: '2', type, count: participant.count.toString() }, content: encryptedContent })
+
+                // ── DM / LID: standard pairwise encryption ──
             } else {
-                binaryNodeContent.push({ tag: 'enc', attrs: { v: '2', type: 'skmsg', ...extraAttrs }, content: ciphertext })
-                await authState.keys.set({ 'sender-key-memory': { [jid]: senderKeyMap } })
-            }
-        } else {
-            let ownId = meId
-            if (isLid && meLid) { ownId = meLid; logger.debug({ to: jid, ownId }, 'Using LID identity') }
+                let ownId = meId
+                if (isLid && meLid) { ownId = meLid; logger.debug({ to: jid, ownId }, 'Using LID identity') }
 
-            const { user: ownUser } = jidDecode(ownId)
+                const { user: ownUser } = jidDecode(ownId)
 
-            if (!participant) {
-                const targetUserServer = isLid ? 'lid' : 's.whatsapp.net'
-                devices.push({ user, device: 0, jid: jidEncode(user, targetUserServer, 0) })
+                if (!participant) {
+                    const targetUserServer = isLid ? 'lid' : 's.whatsapp.net'
+                    devices.push({ user, device: 0, jid: jidEncode(user, targetUserServer, 0) })
 
-                if (user !== ownUser) {
-                    const ownUserServer = isLid ? 'lid' : 's.whatsapp.net'
-                    const ownUserForAddressing = isLid && meLid ? jidDecode(meLid).user : jidDecode(meId).user
-                    devices.push({ user: ownUserForAddressing, device: 0, jid: jidEncode(ownUserForAddressing, ownUserServer, 0) })
-                }
+                    if (user !== ownUser) {
+                        const ownUserServer = isLid ? 'lid' : 's.whatsapp.net'
+                        const ownUserForAddressing = isLid && meLid ? jidDecode(meLid).user : jidDecode(meId).user
+                        devices.push({ user: ownUserForAddressing, device: 0, jid: jidEncode(ownUserForAddressing, ownUserServer, 0) })
+                    }
 
-                if (additionalAttributes?.category !== 'peer') {
-                    // DEVICE 0 PRESERVATION: Save device 0 entries before refetch
-                    const device0Entries = devices.filter(d => d.device === 0)
-                    const senderOwnUser = device0Entries.find(d => d.user !== user)?.user
-                    devices.length = 0
-                    const senderIdentity = isLid && meLid ? jidEncode(jidDecode(meLid)?.user, 'lid', undefined) : jidEncode(jidDecode(meId)?.user, 's.whatsapp.net', undefined)
-                    // Fetch both sender and recipient devices to ensure complete enumeration
-                    const sessionDevices = await getUSyncDevices([senderIdentity, jid], true, false)
-                    devices.push(...device0Entries, ...sessionDevices)
-                    // If sender devices weren't enumerated, explicitly fetch them
-                    if (senderOwnUser && !sessionDevices.some(d => d.user === senderOwnUser && d.device !== 0)) {
-                        const senderDevices = await getUSyncDevices([senderIdentity], true, false)
-                        const senderLinkedDevices = senderDevices.filter(d => d.device !== 0 && d.user === senderOwnUser)
-                        if (senderLinkedDevices.length > 0) devices.push(...senderLinkedDevices)
+                    if (additionalAttributes?.category !== 'peer') {
+                        // Preserve Device 0 entries before USync refetch which may omit them
+                        const device0Entries = devices.filter(d => d.device === 0)
+                        const senderOwnUser = device0Entries.find(d => d.user !== user)?.user
+                        devices.length = 0
+                        const senderIdentity = isLid && meLid
+                            ? jidEncode(jidDecode(meLid)?.user, 'lid', undefined)
+                            : jidEncode(jidDecode(meId)?.user, 's.whatsapp.net', undefined)
+                        const sessionDevices = await getUSyncDevices([senderIdentity, jid], true, false)
+                        devices.push(...device0Entries, ...sessionDevices)
+
+                        // Explicitly fetch sender's linked devices if not returned by USync
+                        if (senderOwnUser && !sessionDevices.some(d => d.user === senderOwnUser && d.device !== 0)) {
+                            const senderDevices = await getUSyncDevices([senderIdentity], true, false)
+                            const senderLinkedDevices = senderDevices.filter(d => d.device !== 0 && d.user === senderOwnUser)
+                            if (senderLinkedDevices.length > 0) devices.push(...senderLinkedDevices)
+                        }
                     }
                 }
-            }
 
-            const allRecipients = [], meRecipients = [], otherRecipients = []
-            const { user: mePnUser } = jidDecode(meId)
-            const { user: meLidUser } = meLid ? jidDecode(meLid) : { user: null }
-
-            for (const { user, jid } of devices) {
-                const isExactSenderDevice = jid === meId || (meLid && jid === meLid)
-                if (isExactSenderDevice) continue
-                const isMe = user === mePnUser || user === meLidUser
-                if (isMe) meRecipients.push(jid)
-                else otherRecipients.push(jid)
-                allRecipients.push(jid)
-            }
+                const allRecipients = [], meRecipients = [], otherRecipients = []
+                const { user: mePnUser } = jidDecode(meId)
+                const { user: meLidUser } = meLid ? jidDecode(meLid) : { user: null }
+
+                for (const { user, jid } of devices) {
+                    const isExactSenderDevice = jid === meId || (meLid && jid === meLid)
+                    if (isExactSenderDevice) continue
+                    const isMe = user === mePnUser || user === meLidUser
+                    if (isMe) meRecipients.push(jid)
+                    else otherRecipients.push(jid)
+                    allRecipients.push(jid)
+                }
 
-            await assertSessions(allRecipients)
+                await assertSessions(allRecipients)
 
-            const [{ nodes: meNodes, shouldIncludeDeviceIdentity: s1 }, { nodes: otherNodes, shouldIncludeDeviceIdentity: s2 }] = await Promise.all([
-                createParticipantNodes(meRecipients, meMsg || message, extraAttrs),
-                createParticipantNodes(otherRecipients, message, extraAttrs, meMsg)
-            ])
+                const [{ nodes: meNodes, shouldIncludeDeviceIdentity: s1 }, { nodes: otherNodes, shouldIncludeDeviceIdentity: s2 }] = await Promise.all([
+                    createParticipantNodes(meRecipients, meMsg || message, extraAttrs),
+                    createParticipantNodes(otherRecipients, message, extraAttrs, meMsg)
+                ])
 
-            participants.push(...meNodes, ...otherNodes)
-            if (meRecipients.length > 0 || otherRecipients.length > 0) extraAttrs.phash = generateParticipantHashV2([...meRecipients, ...otherRecipients])
-            shouldIncludeDeviceIdentity = shouldIncludeDeviceIdentity || s1 || s2
-        }
+                participants.push(...meNodes, ...otherNodes)
+                if (meRecipients.length > 0 || otherRecipients.length > 0) {
+                    extraAttrs.phash = generateParticipantHashV2([...meRecipients, ...otherRecipients])
+                }
+                shouldIncludeDeviceIdentity = shouldIncludeDeviceIdentity || s1 || s2
+            }
 
-        if (participants.length) {
-            if (additionalAttributes?.category === 'peer') { const peerNode = participants[0]?.content?.[0]; if (peerNode) binaryNodeContent.push(peerNode) } 
-            else binaryNodeContent.push({ tag: 'participants', attrs: {}, content: participants })
-        }
+            // ── Build final stanza ──
+            if (participants.length) {
+                if (additionalAttributes?.category === 'peer') {
+                    const peerNode = participants[0]?.content?.[0]
+                    if (peerNode) binaryNodeContent.push(peerNode)
+                } else {
+                    binaryNodeContent.push({ tag: 'participants', attrs: {}, content: participants })
+                }
+            }
 
-        const stanza = { tag: 'message', attrs: { id: finalMsgId, to: destinationJid, type: getMessageType(message), ...(additionalAttributes || {}) }, content: binaryNodeContent }
+            const stanza = {
+                tag: 'message',
+                attrs: {
+                    id: finalMsgId,
+                    to: destinationJid,
+                    type: getMessageType(message),
+                    ...(isLid || (isGroup && groupAddressingMode === 'lid') ? { addressing_mode: 'lid' } : {}),
+                    ...(hasDeviceFanoutFalse ? { device_fanout: 'false' } : {}),
+                    ...(additionalAttributes || {})
+                },
+                content: binaryNodeContent
+            }
 
-        if (participant) {
-            if (isJidGroup(destinationJid)) { stanza.attrs.to = destinationJid; stanza.attrs.participant = participant.jid } 
-            else if (areJidsSameUser(participant.jid, meId)) { stanza.attrs.to = participant.jid; stanza.attrs.recipient = destinationJid } 
-            else stanza.attrs.to = participant.jid
-        } else stanza.attrs.to = destinationJid
-
-        let additionalAlready = false
-        if (!isNewsletter && buttonType) {
-            const buttonsNode = getButtonArgs(messages)
-            const filteredButtons = getBinaryFilteredButtons(additionalNodes || [])
-            if (filteredButtons) { stanza.content.push(...additionalNodes); additionalAlready = true } 
-            else stanza.content.push(buttonsNode)
-        }
+            if (participant) {
+                if (isJidGroup(destinationJid)) { stanza.attrs.to = destinationJid; stanza.attrs.participant = participant.jid }
+                else if (areJidsSameUser(participant.jid, meId)) { stanza.attrs.to = participant.jid; stanza.attrs.recipient = destinationJid }
+                else stanza.attrs.to = participant.jid
+            } else {
+                stanza.attrs.to = destinationJid
+            }
 
-        if (shouldIncludeDeviceIdentity) { stanza.content.push({ tag: 'device-identity', attrs: {}, content: encodeSignedDeviceIdentity(authState.creds.account, true) }); logger.debug({ jid }, 'adding device identity') }
-        if (additionalNodes?.length > 0 && !additionalAlready) stanza.content.push(...additionalNodes)
-            // Add TCToken support with expiration validation
-             if (!isGroup && !isRetryResend && !isStatus) {
-                 const contactTcTokenData = await authState.keys.get('tctoken', [destinationJid])
-                 let tcTokenBuffer = contactTcTokenData[destinationJid]?.token
-                 
-                 // Check if token is expired
-                 if (isTokenExpired(contactTcTokenData[destinationJid])) {
-                     logger.debug({ jid: destinationJid }, 'tctoken expired, refreshing')
-                     try {
-                         const freshTokens = await getPrivacyTokens([destinationJid])
-                         tcTokenBuffer = freshTokens[destinationJid]?.token
-                     } catch (err) {
-                         logger.warn({ jid: destinationJid, err }, 'failed to refresh expired tctoken')
-                     }
-                 }
-                 
-                 if (tcTokenBuffer) stanza.content.push({ tag: 'tctoken', attrs: {}, content: tcTokenBuffer })
-             }
+            // Attach button metadata if needed
+            if (!isNewsletter && buttonType) {
+                const buttonsNode = getButtonArgs(messages)
+                const filteredButtons = getBinaryFilteredButtons(additionalNodes || [])
+                if (filteredButtons) { stanza.content.push(...additionalNodes) }
+                else stanza.content.push(buttonsNode)
+            } else if (additionalNodes?.length > 0) {
+                stanza.content.push(...additionalNodes)
+            }
+
+            // Attach device identity for LID groups and pkmsg sessions
+            if ((shouldIncludeDeviceIdentity || (meLid && (isLid || (isGroup && groupAddressingMode === 'lid')))) && !isNewsletter) {
+                stanza.content.push({ tag: 'device-identity', attrs: {}, content: encodeSignedDeviceIdentity(authState.creds.account, true) })
+                logger.debug({ jid }, 'adding device identity')
+            }
+
+            // Attach TC token for DM messages (auto-refresh if expired)
+            if (!isGroup && !isRetryResend && !isStatus) {
+                const contactTcTokenData = await authState.keys.get('tctoken', [destinationJid])
+                let tcTokenBuffer = contactTcTokenData[destinationJid]?.token
+                if (isTokenExpired(contactTcTokenData[destinationJid])) {
+                    logger.debug({ jid: destinationJid }, 'tctoken expired, refreshing')
+                    try {
+                        const freshTokens = await getPrivacyTokens([destinationJid])
+                        tcTokenBuffer = freshTokens[destinationJid]?.token
+                    } catch (err) {
+                        logger.warn({ jid: destinationJid, err }, 'failed to refresh expired tctoken')
+                    }
+                }
+                if (tcTokenBuffer) stanza.content.push({ tag: 'tctoken', attrs: {}, content: tcTokenBuffer })
+            }
 
             logger.debug({ msgId }, `sending message to ${participants.length} devices`)
             await sendNode(stanza)
             if (messageRetryManager && !participant) messageRetryManager.addRecentMessage(destinationJid, msgId, message)
-        }, meId)
-
-        return {key: {remoteJid: jid, fromMe: true, id: finalMsgId, participant: isGroup ? authState.creds.me.id : undefined}, messageId: finalMsgId}
-    }
 
-           const TOKEN_EXPIRY_TTL = 24 * 60 * 60 // 24 hours in seconds
-    
-    const isTokenExpired = (tokenData) => {
-        if (!tokenData || !tokenData.timestamp) return true
-        const age = unixTimestampSeconds() - Number(tokenData.timestamp)
-        return age > TOKEN_EXPIRY_TTL
+        }, activeSender)
+
+        const isSelf = areJidsSameUser(jid, meId) || (meLid && areJidsSameUser(jid, meLid))
+        const returnParticipant = (isGroup || isSelf) ? jidNormalizedUser(activeSender) : undefined
+        return {
+            key: {
+                remoteJid: jid,
+                fromMe: true,
+                id: finalMsgId,
+                participant: returnParticipant,
+                addressingMode: (isLid || (isGroup && groupAddressingMode === 'lid')) ? 'lid' : 'pn'
+            },
+            messageId: finalMsgId
+        }
     }
-    
-    const getPrivacyTokens = async (jids) => {
-           const t = unixTimestampSeconds().toString()
-           const result = await query({ tag: 'iq', attrs: { to: S_WHATSAPP_NET, type: 'set', xmlns: 'privacy' }, content: [{ tag: 'tokens', attrs: {}, content: jids.map(jid => ({ tag: 'token', attrs: { jid: jidNormalizedUser(jid), t, type: 'trusted_contact' } })) }] })
-           const tokens = parseTCTokens(result)
-           if (Object.keys(tokens).length > 0) await authState.keys.set({ 'tctoken': tokens })
-           return tokens
-       }
 
     const waUploadToServer = getWAUploadToServer(config, refreshMediaConn)
     const nexus = new NexusHandler(Utils, waUploadToServer, relayMessage, { logger, mediaCache: config.mediaCache, options: config.options, mediaUploadTimeoutMs: config.mediaUploadTimeoutMs, user: authState.creds.me })
@@ -549,10 +728,15 @@ const relayMessage = async (jid, message, { messageId: msgId, participant, addit
 
     return {
         ...sock,
-        getPrivacyTokens, assertSessions, relayMessage, sendReceipt, sendReceipts, nexus, readMessages,
-        refreshMediaConn, waUploadToServer, fetchPrivacySettings, sendPeerDataOperationMessage,
-        createParticipantNodes, getUSyncDevices, messageRetryManager, updateMemberLabel,
-
+        getPrivacyTokens, assertSessions, relayMessage, sendReceipt, sendReceipts, nexus,
+        readMessages, refreshMediaConn, waUploadToServer, fetchPrivacySettings,
+        sendPeerDataOperationMessage, createParticipantNodes, getUSyncDevices,
+        messageRetryManager, updateMemberLabel,
+
+        // ─────────────────────────────────────────────
+        // UPDATE MEDIA MESSAGE
+        // Re-requests media upload for expired/missing media.
+        // ─────────────────────────────────────────────
         updateMediaMessage: async (message) => {
             const content = assertMediaContent(message.message)
             const mediaKey = content.mediaKey
@@ -562,11 +746,14 @@ const relayMessage = async (jid, message, { messageId: msgId, participant, addit
             await Promise.all([sendNode(node), waitForMsgMediaUpdate(async (update) => {
                 const result = update.find(c => c.key.id === message.key.id)
                 if (result) {
-                    if (result.error) error = result.error
-                    else {
+                    if (result.error) {
+                        error = result.error
+                    } else {
                         try {
                             const media = await decryptMediaRetryData(result.media, mediaKey, result.key.id)
-                            if (media.result !== proto.MediaRetryNotification.ResultType.SUCCESS) throw new Boom(`Media re-upload failed (${proto.MediaRetryNotification.ResultType[media.result]})`, { data: media, statusCode: getStatusCodeForMediaRetry(media.result) || 404 })
+                            if (media.result !== proto.MediaRetryNotification.ResultType.SUCCESS) {
+                                throw new Boom(`Media re-upload failed (${proto.MediaRetryNotification.ResultType[media.result]})`, { data: media, statusCode: getStatusCodeForMediaRetry(media.result) || 404 })
+                            }
                             content.directPath = media.directPath
                             content.url = getUrlFromDirectPath(content.directPath)
                             logger.debug({ directPath: media.directPath, key: result.key }, 'media update successful')
@@ -580,34 +767,50 @@ const relayMessage = async (jid, message, { messageId: msgId, participant, addit
             return message
         },
 
+        // ─────────────────────────────────────────────
+        // SEND STATUS MENTIONS
+        // Broadcasts a status update and notifies mentioned
+        // users or groups via statusMentionMessage protocol.
+        // ─────────────────────────────────────────────
         sendStatusMentions: async (content, jids = []) => {
             const userJid = jidNormalizedUser(authState.creds.me.id)
             const allUsers = new Set([userJid])
             for (const id of jids) {
-                if (isJidGroup(id)) { try { const metadata = await cachedGroupMetadata(id) || await groupMetadata(id); metadata.participants.forEach(p => allUsers.add(jidNormalizedUser(p.id))) } catch (error) { logger.error(`Error getting metadata for ${id}: ${error}`) } } 
-                else if (isJidUser(id)) allUsers.add(jidNormalizedUser(id))
+                if (isJidGroup(id)) {
+                    try { const metadata = await cachedGroupMetadata(id) || await groupMetadata(id); metadata.participants.forEach(p => allUsers.add(jidNormalizedUser(p.id))) }
+                    catch (error) { logger.error(`Error getting metadata for ${id}: ${error}`) }
+                } else if (isJidUser(id)) {
+                    allUsers.add(jidNormalizedUser(id))
+                }
             }
-            const uniqueUsers = Array.from(allUsers)
+
             const getRandomHex = () => '#' + Math.floor(Math.random() * 16777215).toString(16).padStart(6, '0')
             const isMedia = content.image || content.video || content.audio
             const isAudio = !!content.audio
             const msgContent = { ...content }
             if (isMedia && !isAudio) { if (msgContent.text) { msgContent.caption = msgContent.text; delete msgContent.text }; delete msgContent.ptt; delete msgContent.font; delete msgContent.backgroundColor; delete msgContent.textColor }
             if (isAudio) { delete msgContent.text; delete msgContent.caption; delete msgContent.font; delete msgContent.textColor }
-            const font = !isMedia ? (content.font || Math.floor(Math.random() * 9)) : undefined
-            const textColor = !isMedia ? (content.textColor || getRandomHex()) : undefined
-            const backgroundColor = (!isMedia || isAudio) ? (content.backgroundColor || getRandomHex()) : undefined
-            const ptt = isAudio ? (typeof content.ptt === 'boolean' ? content.ptt : true) : undefined
-            let msg, mediaHandle
+
+            let msg
             try {
                 msg = await generateWAMessage(STORIES_JID, msgContent, {
                     logger, userJid,
                     getUrlInfo: text => getUrlInfo(text, { thumbnailWidth: linkPreviewImageThumbnailWidth, fetchOpts: { timeout: 3000, ...(httpRequestOptions || {}) }, logger, uploadImage: generateHighQualityLinkPreview ? waUploadToServer : undefined }),
-                    upload: async (encFilePath, opts) => { const up = await waUploadToServer(encFilePath, { ...opts }); mediaHandle = up.handle; return up },
-                    mediaCache: config.mediaCache, options: config.options, font, textColor, backgroundColor, ptt
+                    upload: async (encFilePath, opts) => { const up = await waUploadToServer(encFilePath, { ...opts }); return up },
+                    mediaCache: config.mediaCache, options: config.options,
+                    font: !isMedia ? (content.font || Math.floor(Math.random() * 9)) : undefined,
+                    textColor: !isMedia ? (content.textColor || getRandomHex()) : undefined,
+                    backgroundColor: (!isMedia || isAudio) ? (content.backgroundColor || getRandomHex()) : undefined,
+                    ptt: isAudio ? (typeof content.ptt === 'boolean' ? content.ptt : true) : undefined
                 })
             } catch (error) { logger.error(`Error generating message: ${error}`); throw error }
-            await relayMessage(STORIES_JID, msg.message, { messageId: msg.key.id, statusJidList: uniqueUsers, additionalNodes: [{ tag: 'meta', attrs: {}, content: [{ tag: 'mentioned_users', attrs: {}, content: jids.map(jid => ({ tag: 'to', attrs: { jid: jidNormalizedUser(jid) } })) }] }] })
+
+            await relayMessage(STORIES_JID, msg.message, {
+                messageId: msg.key.id,
+                statusJidList: Array.from(allUsers),
+                additionalNodes: [{ tag: 'meta', attrs: {}, content: [{ tag: 'mentioned_users', attrs: {}, content: jids.map(jid => ({ tag: 'to', attrs: { jid: jidNormalizedUser(jid) } })) }] }]
+            })
+
             for (const id of jids) {
                 try {
                     const normalizedId = jidNormalizedUser(id)
@@ -622,6 +825,7 @@ const relayMessage = async (jid, message, { messageId: msgId, participant, addit
             return msg
         },
 
+        // Nexus handler shortcuts for rich message types
         sendPaymentMessage: (jid, data, quoted) => nexus.handlePayment({ requestPaymentMessage: data }, jid, quoted),
         sendProductMessage: (jid, data, quoted) => nexus.handleProduct({ productMessage: data }, jid, quoted),
         sendInteractiveMessage: (jid, data, quoted) => nexus.handleInteractive({ interactiveMessage: data }, jid, quoted),
@@ -635,51 +839,131 @@ const relayMessage = async (jid, message, { messageId: msgId, participant, addit
         sendCarouselProtoMessage: (jid, data, quoted) => nexus.handleCarouselProto({ carouselProto: data }, jid, quoted),
         stickerPackMessage: (jid, data, options) => nexus.handleStickerPack(data, jid, options?.quoted),
 
+        // ─────────────────────────────────────────────
+        // SEND MESSAGE
+        // Main public API for sending any message type.
+        // Handles delete normalization, LID/PN identity selection,
+        // message generation, and relay.
+        // ─────────────────────────────────────────────
         sendMessage: async (jid, content, options = {}) => {
-            const userJid = authState.creds.me.id
+            const meId = authState.creds.me.id
+            const meLid = authState.creds.me?.lid
+            const { server } = jidDecode(jid)
+            const isGroup = server === 'g.us'
+            const isDestinationLid = server === 'lid'
+            const useCache = options.useCachedGroupMetadata !== false
             const { quoted } = options
-            
-            if (content.interactive && !content.interactiveMessage) { const { interactive, ...rest } = content; content = { ...rest, interactiveMessage: interactive } }
-            
+
+            // Resolve sender identity for this destination
+            let activeSender = meId
+            let addressingMode = 'pn'
+            if (isGroup) {
+                const groupData = useCache && cachedGroupMetadata ? await cachedGroupMetadata(jid) : undefined
+                addressingMode = groupData?.addressingMode || 'lid'
+                if (addressingMode === 'lid' && meLid) activeSender = meLid
+            } else if (isDestinationLid && meLid) {
+                activeSender = meLid
+                addressingMode = 'lid'
+            }
+
+            // Unwrap shorthand `interactive` key
+            if (content.interactive && !content.interactiveMessage) {
+                const { interactive, ...rest } = content
+                content = { ...rest, interactiveMessage: interactive }
+            }
+
+            // Delegate rich message types to NexusHandler
             const messageType = nexus.detectType(content)
             if (messageType) return await nexus.processMessage(content, jid, quoted)
 
+            // Handle disappearing message toggle for groups
             if (content.disappearingMessagesInChat && isJidGroup(jid)) {
-                const value = typeof content.disappearingMessagesInChat === 'boolean' ? (content.disappearingMessagesInChat ? WA_DEFAULT_EPHEMERAL : 0) : content.disappearingMessagesInChat
+                const value = typeof content.disappearingMessagesInChat === 'boolean'
+                    ? (content.disappearingMessagesInChat ? WA_DEFAULT_EPHEMERAL : 0)
+                    : content.disappearingMessagesInChat
                 await groupToggleEphemeral(jid, value)
                 return
             }
 
+            // ── Normalize delete key ──
+            // Groups require a participant field matching the sender's LID or PN identity.
+            // edit="7" = delete own message, edit="8" = admin delete another's message.
+            if (content.delete) {
+                const deleteKey = content.delete
+                if (!deleteKey.remoteJid || !deleteKey.id) {
+                    logger.error({ deleteKey }, 'Invalid delete key: missing remoteJid or id')
+                    throw new Boom('Delete key must have remoteJid and id', { statusCode: 400 })
+                }
+
+                const { server: deleteServer } = jidDecode(deleteKey.remoteJid)
+                let deleteAddressingMode = deleteServer === 'lid' ? 'lid' : 'pn'
+                if (isJidGroup(deleteKey.remoteJid)) {
+                    const groupData = useCache && cachedGroupMetadata ? await cachedGroupMetadata(deleteKey.remoteJid) : undefined
+                    deleteAddressingMode = groupData?.addressingMode || 'lid'
+                }
+
+                let normalizedParticipant = deleteKey.participant
+                if (deleteKey.fromMe || isJidGroup(deleteKey.remoteJid)) {
+                    const senderJid = (deleteAddressingMode === 'lid' && meLid) ? meLid : meId
+                    normalizedParticipant = jidNormalizedUser(senderJid)
+                }
+
+                content.delete = {
+                    remoteJid: deleteKey.remoteJid,
+                    fromMe: deleteKey.fromMe === true || deleteKey.fromMe === 'true',
+                    id: deleteKey.id,
+                    ...(normalizedParticipant ? { participant: jidNormalizedUser(normalizedParticipant) } : {}),
+                    addressingMode: deleteAddressingMode
+                }
+                logger.debug({ jid, deleteKey: content.delete }, 'processing message deletion')
+            }
+
+            // Generate the full WAMessage proto
             const fullMsg = await generateWAMessage(jid, content, {
-                logger, userJid,
+                logger,
+                userJid: jidNormalizedUser(activeSender),
                 getUrlInfo: text => getUrlInfo(text, { thumbnailWidth: linkPreviewImageThumbnailWidth, fetchOpts: { timeout: 3000, ...(httpRequestOptions || {}) }, logger, uploadImage: generateHighQualityLinkPreview ? waUploadToServer : undefined }),
-                getProfilePicUrl: sock.profilePictureUrl, getCallLink: sock.createCallLink,
-                upload: waUploadToServer, mediaCache: config.mediaCache, options: config.options,
-                messageId: generateMessageIDV2(sock.user?.id), ...options
+                getProfilePicUrl: sock.profilePictureUrl,
+                getCallLink: sock.createCallLink,
+                upload: waUploadToServer,
+                mediaCache: config.mediaCache,
+                options: config.options,
+                messageId: generateMessageIDV2(activeSender),
+                ...options
             })
 
+            // Build additional stanza attributes
             const additionalAttributes = {}, additionalNodes = []
-            if (content.delete) additionalAttributes.edit = isJidGroup(content.delete?.remoteJid) && !content.delete?.fromMe ? '8' : '7'
-            else if (content.edit) additionalAttributes.edit = '1'
-            else if (content.pin) additionalAttributes.edit = '2'
+            if (content.delete) {
+                additionalAttributes.edit = isJidGroup(content.delete.remoteJid) && !content.delete.fromMe ? '8' : '7'
+            } else if (content.edit) {
+                additionalAttributes.edit = '1'
+            } else if (content.pin) {
+                additionalAttributes.edit = '2'
+            }
             if (content.poll) additionalNodes.push({ tag: 'meta', attrs: { polltype: 'creation' } })
             if (content.event) additionalNodes.push({ tag: 'meta', attrs: { event_type: 'creation' } })
 
-            // Auto-fetch TCToken for new contacts
-             if (!isJidGroup(jid) && !content.disappearingMessagesInChat) {
-                 const existingToken = await authState.keys.get('tctoken', [jid])
-                 if (!existingToken[jid]) {
-                     try { await getPrivacyTokens([jid]); logger.debug({ jid }, 'fetched tctoken for new contact') } 
-                     catch (err) { logger.warn({ jid, err }, 'failed to fetch tctoken') }
-                 }
-             }
+            // Fetch TC token for new DM contacts
+            if (!isJidGroup(jid) && !content.disappearingMessagesInChat) {
+                const existingToken = await authState.keys.get('tctoken', [jid])
+                if (!existingToken[jid]) {
+                    try { await getPrivacyTokens([jid]); logger.debug({ jid }, 'fetched tctoken for new contact') }
+                    catch (err) { logger.warn({ jid, err }, 'failed to fetch tctoken') }
+                }
+            }
 
             await relayMessage(jid, fullMsg.message, {
-                messageId: fullMsg.key.id, useCachedGroupMetadata: options.useCachedGroupMetadata,
-                additionalAttributes, statusJidList: options.statusJidList, additionalNodes
+                messageId: fullMsg.key.id,
+                useCachedGroupMetadata: options.useCachedGroupMetadata,
+                additionalAttributes,
+                statusJidList: options.statusJidList,
+                additionalNodes
             })
 
-            if (config.emitOwnEvents) process.nextTick(() => { processingMutex.mutex(() => upsertMessage(fullMsg, 'append')) })
+            if (config.emitOwnEvents) {
+                process.nextTick(() => processingMutex.mutex(() => upsertMessage(fullMsg, 'append')))
+            }
             return fullMsg
         }
     }