ishumdz-bail 1.0.0

package/lib/Signal/lid-mapping.js

@@ -0,0 +1,277 @@
+import { LRUCache } from 'lru-cache';
+import { isHostedPnUser, isLidUser, isPnUser, jidDecode, jidNormalizedUser, WAJIDDomains } from '../WABinary/index.js';
+export class LIDMappingStore {
+    constructor(keys, logger, pnToLIDFunc) {
+        this.mappingCache = new LRUCache({
+            ttl: 3 * 24 * 60 * 60 * 1000, // 7 days
+            ttlAutopurge: true,
+            updateAgeOnGet: true
+        });
+        this.inflightLIDLookups = new Map();
+        this.inflightPNLookups = new Map();
+        this.keys = keys;
+        this.pnToLIDFunc = pnToLIDFunc;
+        this.logger = logger;
+    }
+    async storeLIDPNMappings(pairs) {
+        if (pairs.length === 0)
+            return;
+        const validatedPairs = [];
+        for (const { lid, pn } of pairs) {
+            if (!((isLidUser(lid) && isPnUser(pn)) || (isPnUser(lid) && isLidUser(pn)))) {
+                this.logger.warn(`Invalid LID-PN mapping: ${lid}, ${pn}`);
+                continue;
+            }
+            const lidDecoded = jidDecode(lid);
+            const pnDecoded = jidDecode(pn);
+            if (!lidDecoded || !pnDecoded)
+                continue;
+            validatedPairs.push({ pnUser: pnDecoded.user, lidUser: lidDecoded.user });
+        }
+        if (validatedPairs.length === 0)
+            return;
+        const cacheMissSet = new Set();
+        const existingMappings = new Map();
+        for (const { pnUser } of validatedPairs) {
+            const cached = this.mappingCache.get(`pn:${pnUser}`);
+            if (cached) {
+                existingMappings.set(pnUser, cached);
+            }
+            else {
+                cacheMissSet.add(pnUser);
+            }
+        }
+        if (cacheMissSet.size > 0) {
+            const cacheMisses = [...cacheMissSet];
+            this.logger.trace(`Batch fetching ${cacheMisses.length} LID mappings from database`);
+            const stored = await this.keys.get('lid-mapping', cacheMisses);
+            for (const pnUser of cacheMisses) {
+                const existingLidUser = stored[pnUser];
+                if (existingLidUser) {
+                    existingMappings.set(pnUser, existingLidUser);
+                    this.mappingCache.set(`pn:${pnUser}`, existingLidUser);
+                    this.mappingCache.set(`lid:${existingLidUser}`, pnUser);
+                }
+            }
+        }
+        const pairMap = {};
+        for (const { pnUser, lidUser } of validatedPairs) {
+            const existingLidUser = existingMappings.get(pnUser);
+            if (existingLidUser === lidUser) {
+                this.logger.debug({ pnUser, lidUser }, 'LID mapping already exists, skipping');
+                continue;
+            }
+            pairMap[pnUser] = lidUser;
+        }
+        if (Object.keys(pairMap).length === 0)
+            return;
+        this.logger.trace({ pairMap }, `Storing ${Object.keys(pairMap).length} pn mappings`);
+        const batchData = {};
+        for (const [pnUser, lidUser] of Object.entries(pairMap)) {
+            batchData[pnUser] = lidUser;
+            batchData[`${lidUser}_reverse`] = pnUser;
+        }
+        await this.keys.transaction(async () => {
+            await this.keys.set({ 'lid-mapping': batchData });
+        }, 'lid-mapping');
+        // Update cache after successful DB write
+        for (const [pnUser, lidUser] of Object.entries(pairMap)) {
+            this.mappingCache.set(`pn:${pnUser}`, lidUser);
+            this.mappingCache.set(`lid:${lidUser}`, pnUser);
+        }
+    }
+    async getLIDForPN(pn) {
+        return (await this.getLIDsForPNs([pn]))?.[0]?.lid || null;
+    }
+    async getLIDsForPNs(pns) {
+        if (pns.length === 0)
+            return null;
+        const sortedPns = [...new Set(pns)].sort();
+        const cacheKey = sortedPns.join(',');
+        const inflight = this.inflightLIDLookups.get(cacheKey);
+        if (inflight) {
+            this.logger.trace(`Coalescing getLIDsForPNs request for ${sortedPns.length} PNs`);
+            return inflight;
+        }
+        const promise = this._getLIDsForPNsImpl(pns);
+        this.inflightLIDLookups.set(cacheKey, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            this.inflightLIDLookups.delete(cacheKey);
+        }
+    }
+    async _getLIDsForPNsImpl(pns) {
+        const usyncFetch = {};
+        const successfulPairs = {};
+        const pending = [];
+        const addResolvedPair = (pn, decoded, lidUser) => {
+            const normalizedLidUser = lidUser.toString();
+            if (!normalizedLidUser) {
+                this.logger.warn(`Invalid or empty LID user for PN ${pn}: lidUser = "${lidUser}"`);
+                return false;
+            }
+            // Push the PN device ID to the LID to maintain device separation
+            const pnDevice = decoded.device !== undefined ? decoded.device : 0;
+            const deviceSpecificLid = `${normalizedLidUser}${!!pnDevice ? `:${pnDevice}` : ``}@${decoded.server === 'hosted' ? 'hosted.lid' : 'lid'}`;
+            this.logger.trace(`getLIDForPN: ${pn} → ${deviceSpecificLid} (user mapping with device ${pnDevice})`);
+            successfulPairs[pn] = { lid: deviceSpecificLid, pn };
+            return true;
+        };
+        for (const pn of pns) {
+            if (!isPnUser(pn) && !isHostedPnUser(pn))
+                continue;
+            const decoded = jidDecode(pn);
+            if (!decoded)
+                continue;
+            const pnUser = decoded.user;
+            const cached = this.mappingCache.get(`pn:${pnUser}`);
+            if (cached && typeof cached === 'string') {
+                if (!addResolvedPair(pn, decoded, cached)) {
+                    this.logger.warn(`Invalid entry for ${pn} (pair not resolved)`);
+                    continue;
+                }
+                continue;
+            }
+            pending.push({ pn, pnUser, decoded });
+        }
+        if (pending.length) {
+            const pnUsers = [...new Set(pending.map(item => item.pnUser))];
+            const stored = await this.keys.get('lid-mapping', pnUsers);
+            for (const pnUser of pnUsers) {
+                const lidUser = stored[pnUser];
+                if (lidUser && typeof lidUser === 'string') {
+                    this.mappingCache.set(`pn:${pnUser}`, lidUser);
+                    this.mappingCache.set(`lid:${lidUser}`, pnUser);
+                }
+            }
+            for (const { pn, pnUser, decoded } of pending) {
+                const cached = this.mappingCache.get(`pn:${pnUser}`);
+                if (cached && typeof cached === 'string') {
+                    if (!addResolvedPair(pn, decoded, cached)) {
+                        this.logger.warn(`Invalid entry for ${pn} (pair not resolved)`);
+                        continue;
+                    }
+                }
+                else {
+                    this.logger.trace(`No LID mapping found for PN user ${pnUser}; batch getting from USync`);
+                    const device = decoded.device || 0;
+                    let normalizedPn = jidNormalizedUser(pn);
+                    if (isHostedPnUser(normalizedPn)) {
+                        normalizedPn = `${pnUser}@s.whatsapp.net`;
+                    }
+                    if (!usyncFetch[normalizedPn]) {
+                        usyncFetch[normalizedPn] = [device];
+                    }
+                    else {
+                        usyncFetch[normalizedPn]?.push(device);
+                    }
+                }
+            }
+        }
+        if (Object.keys(usyncFetch).length > 0) {
+            const result = await this.pnToLIDFunc?.(Object.keys(usyncFetch)); // this function already adds LIDs to mapping
+            if (result && result.length > 0) {
+                await this.storeLIDPNMappings(result);
+                for (const pair of result) {
+                    const pnDecoded = jidDecode(pair.pn);
+                    const pnUser = pnDecoded?.user;
+                    if (!pnUser)
+                        continue;
+                    const lidUser = jidDecode(pair.lid)?.user;
+                    if (!lidUser)
+                        continue;
+                    for (const device of usyncFetch[pair.pn]) {
+                        const deviceSpecificLid = `${lidUser}${!!device ? `:${device}` : ``}@${device === 99 ? 'hosted.lid' : 'lid'}`;
+                        this.logger.trace(`getLIDForPN: USYNC success for ${pair.pn} → ${deviceSpecificLid} (user mapping with device ${device})`);
+                        const deviceSpecificPn = `${pnUser}${!!device ? `:${device}` : ``}@${device === 99 ? 'hosted' : 's.whatsapp.net'}`;
+                        successfulPairs[deviceSpecificPn] = { lid: deviceSpecificLid, pn: deviceSpecificPn };
+                    }
+                }
+            }
+            else {
+                this.logger.warn('USync fetch yielded no results for pending PNs');
+            }
+        }
+        return Object.values(successfulPairs).length > 0 ? Object.values(successfulPairs) : null;
+    }
+    async getPNForLID(lid) {
+        return (await this.getPNsForLIDs([lid]))?.[0]?.pn || null;
+    }
+    async getPNsForLIDs(lids) {
+        if (lids.length === 0)
+            return null;
+        const sortedLids = [...new Set(lids)].sort();
+        const cacheKey = sortedLids.join(',');
+        const inflight = this.inflightPNLookups.get(cacheKey);
+        if (inflight) {
+            this.logger.trace(`Coalescing getPNsForLIDs request for ${sortedLids.length} LIDs`);
+            return inflight;
+        }
+        const promise = this._getPNsForLIDsImpl(lids);
+        this.inflightPNLookups.set(cacheKey, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            this.inflightPNLookups.delete(cacheKey);
+        }
+    }
+    async _getPNsForLIDsImpl(lids) {
+        const successfulPairs = {};
+        const pending = [];
+        const addResolvedPair = (lid, decoded, pnUser) => {
+            if (!pnUser || typeof pnUser !== 'string') {
+                return false;
+            }
+            const lidDevice = decoded.device !== undefined ? decoded.device : 0;
+            const pnJid = `${pnUser}:${lidDevice}@${decoded.domainType === WAJIDDomains.HOSTED_LID ? 'hosted' : 's.whatsapp.net'}`;
+            this.logger.trace(`Found reverse mapping: ${lid} → ${pnJid}`);
+            successfulPairs[lid] = { lid, pn: pnJid };
+            return true;
+        };
+        for (const lid of lids) {
+            if (!isLidUser(lid))
+                continue;
+            const decoded = jidDecode(lid);
+            if (!decoded)
+                continue;
+            const lidUser = decoded.user;
+            const cached = this.mappingCache.get(`lid:${lidUser}`);
+            if (cached && typeof cached === 'string') {
+                addResolvedPair(lid, decoded, cached);
+                continue;
+            }
+            pending.push({ lid, lidUser, decoded });
+        }
+        if (pending.length) {
+            const reverseKeys = [...new Set(pending.map(item => `${item.lidUser}_reverse`))];
+            const stored = await this.keys.get('lid-mapping', reverseKeys);
+            for (const { lid, lidUser, decoded } of pending) {
+                let pnUser = this.mappingCache.get(`lid:${lidUser}`);
+                if (!pnUser || typeof pnUser !== 'string') {
+                    pnUser = stored[`${lidUser}_reverse`];
+                    if (pnUser && typeof pnUser === 'string') {
+                        this.mappingCache.set(`lid:${lidUser}`, pnUser);
+                        this.mappingCache.set(`pn:${pnUser}`, lidUser);
+                    }
+                }
+                if (pnUser && typeof pnUser === 'string') {
+                    addResolvedPair(lid, decoded, pnUser);
+                }
+                else {
+                    this.logger.trace(`No reverse mapping found for LID user: ${lidUser}`);
+                }
+            }
+        }
+        return Object.values(successfulPairs).length ? Object.values(successfulPairs) : null;
+    }
+    /**
+     * Close the cache and release resources
+     */
+    close() {
+        this.mappingCache.clear();
+    }
+}
+//# sourceMappingURL=lid-mapping.js.map

