my-baileys 1.0.1 → 1.0.2

package/README.md

@@ -37,6 +37,7 @@ Built on top of [Baileys](https://github.com/WhiskeySockets/Baileys) (WhiskeySoc
 - [Guard against unexpected group-joins and DMs](#guard-against-unexpected-group-joins-and-dms)
 - [AntiBanned (fresh-number throttle)](#antibanned-fresh-number-send-throttle)
 - [AntiBan (full send-safety suite)](#antiban-full-send-safety-suite)
+- [Binary codec (Protobuf wire-format primitives)](#binary-codec-protobuf-wire-format-primitives)
 - [Message-builder (extra send helpers)](#message-builder-extra-send-helpers)
 - [AI watermark on button messages](#ai-watermark-on-button-messages)
 - [ACK monitor](#ack-monitor)
@@ -529,6 +530,53 @@ for what each sub-module does and how they fit together.
 
 ---
 
+## Binary codec (Protobuf wire-format primitives)
+
+Low-level Protocol Buffers wire-format helpers, exported for building your own custom
+binary/protobuf-shaped payloads — see [`lib/Utils/binary-codec.js`](lib/Utils/binary-codec.js).
+This doesn't touch how Baileys encodes/decodes WhatsApp's own messages (that's still
+`protobufjs` via `WAProto/index.js`, which you should keep using for anything WhatsApp-facing);
+it's for when *you* need direct control over some wire bytes of your own.
+
+```javascript
+import { encodeVarint, decodeVarint, zigzagEncode32, zigzagDecode32,
+         encodeFixed32, encodeFixed64, encodeTag, decodeTag,
+         encodeLengthDelimited, decodeLengthDelimited,
+         BufferWriter, WireType } from '@xayz/baileys';
+
+// varint — the base encoding used for VARINT fields and every length prefix
+encodeVarint(300);              // -> <Buffer ac 02>
+encodeVarint(123456789012345678n); // BigInt for values a plain Number can't hold precisely
+
+// ZigZag — for sint32/sint64 fields (keeps small negative numbers short)
+zigzagEncode32(-1);             // -> 1
+zigzagDecode32(1);              // -> -1
+
+// fixed-width (always little-endian, matches fixed32/fixed64/float/double)
+encodeFixed32(1);               // -> <Buffer 01 00 00 00>
+encodeFixed64(1n);              // -> <Buffer 01 00 00 00 00 00 00 00>
+
+// length-delimited framing — the spec-correct version of a manual
+// `wrapPayload(tagBuffer, data)` helper: pass a field number, get a proper tag
+encodeLengthDelimited(1, Buffer.from('hello')); // tag + varint length + data
+
+// building a multi-field message without a Buffer.concat() per field
+const w = new BufferWriter();
+w.writeTag(1, WireType.VARINT).writeVarint(300);
+w.writeLengthDelimited(2, Buffer.from('xayz'));
+const message = w.finish();
+```
+
+**On Buffer allocation efficiency** (`BufferWriter`'s reason for existing): chaining
+`Buffer.concat([a, b])` calls in a loop allocates a brand-new buffer and copies *everything so
+far* on every call — that's O(n²) total copying for n fields, and wastes the zero-fill
+`Buffer.alloc()` normally does on bytes you're about to overwrite anyway. `BufferWriter` instead
+pre-allocates with `Buffer.allocUnsafe()` and only grows (by doubling) when it actually runs
+out of room, so N writes cost O(N) overall, not O(N²) — the difference matters once you're
+writing more than a handful of fields per message.
+
+---
+
 ## Message-builder (extra send helpers)
 
 A set of convenience methods bolted onto every socket for content types that would otherwise

package/lib/Utils/binary-codec.js

@@ -0,0 +1,230 @@
+/**
+ * lib/Utils/binary-codec.js — general-purpose Protocol Buffers wire-format
+ * primitives: varint, ZigZag (sint32/sint64), fixed32/fixed64, and
+ * length-delimited framing, plus a growable BufferWriter for building up a
+ * message without repeated small allocations.
+ *
+ * This is a from-scratch, standalone module — it does not replace or touch
+ * the small `encodeVarint`/`decodeVarint` pair already private to
+ * lib/Utils/reporting-utils.js (used only for one WAM-reporting feature).
+ * That pair is intentionally 32-bit-only for its narrow use case; the
+ * functions here are exported for general use and are correct up to the
+ * full 64-bit range protobuf's own spec allows (using BigInt where a
+ * regular Number would lose precision).
+ *
+ * None of this is wired into WhatsApp's own protocol handling — Baileys
+ * already encodes/decodes the real WAProto messages via `protobufjs`
+ * (see WAProto/index.js), which is the correct, spec-complete way to do
+ * that and shouldn't be replaced by hand-rolled encoding. This module is
+ * for your OWN custom binary/protobuf-shaped payloads (e.g. a custom field
+ * inside messageContextInfo, or a side-channel binary format) where you
+ * want direct control over the wire bytes.
+ *
+ * Wire format reference: https://protobuf.dev/programming-guides/encoding/
+ */
+
+/** Protobuf wire types (the low 3 bits of every field tag). */
+export const WireType = {
+    VARINT: 0, // int32, int64, uint32, uint64, sint32, sint64, bool, enum
+    FIXED64: 1, // fixed64, sfixed64, double
+    LENGTH_DELIMITED: 2, // string, bytes, embedded messages, packed repeated fields
+    START_GROUP: 3, // deprecated in proto3 — included for completeness only
+    END_GROUP: 4, // deprecated in proto3 — included for completeness only
+    FIXED32: 5 // fixed32, sfixed32, float
+};
+
+// --- Varint (used directly for VARINT wire type, and for the length prefix
+// of every LENGTH_DELIMITED field) ---
+
+/**
+ * Encodes a non-negative integer as a protobuf varint.
+ * Accepts a Number (must be a safe, non-negative integer) or a BigInt
+ * (use BigInt for values that don't fit in a 32-bit int, e.g. uint64/int64
+ * field values > 2^32 — a plain Number loses precision above 2^53).
+ */
+export const encodeVarint = (value) => {
+    let n = typeof value === 'bigint' ? value : BigInt(value);
+    if (n < 0n) {
+        throw new RangeError('encodeVarint: value must be non-negative — use zigzagEncode32/64 first for signed (sint32/sint64) fields');
+    }
+    const bytes = [];
+    while (n >= 0x80n) {
+        bytes.push(Number(n & 0x7fn) | 0x80);
+        n >>= 7n;
+    }
+    bytes.push(Number(n));
+    return Buffer.from(bytes);
+};
+
+/**
+ * Decodes a varint starting at `offset`.
+ * Returns `{ value, bytesRead }`. `value` is a Number if it fits safely
+ * (<= Number.MAX_SAFE_INTEGER), otherwise a BigInt — check
+ * `typeof result.value` if you need to know which you got.
+ */
+export const decodeVarint = (buffer, offset = 0) => {
+    let result = 0n;
+    let shift = 0n;
+    let bytesRead = 0;
+    while (true) {
+        if (offset + bytesRead >= buffer.length) {
+            throw new RangeError('decodeVarint: unexpected end of buffer');
+        }
+        const byte = buffer[offset + bytesRead];
+        result |= BigInt(byte & 0x7f) << shift;
+        bytesRead++;
+        if ((byte & 0x80) === 0) {
+            break;
+        }
+        shift += 7n;
+        if (shift > 70n) {
+            throw new RangeError('decodeVarint: varint is too long (more than 10 bytes)');
+        }
+    }
+    const value = result <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(result) : result;
+    return { value, bytesRead };
+};
+
+// --- ZigZag encoding (for sint32/sint64 — maps signed values to unsigned
+// ones so small-magnitude negative numbers still encode as short varints) ---
+
+/** ZigZag-encodes a 32-bit signed integer. `n` must be in the int32 range. */
+export const zigzagEncode32 = (n) => ((n << 1) ^ (n >> 31)) >>> 0;
+
+/** Decodes a ZigZag-encoded 32-bit unsigned integer back to a signed int32. */
+export const zigzagDecode32 = (n) => (n >>> 1) ^ -(n & 1);
+
+/** ZigZag-encodes a 64-bit signed integer (BigInt in, BigInt out). */
+export const zigzagEncode64 = (n) => {
+    const v = typeof n === 'bigint' ? n : BigInt(n);
+    return BigInt.asUintN(64, (v << 1n) ^ (v >> 63n));
+};
+
+/** Decodes a ZigZag-encoded 64-bit unsigned BigInt back to a signed BigInt. */
+export const zigzagDecode64 = (n) => {
+    const v = typeof n === 'bigint' ? n : BigInt(n);
+    return (v >> 1n) ^ -(v & 1n);
+};
+
+// --- Fixed-width encodings (always little-endian, per the protobuf spec) ---
+
+/** Encodes a 32-bit value as 4 fixed little-endian bytes (fixed32/sfixed32/float use this width). */
+export const encodeFixed32 = (n) => {
+    const buf = Buffer.allocUnsafe(4);
+    buf.writeUInt32LE(n >>> 0, 0);
+    return buf;
+};
+
+/** Decodes 4 little-endian bytes at `offset` back to an unsigned 32-bit integer. */
+export const decodeFixed32 = (buffer, offset = 0) => buffer.readUInt32LE(offset);
+
+/** Encodes a 64-bit value (BigInt) as 8 fixed little-endian bytes (fixed64/sfixed64/double use this width). */
+export const encodeFixed64 = (n) => {
+    const buf = Buffer.allocUnsafe(8);
+    buf.writeBigUInt64LE(BigInt.asUintN(64, typeof n === 'bigint' ? n : BigInt(n)), 0);
+    return buf;
+};
+
+/** Decodes 8 little-endian bytes at `offset` back to an unsigned 64-bit BigInt. */
+export const decodeFixed64 = (buffer, offset = 0) => buffer.readBigUInt64LE(offset);
+
+// --- Field tags and length-delimited framing ---
+
+/** Builds a protobuf field tag: `(fieldNumber << 3) | wireType`, varint-encoded. */
+export const encodeTag = (fieldNumber, wireType) => encodeVarint((fieldNumber << 3) | wireType);
+
+/** Splits a decoded tag varint back into `{ fieldNumber, wireType }`. */
+export const decodeTag = (tagValue) => {
+    const n = typeof tagValue === 'bigint' ? Number(tagValue) : tagValue;
+    return { fieldNumber: n >>> 3, wireType: n & 0x7 };
+};
+
+/**
+ * Frames `data` as a protobuf LENGTH_DELIMITED field: tag + varint length + data.
+ * This is the generalized, spec-correct version of the `wrapPayload(tag, data)`
+ * helper — pass a real field number instead of a raw tag Buffer and this
+ * builds a proper varint tag for you:
+ *
+ *   wrapPayload(tagBuffer, data)                      // your original
+ *   encodeLengthDelimited(fieldNumber, data)           // spec-correct equivalent
+ */
+export const encodeLengthDelimited = (fieldNumber, data) => (
+    Buffer.concat([encodeTag(fieldNumber, WireType.LENGTH_DELIMITED), encodeVarint(data.length), data])
+);
+
+/**
+ * Reads one length-delimited field's payload starting at `offset` (which
+ * must point at the length varint, i.e. right after the tag). Returns
+ * `{ data, bytesRead }` where `bytesRead` covers the length prefix AND the
+ * payload, so `offset + bytesRead` is the start of the next field.
+ */
+export const decodeLengthDelimited = (buffer, offset = 0) => {
+    const { value: length, bytesRead: lengthBytes } = decodeVarint(buffer, offset);
+    const len = typeof length === 'bigint' ? Number(length) : length;
+    const dataStart = offset + lengthBytes;
+    if (dataStart + len > buffer.length) {
+        throw new RangeError('decodeLengthDelimited: declared length exceeds buffer bounds');
+    }
+    return { data: buffer.subarray(dataStart, dataStart + len), bytesRead: lengthBytes + len };
+};
+
+// --- Efficient buffer building ---
+
+/**
+ * A growable buffer writer for building up a message field-by-field without
+ * a `Buffer.concat()` (and therefore a full copy) on every single write.
+ *
+ * Why this matters: `Buffer.concat([a, b])` allocates a brand-new buffer and
+ * copies both `a` and `b` into it every time. Chaining many small
+ * `Buffer.concat()` calls in a loop (once per field) is O(n²) in the total
+ * bytes written — fine for a handful of fields, wasteful for a message with
+ * hundreds. `BufferWriter` instead pre-allocates a working buffer with
+ * `Buffer.allocUnsafe` (skips the zero-fill `Buffer.alloc` normally does,
+ * safe here because every byte gets overwritten before being read) and
+ * doubles its capacity only when it actually runs out — so the amortized
+ * cost of N writes is O(N), not O(N²), and there's no wasted zero-filling.
+ */
+export class BufferWriter {
+    constructor(initialCapacity = 256) {
+        this._buf = Buffer.allocUnsafe(Math.max(initialCapacity, 16));
+        this._len = 0;
+    }
+    _ensure(extra) {
+        const needed = this._len + extra;
+        if (needed <= this._buf.length) return;
+        let newCapacity = this._buf.length * 2;
+        while (newCapacity < needed) newCapacity *= 2;
+        const grown = Buffer.allocUnsafe(newCapacity);
+        this._buf.copy(grown, 0, 0, this._len);
+        this._buf = grown;
+    }
+    writeBytes(data) {
+        this._ensure(data.length);
+        data.copy(this._buf, this._len);
+        this._len += data.length;
+        return this;
+    }
+    writeVarint(value) {
+        return this.writeBytes(encodeVarint(value));
+    }
+    writeTag(fieldNumber, wireType) {
+        return this.writeBytes(encodeTag(fieldNumber, wireType));
+    }
+    writeFixed32(n) {
+        return this.writeBytes(encodeFixed32(n));
+    }
+    writeFixed64(n) {
+        return this.writeBytes(encodeFixed64(n));
+    }
+    /** Writes a full LENGTH_DELIMITED field (tag + length + bytes) in one call. */
+    writeLengthDelimited(fieldNumber, data) {
+        return this.writeBytes(encodeLengthDelimited(fieldNumber, data));
+    }
+    get length() {
+        return this._len;
+    }
+    /** Returns the written bytes as a Buffer. Copies — safe to keep using the writer afterward. */
+    finish() {
+        return Buffer.from(this._buf.subarray(0, this._len));
+    }
+}

package/lib/Utils/index.js

@@ -1,4 +1,5 @@
 export * from './generics.js';
+export * from './binary-codec.js';
 export * from './decode-wa-message.js';
 export * from './messages.js';
 export * from './messages-media.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "my-baileys",
   "type": "module",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "A WebSockets library for interacting with WhatsApp Web — XYCoolcraft fork of Baileys",
   "keywords": [
     "xycoolcraft",
@@ -25,6 +25,7 @@
   "files": [
     "lib/**/*",
     "WAProto/**/*",
+    "scripts/**/*",
     "engine-requirements.js"
   ],
   "scripts": {
@@ -39,6 +40,7 @@
     "prepack": "",
     "prepare": "",
     "preinstall": "node ./engine-requirements.js",
+    "postinstall": "node ./scripts/self-test.js || exit 0",
     "release": "release-it",
     "test": "jest",
     "publish:npm": "bash upload-npm.sh"

package/scripts/self-test.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * self-test.js — runs automatically right after `npm install` (via the
+ * "postinstall" script in package.json). Checks, BEFORE you write a single
+ * line of bot code:
+ *   1. The package's own files loaded correctly (no broken install).
+ *   2. This machine can actually open a WebSocket to WhatsApp's servers.
+ *
+ * Why: the single most common "why doesn't my bot work" report is a
+ * hosting/network problem that has nothing to do with your bot code —
+ * finding that out AFTER writing your whole bot is a waste of your time.
+ * This catches it at install time instead, with a clear pass/fail printed
+ * right in your terminal / panel console.
+ *
+ * This never fails the install itself (always exits 0) — a failing
+ * connectivity check here doesn't mean your files are broken, and blocking
+ * `npm install` over a transient network hiccup would be worse than useless
+ * in CI/CD pipelines. It just makes sure you SEE the warning before you go
+ * looking for bugs in the wrong place.
+ *
+ * Skip this entirely with: BAILEYS_SKIP_SELFTEST=1 npm install
+ */
+import chalk from 'chalk';
+import WebSocket from 'ws';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+
+const results = [];
+const record = (name, pass, detail = '') => results.push({ name, pass, detail });
+
+function banner() {
+    console.log('');
+    console.log(chalk.hex('#a855f7')('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    console.log(chalk.hex('#a855f7').bold('  @xayz/baileys — post-install self-test'));
+    console.log(chalk.gray('  Checking your environment before you start building your bot.'));
+    console.log(chalk.hex('#a855f7')('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    console.log('');
+}
+
+/** Check 1: did the package's own files load without throwing? */
+async function testModuleIntegrity() {
+    try {
+        const mod = await import(path.join(packageRoot, 'lib', 'index.js'));
+        const ok = typeof mod.default === 'function';
+        record('Package installed correctly (makeWASocket loaded)', ok,
+            ok ? '' : 'lib/index.js loaded, but makeWASocket is not a function — the install may be corrupted. Try a clean `npm install` again.');
+    }
+    catch (e) {
+        record('Package installed correctly (makeWASocket loaded)', false,
+            `Failed to import lib/index.js: ${e.message} — try removing node_modules and package-lock.json, then \`npm install\` again.`);
+    }
+}
+
+/** Check 2: can this machine actually open a WebSocket to WhatsApp's servers? */
+function testNetworkReachability() {
+    return new Promise((resolve) => {
+        const url = 'wss://web.whatsapp.com/ws/chat';
+        const start = Date.now();
+        let done = false;
+
+        let ws;
+        try {
+            ws = new WebSocket(url, {
+                origin: 'https://web.whatsapp.com',
+                headers: { 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36' }
+            });
+        }
+        catch (e) {
+            record('This server can reach WhatsApp', false, `Failed to open a connection: ${e.message}`);
+            resolve();
+            return;
+        }
+
+        const finish = (pass, detail) => {
+            if (done) return;
+            done = true;
+            clearTimeout(timer);
+            record('This server can reach WhatsApp', pass, detail);
+            try { ws.terminate(); } catch { }
+            resolve();
+        };
+
+        const timer = setTimeout(() => {
+            finish(false, `Timed out after ${Date.now() - start}ms — the socket never opened. ` +
+                'This strongly suggests this network/host is blocking or throttling connections to ' +
+                'WhatsApp, NOT a code problem. Try a different server/IP if this keeps happening.');
+        }, 12000);
+
+        ws.on('open', () => finish(true, `Succeeded in ${Date.now() - start}ms`));
+        ws.on('error', (err) => finish(false, `${err.message} (after ${Date.now() - start}ms) — check your hosting's firewall/proxy.`));
+        ws.on('unexpected-response', (req, res) => {
+            finish(false, `Server responded, but it wasn't a WebSocket upgrade (HTTP ${res.statusCode}) — ` +
+                'an ISP or hosting proxy/firewall is likely intercepting this connection.');
+        });
+    });
+}
+
+function printResults() {
+    for (const r of results) {
+        const icon = r.pass ? chalk.green('✅') : chalk.red('❌');
+        console.log(`${icon} ${r.name}`);
+        if (r.detail) console.log(chalk.gray(`   ${r.detail}`));
+    }
+    console.log('');
+
+    const allPass = results.every(r => r.pass);
+    if (allPass) {
+        console.log(chalk.green.bold('  All checks passed. You\'re good to go — start building/running your bot.'));
+    }
+    else {
+        console.log(chalk.yellow.bold('  ⚠  Something above failed.'));
+        console.log(chalk.yellow('  This does NOT stop the install (so it won\'t break your CI/CD pipeline),'));
+        console.log(chalk.yellow('  but if your bot later fails to connect or pair, check the point above'));
+        console.log(chalk.yellow('  before you start debugging your code — it\'s the most likely cause.'));
+    }
+    console.log(chalk.hex('#a855f7')('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+    console.log('');
+}
+
+(async () => {
+    if (process.env.BAILEYS_SKIP_SELFTEST === '1') {
+        console.log(chalk.gray('[@xayz/baileys] Self-test skipped (BAILEYS_SKIP_SELFTEST=1).'));
+        process.exit(0);
+    }
+
+    banner();
+    await testModuleIntegrity();
+    await testNetworkReachability();
+    printResults();
+
+    // Always exit 0 — see the comment at the top of this file for why.
+    process.exit(0);
+})().catch((e) => {
+    // Safety net: nothing that goes wrong in this TEST script itself should
+    // ever fail the user's `npm install`.
+    console.log(chalk.red(`[@xayz/baileys] Self-test error (ignored): ${e.message}`));
+    process.exit(0);
+});