feat(history): extract LID-PN mappings from conversation objects

WhatsApp provides LID-PN mappings in two locations within history sync: 1. Top-level `phoneNumberToLidMappings` array (already processed) 2. Individual conversation objects with `lidJid`/`pnJid` properties (new) This change adds extraction from conversation objects, ensuring maximum mapping coverage regardless of sync type or payload structure. Key improvements: - Add `extractLidPnFromConversation()` function with comprehensive JSDoc - Use Map for O(1) deduplication of mappings across both sources - Handle all JID formats: @lid, @hosted.lid, @s.whatsapp.net, @hosted - Normalize JIDs using `jidNormalizedUser()` for consistency - Skip group chats (@g.us) that don't have LID-PN mappings Includes 22 comprehensive tests covering: - LID chat with pnJid extraction - PN chat with lidJid extraction - Hosted format handling - Deduplication between sources - Edge cases (nulls, groups, missing data) - All conversation sync types Related: WhiskeySockets/Baileys#2263 See-also: WhiskeySockets/Baileys#2282
2026-01-20 22:17:09 +00:00
parent bb73662e8f
commit 86c1cf439a
2 changed files with 425 additions and 5 deletions
@@ -6,9 +6,23 @@ import { WAMessageStubType } from '../Types'
 import { toNumber } from './generics'
 import { normalizeMessageContent } from './messages'
 import { downloadContentFromMessage } from './messages-media'
+import {
+	isHostedLidUser,
+	isHostedPnUser,
+	isLidUser,
+	isPnUser,
+	jidNormalizedUser
+} from '../WABinary/index.js'

 const inflatePromise = promisify(inflate)

