@badzz88/baileys 8.5.4 → 8.5.5

package/lib/Socket/socket.js

@@ -12,11 +12,15 @@ const Utils_1 = require('../Utils')
 const browser_utils_1 = require('../Utils/browser-utils')
 const WABinary_1 = require('../WABinary')
 const BinaryInfo_js_1 = require('../WAM/BinaryInfo.js')
-const WAM_1 = require('../WAM')
 const WAUSync_1 = require('../WAUSync/')
 const Client_1 = require('./Client')
 const mex_1 = require('./mex')
-
+/**
+ * Connects to WA servers and performs:
+ * - simple queries (no retry mechanism, wait for connection establishment)
+ * - listen to messages and emit events
+ * - query phone connection
+ */
 const makeSocket = config => {
 	const {
 		waWebSocketUrl,
@@ -57,9 +61,9 @@ const makeSocket = config => {
 	if (url.protocol === 'wss' && authState?.creds?.routingInfo) {
 		url.searchParams.append('ED', authState.creds.routingInfo.toString('base64url'))
 	}
-	
+	/** ephemeral key pair used to encrypt/decrypt communication. Unique for each connection */
 	const ephemeralKeyPair = Utils_1.Curve.generateKeyPair()
-	
+	/** WA noise protocol wrapper */
 	const noise = (0, Utils_1.makeNoiseHandler)({
 		keyPair: ephemeralKeyPair,
 		NOISE_HEADER: Defaults_1.NOISE_WA_HEADER,
@@ -67,10 +71,9 @@ const makeSocket = config => {
 		routingInfo: authState?.creds?.routingInfo
 	})
 	const ws = new Client_1.WebSocketClient(url, config)
-	const connectionStartTs = Date.now()
 	ws.connect()
 	const sendPromise = (0, util_1.promisify)(ws.send)
-	
+	/** send a raw buffer */
 	const sendRawMessage = async data => {
 		if (!ws.isOpen) {
 			throw new boom_1.Boom('Connection Closed', { statusCode: Types_1.DisconnectReason.connectionClosed })
@@ -85,7 +88,7 @@ const makeSocket = config => {
 			}
 		})
 	}
-	
+	/** send a binary node */
 	const sendNode = frame => {
 		if (logger.level === 'trace') {
 			logger.trace({ xml: (0, WABinary_1.binaryNodeToString)(frame), msg: 'xml send' })
@@ -93,7 +96,11 @@ const makeSocket = config => {
 		const buff = (0, WABinary_1.encodeBinaryNode)(frame)
 		return sendRawMessage(buff)
 	}
-	
+	/**
+	 * Wait for a message with a certain tag to be received
+	 * @param msgId the message tag to await
+	 * @param timeoutMs timeout after which the promise will reject
+	 */
 	const waitForMessage = async (msgId, timeoutMs = defaultQueryTimeoutMs) => {
 		let onRecv
 		let onErr
@@ -117,7 +124,7 @@ const makeSocket = config => {
 			})
 			return result
 		} catch (error) {
-			
+			// Catch timeout and return undefined instead of throwing
 			if (error instanceof boom_1.Boom && error.output?.statusCode === Types_1.DisconnectReason.timedOut) {
 				logger?.warn?.({ msgId }, 'timed out waiting for message')
 				return undefined
@@ -131,7 +138,7 @@ const makeSocket = config => {
 			}
 		}
 	}
-	
+	/** send a query, and wait for its response. auto-generates message ID if not provided */
 	const query = async (node, timeoutMs) => {
 		if (!node.attrs.id) {
 			node.attrs.id = generateMessageTag()
@@ -148,7 +155,7 @@ const makeSocket = config => {
 		}
 		return result
 	}
-	
+	// Validate current key-bundle on server; on failure, trigger pre-key upload and rethrow
 	const digestKeyBundle = async () => {
 		const res = await query({
 			tag: 'iq',
@@ -161,7 +168,7 @@ const makeSocket = config => {
 			throw new Error('encrypt/get digest returned no digest node')
 		}
 	}
-	
+	// Rotate our signed pre-key on server; on failure, run digest as fallback and rethrow
 	const rotateSignedPreKey = async () => {
 		const newId = (creds.signedPreKey.keyId || 0) + 1
 		const skey = await (0, Utils_1.signedKeyPair)(creds.signedIdentityKey, newId)
@@ -176,23 +183,21 @@ const makeSocket = config => {
 				}
 			]
 		})
-		
+		// Persist new signed pre-key in creds
 		ev.emit('creds.update', { signedPreKey: skey })
 	}
 	const executeUSyncQuery = async usyncQuery => {
 		if (usyncQuery.protocols.length === 0) {
 			throw new boom_1.Boom('USyncQuery must have at least one protocol')
 		}
-		const validUsers = usyncQuery.users.filter(user => (typeof user.validate === 'function' ? user.validate() : true))
-		if (!validUsers.length) {
-			logger.warn('a usync query must have at least one valid user')
-		}
+		// todo: validate users, throw WARNING on no valid users
+		// variable below has only validated users
+		const validUsers = usyncQuery.users
 		const userNodes = validUsers.map(user => {
 			return {
 				tag: 'user',
 				attrs: {
-					jid: !user.phone ? user.id : undefined,
-					pn_jid: user.pnJid
+					jid: !user.phone ? user.id : undefined
 				},
 				content: usyncQuery.protocols.map(a => a.getUserElement(user)).filter(a => a !== null)
 			}
@@ -228,17 +233,8 @@ const makeSocket = config => {
 				}
 			]
 		}
-		await (0, WAUSync_1.waitForBackoff)(usyncQuery)
 		const result = await query(iq)
-		const parsed = usyncQuery.parseUSyncQueryResult(result)
-		if (parsed?.errors) {
-			for (const [protocolName, err] of Object.entries(parsed.errors)) {
-				if (err?.errorBackoff) {
-					;(0, WAUSync_1.setProtocolBackoffMs)(protocolName, err.errorBackoff * 1000)
-				}
-			}
-		}
-		return parsed
+		return usyncQuery.parseUSyncQueryResult(result)
 	}
 	const onWhatsApp = async (...phoneNumber) => {
 		let usyncQuery = new WAUSync_1.USyncQuery()
@@ -257,7 +253,7 @@ const makeSocket = config => {
 			}
 		}
 		if (usyncQuery.users.length === 0) {
-			return [] 
+			return [] // return early without forcing an empty query
 		}
 		const results = await executeUSyncQuery(usyncQuery)
 		if (results) {
@@ -275,7 +271,7 @@ const makeSocket = config => {
 			}
 		}
 		if (usyncQuery.users.length === 0) {
-			return [] 
+			return [] // return early without forcing an empty query
 		}
 		const results = await executeUSyncQuery(usyncQuery)
 		if (results) {
@@ -283,9 +279,83 @@ const makeSocket = config => {
 		}
 		return []
 	}
+	/**
+	 * @param {string | string[]} lid - @lid JID or array of @lid JID
+	 * @returns {Promise<{ lid: string, pn: string | null }[]>}
+	 */
+	const toPn = async lid => {
+		const lids = Array.isArray(lid) ? lid : [lid]
+		const usyncQuery = new WAUSync_1.USyncQuery().withContactProtocol().withLIDProtocol()
+		for (const l of lids) {
+			const decoded = (0, WABinary_1.jidDecode)(l)
+			if (!decoded) continue
+			usyncQuery.withUser(
+				new WAUSync_1.USyncUser().withId((0, WABinary_1.jidEncode)(decoded.user, 's.whatsapp.net')).withLid(l)
+			)
+		}
+		const result = await executeUSyncQuery(usyncQuery)
+		return lids.map(l => {
+			const decoded = (0, WABinary_1.jidDecode)(l)
+			if (!decoded) return { lid: l, pn: null }
+			const match = result?.list?.find(entry => {
+				const entryDecoded = (0, WABinary_1.jidDecode)(entry.id)
+				return entryDecoded?.user === decoded.user
+			})
+			if (!match?.contact) return { lid: l, pn: null }
+			const pn = (0, WABinary_1.jidEncode)((0, WABinary_1.jidDecode)(match.id)?.user, 's.whatsapp.net')
+			return { lid: l, pn: pn ?? null }
+		})
+	}
+	/**
+	 * @param {string | string[]} pn - @s.whatsapp.net JID or array of @s.whatsapp.net JID
+	 * @returns {Promise<{ pn: string, lid: string | null }[]>}
+	 */
+	const toLID = async pn => {
+		const pns = Array.isArray(pn) ? pn : [pn]
+		const usyncQuery = new WAUSync_1.USyncQuery().withContactProtocol().withLIDProtocol()
+		for (const p of pns) {
+			const decoded = (0, WABinary_1.jidDecode)(p)
+			if (!decoded) continue
+			usyncQuery.withUser(new WAUSync_1.USyncUser().withId((0, WABinary_1.jidEncode)(decoded.user, 's.whatsapp.net')))
+		}
+		const result = await executeUSyncQuery(usyncQuery)
+		return pns.map(p => {
+			const decoded = (0, WABinary_1.jidDecode)(p)
+			if (!decoded) return { pn: p, lid: null }
+			const match = result?.list?.find(entry => {
+				return (0, WABinary_1.jidDecode)(entry.id)?.user === decoded.user
+			})
+			if (!match?.contact) return { pn: p, lid: null }
+			const lidVal = match?.lid ?? null
+			const lid = lidVal ? (0, WABinary_1.jidEncode)((0, WABinary_1.jidDecode)(lidVal)?.user ?? lidVal, 'lid') : null
+			return { pn: p, lid }
+		})
+	}
+	/**
+	 * @param {string | string[]} username - username to fetch
+	 * @param {string} [pin] - pin of username if the user has one set
+	 * @returns {Promise<{ username: string, pn: string | null, lid: string | null }[]>}
+	 */
+	const fetchUsername = async (username, pin) => {
+		const usernames = Array.isArray(username) ? username : [username]
+		const usyncQuery = new WAUSync_1.USyncQuery().withContactProtocol().withLIDProtocol()
+		for (const u of usernames) {
+			const user = new WAUSync_1.USyncUser().withUsername(u)
+			if (pin) user.withUsernameKey(pin)
+			usyncQuery.withUser(user)
+		}
+		const result = await executeUSyncQuery(usyncQuery)
+		return usernames.map(u => {
+			const match = result?.list?.find(entry => entry?.username === u)
+			if (!match?.contact) return { username: u, pn: null, lid: null }
+			const lid = match.lid
+			const pn = (0, WABinary_1.jidEncode)((0, WABinary_1.jidDecode)(match.id)?.user, 's.whatsapp.net')
+			return { username: u, pn: pn ?? null, lid: lid ?? null }
+		})
+	}
 	const ev = (0, Utils_1.makeEventBuffer)(logger)
 	const { creds } = authState
-	
+	// add transaction capability
 	const keys = (0, Utils_1.addTransactionCapability)(authState.keys, logger, transactionOpts)
 	const signalRepository = makeSignalRepository({ creds, keys }, logger, pnFromLIDUSync)
 	let lastDateRecv
@@ -293,11 +363,12 @@ const makeSocket = config => {
 	let keepAliveReq
 	let qrTimer
 	let closed = false
-	
+	const socketEndHandlers = []
+	/** log & process any unexpected errors */
 	const onUnexpectedError = (err, msg) => {
 		logger.error({ err }, `unexpected error in '${msg}'`)
 	}
-	
+	/** await the next incoming message */
 	const awaitNextMessage = async sendMsg => {
 		if (!ws.isOpen) {
 			throw new boom_1.Boom('Connection Closed', {
@@ -322,7 +393,7 @@ const makeSocket = config => {
 		}
 		return result
 	}
-	
+	/** connection handshake */
 	const validateConnection = async () => {
 		let helloMsg = {
 			clientHello: { ephemeral: ephemeralKeyPair.public }
@@ -333,7 +404,7 @@ const makeSocket = config => {
 		const result = await awaitNextMessage(init)
 		const handshake = index_js_1.proto.HandshakeMessage.decode(result)
 		logger.trace({ handshake }, 'handshake recv from WA')
-		const { keyEnc, serverStaticPub } = noise.processHandshake(handshake, creds.noiseKey)
+		const keyEnc = noise.processHandshake(handshake, creds.noiseKey)
 		let node
 		if (!creds.me) {
 			node = (0, Utils_1.generateRegistrationNode)(creds, config)
@@ -352,9 +423,6 @@ const makeSocket = config => {
 			}).finish()
 		)
 		await noise.finishInit()
-		if (serverStaticPub && !creds.serverStaticPub) {
-			ev.emit('creds.update', { serverStaticPub })
-		}
 		startKeepAliveRequest()
 	}
 	const getAvailablePreKeysOnServer = async () => {
@@ -371,12 +439,12 @@ const makeSocket = config => {
 		const countChild = (0, WABinary_1.getBinaryNodeChild)(result, 'count')
 		return +countChild.attrs.value
 	}
-	
+	// Pre-key upload state management
 	let uploadPreKeysPromise = null
 	let lastUploadTime = 0
-	
+	/** generates and uploads a set of pre-keys to the server */
 	const uploadPreKeys = async (count = Defaults_1.MIN_PREKEY_COUNT, retryCount = 0) => {
-		
+		// Check minimum interval (except for retries)
 		if (retryCount === 0) {
 			const timeSinceLastUpload = Date.now() - lastUploadTime
 			if (timeSinceLastUpload < Defaults_1.MIN_UPLOAD_INTERVAL) {
@@ -384,29 +452,29 @@ const makeSocket = config => {
 				return
 			}
 		}
-		
+		// Prevent multiple concurrent uploads
 		if (uploadPreKeysPromise) {
 			logger.debug('Pre-key upload already in progress, waiting for completion')
 			await uploadPreKeysPromise
 		}
 		const uploadLogic = async () => {
 			logger.info({ count, retryCount }, 'uploading pre-keys')
-			
+			// Generate and save pre-keys atomically (prevents ID collisions on retry)
 			const node = await keys.transaction(async () => {
 				logger.debug({ requestedCount: count }, 'generating pre-keys with requested count')
 				const { update, node } = await (0, Utils_1.getNextPreKeysNode)({ creds, keys }, count)
-				
+				// Update credentials immediately to prevent duplicate IDs on retry
 				ev.emit('creds.update', update)
-				return node 
+				return node // Only return node since update is already used
 			}, creds?.me?.id || 'upload-pre-keys')
-			
+			// Upload to server (outside transaction, can fail without affecting local keys)
 			try {
 				await query(node)
 				logger.info({ count }, 'uploaded pre-keys successfully')
 				lastUploadTime = Date.now()
 			} catch (uploadError) {
 				logger.error({ uploadError: uploadError.toString(), count }, 'Failed to upload pre-keys to server')
-				
+				// Exponential backoff retry (max 3 retries)
 				if (retryCount < 3) {
 					const backoffDelay = Math.min(1000 * Math.pow(2, retryCount), 10000)
 					logger.info(`Retrying pre-key upload in ${backoffDelay}ms`)
@@ -416,7 +484,7 @@ const makeSocket = config => {
 				throw uploadError
 			}
 		}
-		
+		// Add timeout protection
 		uploadPreKeysPromise = Promise.race([
 			uploadLogic(),
 			new Promise((_, reject) =>
@@ -464,47 +532,40 @@ const makeSocket = config => {
 			}
 		} catch (error) {
 			logger.error({ error }, 'Failed to check/upload pre-keys during initialization')
-			
+			// Don't throw - allow connection to continue even if pre-key check fails
 		}
 	}
 	const onMessageReceived = async data => {
-		try {
-			await noise.decodeFrame(data, frame => {
-				
-				lastDateRecv = new Date()
-				let anyTriggered = false
-				anyTriggered = ws.emit('frame', frame)
-				
-				if (!(frame instanceof Uint8Array)) {
-					const msgId = frame.attrs.id
-					if (logger.level === 'trace') {
-						logger.trace({ xml: (0, WABinary_1.binaryNodeToString)(frame), msg: 'recv xml' })
-					}
-					
-					anyTriggered = ws.emit(`${Defaults_1.DEF_TAG_PREFIX}${msgId}`, frame) || anyTriggered
-					
-					const l0 = frame.tag
-					const l1 = frame.attrs || {}
-					const l2 = Array.isArray(frame.content) ? frame.content[0]?.tag : ''
-					for (const key of Object.keys(l1)) {
-						anyTriggered =
-							ws.emit(`${Defaults_1.DEF_CALLBACK_PREFIX}${l0},${key}:${l1[key]},${l2}`, frame) || anyTriggered
-						anyTriggered = ws.emit(`${Defaults_1.DEF_CALLBACK_PREFIX}${l0},${key}:${l1[key]}`, frame) || anyTriggered
-						anyTriggered = ws.emit(`${Defaults_1.DEF_CALLBACK_PREFIX}${l0},${key}`, frame) || anyTriggered
-					}
-					anyTriggered = ws.emit(`${Defaults_1.DEF_CALLBACK_PREFIX}${l0},,${l2}`, frame) || anyTriggered
-					anyTriggered = ws.emit(`${Defaults_1.DEF_CALLBACK_PREFIX}${l0}`, frame) || anyTriggered
-					if (!anyTriggered && logger.level === 'debug') {
-						logger.debug({ unhandled: true, msgId, fromMe: false, frame }, 'communication recv')
-					}
+		await noise.decodeFrame(data, frame => {
+			// reset ping timeout
+			lastDateRecv = new Date()
+			let anyTriggered = false
+			anyTriggered = ws.emit('frame', frame)
+			// if it's a binary node
+			if (!(frame instanceof Uint8Array)) {
+				const msgId = frame.attrs.id
+				if (logger.level === 'trace') {
+					logger.trace({ xml: (0, WABinary_1.binaryNodeToString)(frame), msg: 'recv xml' })
 				}
-			})
-		} catch (error) {
-			
-			
-			logger.error({ error }, 'error decoding frame')
-			void end(error instanceof Error ? error : new Error(String(error)))
-		}
+				/* Check if this is a response to a message we sent */
+				anyTriggered = ws.emit(`${Defaults_1.DEF_TAG_PREFIX}${msgId}`, frame) || anyTriggered
+				/* Check if this is a response to a message we are expecting */
+				const l0 = frame.tag
+				const l1 = frame.attrs || {}
+				const l2 = Array.isArray(frame.content) ? frame.content[0]?.tag : ''
+				for (const key of Object.keys(l1)) {
+					anyTriggered =
+						ws.emit(`${Defaults_1.DEF_CALLBACK_PREFIX}${l0},${key}:${l1[key]},${l2}`, frame) || anyTriggered
+					anyTriggered = ws.emit(`${Defaults_1.DEF_CALLBACK_PREFIX}${l0},${key}:${l1[key]}`, frame) || anyTriggered
+					anyTriggered = ws.emit(`${Defaults_1.DEF_CALLBACK_PREFIX}${l0},${key}`, frame) || anyTriggered
+				}
+				anyTriggered = ws.emit(`${Defaults_1.DEF_CALLBACK_PREFIX}${l0},,${l2}`, frame) || anyTriggered
+				anyTriggered = ws.emit(`${Defaults_1.DEF_CALLBACK_PREFIX}${l0}`, frame) || anyTriggered
+				if (!anyTriggered && logger.level === 'debug') {
+					logger.debug({ unhandled: true, msgId, fromMe: false, frame }, 'communication recv')
+				}
+			}
+		})
 	}
 	const end = async error => {
 		if (closed) {
@@ -514,7 +575,6 @@ const makeSocket = config => {
 		closed = true
 		logger.info({ trace: error?.stack }, error ? 'connection errored' : 'connection closed')
 		clearInterval(keepAliveReq)
-		clearInterval(wamFlushInterval)
 		clearTimeout(qrTimer)
 		ws.removeAllListeners('close')
 		ws.removeAllListeners('open')
@@ -524,6 +584,13 @@ const makeSocket = config => {
 				await ws.close()
 			} catch {}
 		}
+		for (const handler of socketEndHandlers) {
+			try {
+				await handler(error)
+			} catch (err) {
+				logger.error({ err }, 'error in socket end handler')
+			}
+		}
 		ev.emit('connection.update', {
 			connection: 'close',
 			lastDisconnect: {
@@ -560,13 +627,14 @@ const makeSocket = config => {
 				lastDateRecv = new Date()
 			}
 			const diff = Date.now() - lastDateRecv.getTime()
-			
+			/*
+            check if it's been a suspicious amount of time since the server responded with our last seen
+            it could be that the network is down
+        */
 			if (diff > keepAliveIntervalMs + 5000) {
 				void end(new boom_1.Boom('Connection was lost', { statusCode: Types_1.DisconnectReason.connectionLost }))
 			} else if (ws.isOpen) {
-				
-				
-				
+				// if its all good, send a keep alive request
 				query({
 					tag: 'iq',
 					attrs: {
@@ -574,7 +642,8 @@ const makeSocket = config => {
 						to: WABinary_1.S_WHATSAPP_NET,
 						type: 'get',
 						xmlns: 'w:p'
-					}
+					},
+					content: [{ tag: 'ping', attrs: {} }]
 				}).catch(err => {
 					logger.error({ trace: err.stack }, 'error in sending keep alive')
 				})
@@ -582,7 +651,7 @@ const makeSocket = config => {
 				logger.warn('keep alive called when WS not open')
 			}
 		}, keepAliveIntervalMs))
-	
+	/** i have no idea why this exists. pls enlighten me */
 	const sendPassiveIq = tag =>
 		query({
 			tag: 'iq',
@@ -593,7 +662,7 @@ const makeSocket = config => {
 			},
 			content: [{ tag, attrs: {} }]
 		})
-	
+	/** logout & invalidate connection */
 	const logout = async msg => {
 		const jid = authState.creds.me?.id
 		if (jid) {
@@ -620,7 +689,7 @@ const makeSocket = config => {
 	}
 	const requestPairingCode = async (phoneNumber, customPairingCode) => {
 		const pairingCode = customPairingCode ?? (0, Utils_1.bytesToCrockford)((0, crypto_1.randomBytes)(5))
-		if (customPairingCode && customPairingCode.length !== 8) {
+		if (customPairingCode && customPairingCode?.length !== 8) {
 			throw new Error('Custom pairing code must be exactly 8 chars')
 		}
 		authState.creds.pairingCode = pairingCode
@@ -690,8 +759,7 @@ const makeSocket = config => {
 			attrs: {
 				to: WABinary_1.S_WHATSAPP_NET,
 				id: generateMessageTag(),
-				xmlns: 'w:stats',
-				type: 'set'
+				xmlns: 'w:stats'
 			},
 			content: [
 				{
@@ -702,30 +770,8 @@ const makeSocket = config => {
 			]
 		})
 	}
-	const flushWAMEvents = async () => {
-		if (!publicWAMBuffer.events.length) return
-		try {
-			const encoded = (0, WAM_1.encodeWAM)(publicWAMBuffer)
-			publicWAMBuffer.events = []
-			publicWAMBuffer.sequence = (publicWAMBuffer.sequence + 1) & 0xffff
-			await sendWAMBuffer(encoded)
-		} catch (e) {
-			logger.debug({ err: e }, 'WAM flush failed')
-		}
-	}
-	const wsOpenTs = { value: connectionStartTs }
 	ws.on('message', onMessageReceived)
 	ws.on('open', async () => {
-		wsOpenTs.value = Date.now()
-		publicWAMBuffer.events.push({
-			WebcSocketConnect: {
-				props: {
-					webcSocketConnectDuration: wsOpenTs.value - connectionStartTs,
-					webcSocketConnectReason: 0
-				},
-				globals: {}
-			}
-		})
 		try {
 			await validateConnection()
 		} catch (err) {
@@ -733,15 +779,12 @@ const makeSocket = config => {
 			void end(err)
 		}
 	})
-	const wamFlushInterval = setInterval(() => {
-		void flushWAMEvents()
-	}, 30_000)
 	ws.on('error', mapWebSocketError(end))
 	ws.on(
 		'close',
 		() => void end(new boom_1.Boom('Connection Terminated', { statusCode: Types_1.DisconnectReason.connectionClosed }))
 	)
-	
+	// the server terminated the connection
 	ws.on(
 		'CB:xmlstreamend',
 		() =>
@@ -749,7 +792,7 @@ const makeSocket = config => {
 				new boom_1.Boom('Connection Terminated by Server', { statusCode: Types_1.DisconnectReason.connectionClosed })
 			)
 	)
-	
+	// QR gen
 	ws.on('CB:iq,type:set,pair-device', async stanza => {
 		const iq = {
 			tag: 'iq',
@@ -765,7 +808,7 @@ const makeSocket = config => {
 		const noiseKeyB64 = Buffer.from(creds.noiseKey.public).toString('base64')
 		const identityKeyB64 = Buffer.from(creds.signedIdentityKey.public).toString('base64')
 		const advB64 = creds.advSecretKey
-		let qrMs = qrTimeout || 60000 
+		let qrMs = qrTimeout || 60000 // time to let a QR live
 		const genPairQR = () => {
 			if (!ws.isOpen) {
 				return
@@ -775,16 +818,16 @@ const makeSocket = config => {
 				void end(new boom_1.Boom('QR refs attempts ended', { statusCode: Types_1.DisconnectReason.timedOut }))
 				return
 			}
-			const ref = refNode.content.toString('utf8')
+			const ref = refNode.content.toString('utf-8')
 			const qr = [ref, noiseKeyB64, identityKeyB64, advB64].join(',')
 			ev.emit('connection.update', { qr })
 			qrTimer = setTimeout(genPairQR, qrMs)
-			qrMs = qrTimeout || 20000 
+			qrMs = qrTimeout || 20000 // shorter subsequent qrs
 		}
 		genPairQR()
 	})
-	
-	
+	// device paired for the first time
+	// if device pairs successfully, the server asks to restart the connection
 	ws.on('CB:iq,,pair-success', async stanza => {
 		logger.debug('pair success recv')
 		try {
@@ -803,16 +846,16 @@ const makeSocket = config => {
 			void end(error)
 		}
 	})
-	
+	// login complete
 	ws.on('CB:success', async node => {
 		try {
 			updateServerTimeOffset(node)
 			await uploadPreKeysToServerIfRequired()
-			
+			// passive→active handshake only for companion (passive) sessions
 			if (!config.masqueradeAsPrimary) {
 				await sendPassiveIq('active')
 			}
-			
+			// After successful login, validate our key-bundle against server
 			try {
 				await digestKeyBundle()
 			} catch (e) {
@@ -822,15 +865,7 @@ const makeSocket = config => {
 			logger.warn({ err }, 'failed to send initial passive iq')
 		}
 		logger.info('opened connection to WA')
-		clearTimeout(qrTimer) 
-		
-		publicWAMBuffer.events.push({
-			Login: {
-				props: { loginResult: 1, loginT: Date.now() - connectionStartTs, connectionOrigin: 1, passive: false },
-				globals: {}
-			}
-		})
-		void flushWAMEvents()
+		clearTimeout(qrTimer) // will never happen in all likelyhood -- but just in case WA sends success on first try
 		ev.emit('creds.update', { me: { ...authState.creds.me, lid: node.attrs.lid } })
 		if (config.syncFullHistory && authState.creds.initialFullSyncDone !== true) {
 			logger.debug('initial full history sync completed, persisting one-time flag')
@@ -843,16 +878,16 @@ const makeSocket = config => {
 			process.nextTick(async () => {
 				try {
 					const myPN = authState.creds.me.id
-					
+					// Store our own LID-PN mapping
 					await signalRepository.lidMapping.storeLIDPNMappings([{ lid: myLID, pn: myPN }])
-					
+					// Create device list for our own user (needed for bulk migration)
 					const { user, device } = (0, WABinary_1.jidDecode)(myPN)
 					await authState.keys.set({
 						'device-list': {
 							[user]: [device?.toString() || '0']
 						}
 					})
-					
+					// migrate our own session
 					await signalRepository.migrateSession(myPN, myLID)
 					logger.info({ myPN, myLID }, 'Own LID session created successfully')
 				} catch (error) {
@@ -867,7 +902,7 @@ const makeSocket = config => {
 		const { reason, statusCode } = (0, Utils_1.getErrorCodeFromStreamError)(node)
 		void end(new boom_1.Boom(`Stream Errored (${reason})`, { statusCode, data: reasonNode || node }))
 	})
-	
+	// stream fail, possible logout
 	ws.on('CB:failure', node => {
 		const reason = +(node.attrs.reason || 500)
 		void end(new boom_1.Boom('Connection Failure', { statusCode: reason, data: node.attrs }))
@@ -877,15 +912,6 @@ const makeSocket = config => {
 			new boom_1.Boom('Multi-device beta not joined', { statusCode: Types_1.DisconnectReason.multideviceMismatch })
 		)
 	})
-	ws.on('CB:ib,,dirty', node => {
-		const dirtyNode = (0, WABinary_1.getBinaryNodeChild)(node, 'dirty')
-		const dirtyType = dirtyNode?.attrs?.type
-		const dirtyTs = dirtyNode?.attrs?.timestamp ? +dirtyNode.attrs.timestamp : undefined
-		
-		
-		logger.debug({ dirtyType, dirtyTs }, 'received dirty flag')
-		ev.emit('account.dirty', { type: dirtyType, timestamp: dirtyTs })
-	})
 	ws.on('CB:ib,,offline_preview', async node => {
 		logger.info('offline preview received', JSON.stringify(node))
 		await sendNode({
@@ -894,19 +920,6 @@ const makeSocket = config => {
 			content: [{ tag: 'offline_batch', attrs: { count: '100' } }]
 		})
 	})
-	ws.on('CB:ib,,thread_metadata', node => {
-		const tmNode = (0, WABinary_1.getBinaryNodeChild)(node, 'thread_metadata')
-		const items = (0, WABinary_1.getBinaryNodeChildren)(tmNode, 'item')
-		if (items.length) {
-			ev.emit(
-				'thread-metadata.update',
-				items.map(item => ({
-					jid: item.attrs.from,
-					t: item.attrs.t ? +item.attrs.t : undefined
-				}))
-			)
-		}
-	})
 	ws.on('CB:ib,,edge_routing', node => {
 		const edgeRoutingNode = (0, WABinary_1.getBinaryNodeChild)(node, 'edge_routing')
 		const routingInfo = (0, WABinary_1.getBinaryNodeChild)(edgeRoutingNode, 'routing_info')
@@ -918,14 +931,14 @@ const makeSocket = config => {
 	let didStartBuffer = false
 	process.nextTick(() => {
 		if (creds.me?.id) {
-			
-			
+			// start buffering important events
+			// if we're logged in
 			ev.buffer()
 			didStartBuffer = true
 		}
 		ev.emit('connection.update', { connection: 'connecting', receivedPendingNotifications: false, qr: undefined })
 	})
-	
+	// called when all offline notifs are handled
 	ws.on('CB:ib,,offline', node => {
 		const child = (0, WABinary_1.getBinaryNodeChild)(node, 'offline')
 		const offlineNotifs = +(child?.attrs.count || 0)
@@ -936,14 +949,11 @@ const makeSocket = config => {
 		}
 		ev.emit('connection.update', { receivedPendingNotifications: true })
 	})
-	
+	// update credentials when required
 	ev.on('creds.update', update => {
 		const name = update.me?.name
-		
-		
-		
-		
-		if (typeof name === 'string' && name.length > 0 && creds.me?.name !== name) {
+		// if name has just been received
+		if (creds.me?.name !== name) {
 			logger.debug({ name }, 'updated pushName')
 			sendNode({
 				tag: 'presence',
@@ -1023,6 +1033,9 @@ const makeSocket = config => {
 			generateMessageTag
 		)
 	}
+	const registerSocketEndHandler = handler => {
+		socketEndHandlers.push(handler)
+	}
 	return {
 		type: 'md',
 		ws,
@@ -1040,6 +1053,10 @@ const makeSocket = config => {
 		sendNode,
 		logout,
 		end,
+		registerSocketEndHandler,
+		toPn,
+		toLID,
+		fetchUsername,
 		onUnexpectedError,
 		uploadPreKeys,
 		uploadPreKeysToServerIfRequired,
@@ -1049,19 +1066,20 @@ const makeSocket = config => {
 		updateServerTimeOffset,
 		sendUnifiedSession,
 		wamBuffer: publicWAMBuffer,
-		
+		/** Waits for the connection to WA to reach a state */
 		waitForConnectionUpdate: (0, Utils_1.bindWaitForConnectionUpdate)(ev),
 		sendWAMBuffer,
 		executeUSyncQuery,
 		onWhatsApp,
 		fetchAccountReachoutTimelock,
-		fetchNewChatMessageCap,
-		logger,
-		masqueradeAsPrimary: config.masqueradeAsPrimary
+		fetchNewChatMessageCap
 	}
 }
 exports.makeSocket = makeSocket
-
+/**
+ * map the websocket error to the right type
+ * so it can be retried by the caller
+ * */
 function mapWebSocketError(handler) {
 	return error => {
 		handler(