zapo-js 0.3.0 → 1.0.0

package/dist/esm/message/primitives/peer-data-operation.js

@@ -0,0 +1,93 @@
+import { proto } from '../../proto.js';
+import { toUserJid } from '../../protocol/jid.js';
+import { setBoundedMapEntry } from '../../util/collections.js';
+const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_MAX_PENDING = 256;
+function buildRequestProtocolMessage(type, body) {
+    return {
+        type: proto.Message.ProtocolMessage.Type.PEER_DATA_OPERATION_REQUEST_MESSAGE,
+        peerDataOperationRequestMessage: {
+            ...body,
+            peerDataOperationRequestType: type
+        }
+    };
+}
+export function createPeerDataOperationRequester(options) {
+    const { logger, publishProtocolMessageToDevice, getCurrentCredentials, generateOutgoingMessageId, subscribeToProtocolMessage } = options;
+    const defaultTimeoutMs = options.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxPending = options.maxPending ?? DEFAULT_MAX_PENDING;
+    const pending = new Map();
+    subscribeToProtocolMessage((event) => {
+        const protocolMessage = event.protocolMessage;
+        if (protocolMessage.type !==
+            proto.Message.ProtocolMessage.Type.PEER_DATA_OPERATION_REQUEST_RESPONSE_MESSAGE) {
+            return;
+        }
+        const response = protocolMessage.peerDataOperationRequestResponseMessage;
+        if (!response) {
+            return;
+        }
+        const stanzaId = response.stanzaId;
+        const results = response.peerDataOperationResult ?? [];
+        if (!stanzaId) {
+            logger.debug('pdo response without stanzaId', {
+                from: event.key.remoteJid,
+                resultCount: results.length
+            });
+            return;
+        }
+        const entry = pending.get(stanzaId);
+        if (!entry) {
+            logger.debug('pdo response for unknown stanzaId', {
+                stanzaId,
+                resultCount: results.length
+            });
+            return;
+        }
+        clearTimeout(entry.timeout);
+        pending.delete(stanzaId);
+        entry.resolve(results);
+    });
+    const publish = async (type, body, id) => {
+        const meJid = getCurrentCredentials()?.meJid;
+        if (!meJid) {
+            throw new Error('peer data operation requires current me jid');
+        }
+        const result = await publishProtocolMessageToDevice(toUserJid(meJid), buildRequestProtocolMessage(type, body), { id, pushPriority: 'high_force' });
+        return result.id;
+    };
+    return {
+        request: async (type, body, requestOptions) => {
+            const messageId = await generateOutgoingMessageId();
+            const timeoutMs = requestOptions?.timeoutMs ?? defaultTimeoutMs;
+            return new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => {
+                    if (!pending.delete(messageId)) {
+                        return;
+                    }
+                    logger.debug('pdo request timed out', { messageId, timeoutMs, type });
+                    reject(new Error(`peer data operation timed out after ${timeoutMs}ms (id=${messageId})`));
+                }, timeoutMs);
+                const entry = { resolve, reject, timeout };
+                setBoundedMapEntry(pending, messageId, entry, maxPending, (evictedKey, evicted) => {
+                    clearTimeout(evicted.timeout);
+                    logger.warn('pdo pending entry evicted: capacity reached', {
+                        evictedId: evictedKey,
+                        maxPending
+                    });
+                    evicted.reject(new Error(`peer data operation evicted from pending map (id=${String(evictedKey)})`));
+                });
+                publish(type, body, messageId).catch((error) => {
+                    clearTimeout(timeout);
+                    if (pending.delete(messageId)) {
+                        reject(error instanceof Error ? error : new Error(String(error)));
+                    }
+                });
+            });
+        },
+        send: async (type, body) => {
+            const messageId = await generateOutgoingMessageId();
+            return { messageId: await publish(type, body, messageId) };
+        }
+    };
+}

package/dist/esm/mex.js

@@ -0,0 +1 @@
+export { WA_MEX_PERSIST_IDS, WA_MEX_OPERATION_SCHEMAS } from '../spec/mex';

package/dist/esm/protocol/abprops.js

