@badzz88/baileys 8.5.4 → 8.5.5

package/lib/Socket/interactive-handler.js

@@ -14,7 +14,7 @@ const {
 } = require('../Utils/index.js')
 const { isJidGroup, isPnUser, jidNormalizedUser, STORIES_JID } = require('../WABinary/index.js')
 
-class badzz88 {
+class InteractiveMessageHandler {
 	constructor(waUploadToServer, relayMessageFn, config, sock) {
 		this.relayMessage = relayMessageFn
 		this.waUploadToServer = waUploadToServer
@@ -24,12 +24,13 @@ class badzz88 {
 	detectType(content) {
 		if (content.requestPaymentMessage) return 'PAYMENT'
 		if (content.productMessage) return 'PRODUCT'
-		if (content.interactiveButtons) return 'INTERACTIVE_BUTTONS'
 		if (content.interactiveMessage) return 'INTERACTIVE'
 		if (content.albumMessage || content.album) return 'ALBUM'
 		if (content.eventMessage) return 'EVENT'
 		if (content.pollResultMessage) return 'POLL_RESULT'
 		if (content.groupStatusMessage) return 'GROUP_STORY'
+		if (content.orderMessage) return 'ORDER'
+		if (content.groupLabel) return 'GROUP_LABEL'
 		return null
 	}
 	async handlePayment(content, quoted) {
@@ -222,114 +223,6 @@ class badzz88 {
 		}
 		return { interactiveMessage }
 	}
-	async handleInteractiveButtons(content, _jid, _quoted) {
-		const {
-			text,
-			caption,
-			title,
-			subtitle,
-			footer,
-			interactiveButtons,
-			hasMediaAttachment,
-			image,
-			video,
-			document,
-			mimetype,
-			jpegThumbnail,
-			location,
-			product,
-			businessOwnerJid
-		} = content
-		const bodyText = text || caption || ''
-		const buttons = interactiveButtons.map(btn => ({
-			name: btn.name,
-			buttonParamsJson:
-				typeof btn.buttonParamsJson === 'string' ? btn.buttonParamsJson : JSON.stringify(btn.buttonParamsJson)
-		}))
-		let headerContent = {}
-		let mediaAttached = typeof hasMediaAttachment === 'boolean' ? hasMediaAttachment : false
-		if (image) {
-			const src = typeof image === 'object' && image.url ? { image: { url: image.url } } : { image }
-			const uploaded = await prepareWAMessageMedia(src, { upload: this.waUploadToServer })
-			headerContent = { ...uploaded }
-			mediaAttached = typeof hasMediaAttachment === 'boolean' ? hasMediaAttachment : true
-		} else if (video) {
-			const src = typeof video === 'object' && video.url ? { video: { url: video.url } } : { video }
-			const uploaded = await prepareWAMessageMedia(src, { upload: this.waUploadToServer })
-			headerContent = { ...uploaded }
-			mediaAttached = typeof hasMediaAttachment === 'boolean' ? hasMediaAttachment : true
-		} else if (document) {
-			const docPayload =
-				typeof document === 'object' && document.url ? { document: { url: document.url } } : { document }
-			if (mimetype) docPayload.mimetype = mimetype
-			const uploaded = await prepareWAMessageMedia(docPayload, { upload: this.waUploadToServer })
-			if (jpegThumbnail) {
-				uploaded.documentMessage.jpegThumbnail =
-					typeof jpegThumbnail === 'string' ? Buffer.from(jpegThumbnail, 'base64') : jpegThumbnail
-			}
-			headerContent = { ...uploaded }
-			mediaAttached = typeof hasMediaAttachment === 'boolean' ? hasMediaAttachment : true
-		} else if (location) {
-			headerContent = {
-				locationMessage: {
-					degreesLatitude: location.degressLatitude || location.degreesLatitude || 0,
-					degreesLongitude: location.degressLongitude || location.degreesLongitude || 0,
-					name: location.name || ''
-				}
-			}
-			mediaAttached = typeof hasMediaAttachment === 'boolean' ? hasMediaAttachment : true
-		} else if (product) {
-			let productImage
-			if (product.productImage) {
-				const imgSrc =
-					typeof product.productImage === 'object' && product.productImage.url
-						? { image: { url: product.productImage.url } }
-						: { image: product.productImage }
-				const uploaded = await prepareWAMessageMedia(imgSrc, { upload: this.waUploadToServer })
-				productImage = uploaded.imageMessage
-			}
-			headerContent = {
-				productMessage: {
-					product: {
-						productImage,
-						productId: product.productId,
-						title: product.title,
-						description: product.description,
-						currencyCode: product.currencyCode || 'IDR',
-						priceAmount1000: product.priceAmount1000,
-						retailerId: product.retailerId,
-						url: product.url,
-						productImageCount: product.productImageCount || 1
-					},
-					businessOwnerJid: businessOwnerJid || '0@s.whatsapp.net'
-				}
-			}
-			mediaAttached = typeof hasMediaAttachment === 'boolean' ? hasMediaAttachment : true
-		}
-		const interactiveMessage = {
-			body: { text: bodyText },
-			footer: { text: footer || '' },
-			header: {
-				title: title || '',
-				subtitle: subtitle || '',
-				hasMediaAttachment: mediaAttached,
-				...headerContent
-			},
-			nativeFlowMessage: { buttons }
-		}
-		return {
-			viewOnceMessage: {
-				message: {
-					messageContextInfo: {
-						deviceListMetadata: {},
-						deviceListMetadataVersion: 2,
-						messageSecret: crypto.randomBytes(32)
-					},
-					interactiveMessage
-				}
-			}
-		}
-	}
 	async handleAlbum(content, jid, quoted) {
 		const array = content.albumMessage || content.album
 		const ctxInfo = content.contextInfo || {}
@@ -344,7 +237,7 @@ class badzz88 {
 					expectedVideoCount: array.filter(a => 'video' in a).length
 				}
 			},
-			{ userJid: jidNormalizedUser(this.sock.authState?.creds?.me?.id || '') }
+			{ userJid: jidNormalizedUser(this.sock.authState?.creds?.me?.id || ''), browser: this.config?.browser }
 		)
 		await this.relayMessage(jid, album.message, {
 			messageId: album.key.id
@@ -394,18 +287,18 @@ class badzz88 {
 							joinLink: eventData.joinLink || '',
 							startTime:
 								typeof eventData.startTime === 'string'
-									? parseInt(eventData.startTime, 10)
+									? parseInt(eventData.startTime)
 									: eventData.startTime || Date.now(),
 							endTime:
 								typeof eventData.endTime === 'string'
-									? parseInt(eventData.endTime, 10)
+									? parseInt(eventData.endTime)
 									: eventData.endTime || Date.now() + 3600000,
 							extraGuestsAllowed: eventData.extraGuestsAllowed !== false
 						}
 					}
 				}
 			},
-			{ quoted, userJid: jidNormalizedUser(this.sock.authState?.creds?.me?.id || '') }
+			{ quoted, userJid: jidNormalizedUser(this.sock.authState?.creds?.me?.id || ''), browser: this.config?.browser }
 		)
 		await this.relayMessage(jid, msg.message, {
 			messageId: msg.key.id
@@ -426,7 +319,7 @@ class badzz88 {
 					}))
 				}
 			},