+/**
+ * Downloads and decompresses history sync data from WhatsApp servers.
+ *
+ * @param msg - The history sync notification message containing download info
+ * @param options - Request options for the download
+ * @returns Decoded HistorySync protocol buffer
+ */
 export const downloadHistory = async (msg: proto.Message.IHistorySyncNotification, options: RequestInit) => {
 	const stream = await downloadContentFromMessage(msg, 'md-msg-hist', { options })
 	const bufferArray: Buffer[] = []
@@ -25,15 +39,103 @@ export const downloadHistory = async (msg: proto.Message.IHistorySyncNotificatio
 	return syncData
 }

+/**
+ * Extracts LID-PN mapping from a conversation object.
+ *
+ * WhatsApp uses two identifier systems:
+ * - LID (Logical ID): Format `{number}@lid` or `{number}@hosted.lid`
+ * - PN (Phone Number): Format `{number}@s.whatsapp.net` or `{number}@hosted`
+ *
+ * Conversations may have their ID in either format, with the alternate
+ * format stored in `lidJid` or `pnJid` properties respectively.
+ *
+ * @param chatId - The conversation ID (may be LID or PN format)
+ * @param lidJid - The LID JID if chat ID is PN format
+ * @param pnJid - The PN JID if chat ID is LID format
+ * @returns LID-PN mapping if extractable, undefined otherwise
+ *
+ * @example
+ * // Chat ID is LID, pnJid contains phone number
+ * extractLidPnFromConversation('123456789@lid', undefined, '5511999999999@s.whatsapp.net')
+ * // Returns: { lid: '123456789@lid', pn: '5511999999999@s.whatsapp.net' }
+ *
+ * @example
+ * // Chat ID is PN, lidJid contains LID
+ * extractLidPnFromConversation('5511999999999@s.whatsapp.net', '123456789@lid', undefined)
+ * // Returns: { lid: '123456789@lid', pn: '5511999999999@s.whatsapp.net' }
+ */
+export function extractLidPnFromConversation(
+	chatId: string,
+	lidJid: string | undefined | null,
+	pnJid: string | undefined | null
+): LIDMapping | undefined {
+	// Check if chat ID is in LID format
+	const chatIsLid = isLidUser(chatId) || isHostedLidUser(chatId)
+	// Check if chat ID is in PN format
+	const chatIsPn = isPnUser(chatId) || isHostedPnUser(chatId)
+
+	if (chatIsLid && pnJid) {
+		// Chat ID is LID, pnJid contains the phone number
+		return {
+			lid: jidNormalizedUser(chatId),
+			pn: jidNormalizedUser(pnJid)
+		}
+	}
+
+	if (chatIsPn && lidJid) {
+		// Chat ID is PN, lidJid contains the LID
+		return {
+			lid: jidNormalizedUser(lidJid),
+			pn: jidNormalizedUser(chatId)
+		}
+	}
+
+	return undefined
+}
+
+/**
+ * Processes a history sync message and extracts chats, contacts, messages,
+ * and LID-PN mappings.
+ *
+ * LID-PN mappings are extracted from two sources:
+ * 1. Top-level `phoneNumberToLidMappings` array in the history sync payload
+ * 2. Individual conversation objects that contain both LID and PN identifiers
+ *
+ * This dual extraction ensures maximum mapping coverage, as WhatsApp may
+ * provide mappings in either or both locations depending on the sync type.
+ *
+ * @param item - The history sync protocol buffer to process
+ * @returns Processed data including chats, contacts, messages, and LID-PN mappings
+ *
+ * @see https://github.com/WhiskeySockets/Baileys/issues/2263
+ */
 export const processHistoryMessage = (item: proto.IHistorySync) => {
 	const messages: WAMessage[] = []
 	const contacts: Contact[] = []
 	const chats: Chat[] = []
-	// Extract LID-PN mappings for all sync types
-	const lidPnMappings: LIDMapping[] = []
+
+	// Use Map for O(1) deduplication of LID-PN mappings
+	const lidPnMap = new Map<string, LIDMapping>()
+
+	/**
+	 * Adds a LID-PN mapping to the map with deduplication.
+	 * Uses LID as key since each LID should map to exactly one PN.
+	 */
+	const addLidPnMapping = (mapping: LIDMapping): void => {
+		// Normalize and validate
+		if (!mapping.lid || !mapping.pn) {
+			return
+		}
+		lidPnMap.set(mapping.lid, mapping)
+	}
+
+	// Source 1: Extract from top-level phoneNumberToLidMappings array
 	for (const m of item.phoneNumberToLidMappings || []) {
 		if (m.lidJid && m.pnJid) {
-			lidPnMappings.push({ lid: m.lidJid, pn: m.pnJid })
+			addLidPnMapping({
+				lid: jidNormalizedUser(m.lidJid),
+				pn: jidNormalizedUser(m.pnJid)
+			})
 		}
 	}

@@ -43,8 +145,21 @@ export const processHistoryMessage = (item: proto.IHistorySync) => {
 		case proto.HistorySync.HistorySyncType.FULL:
 		case proto.HistorySync.HistorySyncType.ON_DEMAND:
 			for (const chat of item.conversations! as Chat[]) {
+				const chatId = chat.id!
+
+				// Source 2: Extract LID-PN mapping from conversation object
+				// This handles cases where the mapping isn't in phoneNumberToLidMappings
+				const conversationMapping = extractLidPnFromConversation(
+					chatId,
+					chat.lidJid,
+					chat.pnJid
+				)
+				if (conversationMapping) {
+					addLidPnMapping(conversationMapping)
+				}
+
 				contacts.push({
-					id: chat.id!,
+					id: chatId,
 					name: chat.name || undefined,
 					lid: chat.lidJid || undefined,
 					phoneNumber: chat.pnJid || undefined
@@ -90,6 +205,9 @@ export const processHistoryMessage = (item: proto.IHistorySync) => {
 			break
 	}

+	// Convert Map back to array for return
+	const lidPnMappings = Array.from(lidPnMap.values())
+
 	return {
 		chats,
 		contacts,
@@ -100,6 +218,13 @@ export const processHistoryMessage = (item: proto.IHistorySync) => {
 	}
 }

+/**
+ * Downloads and processes a history sync notification in one step.
+ *
+ * @param msg - The history sync notification message
+ * @param options - Request options for the download
+ * @returns Processed history data
+ */
 export const downloadAndProcessHistorySyncNotification = async (
 	msg: proto.Message.IHistorySyncNotification,
 	options: RequestInit
@@ -114,6 +239,12 @@ export const downloadAndProcessHistorySyncNotification = async (
 	return processHistoryMessage(historyMsg)
 }

+/**
+ * Extracts the history sync notification from a protocol message.
+ *
+ * @param message - The protocol message to check
+ * @returns The history sync notification if present, undefined otherwise
+ */
 export const getHistoryMsg = (message: proto.IMessage) => {
 	const normalizedContent = !!message ? normalizeMessageContent(message) : undefined
 	const anyHistoryMsg = normalizedContent?.protocolMessage?.historySyncNotification!