zapo-js 0.2.0 → 1.0.0

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,17 +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.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);
@@ -76,17 +122,34 @@ export function parseSignalAddressFromJid(jid) {
     if (colonIndex === -1 || colonIndex > atIndex) {
         return { user: jid.slice(0, atIndex), server, device: 0 };
     }
-    const device = Number.parseInt(jid.slice(colonIndex + 1, atIndex), 10);
-    if (!Number.isFinite(device) || device < 0)
+    if (colonIndex >= atIndex - 1)
         throw new Error(`invalid jid device: ${jid}`);
+    let device = 0;
+    for (let i = colonIndex + 1; i < atIndex; i += 1) {
+        const digit = jid.charCodeAt(i) - 48;
+        if (digit < 0 || digit > 9)
+            throw new Error(`invalid jid device: ${jid}`);
+        device = device * 10 + digit;
+        if (device > Number.MAX_SAFE_INTEGER)
+            throw new Error(`invalid jid device: ${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;
@@ -94,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);
@@ -101,37 +169,87 @@ 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) {
+        const atIndex = jid.indexOf('@');
+        if (atIndex >= 1 && atIndex < jid.length - 1) {
+            const colonIndex = jid.indexOf(':', 0);
+            if (colonIndex === -1 || colonIndex > atIndex) {
+                return jid;
+            }
+        }
+    }
     const address = parseSignalAddressFromJid(jid);
-    const server = options.canonicalizeSignalServer === true
+    const server = canonicalize
         ? canonicalizeSignalServer(address.server ?? WA_DEFAULTS.HOST_DOMAIN, options.hostDomain ?? WA_DEFAULTS.HOST_DOMAIN)
         : 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) {
-    const { user, server } = splitJid(jid);
-    if (isHostedServer(server)) {
+    if (isJidType(jid, WA_DEFAULTS.HOSTED_SERVER) ||
+        isJidType(jid, WA_DEFAULTS.HOSTED_LID_SERVER)) {
         return true;
     }
-    const colonIndex = user.indexOf(':');
-    if (colonIndex < 0) {
+    const atIndex = jid.indexOf('@');
+    if (atIndex < 1 || atIndex >= jid.length - 1)
+        return false;
+    const colonIndex = jid.indexOf(':');
+    if (colonIndex < 0 || colonIndex >= atIndex - 1)
         return false;
+    let deviceId = 0;
+    for (let i = colonIndex + 1; i < atIndex; i += 1) {
+        const digit = jid.charCodeAt(i) - 48;
+        if (digit < 0 || digit > 9)
+            return false;
+        deviceId = deviceId * 10 + digit;
+        if (deviceId > Number.MAX_SAFE_INTEGER)
+            return false;
     }
-    const deviceId = Number.parseInt(user.slice(colonIndex + 1), 10);
-    return Number.isSafeInteger(deviceId) && isHostedDeviceId(deviceId);
+    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)) {
@@ -148,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);
@@ -163,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)

package/dist/esm/protocol/message.js

@@ -11,6 +11,7 @@ export const WA_MESSAGE_TYPES = Object.freeze({
     ACK_TYPE_ERROR: 'error',
     ACK_CLASS_ERROR: 'error',
     ACK_CLASS_MESSAGE: 'message',
+    ACK_CLASS_CALL: 'call',
     RECEIPT_TYPE_DELIVERY: 'delivery',
     RECEIPT_TYPE_SENDER: 'sender',
     RECEIPT_TYPE_INACTIVE: 'inactive',
@@ -21,7 +22,8 @@ export const WA_MESSAGE_TYPES = Object.freeze({
     RECEIPT_TYPE_HISTORY_SYNC: 'hist_sync',
     RECEIPT_TYPE_PEER: 'peer_msg',
     RECEIPT_TYPE_SERVER_ERROR: 'server-error',
-    RECEIPT_TYPE_RETRY: 'retry'
+    RECEIPT_TYPE_RETRY: 'retry',
+    RECEIPT_TYPE_ENC_REKEY_RETRY: 'enc_rekey_retry'
 });
 export const WA_RETRYABLE_ACK_CODES = Object.freeze(['408', '429', '500', '503']);
 export const WA_STANZA_MSG_TYPES = Object.freeze({
@@ -36,6 +38,7 @@ export const WA_STANZA_MSG_TYPES = Object.freeze({
 export const WA_EDIT_ATTRS = Object.freeze({
     MESSAGE_EDIT: '1',
     PIN_IN_CHAT: '2',
+    NEWSLETTER_EDIT: '3',
     SENDER_REVOKE: '7',
     ADMIN_REVOKE: '8'
 });

package/dist/esm/protocol/newsletter.js

@@ -0,0 +1,61 @@
+export const WA_NEWSLETTER_ROLES = Object.freeze({
+    SUBSCRIBER: 'SUBSCRIBER',
+    GUEST: 'GUEST',
+    ADMIN: 'ADMIN',
+    OWNER: 'OWNER'
+});
+export const WA_NEWSLETTER_STATE_TYPES = Object.freeze({
+    ACTIVE: 'ACTIVE',
+    SUSPENDED: 'SUSPENDED',
+    GEOSUSPENDED: 'GEOSUSPENDED',
+    DELETED: 'DELETED',
+    NON_EXISTING: 'NON_EXISTING'
+});
+export const WA_NEWSLETTER_PICTURE_TYPES = Object.freeze({
+    IMAGE: 'IMAGE',
+    PREVIEW: 'PREVIEW'
+});
+export const WA_NEWSLETTER_FETCH_KEY_TYPES = Object.freeze({
+    JID: 'JID',
+    INVITE: 'INVITE'
+});
+export const WA_NEWSLETTER_VIEW_ROLES = Object.freeze({
+    GUEST: 'GUEST',
+    SUBSCRIBER: 'SUBSCRIBER',
+    ADMIN: 'ADMIN',
+    OWNER: 'OWNER'
+});
+export const WA_NEWSLETTER_MUTE_TYPES = Object.freeze({
+    ADMIN_ACTIVITY: 'MUTE_ADMIN_ACTIVITY',
+    FOLLOWER_ACTIVITY: 'MUTE_FOLLOWER_ACTIVITY'
+});
+export const WA_NEWSLETTER_MUTE_VALUES = Object.freeze({
+    ON: 'ON',
+    OFF: 'OFF'
+});
+export const WA_NEWSLETTER_SEND_TYPES = Object.freeze({
+    TEXT: 'text',
+    MEDIA: 'media',
+    REACTION: 'reaction',
+    REVOKE: 'revoke'
+});
+export const WA_NEWSLETTER_RECEIVE_TYPES = Object.freeze({
+    TEXT: 'NewsletterText',
+    MEDIA: 'NewsletterMedia',
+    REACTION: 'NewsletterReaction',
+    REACTION_REVOKE: 'NewsletterReactionRevoke',
+    REVOKE: 'NewsletterRevoke',
+    EDIT: 'NewsletterEdit',
+    POLL_CREATION: 'NewsletterPollCreation',
+    POLL_VOTE: 'NewsletterPollVote',
+    POLL_RESULT_SNAPSHOT: 'NewsletterPollResultSnapshot',
+    QUIZ_CREATION: 'NewsletterQuizCreation',
+    QUESTION: 'NewsletterQuestion',
+    QUESTION_REPLY: 'NewsletterQuestionReply',
+    QUESTION_RESPONSE: 'NewsletterQuestionResponse',
+    WAMO_EMPTY: 'NewsletterWAMOEmpty'
+});
+export const WA_NEWSLETTER_VERIFICATION_STATES = Object.freeze({
+    VERIFIED: 'VERIFIED',
+    UNVERIFIED: 'UNVERIFIED'
+});

package/dist/esm/protocol/nodes.js

@@ -32,6 +32,7 @@ export const WA_NODE_TAGS = Object.freeze({
     DESCRIPTION: 'description',
     MY_ADDONS: 'my_addons',
     KEY: 'key',
+    OP: 'op',
     REGISTRATION: 'registration',
     TYPE: 'type',
     IDENTITY: 'identity',
@@ -60,7 +61,24 @@ export const WA_NODE_TAGS = Object.freeze({
     ANNOUNCEMENT: 'announcement',
     EPHEMERAL: 'ephemeral',
     MEMBERSHIP_APPROVAL_MODE: 'membership_approval_mode',
-    GROUP_JOIN: 'group_join'
+    GROUP_JOIN: 'group_join',
+    ABPROPS: 'abprops',
+    PLAINTEXT: 'plaintext',
+    PRESENCE: 'presence',
+    CHATSTATE: 'chatstate',
+    CALL: 'call',
+    COMPOSING: 'composing',
+    PAUSED: 'paused',
+    BIZ: 'biz',
+    INTERACTIVE: 'interactive',
+    NATIVE_FLOW: 'native_flow',
+    BOT: 'bot',
+    META: 'meta',
+    STATUS: 'status',
+    USERNAME: 'username',
+    TEXT_STATUS: 'text_status',
+    DISAPPEARING_MODE: 'disappearing_mode',
+    BUSINESS: 'business'
 });
 export const WA_IQ_TYPES = Object.freeze({
     GET: 'get',
@@ -82,6 +100,12 @@ export const WA_XMLNS = Object.freeze({
     STATUS: 'status',
     GROUPS: 'w:g2',
     NEWSLETTER: 'newsletter',
+    TOS: 'tos',
     XMPP_PING: 'urn:xmpp:ping',
-    WHATSAPP_PING: 'w:p'
+    WHATSAPP_PING: 'w:p',
+    ABPROPS: 'abt',
+    MEX: 'w:mex',
+    BOT: 'bot',
+    DISAPPEARING_MODE: 'disappearing_mode',
+    PASSIVE: 'passive'
 });

package/dist/esm/protocol/notification.js

@@ -1,7 +1,27 @@
 export const WA_NOTIFICATION_TYPES = Object.freeze({
     GROUP: 'w:gp2',
     ENCRYPT: 'encrypt',
-    DEVICES: 'devices'
+    DEVICES: 'devices',
+    SERVER: 'server',
+    REGISTRATION: 'registration',
+    NEWSLETTER: 'newsletter',
+    BUSINESS: 'business',
+    PICTURE: 'picture'
+});
+export const WA_BUSINESS_NOTIFICATION_TAGS = Object.freeze({
+    VERIFIED_NAME: 'verified_name',
+    REMOVE: 'remove',
+    PROFILE: 'profile',
+    PRODUCT_CATALOG: 'product_catalog',
+    SUBSCRIPTIONS: 'subscriptions',
+    FEATURE_FLAGS: 'feature_flags'
+});
+export const WA_NEWSLETTER_NOTIFICATION_TAGS = Object.freeze({
+    LIVE_UPDATES: 'live_updates'
+});
+export const WA_REGISTRATION_NOTIFICATION_TAGS = Object.freeze({
+    WA_OLD_REGISTRATION: 'wa_old_registration',
+    DEVICE_LOGOUT: 'device_logout'
 });
 export const WA_GROUP_NOTIFICATION_TAGS = Object.freeze({
     REMOVE: 'remove',
@@ -48,5 +68,7 @@ export const WA_GROUP_NOTIFICATION_TAGS = Object.freeze({
     IS_CAPI_HOSTED_GROUP: 'is_capi_hosted_group',
     GROUP_SAFETY_CHECK: 'group_safety_check',
     LIMIT_SHARING_ENABLED: 'limit_sharing_enabled',
-    MISSING_PARTICIPANT_IDENTIFICATION: 'missing_participant_identification'
+    MISSING_PARTICIPANT_IDENTIFICATION: 'missing_participant_identification',
+    GROUP_HISTORY: 'group_history',
+    NO_GROUP_HISTORY: 'no_group_history'
 });

package/dist/esm/protocol/presence.js

@@ -0,0 +1,13 @@
+export const WA_PRESENCE_TYPES = Object.freeze({
+    AVAILABLE: 'available',
+    UNAVAILABLE: 'unavailable',
+    SUBSCRIBE: 'subscribe'
+});
+export const WA_PRESENCE_LAST_SENTINELS = Object.freeze({
+    DENY: 'deny',
+    NONE: 'none',
+    ERROR: 'error'
+});
+export const WA_CHATSTATE_MEDIA = Object.freeze({
+    AUDIO: 'audio'
+});

package/dist/esm/protocol/status.js

@@ -0,0 +1,6 @@
+export const WA_STATUS_DISTRIBUTION_SETTINGS = Object.freeze({
+    CONTACTS: 'contacts',
+    ALLOWLIST: 'allowlist',
+    DENYLIST: 'denylist',
+    CLOSE_FRIENDS: 'close_friends'
+});

package/dist/esm/retry/codec.js

@@ -16,6 +16,10 @@ const RETRY_PAYLOAD_ENC_TYPE_REVERSE = Object.freeze({
     2: 'pkmsg',
     3: 'skmsg'
 });
+/**
+ * Encodes a {@link WaRetryReplayPayload} into the on-disk codec format used
+ * by the retry store. Supports the `plaintext`/`encrypted`/`opaque_node` modes.
+ */
 export function encodeRetryReplayPayload(payload) {
     const chunks = [];
     if (payload.mode === 'plaintext') {
@@ -56,6 +60,7 @@ export function encodeRetryReplayPayload(payload) {
     pushBytesField(chunks, payload.node, 'node');
     return concatBytes(chunks);
 }
+/** Inverse of {@link encodeRetryReplayPayload}. Throws on bad magic/version. */
 export function decodeRetryReplayPayload(raw) {
     if (raw.byteLength < 3) {
         throw new Error('invalid retry replay payload: unsupported codec version');

package/dist/esm/retry/parse.js

@@ -1,8 +1,8 @@
-import { WA_MESSAGE_TAGS, WA_NODE_TAGS } from '../protocol/constants.js';
+import { WA_MESSAGE_TAGS, WA_MESSAGE_TYPES, WA_NODE_TAGS } from '../protocol/constants.js';
 import { normalizeDeviceJid } from '../protocol/jid.js';
-import { decodeExactLength, parseUint } from '../signal/api/codec.js';
-import { SIGNAL_KEY_DATA_LENGTH, SIGNAL_KEY_ID_LENGTH, SIGNAL_REGISTRATION_ID_LENGTH, SIGNAL_SIGNATURE_LENGTH } from '../signal/api/constants.js';
-import { decodeNodeContentBase64OrBytes, findNodeChildrenByTags } from '../transport/node/helpers.js';
+import { decodeExactLength, parseSignalKeyBundleFromNode, parseUint } from '../signal/api/codec.js';
+import { SIGNAL_REGISTRATION_ID_LENGTH } from '../signal/api/constants.js';
+import { findNodeChildrenByTags } from '../transport/node/helpers.js';
 import { parseOptionalInt } from '../util/primitives.js';
 const RETRY_STATE_RANK = {
     pending: 0,
@@ -47,47 +47,25 @@ function parseRetryKeyBundle(node) {
     if (!node) {
         return undefined;
     }
-    const [identityNode, signedKeyNode, keyNode, deviceIdentityNode] = findNodeChildrenByTags(node, [WA_NODE_TAGS.IDENTITY, WA_NODE_TAGS.SKEY, WA_NODE_TAGS.KEY, WA_NODE_TAGS.DEVICE_IDENTITY]);
-    const identity = requireNode(identityNode, 'retry keys section missing identity or skey');
-    const signedKey = requireNode(signedKeyNode, 'retry keys section missing identity or skey');
-    const [signedKeyIdNode, signedKeyValueNode, signedKeySignatureNode] = findNodeChildrenByTags(signedKey, [WA_NODE_TAGS.ID, WA_NODE_TAGS.VALUE, WA_NODE_TAGS.SIGNATURE]);
-    const signedKeyId = requireNode(signedKeyIdNode, 'retry keys section has incomplete skey');
-    const signedKeyValue = requireNode(signedKeyValueNode, 'retry keys section has incomplete skey');
-    const signedKeySignature = requireNode(signedKeySignatureNode, 'retry keys section has incomplete skey');
-    let keyIdNode;
-    let keyValueNode;
-    if (keyNode) {
-        const keyNodes = findNodeChildrenByTags(keyNode, [WA_NODE_TAGS.ID, WA_NODE_TAGS.VALUE]);
-        keyIdNode = keyNodes[0];
-        keyValueNode = keyNodes[1];
-    }
-    const keyId = keyNode ? requireNode(keyIdNode, 'retry keys section has incomplete key') : null;
-    const keyValue = keyNode
-        ? requireNode(keyValueNode, 'retry keys section has incomplete key')
-        : null;
+    const parsed = parseSignalKeyBundleFromNode(node, 'retry.keys');
     return {
-        identity: decodeExactLength(identity.content, 'retry.keys.identity', SIGNAL_KEY_DATA_LENGTH),
-        deviceIdentity: deviceIdentityNode
-            ? decodeNodeContentBase64OrBytes(deviceIdentityNode.content, 'retry.keys.device-identity')
-            : undefined,
-        key: keyId && keyValue
-            ? {
-                id: parseUint(decodeExactLength(keyId.content, 'retry.keys.key.id', SIGNAL_KEY_ID_LENGTH), 'retry.keys.key.id'),
-                publicKey: decodeExactLength(keyValue.content, 'retry.keys.key.value', SIGNAL_KEY_DATA_LENGTH)
-            }
-            : undefined,
-        skey: {
-            id: parseUint(decodeExactLength(signedKeyId.content, 'retry.keys.skey.id', SIGNAL_KEY_ID_LENGTH), 'retry.keys.skey.id'),
-            publicKey: decodeExactLength(signedKeyValue.content, 'retry.keys.skey.value', SIGNAL_KEY_DATA_LENGTH),
-            signature: decodeExactLength(signedKeySignature.content, 'retry.keys.skey.signature', SIGNAL_SIGNATURE_LENGTH)
-        }
+        identity: parsed.identity,
+        ...(parsed.deviceIdentity ? { deviceIdentity: parsed.deviceIdentity } : {}),
+        ...(parsed.oneTimeKey ? { key: parsed.oneTimeKey } : {}),
+        skey: parsed.signedKey
     };
 }
+/**
+ * Parses an incoming `receipt` stanza into a {@link WaParsedRetryRequest}.
+ * Returns `null` when the stanza is not a retry/rekey-retry receipt; throws
+ * when required attrs/children are missing.
+ */
 export function parseRetryReceiptRequest(node, options) {
     if (node.tag !== WA_MESSAGE_TAGS.RECEIPT) {
         return null;
     }
-    const receiptType = node.attrs.type === 'retry' || node.attrs.type === 'enc_rekey_retry'
+    const receiptType = node.attrs.type === WA_MESSAGE_TYPES.RECEIPT_TYPE_RETRY ||
+        node.attrs.type === WA_MESSAGE_TYPES.RECEIPT_TYPE_ENC_REKEY_RETRY
         ? node.attrs.type
         : null;
     if (!receiptType) {
@@ -127,6 +105,10 @@ export function parseRetryReceiptRequest(node, options) {
         keyBundle: parseRetryKeyBundle(keysNode)
     };
 }
+/**
+ * Returns whichever of `left`/`right` represents the more advanced retry
+ * state (according to the internal precedence rank).
+ */
 export function pickRetryStateMax(left, right) {
     return RETRY_STATE_RANK[left] >= RETRY_STATE_RANK[right] ? left : right;
 }

package/dist/esm/retry/reason.js

@@ -37,6 +37,11 @@ const RETRY_REASON_MATCHERS = [
         code: RETRY_REASON.StatusRevokeDelay
     }
 ];
+/**
+ * Maps a decryption/Signal error to the appropriate {@link WaRetryReasonCode}
+ * so an outbound retry receipt carries the correct `error` attribute.
+ * Returns `undefined` when no known reason matches.
+ */
 export function mapRetryReasonFromError(error) {
     const message = toError(error).message.toLowerCase();
     for (const matcher of RETRY_REASON_MATCHERS) {
@@ -46,5 +51,5 @@ export function mapRetryReasonFromError(error) {
             return matcher.code;
         }
     }
-    return RETRY_REASON.UnknownError;
+    return undefined;
 }