package/lib/Socket/Client/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './websocket.js';
+//# sourceMappingURL=index.js.map

package/lib/Socket/Client/types.js

@@ -0,0 +1,11 @@
+import { EventEmitter } from 'events';
+import { URL } from 'url';
+export class AbstractSocketClient extends EventEmitter {
+    constructor(url, config) {
+        super();
+        this.url = url;
+        this.config = config;
+        this.setMaxListeners(0);
+    }
+}
+//# sourceMappingURL=types.js.map

package/lib/Socket/Client/websocket.js

@@ -0,0 +1,84 @@
+import WebSocket from 'ws';
+import { DEFAULT_ORIGIN } from '../../Defaults/index.js';
+import { AbstractSocketClient } from './types.js';
+export class WebSocketClient extends AbstractSocketClient {
+    constructor() {
+        super(...arguments);
+        this.socket = null;
+    }
+    get isOpen() {
+        return this.socket?.readyState === WebSocket.OPEN;
+    }
+    get isClosed() {
+        return this.socket === null || this.socket?.readyState === WebSocket.CLOSED;
+    }
+    get isClosing() {
+        return this.socket === null || this.socket?.readyState === WebSocket.CLOSING;
+    }
+    get isConnecting() {
+        return this.socket?.readyState === WebSocket.CONNECTING;
+    }
+    connect() {
+        if (this.socket) {
+            return;
+        }
+        
+        const headers = {
+            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36',
+            'Accept-Language': 'en-US,en;q=0.9',
+            'Accept-Encoding': 'gzip, deflate, br',
+            'Accept': '*/*',
+            'DNT': '1',
+            'Pragma': 'no-cache',
+            'Cache-Control': 'no-cache',
+            'Sec-Fetch-Dest': 'empty',
+            'Sec-Fetch-Mode': 'cors',
+            'Sec-Fetch-Site': 'same-origin',
+            'Sec-GPC': '1',
+            ...this.config.options?.headers
+        };
+
+        this.socket = new WebSocket(this.url, {
+            origin: DEFAULT_ORIGIN,
+            headers: headers,
+            handshakeTimeout: this.config.connectTimeoutMs || 30000,
+            timeout: this.config.connectTimeoutMs || 30000,
+            agent: this.config.agent,
+            perMessageDeflate: false,
+            maxPayload: 100 * 1024 * 1024,
+            rejectUnauthorized: false,
+            keepalive: true,
+            keepaliveInterval: 25000
+        });
+        
+        this.socket.setMaxListeners(0);
+        
+        this.socket.on('error', (error) => {
+            const errorCode = error?.code;
+            if (errorCode === 'ECONNREFUSED' || errorCode === 'ENOTFOUND') {
+                console.warn('WebSocket connection refused, retrying...');
+            }
+        });
+        
+        const events = ['close', 'error', 'upgrade', 'message', 'open', 'ping', 'pong', 'unexpected-response'];
+        for (const event of events) {
+            this.socket?.on(event, (...args) => this.emit(event, ...args));
+        }
+    }
+    async close() {
+        if (!this.socket) {
+            return;
+        }
+        const closePromise = new Promise(resolve => {
+            this.socket?.once('close', resolve);
+        });
+        this.socket.close();
+        await closePromise;
+        this.socket = null;
+    }
+    send(str, cb) {
+        this.socket?.send(str, cb);
+        return Boolean(this.socket);
+    }
+}
+//# sourceMappingURL=websocket.js.map

