From 5d97e170d2f6abd5653574d3e65b185a7d4c8402 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 22 Jan 2026 19:24:36 +0000
Subject: [PATCH] feat(history): add proper logging support for history sync
 debugging

- Add optional ILogger parameter to processHistoryMessage and
  downloadAndProcessHistorySyncNotification functions
- Add trace-level logging with syncType and progress for debugging
- Preserve all existing imports and LID-PN extraction functionality
- Enhanced JSDoc documentation with detailed parameter descriptions

This enables trace-level visibility into history sync processing,
helping debug issues with message synchronization and LID mappings.
---
 src/Utils/history.ts         | 20 ++++++++++++++++----
 src/Utils/process-message.ts |  2 +-
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/src/Utils/history.ts b/src/Utils/history.ts
index 7754395e..4f1dac6e 100644
--- a/src/Utils/history.ts
+++ b/src/Utils/history.ts
@@ -6,6 +6,7 @@ import { WAMessageStubType } from '../Types'
 import { toNumber } from './generics'
 import { normalizeMessageContent } from './messages'
 import { downloadContentFromMessage } from './messages-media'
+import type { ILogger } from './logger.js'
 import {
 	isHostedLidUser,
 	isHostedPnUser,
@@ -255,11 +256,16 @@ const extractPnFromMessages = (messages: proto.IHistorySyncMsg[]): string | unde
  * - `@newsletter` (channels)
  *
  * @param item - The history sync protocol buffer to process
+ * @param logger - Optional logger instance for trace-level debugging
  * @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) => {
+export const processHistoryMessage = (item: proto.IHistorySync, logger?: ILogger) => {
+	logger?.trace(
+		{ syncType: item.syncType, progress: item.progress },
+		'processing history sync'
+	)
 	const messages: WAMessage[] = []
 	const contacts: Contact[] = []
 	const chats: Chat[] = []
@@ -393,13 +399,19 @@ export const processHistoryMessage = (item: proto.IHistorySync) => {
 /**
  * Downloads and processes a history sync notification in one step.
  *
+ * Handles two cases:
+ * - Inline payload: Decodes directly from `initialHistBootstrapInlinePayload`
+ * - Remote download: Fetches from WhatsApp servers via `downloadHistory`
+ *
  * @param msg - The history sync notification message
  * @param options - Request options for the download
- * @returns Processed history data
+ * @param logger - Optional logger instance for trace-level debugging
+ * @returns Processed history data including chats, contacts, messages, and LID-PN mappings
  */
 export const downloadAndProcessHistorySyncNotification = async (
 	msg: proto.Message.IHistorySyncNotification,
-	options: RequestInit
+	options: RequestInit,
+	logger?: ILogger
 ) => {
 	let historyMsg: proto.HistorySync
 	if (msg.initialHistBootstrapInlinePayload) {
@@ -408,7 +420,7 @@ export const downloadAndProcessHistorySyncNotification = async (
 		historyMsg = await downloadHistory(msg, options)
 	}
 
-	return processHistoryMessage(historyMsg)
+	return processHistoryMessage(historyMsg, logger)
 }
 
 /**
diff --git a/src/Utils/process-message.ts b/src/Utils/process-message.ts
index b1743cca..c5cecd8a 100644
--- a/src/Utils/process-message.ts
+++ b/src/Utils/process-message.ts
@@ -320,7 +320,7 @@ const processMessage = async (
 						})
 					}
 
-					const data = await downloadAndProcessHistorySyncNotification(histNotification, options)
+					const data = await downloadAndProcessHistorySyncNotification(histNotification, options, logger)
 
 					// Emit LID-PN mappings from history sync
 					// This is how WhatsApp Web learns mappings for chats with non-contacts