zapo-js 1.8.1 → 1.9.0

package/dist/auth/credentials-flow.js

@@ -113,9 +113,7 @@ async function buildCommsConfig(logger, credentials, socketOptions, clientOption
         assertValidVersion(resolvedVersion, Boolean(effectiveMobileTransport));
     }
     if (effectiveMobileTransport) {
-        if (wsProxy) {
-            throw new Error('mobileTransport does not support socketOptions.proxy.ws – remove the proxy option or open an issue to add TCP proxy support');
-        }
+        (0, proxy_1.assertTcpProxySupported)(wsProxy);
         if (!loginIdentity) {
             throw new Error('mobileTransport requires registered credentials (meJid) – run the mobile bridge flow first');
         }
@@ -138,6 +136,7 @@ async function buildCommsConfig(logger, credentials, socketOptions, clientOption
         return {
             url: effectiveMobileTransport.tcpUrl ?? 'tcp://g.whatsapp.net:443',
             rawWebSocketConstructor: WaMobileTcpSocket_1.WaMobileTcpSocketCtor,
+            agent: (0, proxy_1.toProxyAgent)(wsProxy),
             connectTimeoutMs: socketOptions.connectTimeoutMs,
             reconnectIntervalMs: socketOptions.reconnectIntervalMs,
             timeoutIntervalMs: socketOptions.timeoutIntervalMs,

package/dist/client/coordinators/WaOfflineResumeCoordinator.d.ts

@@ -15,6 +15,11 @@ export declare class WaOfflineResumeCoordinator {
     private state;
     private totalStanzas;
     private pendingStanzas;
+    private batchInFlight;
+    private batchRetries;
+    private resumeGeneration;
+    private lastBatchRequestMs;
+    private batchTimeout;
     private stanzaTimeout;
     constructor(options: WaOfflineResumeCoordinatorOptions);
     get isComplete(): boolean;
@@ -24,6 +29,23 @@ export declare class WaOfflineResumeCoordinator {
     trackOfflineStanza(): void;
     reset(): void;
     private completeResume;
+    /**
+     * Ask the server for the next window of queued stanzas, at most one request
+     * per `REQUEST_DEBOUNCE_MS` and never while one is still outstanding. Only a
+     * delivered stanza schedules a request, so the loop winds down on its own
+     * once the queue dries up; the resume itself ends on the terminal `offline`
+     * bulletin or on the stanza timeout, never on the preview counter, which is
+     * a progress estimate rather than an authoritative total.
+     */
+    private scheduleNextBatch;
+    private requestOfflineBatch;
+    /**
+     * A rejected request delivers no stanza, and only a delivered stanza
+     * schedules the next one, so without a retry here a single transport blip
+     * strands the whole queue until the stanza timeout. `generation` pins the
+     * outcome to the resume that issued it: a rejection from a torn-down resume
+     * must not clear the current one's in-flight flag or retry on its behalf.
+     */
     private sendOfflineBatch;
     private resetStanzaTimeout;
     private clearTimers;

package/dist/client/coordinators/WaOfflineResumeCoordinator.js

@@ -5,6 +5,8 @@ const offline_1 = require("../../transport/node/builders/offline");
 const primitives_1 = require("../../util/primitives");
 const WA_OFFLINE_RESUME = Object.freeze({
     BATCH_SIZE: 200,
+    REQUEST_DEBOUNCE_MS: 100,
+    MAX_BATCH_RETRIES: 3,
     STANZA_TIMEOUT_MS: 60000
 });
 const WA_OFFLINE_RESUME_STATE = Object.freeze({
@@ -19,6 +21,11 @@ class WaOfflineResumeCoordinator {
         this.state = WA_OFFLINE_RESUME_STATE.INIT;
         this.totalStanzas = 0;
         this.pendingStanzas = 0;
+        this.batchInFlight = false;
+        this.batchRetries = 0;
+        this.resumeGeneration = 0;
+        this.lastBatchRequestMs = 0;
+        this.batchTimeout = null;
         this.stanzaTimeout = null;
     }
     get isComplete() {
@@ -32,6 +39,10 @@ class WaOfflineResumeCoordinator {
         this.state = WA_OFFLINE_RESUME_STATE.RESUMING;
         this.totalStanzas = stanzaCount;
         this.pendingStanzas = stanzaCount;
+        this.batchInFlight = false;
+        this.batchRetries = 0;
+        this.resumeGeneration += 1;
+        this.lastBatchRequestMs = 0;
         this.logger.info('offline resume started', {
             totalStanzas: stanzaCount
         });
@@ -41,7 +52,7 @@ class WaOfflineResumeCoordinator {
             remainingStanzas: stanzaCount,
             forced: false
         });
-        void this.sendOfflineBatch();
+        this.requestOfflineBatch();
         this.resetStanzaTimeout();
     }
     handleOfflineComplete(serverStanzaCount) {
@@ -55,17 +66,24 @@ class WaOfflineResumeCoordinator {
             return;
         }
         this.pendingStanzas = Math.max(0, this.pendingStanzas - 1);
+        this.batchInFlight = false;
         this.resetStanzaTimeout();
+        this.scheduleNextBatch();
     }
     reset() {
         this.clearTimers();
         this.state = WA_OFFLINE_RESUME_STATE.INIT;
         this.totalStanzas = 0;
         this.pendingStanzas = 0;
+        this.batchInFlight = false;
+        this.batchRetries = 0;
+        this.resumeGeneration += 1;
+        this.lastBatchRequestMs = 0;
     }
     completeResume(forced, serverStanzaCount) {
         this.clearTimers();
         this.state = WA_OFFLINE_RESUME_STATE.COMPLETE;
+        this.batchInFlight = false;
         this.logger.info('offline resume complete', {
             totalStanzas: this.totalStanzas,
             remainingStanzas: this.pendingStanzas,
@@ -79,14 +97,73 @@ class WaOfflineResumeCoordinator {
             forced
         });
     }
-    async sendOfflineBatch() {
+    /**
+     * Ask the server for the next window of queued stanzas, at most one request
+     * per `REQUEST_DEBOUNCE_MS` and never while one is still outstanding. Only a
+     * delivered stanza schedules a request, so the loop winds down on its own
+     * once the queue dries up; the resume itself ends on the terminal `offline`
+     * bulletin or on the stanza timeout, never on the preview counter, which is
+     * a progress estimate rather than an authoritative total.
+     */
+    scheduleNextBatch() {
+        if (this.batchInFlight || this.batchTimeout !== null) {
+            return;
+        }
+        const elapsedMs = Date.now() - this.lastBatchRequestMs;
+        if (elapsedMs >= WA_OFFLINE_RESUME.REQUEST_DEBOUNCE_MS) {
+            this.requestOfflineBatch();
+            return;
+        }
+        this.batchTimeout = setTimeout(() => {
+            this.batchTimeout = null;
+            if (this.state === WA_OFFLINE_RESUME_STATE.RESUMING) {
+                this.scheduleNextBatch();
+            }
+        }, WA_OFFLINE_RESUME.REQUEST_DEBOUNCE_MS - elapsedMs);
+    }
+    requestOfflineBatch() {
+        this.batchInFlight = true;
+        this.lastBatchRequestMs = Date.now();
+        this.logger.debug('offline batch requested', {
+            batchSize: WA_OFFLINE_RESUME.BATCH_SIZE,
+            remainingStanzas: this.pendingStanzas
+        });
+        void this.sendOfflineBatch(this.resumeGeneration);
+    }
+    /**
+     * A rejected request delivers no stanza, and only a delivered stanza
+     * schedules the next one, so without a retry here a single transport blip
+     * strands the whole queue until the stanza timeout. `generation` pins the
+     * outcome to the resume that issued it: a rejection from a torn-down resume
+     * must not clear the current one's in-flight flag or retry on its behalf.
+     */
+    async sendOfflineBatch(generation) {
         try {
             await this.runtime.sendNode((0, offline_1.buildOfflineBatchNode)(WA_OFFLINE_RESUME.BATCH_SIZE));
+            if (generation === this.resumeGeneration) {
+                this.batchRetries = 0;
+            }
         }
         catch (err) {
-            this.logger.warn('offline batch request failed', {
+            if (generation !== this.resumeGeneration ||
+                this.state !== WA_OFFLINE_RESUME_STATE.RESUMING) {
+                return;
+            }
+            this.batchInFlight = false;
+            this.batchRetries += 1;
+            if (this.batchRetries > WA_OFFLINE_RESUME.MAX_BATCH_RETRIES) {
+                this.logger.warn('offline batch request failed, giving up', {
+                    attempts: this.batchRetries,
+                    remainingStanzas: this.pendingStanzas,
+                    message: (0, primitives_1.toError)(err).message
+                });
+                return;
+            }
+            this.logger.debug('offline batch request failed, retrying', {
+                attempt: this.batchRetries,
                 message: (0, primitives_1.toError)(err).message
             });
+            this.scheduleNextBatch();
         }
     }
     resetStanzaTimeout() {
@@ -109,6 +186,10 @@ class WaOfflineResumeCoordinator {
             clearTimeout(this.stanzaTimeout);
             this.stanzaTimeout = null;
         }
+        if (this.batchTimeout !== null) {
+            clearTimeout(this.batchTimeout);
+            this.batchTimeout = null;
+        }
     }
 }
 exports.WaOfflineResumeCoordinator = WaOfflineResumeCoordinator;

package/dist/client/types.d.ts

@@ -1458,9 +1458,19 @@ export interface WaClientEventMap {
 export interface WaOfflineResumeEvent {
     readonly status: 'resuming' | 'complete';
     readonly totalStanzas: number;
-    /** `0` on the terminal `'complete'` event. */
+    /**
+     * Stanzas still outstanding against `totalStanzas`, counted down from the
+     * server's preview figure. That figure is an estimate, so a clean finish
+     * can still report a small non-zero remainder. Read it together with
+     * `forced`: a remainder alongside `forced: true` is the case where the
+     * flush was cut short and the rest stays queued for the next connection.
+     */
     readonly remainingStanzas: number;
-    /** `true` when triggered by an explicit catch-up request rather than auto-resume on reconnect. */
+    /**
+     * `true` when the resume was closed by the client because the server went
+     * quiet for 60s instead of by the server's terminal `offline` bulletin.
+     * Pair with `remainingStanzas` to tell a clean finish from a cut-short one.
+     */
     readonly forced: boolean;
 }
 export interface WaOfflineThreadPreview {

package/dist/esm/auth/credentials-flow.js

@@ -5,7 +5,7 @@ import { getLoginIdentity } from '../protocol/jid.js';
 import { createAndStoreInitialKeys } from '../signal/index.js';
 import { WaMobileTcpSocketCtor } from '../transport/node/WaMobileTcpSocket.js';
 import { buildMobileLoginPayload } from '../transport/noise/WaMobileClientPayload.js';
-import { toProxyAgent, toProxyDispatcher } from '../transport/proxy.js';
+import { assertTcpProxySupported, toProxyAgent, toProxyDispatcher } from '../transport/proxy.js';
 import { parseOptionalInt, toError } from '../util/primitives.js';
 export async function loadOrCreateCredentials(args) {
     args.logger.trace('auth credentials loadOrCreate start');
@@ -108,9 +108,7 @@ export async function buildCommsConfig(logger, credentials, socketOptions, clien
         assertValidVersion(resolvedVersion, Boolean(effectiveMobileTransport));
     }
     if (effectiveMobileTransport) {
-        if (wsProxy) {
-            throw new Error('mobileTransport does not support socketOptions.proxy.ws – remove the proxy option or open an issue to add TCP proxy support');
-        }
+        assertTcpProxySupported(wsProxy);
         if (!loginIdentity) {
             throw new Error('mobileTransport requires registered credentials (meJid) – run the mobile bridge flow first');
         }
@@ -133,6 +131,7 @@ export async function buildCommsConfig(logger, credentials, socketOptions, clien
         return {
             url: effectiveMobileTransport.tcpUrl ?? 'tcp://g.whatsapp.net:443',
             rawWebSocketConstructor: WaMobileTcpSocketCtor,
+            agent: toProxyAgent(wsProxy),
             connectTimeoutMs: socketOptions.connectTimeoutMs,
             reconnectIntervalMs: socketOptions.reconnectIntervalMs,
             timeoutIntervalMs: socketOptions.timeoutIntervalMs,

package/dist/esm/client/coordinators/WaOfflineResumeCoordinator.js

@@ -2,6 +2,8 @@ import { buildOfflineBatchNode } from '../../transport/node/builders/offline.js'
 import { toError } from '../../util/primitives.js';
 const WA_OFFLINE_RESUME = Object.freeze({
     BATCH_SIZE: 200,
+    REQUEST_DEBOUNCE_MS: 100,
+    MAX_BATCH_RETRIES: 3,
     STANZA_TIMEOUT_MS: 60000
 });
 const WA_OFFLINE_RESUME_STATE = Object.freeze({
@@ -16,6 +18,11 @@ export class WaOfflineResumeCoordinator {
         this.state = WA_OFFLINE_RESUME_STATE.INIT;
         this.totalStanzas = 0;
         this.pendingStanzas = 0;
+        this.batchInFlight = false;
+        this.batchRetries = 0;
+        this.resumeGeneration = 0;
+        this.lastBatchRequestMs = 0;
+        this.batchTimeout = null;
         this.stanzaTimeout = null;
     }
     get isComplete() {
@@ -29,6 +36,10 @@ export class WaOfflineResumeCoordinator {
         this.state = WA_OFFLINE_RESUME_STATE.RESUMING;
         this.totalStanzas = stanzaCount;
         this.pendingStanzas = stanzaCount;
+        this.batchInFlight = false;
+        this.batchRetries = 0;
+        this.resumeGeneration += 1;
+        this.lastBatchRequestMs = 0;
         this.logger.info('offline resume started', {
             totalStanzas: stanzaCount
         });
@@ -38,7 +49,7 @@ export class WaOfflineResumeCoordinator {
             remainingStanzas: stanzaCount,
             forced: false
         });
-        void this.sendOfflineBatch();
+        this.requestOfflineBatch();
         this.resetStanzaTimeout();
     }
     handleOfflineComplete(serverStanzaCount) {
@@ -52,17 +63,24 @@ export class WaOfflineResumeCoordinator {
             return;
         }
         this.pendingStanzas = Math.max(0, this.pendingStanzas - 1);
+        this.batchInFlight = false;
         this.resetStanzaTimeout();
+        this.scheduleNextBatch();
     }
     reset() {
         this.clearTimers();
         this.state = WA_OFFLINE_RESUME_STATE.INIT;
         this.totalStanzas = 0;
         this.pendingStanzas = 0;
+        this.batchInFlight = false;
+        this.batchRetries = 0;
+        this.resumeGeneration += 1;
+        this.lastBatchRequestMs = 0;
     }
     completeResume(forced, serverStanzaCount) {
         this.clearTimers();
         this.state = WA_OFFLINE_RESUME_STATE.COMPLETE;
+        this.batchInFlight = false;
         this.logger.info('offline resume complete', {
             totalStanzas: this.totalStanzas,
             remainingStanzas: this.pendingStanzas,
@@ -76,14 +94,73 @@ export class WaOfflineResumeCoordinator {
             forced
         });
     }
-    async sendOfflineBatch() {
+    /**
+     * Ask the server for the next window of queued stanzas, at most one request
+     * per `REQUEST_DEBOUNCE_MS` and never while one is still outstanding. Only a
+     * delivered stanza schedules a request, so the loop winds down on its own
+     * once the queue dries up; the resume itself ends on the terminal `offline`
+     * bulletin or on the stanza timeout, never on the preview counter, which is
+     * a progress estimate rather than an authoritative total.
+     */
+    scheduleNextBatch() {
+        if (this.batchInFlight || this.batchTimeout !== null) {
+            return;
+        }
+        const elapsedMs = Date.now() - this.lastBatchRequestMs;
+        if (elapsedMs >= WA_OFFLINE_RESUME.REQUEST_DEBOUNCE_MS) {
+            this.requestOfflineBatch();
+            return;
+        }
+        this.batchTimeout = setTimeout(() => {
+            this.batchTimeout = null;
+            if (this.state === WA_OFFLINE_RESUME_STATE.RESUMING) {
+                this.scheduleNextBatch();
+            }
+        }, WA_OFFLINE_RESUME.REQUEST_DEBOUNCE_MS - elapsedMs);
+    }
+    requestOfflineBatch() {
+        this.batchInFlight = true;
+        this.lastBatchRequestMs = Date.now();
+        this.logger.debug('offline batch requested', {
+            batchSize: WA_OFFLINE_RESUME.BATCH_SIZE,
+            remainingStanzas: this.pendingStanzas
+        });
+        void this.sendOfflineBatch(this.resumeGeneration);
+    }
+    /**
+     * A rejected request delivers no stanza, and only a delivered stanza
+     * schedules the next one, so without a retry here a single transport blip
+     * strands the whole queue until the stanza timeout. `generation` pins the
+     * outcome to the resume that issued it: a rejection from a torn-down resume
+     * must not clear the current one's in-flight flag or retry on its behalf.
+     */
+    async sendOfflineBatch(generation) {
         try {
             await this.runtime.sendNode(buildOfflineBatchNode(WA_OFFLINE_RESUME.BATCH_SIZE));
+            if (generation === this.resumeGeneration) {
+                this.batchRetries = 0;
+            }
         }
         catch (err) {
-            this.logger.warn('offline batch request failed', {
+            if (generation !== this.resumeGeneration ||
+                this.state !== WA_OFFLINE_RESUME_STATE.RESUMING) {
+                return;
+            }
+            this.batchInFlight = false;
+            this.batchRetries += 1;
+            if (this.batchRetries > WA_OFFLINE_RESUME.MAX_BATCH_RETRIES) {
+                this.logger.warn('offline batch request failed, giving up', {
+                    attempts: this.batchRetries,
+                    remainingStanzas: this.pendingStanzas,
+                    message: toError(err).message
+                });
+                return;
+            }
+            this.logger.debug('offline batch request failed, retrying', {
+                attempt: this.batchRetries,
                 message: toError(err).message
             });
+            this.scheduleNextBatch();
         }
     }
     resetStanzaTimeout() {
@@ -106,5 +183,9 @@ export class WaOfflineResumeCoordinator {
             clearTimeout(this.stanzaTimeout);
             this.stanzaTimeout = null;
         }
+        if (this.batchTimeout !== null) {
+            clearTimeout(this.batchTimeout);
+            this.batchTimeout = null;
+        }
     }
 }

package/dist/esm/message/crypto/phash.js

@@ -9,39 +9,84 @@ const CHAR_AT = 0x40;
 const CHAR_C = 0x63;
 const CHAR_U = 0x75;
 const CHAR_S = 0x73;
-const MAX_PARTICIPANTS = 2048;
-const PER_WID_BYTES = 96;
-const SCRATCH = new Uint8Array(MAX_PARTICIPANTS * PER_WID_BYTES);
-const OFFSETS = new Uint32Array(MAX_PARTICIPANTS + 1);
-const ORDER = new Uint32Array(MAX_PARTICIPANTS);
+/**
+ * Upper bound on the bytes the canonical rewrite can add to a single jid: the
+ * `.0:` agent marker plus a device digit when the input carries neither, plus
+ * the `c.us` server substitution.
+ */
+const CANONICAL_GROWTH_BYTES = 4 + WA_DEFAULTS.HOST_DOMAIN.length;
+/**
+ * Largest canonical buffer kept alive between calls (the index arrays scale
+ * with it). Lists above this bound are rare enough that a throwaway allocation
+ * beats holding the memory for the life of the process.
+ */
+const RETAINED_SCRATCH_BYTES = 1024 * 1024;
+const RETAINED = {
+    scratch: new Uint8Array(0),
+    offsets: new Uint32Array(0),
+    order: new Uint32Array(0)
+};
+/**
+ * Computes the v2 participant hash (`2:<base64>`) attached to group and
+ * broadcast-list fanouts.
+ *
+ * Every participant is canonicalized to `<user>.0:<device>@<server>`, the set
+ * is sorted bytewise and hashed as a single SHA-256 stream. There is no
+ * participant ceiling: the canonical buffer grows to fit the list, so a group
+ * whose members resolve to tens of thousands of devices still hashes.
+ *
+ * @param participants device jids, in any order
+ * @returns the `2:`-prefixed phash, or `'2:'` when the list is empty
+ */
 export function computePhashV2(participants) {
-    if (participants.length === 0)
-        return '2:';
     const n = participants.length;
-    if (n > MAX_PARTICIPANTS) {
-        throw new Error(`phash participant count ${n} exceeds MAX_PARTICIPANTS ${MAX_PARTICIPANTS}`);
+    if (n === 0)
+        return '2:';
+    let requiredBytes = 0;
+    for (let i = 0; i < n; i += 1) {
+        requiredBytes += participants[i].length + CANONICAL_GROWTH_BYTES;
     }
+    const { scratch, offsets, order } = acquireBuffers(n, requiredBytes);
     let off = 0;
     for (let i = 0; i < n; i += 1) {
-        OFFSETS[i] = off;
-        const nextOff = writeCanonicalUtf8(SCRATCH, off, participants[i]);
-        if (nextOff > SCRATCH.length) {
-            throw new Error(`phash canonical buffer overflow at participant ${i}: needs ${nextOff} bytes, scratch is ${SCRATCH.length}`);
-        }
-        off = nextOff;
+        offsets[i] = off;
+        off = writeCanonicalUtf8(scratch, off, participants[i]);
+    }
+    offsets[n] = off;
+    if (off > scratch.length) {
+        throw new Error(`phash canonical buffer overflow: needs ${off} bytes, scratch is ${scratch.length}`);
     }
-    OFFSETS[n] = off;
     for (let i = 0; i < n; i += 1)
-        ORDER[i] = i;
-    ORDER.subarray(0, n).sort((a, b) => compareScratchSlice(SCRATCH, OFFSETS, a, b));
+        order[i] = i;
+    const ranked = order.subarray(0, n);
+    ranked.sort((a, b) => compareScratchSlice(scratch, offsets, a, b));
     const parts = new Array(n);
     for (let i = 0; i < n; i += 1) {
-        const idx = ORDER[i];
-        parts[i] = SCRATCH.subarray(OFFSETS[idx], OFFSETS[idx + 1]);
+        const idx = ranked[i];
+        parts[i] = scratch.subarray(offsets[idx], offsets[idx + 1]);
     }
     const digest = sha256(parts);
     return `2:${bytesToBase64(digest.subarray(0, PHASH_DIGEST_PREFIX))}`;
 }
+function acquireBuffers(participantCount, requiredBytes) {
+    if (requiredBytes > RETAINED_SCRATCH_BYTES) {
+        return {
+            scratch: new Uint8Array(requiredBytes),
+            offsets: new Uint32Array(participantCount + 1),
+            order: new Uint32Array(participantCount)
+        };
+    }
+    if (RETAINED.scratch.length < requiredBytes) {
+        const nextBytes = Math.max(requiredBytes, RETAINED.scratch.length * 2);
+        RETAINED.scratch = new Uint8Array(Math.min(RETAINED_SCRATCH_BYTES, nextBytes));
+    }
+    if (RETAINED.order.length < participantCount) {
+        const capacity = Math.max(participantCount, RETAINED.order.length * 2);
+        RETAINED.offsets = new Uint32Array(capacity + 1);
+        RETAINED.order = new Uint32Array(capacity);
+    }
+    return RETAINED;
+}
 function writeCanonicalUtf8(out, start, jid) {
     const atIndex = jid.indexOf('@');
     if (atIndex < 1 || atIndex >= jid.length - 1) {

package/dist/esm/message/encode/content.js

@@ -154,7 +154,8 @@ export function unwrapMessage(message) {
             msg.viewOnceMessageV2?.message ??
             msg.documentWithCaptionMessage?.message ??
             msg.groupStatusMessage?.message ??
-            msg.groupStatusMessageV2?.message;
+            msg.groupStatusMessageV2?.message ??
+            msg.botForwardedMessage?.message;
         if (!inner)
             return msg;
         msg = inner;
@@ -202,6 +203,8 @@ function resolveMessageTypeAttrFrom(msg) {
         msg.pollResultSnapshotMessageV3 ||
         msg.templateButtonReplyMessage ||
         msg.messageHistoryNotice ||
+        msg.richResponseMessage ||
+        msg.botForwardedMessage ||
         msg.secretEncryptedMessage?.secretEncType ===
             proto.Message.SecretEncryptedMessage.SecretEncType.MESSAGE_EDIT ||
         msg.secretEncryptedMessage?.secretEncType ===

package/dist/esm/transport/node/WaMobileTcpSocket.js

@@ -1,13 +1,14 @@
 import { connect as netConnect } from 'node:net';
 import { WA_READY_STATES } from '../../protocol/constants.js';
-import { TEXT_ENCODER } from '../../util/bytes.js';
+import { toTcpProxyEndpoint } from '../proxy.js';
+import { concatBytes, TEXT_DECODER, TEXT_ENCODER } from '../../util/bytes.js';
 /**
  * `RawWebSocket`-shaped adapter over a raw Node TCP socket. Used by the
  * mobile transport to speak the WhatsApp Mobile binary protocol over
  * `tcp://host:port` URLs.
  */
 export class WaMobileTcpSocket {
-    constructor(url, _protocols, _options) {
+    constructor(url, _protocols, options) {
         this.binaryType = 'arraybuffer';
         this.readyState = WA_READY_STATES.CONNECTING;
         this.onopen = null;
@@ -19,19 +20,55 @@ export class WaMobileTcpSocket {
         this.closedClean = true;
         this.forceCloseTimer = null;
         const { host, port } = parseTcpUrl(url);
-        this.socket = netConnect({ host, port });
+        const proxy = toTcpProxyEndpoint(options?.agent);
+        this.socket = proxy
+            ? netConnect({ host: proxy.hostname, port: proxy.port })
+            : netConnect({ host, port });
+        let tunnelReady = !proxy;
+        let proxyResponse = new Uint8Array(0);
         this.socket.on('connect', () => {
             if (this.readyState !== WA_READY_STATES.CONNECTING)
                 return;
-            this.readyState = WA_READY_STATES.OPEN;
-            this.onopen?.({});
+            if (proxy) {
+                const authority = `${host}:${port}`;
+                const lines = [
+                    `CONNECT ${authority} HTTP/1.1`,
+                    `Host: ${authority}`,
+                    'Proxy-Connection: Keep-Alive'
+                ];
+                if (proxy.authorization)
+                    lines.push(`Proxy-Authorization: ${proxy.authorization}`);
+                this.socket.write(TEXT_ENCODER.encode(`${lines.join('\r\n')}\r\n\r\n`));
+                return;
+            }
+            this.markOpen();
         });
         this.socket.on('data', (chunk) => {
-            if (!this.onmessage || this.readyState !== WA_READY_STATES.OPEN)
+            if (!tunnelReady && proxy) {
+                proxyResponse = concatBytes([proxyResponse, chunk]);
+                const headerEnd = findHttpHeaderEnd(proxyResponse);
+                const scanned = headerEnd === -1 ? proxyResponse.byteLength : headerEnd;
+                if (scanned > MAX_PROXY_HEADER_BYTES) {
+                    this.socket.destroy(new Error('WaMobileTcpSocket: proxy response headers too large'));
+                    return;
+                }
+                if (headerEnd === -1) {
+                    return;
+                }
+                const statusLine = TEXT_DECODER.decode(proxyResponse.subarray(0, headerEnd)).split('\r\n')[0];
+                if (!/^HTTP\/1\.[01] 2\d\d(?:\s|$)/.test(statusLine)) {
+                    this.socket.destroy(new Error(`WaMobileTcpSocket: proxy CONNECT failed (${statusLine})`));
+                    return;
+                }
+                const remaining = proxyResponse.subarray(headerEnd + 4);
+                proxyResponse = new Uint8Array(0);
+                tunnelReady = true;
+                this.markOpen();
+                if (remaining.byteLength > 0)
+                    this.emitMessage(remaining);
                 return;
-            const copy = new Uint8Array(chunk.byteLength);
-            copy.set(chunk);
-            this.onmessage({ data: copy });
+            }
+            this.emitMessage(chunk);
         });
         this.socket.on('error', (err) => {
             this.closedClean = false;
@@ -53,6 +90,19 @@ export class WaMobileTcpSocket {
             });
         });
     }
+    markOpen() {
+        if (this.readyState !== WA_READY_STATES.CONNECTING)
+            return;
+        this.readyState = WA_READY_STATES.OPEN;
+        this.onopen?.({});
+    }
+    emitMessage(chunk) {
+        if (!this.onmessage || this.readyState !== WA_READY_STATES.OPEN)
+            return;
+        const copy = new Uint8Array(chunk.byteLength);
+        copy.set(chunk);
+        this.onmessage({ data: copy });
+    }
     send(data) {
         if (this.readyState !== WA_READY_STATES.OPEN) {
             throw new Error('WaMobileTcpSocket: send() called on non-OPEN socket');
@@ -85,6 +135,16 @@ export class WaMobileTcpSocket {
         this.forceCloseTimer.unref();
     }
 }
+/** Cap on the CONNECT response headers buffered before the tunnel is rejected. */
+const MAX_PROXY_HEADER_BYTES = 65536;
+function findHttpHeaderEnd(bytes) {
+    for (let i = 3; i < bytes.byteLength; i += 1) {
+        if (bytes[i - 3] === 13 && bytes[i - 2] === 10 && bytes[i - 1] === 13 && bytes[i] === 10) {
+            return i - 3;
+        }
+    }
+    return -1;
+}
 function parseTcpUrl(url) {
     let work = url;
     if (work.startsWith('tcp://')) {

package/dist/esm/transport/noise/WaMobileClientPayload.js

@@ -13,6 +13,20 @@ function parseAppVersion(version) {
         quaternary: at(3)
     };
 }
+function distributionChannelId(channel) {
+    const { DistributionChannel } = proto.ClientPayload.UserAgent;
+    switch (channel) {
+        case 'website':
+            return DistributionChannel.WEBSITE;
+        case 'testflight':
+            return DistributionChannel.TESTFLIGHT;
+        case 'internal':
+            return DistributionChannel.INTERNAL;
+        case 'appstore':
+        case undefined:
+            return DistributionChannel.APPSTORE;
+    }
+}
 /**
  * Builds the encoded {@link Proto.ClientPayload} bytes the WhatsApp Mobile
  * transport sends after the noise login handshake. Throws when
@@ -24,14 +38,18 @@ export function buildMobileLoginPayload(config) {
     }
     const info = config.deviceInfo;
     const version = parseAppVersion(info.appVersion);
-    const userAgent = {
-        platform: info.business
+    const isIos = info.os === 'ios';
+    const platform = isIos
+        ? info.business
+            ? proto.ClientPayload.UserAgent.Platform.SMB_IOS
+            : proto.ClientPayload.UserAgent.Platform.IOS
+        : info.business
             ? proto.ClientPayload.UserAgent.Platform.SMB_ANDROID
-            : proto.ClientPayload.UserAgent.Platform.ANDROID,
+            : proto.ClientPayload.UserAgent.Platform.ANDROID;
+    const userAgent = {
+        platform,
         releaseChannel: proto.ClientPayload.UserAgent.ReleaseChannel.RELEASE,
         appVersion: version,
-        mcc: info.mcc ?? '000',
-        mnc: info.mnc ?? '000',
         osVersion: info.osVersion,
         manufacturer: info.manufacturer,
         device: info.device,
@@ -40,8 +58,10 @@ export function buildMobileLoginPayload(config) {
         localeLanguageIso6391: info.localeLanguageIso6391 ?? 'en',
         localeCountryIso31661Alpha2: info.localeCountryIso31661Alpha2 ?? 'US',
         deviceType: proto.ClientPayload.UserAgent.DeviceType.PHONE,
-        deviceBoard: info.deviceBoard,
-        deviceModelType: info.deviceModelType
+        deviceModelType: info.deviceModelType,
+        ...(isIos
+            ? { distributionChannel: distributionChannelId(info.distributionChannel) }
+            : { mcc: info.mcc ?? '000', mnc: info.mnc ?? '000', deviceBoard: info.deviceBoard })
     };
     return proto.ClientPayload.encode({
         passive: config.passive === true,

package/dist/esm/transport/proxy.js

@@ -1,3 +1,4 @@
+import { bytesToBase64, TEXT_ENCODER } from '../util/bytes.js';
 /** Type guard for an undici-style proxy dispatcher (has `dispatch` method). */
 export function isProxyDispatcher(value) {
     return (typeof value === 'object' &&
@@ -30,3 +31,85 @@ export function toProxyAgent(proxy) {
     }
     return proxy;
 }
+const TCP_PROXY_HINT = 'socketOptions.proxy.ws must hold an http.Agent-style proxy pointing at an http: url (e.g. new HttpProxyAgent("http://host:port")) to tunnel raw TCP';
+/**
+ * Resolves the proxy endpoint a raw TCP transport tunnels through with HTTP
+ * CONNECT.
+ *
+ * Returns `undefined` only when no proxy is configured. Proxy shapes the tunnel
+ * cannot honour throw instead of resolving to `undefined`, because dropping one
+ * silently would dial the destination directly – the opposite of what a
+ * deployment that pins its egress to a proxy asked for.
+ */
+export function toTcpProxyEndpoint(proxy) {
+    if (!proxy) {
+        return undefined;
+    }
+    if (!isProxyAgent(proxy)) {
+        if (isProxyDispatcher(proxy)) {
+            throw new Error(`undici-style proxy dispatchers cannot tunnel raw TCP – ${TCP_PROXY_HINT}`);
+        }
+        throw new Error(`unsupported proxy transport – ${TCP_PROXY_HINT}`);
+    }
+    const url = readAgentProxyUrl(proxy);
+    if (url.protocol !== 'http:') {
+        throw new Error(`proxy protocol ${url.protocol} is not supported by the raw TCP tunnel – ${TCP_PROXY_HINT}`);
+    }
+    const username = decodeProxyUserInfo(url.username, 'username');
+    const password = decodeProxyUserInfo(url.password, 'password');
+    return {
+        hostname: url.hostname,
+        port: url.port ? Number(url.port) : 80,
+        authorization: username || password
+            ? `Basic ${bytesToBase64(TEXT_ENCODER.encode(`${username}:${password}`))}`
+            : undefined
+    };
+}
+/** Throws when {@link toTcpProxyEndpoint} cannot honour `proxy`. */
+export function assertTcpProxySupported(proxy) {
+    toTcpProxyEndpoint(proxy);
+}
+/**
+ * Decodes one userinfo component of a proxy url. `new URL()` keeps invalid
+ * percent escapes verbatim, so a credential holding a literal `%` would reach
+ * `decodeURIComponent` and throw a bare `URIError`. The value never reaches the
+ * message – only the field name does.
+ */
+function decodeProxyUserInfo(value, field) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        throw new Error(`proxy url ${field} contains a malformed percent escape`);
+    }
+}
+/**
+ * Reads the proxy url an `http.Agent`-style proxy exposes. Every `*-proxy-agent`
+ * package keeps it on `.proxy`, but only the http/https ones store a `URL`
+ * there – `socks-proxy-agent` stores a parsed `{ host, port, type }` endpoint.
+ */
+function readAgentProxyUrl(agent) {
+    const value = agent.proxy;
+    if (value instanceof URL) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        try {
+            return new URL(value);
+        }
+        catch {
+            throw new Error(`proxy agent exposes an unparseable proxy url ${JSON.stringify(value)}`);
+        }
+    }
+    if (isSocksProxyEndpoint(value)) {
+        throw new Error(`socks proxy agents cannot tunnel raw TCP – ${TCP_PROXY_HINT}`);
+    }
+    throw new Error(`proxy agent exposes no proxy url – ${TCP_PROXY_HINT}`);
+}
+/** Matches the `{ host, port, type }` endpoint `socks-proxy-agent` keeps on `.proxy`. */
+function isSocksProxyEndpoint(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.host === 'string' &&
+        typeof value.port === 'number');
+}

package/dist/message/crypto/phash.d.ts

@@ -1 +1,13 @@
+/**
+ * Computes the v2 participant hash (`2:<base64>`) attached to group and
+ * broadcast-list fanouts.
+ *
+ * Every participant is canonicalized to `<user>.0:<device>@<server>`, the set
+ * is sorted bytewise and hashed as a single SHA-256 stream. There is no
+ * participant ceiling: the canonical buffer grows to fit the list, so a group
+ * whose members resolve to tens of thousands of devices still hashes.
+ *
+ * @param participants device jids, in any order
+ * @returns the `2:`-prefixed phash, or `'2:'` when the list is empty
+ */
 export declare function computePhashV2(participants: readonly string[]): string;

package/dist/message/crypto/phash.js

@@ -12,39 +12,84 @@ const CHAR_AT = 0x40;
 const CHAR_C = 0x63;
 const CHAR_U = 0x75;
 const CHAR_S = 0x73;
-const MAX_PARTICIPANTS = 2048;
-const PER_WID_BYTES = 96;
-const SCRATCH = new Uint8Array(MAX_PARTICIPANTS * PER_WID_BYTES);
-const OFFSETS = new Uint32Array(MAX_PARTICIPANTS + 1);
-const ORDER = new Uint32Array(MAX_PARTICIPANTS);
+/**
+ * Upper bound on the bytes the canonical rewrite can add to a single jid: the
+ * `.0:` agent marker plus a device digit when the input carries neither, plus
+ * the `c.us` server substitution.
+ */
+const CANONICAL_GROWTH_BYTES = 4 + constants_1.WA_DEFAULTS.HOST_DOMAIN.length;
+/**
+ * Largest canonical buffer kept alive between calls (the index arrays scale
+ * with it). Lists above this bound are rare enough that a throwaway allocation
+ * beats holding the memory for the life of the process.
+ */
+const RETAINED_SCRATCH_BYTES = 1024 * 1024;
+const RETAINED = {
+    scratch: new Uint8Array(0),
+    offsets: new Uint32Array(0),
+    order: new Uint32Array(0)
+};
+/**
+ * Computes the v2 participant hash (`2:<base64>`) attached to group and
+ * broadcast-list fanouts.
+ *
+ * Every participant is canonicalized to `<user>.0:<device>@<server>`, the set
+ * is sorted bytewise and hashed as a single SHA-256 stream. There is no
+ * participant ceiling: the canonical buffer grows to fit the list, so a group
+ * whose members resolve to tens of thousands of devices still hashes.
+ *
+ * @param participants device jids, in any order
+ * @returns the `2:`-prefixed phash, or `'2:'` when the list is empty
+ */
 function computePhashV2(participants) {
-    if (participants.length === 0)
-        return '2:';
     const n = participants.length;
-    if (n > MAX_PARTICIPANTS) {
-        throw new Error(`phash participant count ${n} exceeds MAX_PARTICIPANTS ${MAX_PARTICIPANTS}`);
+    if (n === 0)
+        return '2:';
+    let requiredBytes = 0;
+    for (let i = 0; i < n; i += 1) {
+        requiredBytes += participants[i].length + CANONICAL_GROWTH_BYTES;
     }
+    const { scratch, offsets, order } = acquireBuffers(n, requiredBytes);
     let off = 0;
     for (let i = 0; i < n; i += 1) {
-        OFFSETS[i] = off;
-        const nextOff = writeCanonicalUtf8(SCRATCH, off, participants[i]);
-        if (nextOff > SCRATCH.length) {
-            throw new Error(`phash canonical buffer overflow at participant ${i}: needs ${nextOff} bytes, scratch is ${SCRATCH.length}`);
-        }
-        off = nextOff;
+        offsets[i] = off;
+        off = writeCanonicalUtf8(scratch, off, participants[i]);
+    }
+    offsets[n] = off;
+    if (off > scratch.length) {
+        throw new Error(`phash canonical buffer overflow: needs ${off} bytes, scratch is ${scratch.length}`);
     }
-    OFFSETS[n] = off;
     for (let i = 0; i < n; i += 1)
-        ORDER[i] = i;
-    ORDER.subarray(0, n).sort((a, b) => compareScratchSlice(SCRATCH, OFFSETS, a, b));
+        order[i] = i;
+    const ranked = order.subarray(0, n);
+    ranked.sort((a, b) => compareScratchSlice(scratch, offsets, a, b));
     const parts = new Array(n);
     for (let i = 0; i < n; i += 1) {
-        const idx = ORDER[i];
-        parts[i] = SCRATCH.subarray(OFFSETS[idx], OFFSETS[idx + 1]);
+        const idx = ranked[i];
+        parts[i] = scratch.subarray(offsets[idx], offsets[idx + 1]);
     }
     const digest = (0, core_1.sha256)(parts);
     return `2:${(0, bytes_1.bytesToBase64)(digest.subarray(0, PHASH_DIGEST_PREFIX))}`;
 }
+function acquireBuffers(participantCount, requiredBytes) {
+    if (requiredBytes > RETAINED_SCRATCH_BYTES) {
+        return {
+            scratch: new Uint8Array(requiredBytes),
+            offsets: new Uint32Array(participantCount + 1),
+            order: new Uint32Array(participantCount)
+        };
+    }
+    if (RETAINED.scratch.length < requiredBytes) {
+        const nextBytes = Math.max(requiredBytes, RETAINED.scratch.length * 2);
+        RETAINED.scratch = new Uint8Array(Math.min(RETAINED_SCRATCH_BYTES, nextBytes));
+    }
+    if (RETAINED.order.length < participantCount) {
+        const capacity = Math.max(participantCount, RETAINED.order.length * 2);
+        RETAINED.offsets = new Uint32Array(capacity + 1);
+        RETAINED.order = new Uint32Array(capacity);
+    }
+    return RETAINED;
+}
 function writeCanonicalUtf8(out, start, jid) {
     const atIndex = jid.indexOf('@');
     if (atIndex < 1 || atIndex >= jid.length - 1) {

package/dist/message/encode/content.js

@@ -180,7 +180,8 @@ function unwrapMessage(message) {
             msg.viewOnceMessageV2?.message ??
             msg.documentWithCaptionMessage?.message ??
             msg.groupStatusMessage?.message ??
-            msg.groupStatusMessageV2?.message;
+            msg.groupStatusMessageV2?.message ??
+            msg.botForwardedMessage?.message;
         if (!inner)
             return msg;
         msg = inner;
@@ -228,6 +229,8 @@ function resolveMessageTypeAttrFrom(msg) {
         msg.pollResultSnapshotMessageV3 ||
         msg.templateButtonReplyMessage ||
         msg.messageHistoryNotice ||
+        msg.richResponseMessage ||
+        msg.botForwardedMessage ||
         msg.secretEncryptedMessage?.secretEncType ===
             _proto_1.proto.Message.SecretEncryptedMessage.SecretEncType.MESSAGE_EDIT ||
         msg.secretEncryptedMessage?.secretEncType ===

package/dist/transport/node/WaMobileTcpSocket.d.ts

@@ -16,7 +16,9 @@ export declare class WaMobileTcpSocket implements RawWebSocket {
     private closedReason;
     private closedClean;
     private forceCloseTimer;
-    constructor(url: string, _protocols?: unknown, _options?: WaRawWebSocketInit);
+    constructor(url: string, _protocols?: unknown, options?: WaRawWebSocketInit);
+    private markOpen;
+    private emitMessage;
     send(data: string | ArrayBuffer | Uint8Array): void;
     close(code?: number, reason?: string): void;
 }

package/dist/transport/node/WaMobileTcpSocket.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WaMobileTcpSocketCtor = exports.WaMobileTcpSocket = void 0;
 const node_net_1 = require("node:net");
 const constants_1 = require("../../protocol/constants");
+const proxy_1 = require("../proxy");
 const bytes_1 = require("../../util/bytes");
 /**
  * `RawWebSocket`-shaped adapter over a raw Node TCP socket. Used by the
@@ -10,7 +11,7 @@ const bytes_1 = require("../../util/bytes");
  * `tcp://host:port` URLs.
  */
 class WaMobileTcpSocket {
-    constructor(url, _protocols, _options) {
+    constructor(url, _protocols, options) {
         this.binaryType = 'arraybuffer';
         this.readyState = constants_1.WA_READY_STATES.CONNECTING;
         this.onopen = null;
@@ -22,19 +23,55 @@ class WaMobileTcpSocket {
         this.closedClean = true;
         this.forceCloseTimer = null;
         const { host, port } = parseTcpUrl(url);
-        this.socket = (0, node_net_1.connect)({ host, port });
+        const proxy = (0, proxy_1.toTcpProxyEndpoint)(options?.agent);
+        this.socket = proxy
+            ? (0, node_net_1.connect)({ host: proxy.hostname, port: proxy.port })
+            : (0, node_net_1.connect)({ host, port });
+        let tunnelReady = !proxy;
+        let proxyResponse = new Uint8Array(0);
         this.socket.on('connect', () => {
             if (this.readyState !== constants_1.WA_READY_STATES.CONNECTING)
                 return;
-            this.readyState = constants_1.WA_READY_STATES.OPEN;
-            this.onopen?.({});
+            if (proxy) {
+                const authority = `${host}:${port}`;
+                const lines = [
+                    `CONNECT ${authority} HTTP/1.1`,
+                    `Host: ${authority}`,
+                    'Proxy-Connection: Keep-Alive'
+                ];
+                if (proxy.authorization)
+                    lines.push(`Proxy-Authorization: ${proxy.authorization}`);
+                this.socket.write(bytes_1.TEXT_ENCODER.encode(`${lines.join('\r\n')}\r\n\r\n`));
+                return;
+            }
+            this.markOpen();
         });
         this.socket.on('data', (chunk) => {
-            if (!this.onmessage || this.readyState !== constants_1.WA_READY_STATES.OPEN)
+            if (!tunnelReady && proxy) {
+                proxyResponse = (0, bytes_1.concatBytes)([proxyResponse, chunk]);
+                const headerEnd = findHttpHeaderEnd(proxyResponse);
+                const scanned = headerEnd === -1 ? proxyResponse.byteLength : headerEnd;
+                if (scanned > MAX_PROXY_HEADER_BYTES) {
+                    this.socket.destroy(new Error('WaMobileTcpSocket: proxy response headers too large'));
+                    return;
+                }
+                if (headerEnd === -1) {
+                    return;
+                }
+                const statusLine = bytes_1.TEXT_DECODER.decode(proxyResponse.subarray(0, headerEnd)).split('\r\n')[0];
+                if (!/^HTTP\/1\.[01] 2\d\d(?:\s|$)/.test(statusLine)) {
+                    this.socket.destroy(new Error(`WaMobileTcpSocket: proxy CONNECT failed (${statusLine})`));
+                    return;
+                }
+                const remaining = proxyResponse.subarray(headerEnd + 4);
+                proxyResponse = new Uint8Array(0);
+                tunnelReady = true;
+                this.markOpen();
+                if (remaining.byteLength > 0)
+                    this.emitMessage(remaining);
                 return;
-            const copy = new Uint8Array(chunk.byteLength);
-            copy.set(chunk);
-            this.onmessage({ data: copy });
+            }
+            this.emitMessage(chunk);
         });
         this.socket.on('error', (err) => {
             this.closedClean = false;
@@ -56,6 +93,19 @@ class WaMobileTcpSocket {
             });
         });
     }
+    markOpen() {
+        if (this.readyState !== constants_1.WA_READY_STATES.CONNECTING)
+            return;
+        this.readyState = constants_1.WA_READY_STATES.OPEN;
+        this.onopen?.({});
+    }
+    emitMessage(chunk) {
+        if (!this.onmessage || this.readyState !== constants_1.WA_READY_STATES.OPEN)
+            return;
+        const copy = new Uint8Array(chunk.byteLength);
+        copy.set(chunk);
+        this.onmessage({ data: copy });
+    }
     send(data) {
         if (this.readyState !== constants_1.WA_READY_STATES.OPEN) {
             throw new Error('WaMobileTcpSocket: send() called on non-OPEN socket');
@@ -89,6 +139,16 @@ class WaMobileTcpSocket {
     }
 }
 exports.WaMobileTcpSocket = WaMobileTcpSocket;
+/** Cap on the CONNECT response headers buffered before the tunnel is rejected. */
+const MAX_PROXY_HEADER_BYTES = 65536;
+function findHttpHeaderEnd(bytes) {
+    for (let i = 3; i < bytes.byteLength; i += 1) {
+        if (bytes[i - 3] === 13 && bytes[i - 2] === 10 && bytes[i - 1] === 13 && bytes[i] === 10) {
+            return i - 3;
+        }
+    }
+    return -1;
+}
 function parseTcpUrl(url) {
     let work = url;
     if (work.startsWith('tcp://')) {

package/dist/transport/noise/WaMobileClientPayload.d.ts

@@ -1,5 +1,25 @@
 import { type Proto } from '../../proto';
+/**
+ * Distribution channel advertised by an iOS login (`UserAgent.distributionChannel`).
+ * iOS-only – Android leaves the field unset. `appstore` is the normal
+ * production install; `testflight`/`internal` mark beta builds.
+ */
+export type WaMobileDistributionChannel = 'appstore' | 'website' | 'testflight' | 'internal';
 export interface WaMobileTransportDeviceInfo {
+    /**
+     * Operating system the login payload impersonates. `android` (the default,
+     * for backwards compatibility) advertises the `ANDROID`/`SMB_ANDROID`
+     * platform and fills the Android-only `mcc`/`mnc`/`deviceBoard` fields.
+     * `ios` advertises `IOS`/`SMB_IOS`, omits those Android-only fields (the
+     * real iPhone client never sends them) and carries `distributionChannel`
+     * instead.
+     *
+     * Field mapping differs by OS and must match the real client:
+     * - **Android** `device` = a device codename (e.g. `moto_g52`).
+     * - **iOS** `device` = the marketing name (e.g. `iPhone 15 Pro`) while
+     *   {@link deviceModelType} carries the raw machine id (`iPhone16,1`).
+     */
+    readonly os?: 'android' | 'ios';
     readonly manufacturer: string;
     readonly device: string;
     readonly osVersion: string;
@@ -12,6 +32,8 @@ export interface WaMobileTransportDeviceInfo {
     readonly phoneId?: string;
     readonly deviceBoard?: string;
     readonly deviceModelType?: string;
+    /** iOS distribution channel; ignored for Android. Defaults to `appstore`. */
+    readonly distributionChannel?: WaMobileDistributionChannel;
     readonly business?: boolean;
 }
 export interface WaMobileLoginPayloadConfig {

package/dist/transport/noise/WaMobileClientPayload.js

@@ -16,6 +16,20 @@ function parseAppVersion(version) {
         quaternary: at(3)
     };
 }
+function distributionChannelId(channel) {
+    const { DistributionChannel } = _proto_1.proto.ClientPayload.UserAgent;
+    switch (channel) {
+        case 'website':
+            return DistributionChannel.WEBSITE;
+        case 'testflight':
+            return DistributionChannel.TESTFLIGHT;
+        case 'internal':
+            return DistributionChannel.INTERNAL;
+        case 'appstore':
+        case undefined:
+            return DistributionChannel.APPSTORE;
+    }
+}
 /**
  * Builds the encoded {@link Proto.ClientPayload} bytes the WhatsApp Mobile
  * transport sends after the noise login handshake. Throws when
@@ -27,14 +41,18 @@ function buildMobileLoginPayload(config) {
     }
     const info = config.deviceInfo;
     const version = parseAppVersion(info.appVersion);
-    const userAgent = {
-        platform: info.business
+    const isIos = info.os === 'ios';
+    const platform = isIos
+        ? info.business
+            ? _proto_1.proto.ClientPayload.UserAgent.Platform.SMB_IOS
+            : _proto_1.proto.ClientPayload.UserAgent.Platform.IOS
+        : info.business
             ? _proto_1.proto.ClientPayload.UserAgent.Platform.SMB_ANDROID
-            : _proto_1.proto.ClientPayload.UserAgent.Platform.ANDROID,
+            : _proto_1.proto.ClientPayload.UserAgent.Platform.ANDROID;
+    const userAgent = {
+        platform,
         releaseChannel: _proto_1.proto.ClientPayload.UserAgent.ReleaseChannel.RELEASE,
         appVersion: version,
-        mcc: info.mcc ?? '000',
-        mnc: info.mnc ?? '000',
         osVersion: info.osVersion,
         manufacturer: info.manufacturer,
         device: info.device,
@@ -43,8 +61,10 @@ function buildMobileLoginPayload(config) {
         localeLanguageIso6391: info.localeLanguageIso6391 ?? 'en',
         localeCountryIso31661Alpha2: info.localeCountryIso31661Alpha2 ?? 'US',
         deviceType: _proto_1.proto.ClientPayload.UserAgent.DeviceType.PHONE,
-        deviceBoard: info.deviceBoard,
-        deviceModelType: info.deviceModelType
+        deviceModelType: info.deviceModelType,
+        ...(isIos
+            ? { distributionChannel: distributionChannelId(info.distributionChannel) }
+            : { mcc: info.mcc ?? '000', mnc: info.mnc ?? '000', deviceBoard: info.deviceBoard })
     };
     return _proto_1.proto.ClientPayload.encode({
         passive: config.passive === true,

package/dist/transport/proxy.d.ts

@@ -9,3 +9,27 @@ export declare function isProxyTransport(value: unknown): value is WaProxyTransp
 export declare function toProxyDispatcher(proxy: WaProxyTransport | undefined): WaProxyDispatcher | undefined;
 /** Narrows `proxy` to {@link WaProxyAgent} or returns `undefined`. */
 export declare function toProxyAgent(proxy: WaProxyTransport | undefined): WaProxyAgent | undefined;
+/**
+ * HTTP CONNECT endpoint a raw TCP transport dials to reach its destination.
+ *
+ * @sensitive Contains proxy credentials (`authorization`). Never log, serialize
+ * via `JSON.stringify`, or transmit unencrypted. Persist with encryption-at-rest.
+ */
+export interface WaTcpProxyEndpoint {
+    readonly hostname: string;
+    readonly port: number;
+    /** Ready-to-send `Proxy-Authorization` value when the proxy url carries credentials. */
+    readonly authorization?: string;
+}
+/**
+ * Resolves the proxy endpoint a raw TCP transport tunnels through with HTTP
+ * CONNECT.
+ *
+ * Returns `undefined` only when no proxy is configured. Proxy shapes the tunnel
+ * cannot honour throw instead of resolving to `undefined`, because dropping one
+ * silently would dial the destination directly – the opposite of what a
+ * deployment that pins its egress to a proxy asked for.
+ */
+export declare function toTcpProxyEndpoint(proxy: WaProxyTransport | undefined): WaTcpProxyEndpoint | undefined;
+/** Throws when {@link toTcpProxyEndpoint} cannot honour `proxy`. */
+export declare function assertTcpProxySupported(proxy: WaProxyTransport | undefined): void;

package/dist/transport/proxy.js

@@ -5,6 +5,9 @@ exports.isProxyAgent = isProxyAgent;
 exports.isProxyTransport = isProxyTransport;
 exports.toProxyDispatcher = toProxyDispatcher;
 exports.toProxyAgent = toProxyAgent;
+exports.toTcpProxyEndpoint = toTcpProxyEndpoint;
+exports.assertTcpProxySupported = assertTcpProxySupported;
+const bytes_1 = require("../util/bytes");
 /** Type guard for an undici-style proxy dispatcher (has `dispatch` method). */
 function isProxyDispatcher(value) {
     return (typeof value === 'object' &&
@@ -37,3 +40,85 @@ function toProxyAgent(proxy) {
     }
     return proxy;
 }
+const TCP_PROXY_HINT = 'socketOptions.proxy.ws must hold an http.Agent-style proxy pointing at an http: url (e.g. new HttpProxyAgent("http://host:port")) to tunnel raw TCP';
+/**
+ * Resolves the proxy endpoint a raw TCP transport tunnels through with HTTP
+ * CONNECT.
+ *
+ * Returns `undefined` only when no proxy is configured. Proxy shapes the tunnel
+ * cannot honour throw instead of resolving to `undefined`, because dropping one
+ * silently would dial the destination directly – the opposite of what a
+ * deployment that pins its egress to a proxy asked for.
+ */
+function toTcpProxyEndpoint(proxy) {
+    if (!proxy) {
+        return undefined;
+    }
+    if (!isProxyAgent(proxy)) {
+        if (isProxyDispatcher(proxy)) {
+            throw new Error(`undici-style proxy dispatchers cannot tunnel raw TCP – ${TCP_PROXY_HINT}`);
+        }
+        throw new Error(`unsupported proxy transport – ${TCP_PROXY_HINT}`);
+    }
+    const url = readAgentProxyUrl(proxy);
+    if (url.protocol !== 'http:') {
+        throw new Error(`proxy protocol ${url.protocol} is not supported by the raw TCP tunnel – ${TCP_PROXY_HINT}`);
+    }
+    const username = decodeProxyUserInfo(url.username, 'username');
+    const password = decodeProxyUserInfo(url.password, 'password');
+    return {
+        hostname: url.hostname,
+        port: url.port ? Number(url.port) : 80,
+        authorization: username || password
+            ? `Basic ${(0, bytes_1.bytesToBase64)(bytes_1.TEXT_ENCODER.encode(`${username}:${password}`))}`
+            : undefined
+    };
+}
+/** Throws when {@link toTcpProxyEndpoint} cannot honour `proxy`. */
+function assertTcpProxySupported(proxy) {
+    toTcpProxyEndpoint(proxy);
+}
+/**
+ * Decodes one userinfo component of a proxy url. `new URL()` keeps invalid
+ * percent escapes verbatim, so a credential holding a literal `%` would reach
+ * `decodeURIComponent` and throw a bare `URIError`. The value never reaches the
+ * message – only the field name does.
+ */
+function decodeProxyUserInfo(value, field) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        throw new Error(`proxy url ${field} contains a malformed percent escape`);
+    }
+}
+/**
+ * Reads the proxy url an `http.Agent`-style proxy exposes. Every `*-proxy-agent`
+ * package keeps it on `.proxy`, but only the http/https ones store a `URL`
+ * there – `socks-proxy-agent` stores a parsed `{ host, port, type }` endpoint.
+ */
+function readAgentProxyUrl(agent) {
+    const value = agent.proxy;
+    if (value instanceof URL) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        try {
+            return new URL(value);
+        }
+        catch {
+            throw new Error(`proxy agent exposes an unparseable proxy url ${JSON.stringify(value)}`);
+        }
+    }
+    if (isSocksProxyEndpoint(value)) {
+        throw new Error(`socks proxy agents cannot tunnel raw TCP – ${TCP_PROXY_HINT}`);
+    }
+    throw new Error(`proxy agent exposes no proxy url – ${TCP_PROXY_HINT}`);
+}
+/** Matches the `{ host, port, type }` endpoint `socks-proxy-agent` keeps on `.proxy`. */
+function isSocksProxyEndpoint(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.host === 'string' &&
+        typeof value.port === 'number');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "zapo-js",
-    "version": "1.8.1",
+    "version": "1.9.0",
     "description": "High-performance WhatsApp Web TypeScript library",
     "license": "MIT",
     "author": "vinikjkkj <contact@vinicius.email> (https://github.com/vinikjkkj)",