@@ -28,6 +28,16 @@ export const AB_PROP_CONFIGS = Object.freeze({
     enable_syncd_debug_data_in_patch: prop(6614, 'bool', false),
     enable_mention_everyone_syncd_sender: prop(24244, 'bool', false),
     username_contact_syncd_support_enable: prop(17614, 'bool', false),
+    // --- newsletter ToS / NUX notice ids ---
+    newsletter_tos_notice_id: prop(3810, 'string', '20601216'),
+    newsletter_tos_notice_id_smb_web: prop(5597, 'string', '20601216'),
+    newsletter_creation_tos_id: prop(3834, 'string', '20601217'),
+    newsletter_creation_tos_id_smb_web: prop(5598, 'string', '20601217'),
+    newsletter_admin_invite_tos_id: prop(6498, 'string', '20610101'),
+    newsletter_admin_invite_tos_id_smb_web: prop(6536, 'string', '20610104'),
+    newsletter_creation_nux_id: prop(3835, 'string', '20601218'),
+    newsletter_nux_notice_id: prop(15255, 'string', '20610210'),
+    newsletter_admin_invite_nux_id: prop(15256, 'string', '20610220'),
     // --- message sending / encryption ---
     after_read_sending_enabled: prop(7293, 'bool', false),
     after_read_fallback_duration: prop(7294, 'int', 86400),

package/dist/esm/protocol/appstate.js

@@ -1,3 +1,4 @@
+import { TEXT_ENCODER } from '../util/bytes.js';
 export const WA_APP_STATE_COLLECTIONS = Object.freeze({
     REGULAR: 'regular',
     REGULAR_LOW: 'regular_low',
@@ -17,7 +18,9 @@ export const WA_APP_STATE_COLLECTION_STATES = Object.freeze({
 export const WA_APP_STATE_ERROR_CODES = Object.freeze({
     CONFLICT: '409',
     BAD_REQUEST: '400',
-    NOT_FOUND: '404'
+    NOT_FOUND: '404',
+    NOT_ALLOWED: '405',
+    NOT_ACCEPTABLE: '406'
 });
 export const WA_APP_STATE_SYNC_DATA_TYPE = Object.freeze({
     PATCH: 'Patch',
@@ -29,33 +32,6 @@ export const WA_APP_STATE_KEY_TYPES = Object.freeze({
     MD_MSG_HIST: 'md-msg-hist'
 });
 export const WA_APP_STATE_KDF_INFO = Object.freeze({
-    MUTATION_KEYS: 'WhatsApp Mutation Keys',
-    PATCH_INTEGRITY: 'WhatsApp Patch Integrity'
-});
-export const WA_APP_STATE_CHAT_MUTATION_SPECS = Object.freeze({
-    STAR: { collection: WA_APP_STATE_COLLECTIONS.REGULAR_HIGH, action: 'star', version: 2 },
-    MUTE: { collection: WA_APP_STATE_COLLECTIONS.REGULAR_HIGH, action: 'mute', version: 2 },
-    PIN: { collection: WA_APP_STATE_COLLECTIONS.REGULAR_LOW, action: 'pin_v1', version: 5 },
-    ARCHIVE: { collection: WA_APP_STATE_COLLECTIONS.REGULAR_LOW, action: 'archive', version: 3 },
-    DELETE_MESSAGE_FOR_ME: {
-        collection: WA_APP_STATE_COLLECTIONS.REGULAR_HIGH,
-        action: 'deleteMessageForMe',
-        version: 3
-    },
-    MARK_CHAT_AS_READ: {
-        collection: WA_APP_STATE_COLLECTIONS.REGULAR_LOW,
-        action: 'markChatAsRead',
-        version: 3
-    },
-    CLEAR_CHAT: {
-        collection: WA_APP_STATE_COLLECTIONS.REGULAR_HIGH,
-        action: 'clearChat',
-        version: 6
-    },
-    DELETE_CHAT: {
-        collection: WA_APP_STATE_COLLECTIONS.REGULAR_HIGH,
-        action: 'deleteChat',
-        version: 6
-    },
-    LOCK_CHAT: { collection: WA_APP_STATE_COLLECTIONS.REGULAR_LOW, action: 'lock', version: 7 }
+    MUTATION_KEYS: TEXT_ENCODER.encode('WhatsApp Mutation Keys'),
+    PATCH_INTEGRITY: TEXT_ENCODER.encode('WhatsApp Patch Integrity')
 });

package/dist/esm/protocol/auth.js

@@ -1,3 +1,4 @@
+import { TEXT_ENCODER } from '../util/bytes.js';
 export const WA_SIGNALING = Object.freeze({
     LINK_CODE_STAGE_COMPANION_HELLO: 'companion_hello',
     LINK_CODE_STAGE_GET_COUNTRY_CODE: 'get_country_code',
@@ -7,6 +8,6 @@ export const WA_SIGNALING = Object.freeze({
     COMPANION_REG_REFRESH_NOTIFICATION: 'companion_reg_refresh'
 });
 export const WA_PAIRING_KDF_INFO = Object.freeze({
-    LINK_CODE_BUNDLE: 'link_code_pairing_key_bundle_encryption_key',
-    ADV_SECRET: 'adv_secret'
+    LINK_CODE_BUNDLE: TEXT_ENCODER.encode('link_code_pairing_key_bundle_encryption_key'),
+    ADV_SECRET: TEXT_ENCODER.encode('adv_secret')
 });

package/dist/esm/protocol/bot.js

@@ -0,0 +1,77 @@
+import { proto } from '../proto.js';
+import { WA_DEFAULTS } from './defaults.js';
+import { isBotJid } from './jid.js';
+import { TEXT_ENCODER } from '../util/bytes.js';
+export const WA_BOT_MSG_EDIT_TYPES = Object.freeze({
+    FIRST: 'first',
+    INNER: 'inner',
+    LAST: 'last',
+    FULL: 'full'
+});
+export const WA_BOT_MSG_BODY_TYPES = Object.freeze({
+    PROMPT: 'prompt',
+    COMMAND: 'command',
+    VOICE: 'voice'
+});
+export const WA_BIZ_BOT_TYPES = Object.freeze({
+    ONE_P: '1',
+    THREE_P: '3'
+});
+const META_AI_PN_USER = '13135550002';
+const META_AI_FBID_USER = '867051314767696';
+const META_AI_TEE_FBID_USER = '1273596044787272';
+const META_AI_SIDECHAT_FBID_USER = '867051314767696555';
+const MANUS_FBID_USER = '1807055946647696';
+const HATCH_FBID_USER = '1807055946647697';
+export const WA_BOT_KNOWN_JIDS = Object.freeze({
+    META_AI_PN: `${META_AI_PN_USER}@${WA_DEFAULTS.HOST_DOMAIN}`,
+    META_AI_FBID: `${META_AI_FBID_USER}@${WA_DEFAULTS.BOT_SERVER}`,
+    META_AI_TEE_FBID: `${META_AI_TEE_FBID_USER}@${WA_DEFAULTS.BOT_SERVER}`,
+    META_AI_SIDECHAT_FBID: `${META_AI_SIDECHAT_FBID_USER}@${WA_DEFAULTS.BOT_SERVER}`,
+    MANUS_FBID: `${MANUS_FBID_USER}@${WA_DEFAULTS.BOT_SERVER}`,
+    HATCH_FBID: `${HATCH_FBID_USER}@${WA_DEFAULTS.BOT_SERVER}`
+});
+const PN_TO_FBID_BOT = Object.freeze({
+    [WA_BOT_KNOWN_JIDS.META_AI_PN]: WA_BOT_KNOWN_JIDS.META_AI_FBID
+});
+export function resolveBotFbidJid(jid) {
+    if (isBotJid(jid))
+        return jid;
+    return PN_TO_FBID_BOT[jid] ?? null;
+}
+export const WA_BOT_NODE_ATTRS = Object.freeze({
+    EDIT: 'edit',
+    EDIT_TARGET_ID: 'edit_target_id',
+    SENDER_TIMESTAMP_MS: 'sender_timestamp_ms',
+    BIZ_BOT: 'biz_bot',
+    TYPE: 'type'
+});
+export const WA_META_NODE_ATTRS_BOT = Object.freeze({
+    TARGET_ID: 'target_id',
+    TARGET_SENDER_JID: 'target_sender_jid',
+    TARGET_CHAT_JID: 'target_chat_jid'
+});
+export const WA_BOT_HKDF_INFO = TEXT_ENCODER.encode('Bot Message');
+export const WA_BOT_MSG_SECRET_BYTES = 32;
+// Without a matching Bloks hash, Meta AI silently drops invoke mentions.
+// Bump alongside the Bloks bundle versions shipped by WA Web.
+export const WA_BLOKS_VERSIONING_ID = '98153664e5d904059a94ea08a59fc7eeaf977544cec64ab3ab793c0ce001eb92';
+export const WA_BOT_RENDERING_PIXEL_DENSITY = 2.8125;
+// Default rich-response capability set; bots may reject prompts without one.
+export const WA_BOT_DEFAULT_CAPABILITIES = Object.freeze([
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_HEADING,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_NESTED_LIST,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_TABLE,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_CODE,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_STRUCTURED_RESPONSE,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_SUB_HEADING,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_LATEX,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_INLINE_REELS,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_LATEX_INLINE,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_UNIFIED_RESPONSE,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_SOURCES_IN_MESSAGE,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_UNIFIED_TEXT_COMPONENT,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_UNIFIED_SOURCES,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_UNIFIED_DOMAIN_CITATIONS,
+    proto.BotCapabilityMetadata.BotCapabilityType.RICH_RESPONSE_UR_INLINE_REELS_ENABLED
+]);

package/dist/esm/protocol/browser.js

@@ -38,10 +38,18 @@ const BROWSER_TO_DISPLAY_NAME = {
     [WA_BROWSERS.SAFARI]: 'Safari',
     [WA_BROWSERS.EDGE]: 'Edge'
 };
+/**
+ * Maps a {@link WA_BROWSERS} value to the companion platform id sent in the
+ * pairing `link_code` stanza. Unknown inputs fall back to `OTHER_WEB_CLIENT`.
+ */
 export function getWaCompanionPlatformId(browser) {
     return (BROWSER_TO_PLATFORM_ID[browser.trim().toLowerCase()] ??
         WA_COMPANION_PLATFORM_IDS.OTHER_WEB_CLIENT);
 }
+/**
+ * Returns the human-readable browser name advertised during pairing.
+ * Unknown inputs are echoed back unchanged.
+ */
 export function getWaBrowserDisplayName(browser) {
     return BROWSER_TO_DISPLAY_NAME[browser.trim().toLowerCase()] ?? browser;
 }

package/dist/esm/protocol/business.js

@@ -0,0 +1,19 @@
+export const WA_BUSINESS_HOURS_DAYS = Object.freeze({
+    SUN: 'sun',
+    MON: 'mon',
+    TUE: 'tue',
+    WED: 'wed',
+    THU: 'thu',
+    FRI: 'fri',
+    SAT: 'sat'
+});
+/**
+ * Per-day open mode accepted by the `business_profile` edit IQ. A closed day is
+ * expressed by omitting it from the config entirely, not by a dedicated mode.
+ * `open_time` / `close_time` are only meaningful for `specific_hours`.
+ */
+export const WA_BUSINESS_HOURS_MODES = Object.freeze({
+    OPEN_24H: 'open_24h',
+    SPECIFIC_HOURS: 'specific_hours',
+    APPOINTMENT_ONLY: 'appointment_only'
+});

package/dist/esm/protocol/call.js

@@ -0,0 +1,48 @@
+export const WA_CALL_PAYLOAD_TAGS = Object.freeze({
+    OFFER: 'offer',
+    OFFER_NOTICE: 'offer_notice',
+    ACCEPT: 'accept',
+    PREACCEPT: 'preaccept',
+    REJECT: 'reject',
+    TERMINATE: 'terminate',
+    TRANSPORT: 'transport',
+    MUTE: 'mute',
+    VIDEO_STATE: 'video_state',
+    GROUP_INFO: 'group_info',
+    GROUP_UPDATE: 'group_update',
+    ENC_REKEY: 'enc_rekey',
+    PEER_STATE: 'peer_state',
+    FLOW_CONTROL: 'flow_control',
+    WEB_CLIENT: 'web_client'
+});
+/**
+ * Payload tags that wa-web responds to with a `<receipt>` carrying a typed
+ * child node (`<offer call-id call-creator/>`, etc.) instead of a plain
+ * `<ack class="call"/>`. Source: `WAWebHandleVoipCall.js`.
+ */
+export const WA_CALL_RECEIPT_PAYLOAD_TAGS = new Set([
+    WA_CALL_PAYLOAD_TAGS.OFFER,
+    WA_CALL_PAYLOAD_TAGS.ACCEPT,
+    WA_CALL_PAYLOAD_TAGS.REJECT,
+    WA_CALL_PAYLOAD_TAGS.ENC_REKEY
+]);
+export const WA_CALL_NODE_ATTRS = Object.freeze({
+    CALL_ID: 'call-id',
+    CALL_CREATOR: 'call-creator',
+    GROUP_JID: 'group-jid',
+    CALLER_PN: 'caller_pn',
+    CALLER_COUNTRY_CODE: 'caller_country_code',
+    USERNAME: 'username',
+    NOTIFY: 'notify',
+    SENDER_LID: 'sender_lid',
+    PLATFORM: 'platform',
+    VERSION: 'version',
+    REASON: 'reason',
+    USER_PN: 'user_pn',
+    GUEST_NAME: 'guest_name'
+});
+export const WA_CALL_CHILD_TAGS = Object.freeze({
+    VIDEO: 'video',
+    SILENCE: 'silence',
+    GROUP_INFO: 'group_info'
+});

package/dist/esm/protocol/constants.js

@@ -2,15 +2,21 @@ export { getWaCompanionPlatformId, WA_BROWSERS, WA_COMPANION_PLATFORM_IDS } from
 export { WA_SIGNALING, WA_PAIRING_KDF_INFO } from './auth.js';
 export { WA_CONNECTION_REASONS, WA_DISCONNECT_REASONS, WA_FAILURE_REASONS, WA_LOGOUT_REASONS, WA_READY_STATES, WA_STREAM_SIGNALING } from './stream.js';
 export { WA_IQ_TYPES, WA_NODE_TAGS, WA_XMLNS } from './nodes.js';
+export { WA_CALL_CHILD_TAGS, WA_CALL_NODE_ATTRS, WA_CALL_PAYLOAD_TAGS, WA_CALL_RECEIPT_PAYLOAD_TAGS } from './call.js';
 export { WA_EDIT_ATTRS, WA_ENC_MEDIA_TYPES, WA_EVENT_META_TYPES, WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_POLL_META_TYPES, WA_RETRYABLE_ACK_CODES, WA_STANZA_MSG_TYPES } from './message.js';
-export { WA_APP_STATE_COLLECTIONS, WA_APP_STATE_COLLECTION_STATES, WA_APP_STATE_CHAT_MUTATION_SPECS, WA_APP_STATE_ERROR_CODES, WA_APP_STATE_KDF_INFO, WA_APP_STATE_KEY_TYPES, WA_APP_STATE_SYNC_DATA_TYPE } from './appstate.js';
+export { WA_APP_STATE_COLLECTIONS, WA_APP_STATE_COLLECTION_STATES, WA_APP_STATE_ERROR_CODES, WA_APP_STATE_KDF_INFO, WA_APP_STATE_KEY_TYPES, WA_APP_STATE_SYNC_DATA_TYPE } from './appstate.js';
 export { getWaMediaHkdfInfo, WA_MEDIA_HKDF_INFO, WA_PREVIEW_MEDIA_HKDF_INFO } from './media.js';
 export { WA_ACCOUNT_SYNC_PROTOCOLS, WA_DIRTY_PROTOCOLS, WA_DIRTY_TYPES, WA_SUPPORTED_DIRTY_TYPES } from './dirty.js';
-export { WA_GROUP_NOTIFICATION_TAGS, WA_NOTIFICATION_TYPES, WA_REGISTRATION_NOTIFICATION_TAGS } from './notification.js';
+export { WA_BUSINESS_NOTIFICATION_TAGS, WA_GROUP_NOTIFICATION_TAGS, WA_NEWSLETTER_NOTIFICATION_TAGS, WA_NOTIFICATION_TYPES, WA_REGISTRATION_NOTIFICATION_TAGS } from './notification.js';
+export { WA_BUSINESS_HOURS_DAYS, WA_BUSINESS_HOURS_MODES } from './business.js';
+export { WA_CHATSTATE_MEDIA, WA_PRESENCE_LAST_SENTINELS, WA_PRESENCE_TYPES } from './presence.js';
 export { WA_PRIVACY_TOKEN_NOTIFICATION_TYPE, WA_PRIVACY_TOKEN_TAGS, WA_PRIVACY_TOKEN_TYPES, WA_TC_TOKEN_DEFAULTS } from './privacy-token.js';
 export { WA_PRIVACY_CATEGORIES, WA_PRIVACY_CATEGORY_TO_SETTING, WA_PRIVACY_DISALLOWED_LIST_CATEGORIES, WA_PRIVACY_SETTING_TO_CATEGORY, WA_PRIVACY_TAGS, WA_PRIVACY_VALUES } from './privacy.js';
 export { WA_DEFAULTS } from './defaults.js';
+export { WA_BIZ_BOT_TYPES, WA_BOT_DEFAULT_CAPABILITIES, WA_BOT_HKDF_INFO, WA_BOT_KNOWN_JIDS, WA_BOT_MSG_BODY_TYPES, WA_BOT_MSG_EDIT_TYPES, WA_BOT_MSG_SECRET_BYTES, WA_BOT_NODE_ATTRS, WA_META_NODE_ATTRS_BOT } from './bot.js';
+export { WA_STATUS_DISTRIBUTION_SETTINGS } from './status.js';
 export { WA_EMAIL_CONTEXTS, WA_EMAIL_ERROR_CODES, WA_EMAIL_LIMITS, WA_EMAIL_TAGS, WA_EMAIL_XMLNS } from './email.js';
 export { AB_PROP_CONFIGS, resolveAbPropNameByCode, WA_ABPROPS_PROTOCOL_VERSION, WA_ABPROPS_REFRESH_BOUNDS } from './abprops.js';
 export { WA_GROUP_PARTICIPANT_TYPES } from './group.js';
 export { WA_USYNC_CONTEXTS, WA_USYNC_DEFAULTS, WA_USYNC_MODES } from './usync.js';
+export { WA_NEWSLETTER_FETCH_KEY_TYPES, WA_NEWSLETTER_MUTE_TYPES, WA_NEWSLETTER_MUTE_VALUES, WA_NEWSLETTER_PICTURE_TYPES, WA_NEWSLETTER_RECEIVE_TYPES, WA_NEWSLETTER_ROLES, WA_NEWSLETTER_SEND_TYPES, WA_NEWSLETTER_STATE_TYPES, WA_NEWSLETTER_VERIFICATION_STATES, WA_NEWSLETTER_VIEW_ROLES } from './newsletter.js';

package/dist/esm/protocol/defaults.js

@@ -9,6 +9,9 @@ export const WA_DEFAULTS = Object.freeze({
     HOSTED_DEVICE_ID: 99,
     MSGR_SERVER: 'msgr',
     INTEROP_SERVER: 'interop',
+    NEWSLETTER_SERVER: 'newsletter',
+    BOT_SERVER: 'bot',
+    STATUS_BROADCAST_JID: 'status@broadcast',
     DEVICE_BROWSER: WA_BROWSERS.FIREFOX,
     DEVICE_PLATFORM: getWaCompanionPlatformId(WA_BROWSERS.FIREFOX),
     CHAT_SOCKET_URLS: ['wss://web.whatsapp.com/ws/chat', 'wss://web.whatsapp.com:5222/ws/chat'],

package/dist/esm/protocol/index.js

@@ -1,2 +1,2 @@
 export * from './constants.js';
-export { buildDeviceJid, canonicalizeSignalJid, canonicalizeSignalServer, getLoginIdentity, isHostedDeviceId, isHostedDeviceJid, isHostedServer, isGroupJid, normalizeDeviceJid, normalizeRecipientJid, parsePhoneJid, parseSignalAddressFromJid, splitJid, signalAddressKey, toUserJid } from './jid.js';
+export { applyDeviceToJid, buildDeviceJid, canonicalizeSignalJid, canonicalizeSignalServer, getLoginIdentity, isBotJid, isBroadcastJid, isGroupJid, isGroupOrBroadcastJid, isHostedDeviceId, isHostedDeviceJid, isHostedServer, isLidJid, isNewsletterJid, isStatusBroadcastJid, isUserJid, normalizeDeviceJid, normalizeRecipientJid, parseJidFull, parsePhoneJid, parseSignalAddressFromJid, signalAddressKey, splitJid, toUserJid } from './jid.js';

package/dist/esm/protocol/jid.js

@@ -7,7 +7,9 @@ const KNOWN_SERVERS = {
     [WA_DEFAULTS.HOSTED_SERVER]: WA_DEFAULTS.HOSTED_SERVER,
     [WA_DEFAULTS.HOSTED_LID_SERVER]: WA_DEFAULTS.HOSTED_LID_SERVER,
     [WA_DEFAULTS.MSGR_SERVER]: WA_DEFAULTS.MSGR_SERVER,
-    [WA_DEFAULTS.INTEROP_SERVER]: WA_DEFAULTS.INTEROP_SERVER
+    [WA_DEFAULTS.INTEROP_SERVER]: WA_DEFAULTS.INTEROP_SERVER,
+    [WA_DEFAULTS.NEWSLETTER_SERVER]: WA_DEFAULTS.NEWSLETTER_SERVER,
+    [WA_DEFAULTS.BOT_SERVER]: WA_DEFAULTS.BOT_SERVER
 };
 /**
  * Returns the canonical reference for known server strings, avoiding
@@ -32,10 +34,20 @@ function findAtIndex(jid) {
         throw new Error(`invalid jid: ${jid}`);
     return atIndex;
 }
+/**
+ * Splits a JID into `user` and `server` parts at the `@` separator.
+ * Throws if the input does not contain a valid `user@server` shape.
+ */
 export function splitJid(jid) {
     const atIndex = findAtIndex(jid);
     return { user: jid.slice(0, atIndex), server: internServer(jid.slice(atIndex + 1)) };
 }
+/**
+ * Normalizes a user-supplied recipient (phone number, group id, or full JID)
+ * into a canonical JID. Strings already containing `@` are returned as-is;
+ * dashed inputs map to `<input>@g.us` (group); pure-digit inputs map to
+ * `<digits>@s.whatsapp.net`.
+ */
 export function normalizeRecipientJid(to) {
     const input = to.trim();
     if (input.length === 0)
@@ -58,23 +70,51 @@ export function normalizeRecipientJid(to) {
 }
 function isJidType(jid, type) {
     const atIndex = jid.length - type.length - 1;
-    return (atIndex >= 1 &&
-        jid.charCodeAt(atIndex) === 64 &&
-        jid.indexOf('@') === atIndex &&
-        jid.endsWith(type));
+    if (atIndex < 1 || jid.charCodeAt(atIndex) !== 64 || !jid.endsWith(type))
+        return false;
+    // Reject multi-@ JIDs (consistency with splitJid). Manual loop beats indexOf.
+    for (let i = 0; i < atIndex; i += 1) {
+        if (jid.charCodeAt(i) === 64)
+            return false;
+    }
+    return true;
 }
+/** Returns `true` for JIDs in the `@lid` server (linked-device identity). */
 export function isLidJid(jid) {
     return isJidType(jid, WA_DEFAULTS.LID_SERVER);
 }
+/** Returns `true` for JIDs in the `@s.whatsapp.net` server (phone-number user JIDs). */
+export function isUserJid(jid) {
+    return isJidType(jid, WA_DEFAULTS.HOST_DOMAIN);
+}
+/** Returns `true` for JIDs in the `@bot` server. */
+export function isBotJid(jid) {
+    return isJidType(jid, WA_DEFAULTS.BOT_SERVER);
+}
+/** Returns `true` for JIDs in the `@g.us` server (groups). */
 export function isGroupJid(jid) {
     return isJidType(jid, WA_DEFAULTS.GROUP_SERVER);
 }
+/** Returns `true` for JIDs in the `@broadcast` server (broadcast lists). */
 export function isBroadcastJid(jid) {
     return isJidType(jid, WA_DEFAULTS.BROADCAST_SERVER);
 }
+/** Returns `true` for the special `status@broadcast` JID. */
+export function isStatusBroadcastJid(jid) {
+    return jid === WA_DEFAULTS.STATUS_BROADCAST_JID;
+}
+/** Returns `true` for JIDs in the `@newsletter` server. */
+export function isNewsletterJid(jid) {
+    return isJidType(jid, WA_DEFAULTS.NEWSLETTER_SERVER);
+}
+/** Returns `true` for any group or broadcast JID. */
 export function isGroupOrBroadcastJid(jid) {
     return isGroupJid(jid) || isBroadcastJid(jid);
 }
+/**
+ * Parses a JID into a Signal-style `{ user, server, device }` address.
+ * `device` is `0` when the JID has no `:device` segment.
+ */
 export function parseSignalAddressFromJid(jid) {
     const atIndex = findAtIndex(jid);
     const colonIndex = jid.indexOf(':', 0);
@@ -95,12 +135,21 @@ export function parseSignalAddressFromJid(jid) {
     }
     return { user: jid.slice(0, colonIndex), server, device };
 }
+/**
+ * Parses a JID and returns the Signal address plus the user-only and
+ * fully-normalized device JID forms in a single pass.
+ */
 export function parseJidFull(jid) {
     const address = parseSignalAddressFromJid(jid);
     const userJid = `${address.user}@${address.server}`;
     const normalizedJid = address.device === 0 ? userJid : `${address.user}:${address.device}@${address.server}`;
     return { address, userJid, normalizedJid };
 }
+/**
+ * Maps the hosted-account server variants (`hosted` / `hosted.lid`) back to
+ * their canonical Signal server (`hostDomain` / `lid`). Other servers are
+ * returned unchanged.
+ */
 export function canonicalizeSignalServer(server, hostDomain = WA_DEFAULTS.HOST_DOMAIN) {
     if (server === WA_DEFAULTS.HOSTED_SERVER)
         return hostDomain;
@@ -108,6 +157,11 @@ export function canonicalizeSignalServer(server, hostDomain = WA_DEFAULTS.HOST_D
         return WA_DEFAULTS.LID_SERVER;
     return server;
 }
+/**
+ * Returns the JID rewritten with its server canonicalized via
+ * {@link canonicalizeSignalServer} – used to derive the address Signal
+ * sessions are keyed by.
+ */
 export function canonicalizeSignalJid(jid, hostDomain = WA_DEFAULTS.HOST_DOMAIN) {
     const address = parseSignalAddressFromJid(jid);
     const server = canonicalizeSignalServer(address.server ?? WA_DEFAULTS.HOST_DOMAIN, hostDomain);
@@ -115,6 +169,11 @@ export function canonicalizeSignalJid(jid, hostDomain = WA_DEFAULTS.HOST_DOMAIN)
         return `${address.user}@${server}`;
     return `${address.user}:${address.device}@${server}`;
 }
+/**
+ * Strips the `:device` segment from a JID, returning the bare `user@server`
+ * form. Set `options.canonicalizeSignalServer` to also rewrite hosted servers
+ * via {@link canonicalizeSignalServer}.
+ */
 export function toUserJid(jid, options = {}) {
     const canonicalize = options.canonicalizeSignalServer === true;
     if (!canonicalize) {
@@ -132,18 +191,38 @@ export function toUserJid(jid, options = {}) {
         : address.server;
     return `${address.user}@${server}`;
 }
+/**
+ * Returns the JID in its full device form. JIDs with `device === 0` lose the
+ * device segment (`user@server`); all others keep `user:device@server`.
+ */
 export function normalizeDeviceJid(jid) {
     const address = parseSignalAddressFromJid(jid);
     if (address.device === 0)
         return `${address.user}@${address.server}`;
     return `${address.user}:${address.device}@${address.server}`;
 }
+/**
+ * Appends `:device` to a bare user JID. A falsy `device` returns the input
+ * unchanged.
+ */
+export function applyDeviceToJid(userJid, device) {
+    if (!device)
+        return userJid;
+    const address = parseSignalAddressFromJid(userJid);
+    return buildDeviceJid(address.user, address.server ?? WA_DEFAULTS.HOST_DOMAIN, device);
+}
+/** Returns `true` when `deviceId` matches the WhatsApp hosted-device id. */
 export function isHostedDeviceId(deviceId) {
     return deviceId === WA_DEFAULTS.HOSTED_DEVICE_ID;
 }
+/** Returns `true` for the hosted server variants (`hosted` and `hosted.lid`). */
 export function isHostedServer(server) {
     return server === WA_DEFAULTS.HOSTED_SERVER || server === WA_DEFAULTS.HOSTED_LID_SERVER;
 }
+/**
+ * Returns `true` when the JID refers to a hosted device – either by server
+ * (`@hosted` / `@hosted.lid`) or by a `:HOSTED_DEVICE_ID@…` device segment.
+ */
 export function isHostedDeviceJid(jid) {
     if (isJidType(jid, WA_DEFAULTS.HOSTED_SERVER) ||
         isJidType(jid, WA_DEFAULTS.HOSTED_LID_SERVER)) {
@@ -166,6 +245,11 @@ export function isHostedDeviceJid(jid) {
     }
     return isHostedDeviceId(deviceId);
 }
+/**
+ * Builds a device JID from its parts. When `options.isHosted` is set, the
+ * hosted-server variant is selected (preserving LID vs phone) and the canonical
+ * hosted device id is used.
+ */
 export function buildDeviceJid(user, normalizedServer, deviceId, options = {}) {
     if (options.isHosted === true) {
         if (!isHostedDeviceId(deviceId)) {
@@ -182,6 +266,11 @@ export function buildDeviceJid(user, normalizedServer, deviceId, options = {}) {
     }
     return `${user}:${deviceId}@${normalizedServer}`;
 }
+/**
+ * Extracts the numeric username and device id from the authenticated user's
+ * own JID. Throws when either segment is missing, non-numeric, or out of the
+ * safe-integer range.
+ */
 export function getLoginIdentity(meJid) {
     const atIndex = findAtIndex(meJid);
     const colonIndex = meJid.indexOf(':', 0);
@@ -197,12 +286,20 @@ export function getLoginIdentity(meJid) {
         throw new Error(`invalid device from ${meJid}`);
     return { username, device };
 }
+/**
+ * Builds a `<digits>@s.whatsapp.net` JID from a free-form phone number,
+ * stripping non-digit characters. Throws when no digits are found.
+ */
 export function parsePhoneJid(input) {
     const digits = extractDigits(input);
     if (!digits)
         throw new Error('phone number is empty after normalization');
     return `${digits}@${WA_DEFAULTS.HOST_DOMAIN}`;
 }
+/**
+ * Returns a stable `user|server|device` key for a Signal address, suitable
+ * as a Map/Set key.
+ */
 export function signalAddressKey(address) {
     const server = address.server ?? WA_DEFAULTS.HOST_DOMAIN;
     return `${address.user}|${server}|${address.device}`;

package/dist/esm/protocol/media.js

@@ -1,17 +1,30 @@
+import { TEXT_ENCODER } from '../util/bytes.js';
+const IMAGE_KEYS = TEXT_ENCODER.encode('WhatsApp Image Keys');
+const VIDEO_KEYS = TEXT_ENCODER.encode('WhatsApp Video Keys');
+const AUDIO_KEYS = TEXT_ENCODER.encode('WhatsApp Audio Keys');
+const HISTORY_KEYS = TEXT_ENCODER.encode('WhatsApp History Keys');
 export const WA_MEDIA_HKDF_INFO = Object.freeze({
-    document: 'WhatsApp Document Keys',
-    image: 'WhatsApp Image Keys',
-    sticker: 'WhatsApp Image Keys',
-    'xma-image': 'WhatsApp Image Keys',
-    video: 'WhatsApp Video Keys',
-    gif: 'WhatsApp Video Keys',
-    audio: 'WhatsApp Audio Keys',
-    ptt: 'WhatsApp Audio Keys',
-    'md-app-state': 'WhatsApp App State Keys',
-    'md-msg-hist': 'WhatsApp History Keys',
-    history: 'WhatsApp History Keys'
+    document: TEXT_ENCODER.encode('WhatsApp Document Keys'),
+    image: IMAGE_KEYS,
+    sticker: IMAGE_KEYS,
+    'xma-image': IMAGE_KEYS,
+    video: VIDEO_KEYS,
+    gif: VIDEO_KEYS,
+    audio: AUDIO_KEYS,
+    ptt: AUDIO_KEYS,
+    'md-app-state': TEXT_ENCODER.encode('WhatsApp App State Keys'),
+    'md-msg-hist': HISTORY_KEYS,
+    history: HISTORY_KEYS,
+    'sticker-pack': TEXT_ENCODER.encode('WhatsApp Sticker Pack Keys'),
+    'thumbnail-sticker-pack': TEXT_ENCODER.encode('WhatsApp Sticker Pack Thumbnail Keys'),
+    'thumbnail-link': TEXT_ENCODER.encode('WhatsApp Link Thumbnail Keys')
 });
-export const WA_PREVIEW_MEDIA_HKDF_INFO = 'Messenger Preview Keys';
+export const WA_PREVIEW_MEDIA_HKDF_INFO = TEXT_ENCODER.encode('Messenger Preview Keys');
+/**
+ * Returns the HKDF `info` bytes used to derive per-media keys for a given
+ * media type. Throws for unsupported types – see {@link WA_MEDIA_HKDF_INFO}
+ * for the supported set.
+ */
 export function getWaMediaHkdfInfo(mediaType) {
     const info = WA_MEDIA_HKDF_INFO[mediaType];
     if (info !== undefined)