-			{ quoted, userJid: jidNormalizedUser(this.sock.authState?.creds?.me?.id || '') }
+			{ quoted, userJid: jidNormalizedUser(this.sock.authState?.creds?.me?.id || ''), browser: this.config?.browser }
 		)
 		await this.relayMessage(jid, msg.message, {
 			messageId: msg.key.id
@@ -454,6 +347,55 @@ class badzz88 {
 			messageId: generateMessageID()
 		})
 	}
+	async handleOrderMessage(content, jid, quoted) {
+		const orderData = content.orderMessage
+		const orderMsg = await generateWAMessageFromContent(jid, {
+			orderMessage: {
+				orderId: orderData.orderId || 'ORDER' + generateMessageID(),
+				thumbnail: orderData.thumbnail || null,
+				itemCount: orderData.itemCount || 0,
+				status: orderData.status || 'ACCEPTED',
+				surface: orderData.surface || 'CATALOG',
+				message: orderData.message,
+				orderTitle: orderData.orderTitle,
+				sellerJid: orderData.sellerJid || jid,
+				token: orderData.token || generateMessageID(),
+				totalAmount1000: orderData.totalAmount1000 || 0,
+				totalCurrencyCode: orderData.totalCurrencyCode || 'IDR',
+				messageVersion: 2
+			}
+		}, { quoted, browser: this.config?.browser })
+		await this.relayMessage(jid, orderMsg.message, {
+			messageId: orderMsg.key.id
+		})
+		return orderMsg
+	}
+	async handleGbLabel(content, jid) {
+		const labelData = content.groupLabel
+		if (!isJidGroup(jid)) {
+			throw new Error('handleGbLabel requires a group jid')
+		}
+		const msg = await generateWAMessageFromContent(jid, {
+			protocolMessage: {
+				type: 'GROUP_MEMBER_LABEL_CHANGE',
+				memberLabel: {
+					label: labelData.labelText.slice(0, 30)
+				}
+			}
+		}, { browser: this.config?.browser })
+		return await this.relayMessage(jid, msg.message, {
+			additionalNodes: [
+				{
+					tag: 'meta',
+					attrs: {
+						tag_reason: 'user_update',
+						appdata: 'member_tag'
+					},
+					content: undefined
+				}
+			]
+		})
+	}
 	async sendStatusWhatsApp(content, jids = []) {
 		const userJid = jidNormalizedUser(this.sock.authState.creds.me.id)
 		const allUsers = new Set()
@@ -557,7 +499,8 @@ class badzz88 {
 					}
 				}
 				const statusMsg = await generateWAMessageFromContent(normalizedId, protocolMessage, {
-					userJid: jidNormalizedUser(this.sock.authState?.creds?.me?.id || '')
+					userJid: jidNormalizedUser(this.sock.authState?.creds?.me?.id || ''),
+					browser: this.config?.browser
 				})
 				await this.relayMessage(normalizedId, statusMsg.message, {
 					additionalNodes: [
@@ -576,4 +519,4 @@ class badzz88 {
 	}
 }
 
-module.exports = { badzz88 }
+module.exports = { InteractiveMessageHandler }

package/lib/Socket/interop.js

@@ -5,36 +5,47 @@ exports.makeInteropSocket = void 0
 const { getBinaryNodeChild, getBinaryNodeChildren, S_WHATSAPP_NET } = require('../WABinary')
 const { executeWMexQuery } = require('./mex')
 
-
 const INTEROP_MEX_QUERY_IDS = {
-	CREATE_GROUP: '25726817620301611', 
-	LEAVE_GROUP: '25346167795013271', 
-	ADD_PARTICIPANTS: '25732168276369451', 
-	QUERY_GROUP_INFO: '32734144032867938', 
-	PRIVACY_SETTINGS_QUERY: '24849123668112654', 
-	PRIVACY_SETTINGS_UPDATE: '25421856497452763', 
-	PRIVACY_SETTINGS_WITH_CONTACT_LIST: '24913399124998598' 
+	CREATE_GROUP: '25726817620301612', // GroupsCreateInteropGroup
+	LEAVE_GROUP: '25346167795013270', // LeaveInteropGroup
+	ADD_PARTICIPANTS: '25732168276369452', // AddParticipantsToInteropGroup
+	QUERY_GROUP_INFO: '32734144032867936', // QueryInteropGroupInfo
+	PRIVACY_SETTINGS_QUERY: '24849123668112656', // InteropPrivacySettingsQuery
+	PRIVACY_SETTINGS_UPDATE: '25421856497452764', // InteropPrivacySettingsUpdate
+	PRIVACY_SETTINGS_WITH_CONTACT_LIST: '24913399124998600' // InteropPrivacySettingWithContactListUpdate
 }
 
-
+/**
+ * Known integrator IDs (assigned by WhatsApp).
+ * BirdyChat → identifier_type="email"
+ * Haiket    → identifier_type="pn"
+ */
 const INTEGRATOR_BIRDYCHAT = 12
 const INTEGRATOR_HAIKET = 13
 
-
+/**
+ * TOS trackable results sent by WA on first interop opt-in.
+ * 105 = TOS shown, 160 = TOS accepted.
+ */
 const TOS_TRACKABLE_ID = '20240306'
 const TOS_RESULT_SHOWN = '105'
 const TOS_RESULT_ACCEPTED = '160'
 
-
+/** Maximum users per batch lookup (enforced server-side too). */
 const INTEROP_BATCH_MAX = 256
 
 const makeInteropSocket = sock => {
-	const { query, generateMessageTag, logger, signalRepository, masqueradeAsPrimary } = sock
+	const { query, generateMessageTag, logger, signalRepository } = sock
 
 	const mexQuery = (variables, queryId, dataPath) =>
 		executeWMexQuery(variables, queryId, dataPath, query, generateMessageTag)
 
-	
+	/**
+	 * Fetch all available interop integrators from the server.
+	 * Each integrator carries: id, name, status, icon, identifierType,
+	 * optedIn, features.groupMessaging.
+	 * status can be "active" | "onboarding" | "removed".
+	 */
 	const fetchIntegrators = async () => {
 		const result = await query({
 			tag: 'iq',
@@ -51,14 +62,14 @@ const makeInteropSocket = sock => {
 		return getBinaryNodeChildren(listNode, 'integrator').map(node => {
 			const featuresNode = getBinaryNodeChild(node, 'features')
 			return {
-				id: parseInt(node.attrs.id, 10),
+				id: parseInt(node.attrs.id),
 				name: node.attrs.name,
-				
+				// "active" | "onboarding" | "removed"
 				status: node.attrs.status,
 				icon: node.attrs.icon,
-				
+				// "email" | "pn" | "username"
 				identifierType: node.attrs.identifier_type,
-				
+				// Whether we are already opted-in to this integrator
 				optedIn: node.attrs.opted_in === 'true' || globalOptedIn,
 				features: {
 					groupMessaging: featuresNode?.attrs?.group_messaging === 'true'
@@ -67,7 +78,7 @@ const makeInteropSocket = sock => {
 		})
 	}
 
-	
+	/** Send a single TOS trackable item (shown or accepted). */
 	const sendTOSTrackable = async (id, result) => {
 		await query({
 			tag: 'iq',
@@ -76,13 +87,20 @@ const makeInteropSocket = sock => {
 		})
 	}
 
-	
+	/**
+	 * Accept TOS for interop.
+	 * Sends two trackable items: shown (105) then accepted (160).
+	 * Must be called before opting in.
+	 */
 	const acceptInteropTOS = async () => {
 		await sendTOSTrackable(TOS_TRACKABLE_ID, TOS_RESULT_SHOWN)
 		await sendTOSTrackable(TOS_TRACKABLE_ID, TOS_RESULT_ACCEPTED)
 	}
 
-	
+	/**
+	 * Opt in to a list of integrators (by numeric ID).
+	 * Defaults to both known integrators (BirdyChat + Haiket).
+	 */
 	const optInIntegrators = async (integratorIds = [INTEGRATOR_BIRDYCHAT, INTEGRATOR_HAIKET]) => {
 		await query({
 			tag: 'iq',
@@ -106,7 +124,10 @@ const makeInteropSocket = sock => {
 		})
 	}
 
-	
+	/**
+	 * Opt out of a list of integrators (by numeric ID).
+	 * Mirror of optInIntegrators — uses <opt_out_integrators>.
+	 */
 	const optOutIntegrators = async (integratorIds = [INTEGRATOR_BIRDYCHAT, INTEGRATOR_HAIKET]) => {
 		await query({
 			tag: 'iq',
@@ -130,7 +151,18 @@ const makeInteropSocket = sock => {
 		})
 	}
 
-	
+	/**
+	 * Resolve one or more interop users by external ID in a single IQ.
+	 * Each entry: { externalId, integratorId }
+	 *   - BirdyChat (12): externalId = email address
+	 *   - Haiket    (13): externalId = phone number string (e.g. "19146088152")
+	 *
+	 * Max 256 entries per call (server limit).
+	 *
+	 * Returns an array of results:
+	 *   { jid, externalId, normalizedExternalId, integratorId }  on success
+	 *   { externalId, integratorId, error: { code, text } }       on failure
+	 */
 	const resolveInteropUsers = async users => {
 		if (!users || users.length === 0) return []
 		if (users.length > INTEROP_BATCH_MAX) {
@@ -160,9 +192,9 @@ const makeInteropSocket = sock => {
 			if (errorNode) {
 				return {
 					externalId: userNode.attrs.external_id,
-					integratorId: parseInt(userNode.attrs.integrator_id, 10),
+					integratorId: parseInt(userNode.attrs.integrator_id),
 					error: {
-						code: parseInt(errorNode.attrs.code, 10),
+						code: parseInt(errorNode.attrs.code),
 						text: errorNode.attrs.text
 					}
 				}
@@ -171,18 +203,25 @@ const makeInteropSocket = sock => {
 				jid: userNode.attrs.jid,
 				externalId: userNode.attrs.external_id,
 				normalizedExternalId: userNode.attrs.normalized_external_id,
-				integratorId: parseInt(userNode.attrs.integrator_id, 10)
+				integratorId: parseInt(userNode.attrs.integrator_id)
 			}
 		})
 	}
 
-	
+	/**
+	 * Convenience wrapper: resolve a single interop user.
+	 * Returns the result object or null.
+	 */
 	const resolveInteropUser = async (externalId, integratorId) => {
 		const results = await resolveInteropUsers([{ externalId, integratorId }])
 		return results[0] ?? null
 	}
 
-	
+	/**
+	 * Get reachability settings for interop contacts.
+	 * Returns the raw <reachability_settings> node content.
+	 * WA uses this as the interop presence/subscription mechanism.
+	 */
 	const getReachabilitySettings = async () => {
 		const result = await query({
 			tag: 'iq',
@@ -195,13 +234,17 @@ const makeInteropSocket = sock => {
 			enabled: settingsNode.attrs?.enabled,
 			users: getBinaryNodeChildren(settingsNode, 'user').map(n => ({
 				externalId: n.attrs.external_id,
-				integratorId: parseInt(n.attrs.integrator_id, 10),
+				integratorId: parseInt(n.attrs.integrator_id),
 				jid: n.attrs.jid
 			}))
 		}
 	}
 
-	
+	/**
+	 * Set reachability settings (subscribe to presence) for interop contacts.
+	 * users: array of { externalId, integratorId }
+	 * enabled: "true" | "false"
+	 */
 	const setReachabilitySettings = async (users, enabled = 'true') => {
 		await query({
 			tag: 'iq',
@@ -222,7 +265,10 @@ const makeInteropSocket = sock => {
 		})
 	}
 
-	
+	/**
+	 * Block or unblock an interop user via the w:interop blocklist.
+	 * Different from regular WA block (xmlns=blocklist).
+	 */
 	const updateInteropBlockStatus = async (jid, action) => {
 		await query({
 			tag: 'iq',
@@ -240,7 +286,10 @@ const makeInteropSocket = sock => {
 	const blockInteropUser = jid => updateInteropBlockStatus(jid, 'block')
 	const unblockInteropUser = jid => updateInteropBlockStatus(jid, 'unblock')
 
-	
+	/**
+	 * Report an interop contact as spam.
+	 * spam_flow="account_info_block" = block + report (WA Web default).
+	 */
 	const reportInteropSpam = async (jid, spamFlow = 'account_info_block') => {
 		await query({
 			tag: 'iq',
@@ -249,7 +298,10 @@ const makeInteropSocket = sock => {
 		})
 	}
 
-	
+	/**
+	 * Mark an interop JID as trusted_contact in privacy tokens.
+	 * WA calls this automatically after the first outgoing message.
+	 */
 	const trustInteropContact = async jid => {
 		const t = Math.floor(Date.now() / 1000).toString()
 		await query({
@@ -265,7 +317,15 @@ const makeInteropSocket = sock => {
 		})
 	}
 
-	
+	/**
+	 * Full interop initialization sequence matching WA Web:
+	 * 1. Fetch available integrators
+	 * 2. Accept TOS (shown 105 + accepted 160)
+	 * 3. Opt-in to all active/onboarding integrators
+	 *
+	 * Silently tolerates TOS/opt-in errors.
+	 * Returns the full integrator list.
+	 */
 	const initInterop = async () => {
 		let integrators
 		try {
@@ -286,23 +346,30 @@ const makeInteropSocket = sock => {
 		} catch (err) {
 			logger.warn({ err }, 'interop: failed to opt-in integrators')
 		}
-		logger.info({ integrators: toOptIn.map(i => i.name) }, 'interop: opted in')
-		logger.warn(
-			{ integrators: toOptIn.map(i => i.name) },
-			'interop: receiving messages from interop contacts (BirdyChat/Haiket) is NOT YET SUPPORTED. ' +
-			'The interop bridge only delivers to device 0 (primary phone) via a single Signal session — ' +
-			'no fan-out to companion devices. Opt-in and sending may work, but inbound messages will not arrive.'
-		)
+		logger.info({ integrators: toOptIn.map(i => i.name) }, 'interop: initialized')
 		return integrators
 	}
 
-	
+	/**
+	 * Reset the Signal session with an interop contact and force a fresh pkmsg handshake.
+	 * Call this when incoming messages from an interop contact are not arriving or
+	 * failing to decrypt — it clears the stale session so the next sendMessage
+	 * generates a new pre-key message and re-establishes both directions.
+	 */
 	const resetInteropSession = async jid => {
 		await signalRepository.deleteSession([jid])
 		logger.info({ jid }, '[interop] session reset — next send will use pkmsg')
 	}
 
-	
+	/**
+	 * Create an interop group via MEX.
+	 * Confirmed from C80913Xf.java opcode 15:
+	 *   input: { participants: [{ jid }] }
+	 *   dataPath: xwa2_interop_group_create
+	 *
+	 * @param {string[]} participants - Interop JIDs to add
+	 * @returns {{ gid, creationTime, creator, participants }}
+	 */
 	const createInteropGroup = async participants => {
 		const result = await mexQuery(
 			{ input: { participants: participants.map(jid => ({ jid })) } },
@@ -313,7 +380,15 @@ const makeInteropSocket = sock => {
 		return result
 	}
 
-	
+	/**
+	 * Leave one or more interop groups via MEX.
+	 * Confirmed from C80913Xf.java opcode 28:
+	 *   input: { groups_to_leave: [{ gid }] }
+	 *   dataPath: xwa2_interop_group_leave
+	 *
+	 * gid is the raw interop group ID (without @g.us suffix).
+	 * @param {string|string[]} jids - Interop group JID(s)
+	 */
 	const leaveInteropGroup = async jids => {
 		const ids = Array.isArray(jids) ? jids : [jids]
 		const result = await mexQuery(
@@ -325,7 +400,15 @@ const makeInteropSocket = sock => {
 		return result
 	}
 
-	
+	/**
+	 * Add participants to an existing interop group via MEX.
+	 * Confirmed from C3Wt.java opcode 9:
+	 *   input: { gid, participants: [{ jid }] }
+	 *   dataPath: xwa2_interop_add_participants_to_group
+	 *
+	 * @param {string} groupJid - Interop group JID
+	 * @param {string[]} participants - Interop JIDs to add
+	 */
 	const addParticipantsToInteropGroup = async (groupJid, participants) => {
 		const gid = groupJid.split('@')[0]
 		return mexQuery(
@@ -335,13 +418,35 @@ const makeInteropSocket = sock => {
 		)
 	}
 
-	
+	/**
+	 * Query info about an interop group via MEX.
+	 * Confirmed from C3Wt.java opcode 10:
+	 *   group_input: { gid }
+	 *   dataPath: xwa2_interop_group_query_by_id
+	 *
+	 * @param {string} groupJid - Interop group JID
+	 */
 	const queryInteropGroupInfo = async groupJid => {
 		const gid = groupJid.split('@')[0]
-		return mexQuery({ group_input: { gid } }, INTEROP_MEX_QUERY_IDS.QUERY_GROUP_INFO, 'xwa2_interop_group_query_by_id')
+		return mexQuery(
+			{ group_input: { gid } },
+			INTEROP_MEX_QUERY_IDS.QUERY_GROUP_INFO,
+			'xwa2_interop_group_query_by_id'
+		)
 	}
 
-	
+	/**
+	 * Update an interop privacy setting via MEX.
+	 * Confirmed from C24385Ak0.java (InteropPrivacySettingsUpdate):
+	 *   feature, setting
+	 *   dataPath: xwa2_interop_privacy_setting_update
+	 *
+	 * Known features: "GROUPADD"
+	 * Known settings: "ALL" | "CONTACTS" | "NONE"
+	 *
+	 * @param {string} feature - Privacy feature name
+	 * @param {string} setting - New value
+	 */
 	const updateInteropPrivacySetting = async (feature, setting) => {
 		return mexQuery(
 			{ feature, setting },
@@ -350,7 +455,20 @@ const makeInteropSocket = sock => {
 		)
 	}
 
-	
+	/**
+	 * Update an interop privacy setting with an explicit contact list via MEX.
+	 * Confirmed from C24388Ak8.java (InteropPrivacySettingWithContactListUpdate):
+	 *   feature, setting, contacts[], contact_list_type, dhash
+	 *   dataPath: xwa2_interop_privacy_setting_with_contact_list_update
+	 *
+	 * Used when setting is "CONTACTS" and you want to specify exact allowed contacts.
+	 *
+	 * @param {string} feature - Privacy feature (e.g. "GROUPADD")
+	 * @param {string} setting - "CONTACTS"
+	 * @param {string[]} contacts - List of JIDs to allow
+	 * @param {string} contactListType - Contact list type string
+	 * @param {string} [dhash] - Hash of the current contact list (or null/"none")
+	 */
 	const updateInteropPrivacySettingWithContactList = async (
 		feature,
 		setting,
@@ -365,11 +483,13 @@ const makeInteropSocket = sock => {
 		)
 	}
 
-	
-	const queryInteropPrivacySettings = () =>
-		mexQuery({}, INTEROP_MEX_QUERY_IDS.PRIVACY_SETTINGS_QUERY, 'xwa2_interop_privacy_settings')
-
-	
+	/**
+	 * Check whether an interop user allows being added to groups (GROUPADD privacy).
+	 * Returns true if the user can be added, false if blocked by their privacy settings.
+	 *
+	 * Mirrors InteropPrivacySettingsManager.A01() in the APK which queries
+	 * the "GROUPADD" feature for the given account.
+	 */
 	const getInteropGroupAddPrivacy = async (jid, integratorId) => {
 		const result = await query({
 			tag: 'iq',
@@ -392,8 +512,8 @@ const makeInteropSocket = sock => {
 		})
 		const privacyNode = getBinaryNodeChild(result, 'privacy')
 		const userNode = getBinaryNodeChild(privacyNode, 'user')
-		
-		
+		// "allowed" means the server confirmed the user can be added; any other value or
+		// absence of the attribute means the privacy setting blocks the add.
 		return userNode?.attrs?.result === 'allowed'
 	}
 
@@ -417,7 +537,6 @@ const makeInteropSocket = sock => {
 		leaveInteropGroup,
 		addParticipantsToInteropGroup,
 		queryInteropGroupInfo,
-		queryInteropPrivacySettings,
 		updateInteropPrivacySetting,
 		updateInteropPrivacySettingWithContactList,
 		getInteropGroupAddPrivacy,