package/lib/Socket/ban-checker.js

@@ -0,0 +1,265 @@
+import {
+    USyncQuery,
+    USyncUser
+} from '../WAUSync/index.js';
+
+// ────────────────────────────────────────────────────────────────────────
+// PASQUA BAN CHECKER API — 4-factor WhatsApp ban-status detection
+// ────────────────────────────────────────────────────────────────────────
+//
+// Usage:
+//   const result = await sock.checkBanStatus('1234567890');
+//   // or with @s.whatsapp.net suffix:
+//   const result = await sock.checkBanStatus('1234567890@s.whatsapp.net');
+//
+// Returned shape:
+//   {
+//     status : 'ACTIVE' | 'PROFILE_HIDDEN' | 'LIKELY_ACTIVE' | 'BANNED' |
+//              'OFF_WHATSAPP' | 'UNKNOWN',
+//     emoji  : '🟢' | '🟡' | '🔴' | '❓',
+//     confidence : 0..1,
+//     deviceCount: number | null,      // identity-key probe result
+//     registryExists: boolean | null,  // sock.onWhatsApp result
+//     pageVisible: boolean | null,     // public send-page profile probe
+//     profileName: string | null       // display name if visible
+//   }
+//
+// THE FOUR FACTORS (all exercised against WhatsApp's own servers):
+//   Factor A — Live registry        (sock.onWhatsApp)
+//   Factor B — Public send-page     (og:title / og:image on api.whatsapp.com)
+//   Factor C — Identity-key device  (USync device-protocol probe — the
+//                strongest signal: banned numbers have their keys destroyed)
+//   Factor D — Device-count signature
+//        2+ devices          → real multi-device account → ACTIVE
+//        1 device + generic  → stale key mid-deletion → BANNED
+//        0 devices           → keys fully garbage-collected → BANNED/OFF-WHATSAPP
+//        null (probe failed) → falls back to Factors A + B
+
+// ── Number normalization ───────────────────────────────────────────────
+export function normalizeJidTarget(input) {
+    if (!input) return null;
+    let num = String(input).replace(/[^0-9+]/g, '');
+    if (!num) return null;
+    if (num.startsWith('+')) num = num.slice(1);
+    if (num.endsWith('@s.whatsapp.net')) {
+        num = num.replace('@s.whatsapp.net', '');
+    }
+    if (num.length < 8 || num.length > 15) return null;
+    return num;
+}
+
+// ── Factor B: public send-page profile probe ───────────────────────────
+// Active account → og:title carries the display name
+//                  AND og:image points to their profile picture (pps.whatsapp.net)
+// Banned/offline → generic "Share on WhatsApp" title
+//                  AND og:image is WhatsApp's default avatar (static.whatsapp.net)
+const DEFAULT_AVATAR_DOMAIN = 'static.whatsapp.net';
+const OWN_AVATAR_DOMAIN = 'pps.whatsapp.net';
+
+export async function probeSendPage(num, fetchImpl) {
+    const impl = fetchImpl || globalThis.fetch;
+    if (!impl) return { ok: false, generic: null, title: null, hasOwnPic: false };
+    // Retry twice: WhatsApp's edge servers can return the generic page
+    // momentarily even for active numbers (eventual-consistency blip).
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const res = await impl(
+                `https://api.whatsapp.com/send?phone=${encodeURIComponent(num)}&type=phone_number&app_absent=0`,
+                {
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36',
+                        'Accept-Language': 'en-US,en;q=0.9',
+                    },
+                    signal: AbortSignal.timeout(15000),
+                }
+            );
+            const html = await res.text();
+
+            // Decode the title (WhatsApp encodes fancy fonts as HTML entities)
+            const raw = ((html.match(/property="og:title" content="([^"]*)"/i) || [])[1] || '');
+            const title = raw.replace(/&#x([0-9a-f]+);/gi, (_, h) => String.fromCodePoint(parseInt(h, 16)));
+            const generic = /share on whatsapp/i.test(title);
+
+            const avatar = ((html.match(/property="og:image" content="([^"]*)"/i) || [])[1] || '');
+            const hasOwnPic = !generic && new RegExp(OWN_AVATAR_DOMAIN, 'i').test(avatar);
+
+            // A real display name is a strong ACTIVE signal; bail early
+            if (!generic) {
+                return { ok: true, generic: false, title: title.trim(), hasOwnPic };
+            }
+            // Generic page — only consider it stable after the final retry
+            if (attempt === 2) {
+                return { ok: true, generic: true, title: null, hasOwnPic: false };
+            }
+            // Intermediate retries: wait before re-probing
+            await new Promise(r => setTimeout(r, 1500));
+        }
+        catch (_) {
+            if (attempt === 2) return { ok: false, generic: null, title: null, hasOwnPic: false };
+            await new Promise(r => setTimeout(r, 1500));
+        }
+    }
+    return { ok: false, generic: null, title: null, hasOwnPic: false };
+}
+
+// ── Factor C: identity-key (device) probe ──────────────────────────────
+// The bot's own authenticated session can query any number's device list
+// via USync device-protocol. A banned number's identity keys are destroyed
+// on the server, so this query returns zero devices (or fails) for banned
+// accounts while an active account returns its real device list.
+export async function probeIdentityDevices(sock, target) {
+    try {
+        if (typeof sock.executeUSyncQuery !== 'function') return null;
+        const q = new USyncQuery()
+            .withDeviceProtocol()
+            .withUser(new USyncUser().withId(target + '@s.whatsapp.net'));
+        const devRes = await sock.executeUSyncQuery(q);
+        if (devRes && Array.isArray(devRes.list) && devRes.list.length > 0) {
+            const devInfo = devRes.list[0];
+            const dl = devInfo?.devices?.deviceList || devInfo?.devices?.device_list || null;
+            let devices = Array.isArray(dl) ? dl : null;
+            // NOTE: devRes shape depends on fork version; if we can't parse
+            // it, keep devices === null (probe failed)
+            if (devices === null && devInfo && devInfo.devices) {
+                const d = devInfo.devices;
+                for (const k of Object.keys(d)) {
+                    if (Array.isArray(d[k])) { devices = d[k]; break; }
+                }
+            }
+            return devices === null ? null : devices.length;
+        }
+        // Parsed response but empty list → zero devices on the servers
+        return 0;
+    }
+    catch (_) { /* probe failed */ }
+    return null;
+}
+
+// ── Factor A: live registry ────────────────────────────────────────────
+export async function probeRegistry(sock, target) {
+    try {
+        if (typeof sock.onWhatsApp !== 'function') return null;
+        const onWA = await sock.onWhatsApp(target + '@s.whatsapp.net');
+        return Array.isArray(onWA) && onWA.length > 0 && onWA[0].exists === true;
+    }
+    catch (_) { /* registry probe failed */ }
+    return null;
+}
+
+// ── The verdict ────────────────────────────────────────────────────────
+export function buildVerdict(target, { devices, registry, page }) {
+    const profileName = page?.title || null;
+    const pageVisible = page?.ok === true && page.generic === false;
+    const pageGeneric = page?.ok === true && page.generic === true;
+
+    // Factor C/D (identity-key probe) is the strongest signal — use it first
+    if (devices !== null) {
+        if (devices >= 2 && page?.ok) {
+            return {
+                status: 'ACTIVE', emoji: '🟢', confidence: 0.99,
+                deviceCount: devices, registryExists: registry,
+                pageVisible, profileName
+            };
+        }
+        if (devices === 1 && pageGeneric) {
+            // The ban-decay signature: WhatsApp removes keys lazily,
+            // so a banned account often leaves ONE orphaned stale key
+            // with its public profile already stripped.
+            return {
+                status: 'BANNED', emoji: '🔴', confidence: 0.9,
+                deviceCount: devices, registryExists: registry,
+                pageVisible: false, profileName: null
+            };
+        }
+        if (devices === 1 && pageVisible) {
+            // Single device + name/photo visible: rare but possible
+            // (new install, no linked devices) — benefit of the doubt.
+            return {
+                status: 'ACTIVE', emoji: '🟢', confidence: 0.8,
+                deviceCount: devices, registryExists: registry,
+                pageVisible, profileName
+            };
+        }
+        if (devices === 0 && page?.ok) {
+            // Keys fully garbage-collected AND public profile gone
+            return {
+                status: pageGeneric ? 'BANNED' : 'OFF_WHATSAPP',
+                emoji: '🔴', confidence: 0.95,
+                deviceCount: devices, registryExists: registry,
+                pageVisible: false, profileName: null
+            };
+        }
+        if (devices === 0) {
+            return {
+                status: 'OFF_WHATSAPP', emoji: '🔴', confidence: 0.85,
+                deviceCount: devices, registryExists: registry,
+                pageVisible: false, profileName: null
+            };
+        }
+    }
+
+    // Device probe unavailable — fall back to Factors A + B
+    if (page?.ok) {
+        if (!pageGeneric && registry === true) {
+            return {
+                status: 'ACTIVE', emoji: '🟢', confidence: 0.98,
+                deviceCount: null, registryExists: registry,
+                pageVisible, profileName
+            };
+        }
+        if (pageGeneric && registry === true) {
+            // Account exists on the servers but its public profile is
+            // invisible: privacy mode OR a fresh ban mid-deletion.
+            return {
+                status: 'PROFILE_HIDDEN', emoji: '🟡', confidence: 0.6,
+                deviceCount: null, registryExists: registry,
+                pageVisible: false, profileName: null
+            };
+        }
+        if (pageGeneric && registry === false) {
+            return {
+                status: 'OFF_WHATSAPP', emoji: '🔴', confidence: 0.9,
+                deviceCount: null, registryExists: registry,
+                pageVisible: false, profileName: null
+            };
+        }
+    }
+
+    // Last resort: registry alone
+    if (registry === true) {
+        return {
+            status: 'LIKELY_ACTIVE', emoji: '🟡', confidence: 0.55,
+            deviceCount: null, registryExists: registry,
+            pageVisible: false, profileName: null
+        };
+    }
+    if (registry === false) {
+        return {
+            status: 'OFF_WHATSAPP', emoji: '🔴', confidence: 0.7,
+            deviceCount: null, registryExists: registry,
+            pageVisible: false, profileName: null
+        };
+    }
+    return {
+        status: 'UNKNOWN', emoji: '❓', confidence: 0,
+        deviceCount: null, registryExists: null,
+        pageVisible: null, profileName: null
+    };
+}
+
+// ── The exported socket method ─────────────────────────────────────────
+export const makeBanCheckerSocket = (sock) => {
+    sock.checkBanStatus = async (input) => {
+        const target = normalizeJidTarget(input);
+        if (!target) {
+            throw new Error('checkBanStatus: invalid phone number (need 8-15 digits)');
+        }
+        const [devices, registry, page] = await Promise.all([
+            probeIdentityDevices(sock, target),
+            probeRegistry(sock, target),
+            probeSendPage(target)
+        ]);
+        return buildVerdict(target, { devices, registry, page });
+    };
+    return sock;
+};