ishumdz-bail 1.0.17 → 1.0.19

package/README.md

@@ -83,6 +83,7 @@ sock.ev.on('creds.update', saveCreds)
 | 🔄 **Classify Disconnect** | Maps every WA disconnect code to `{ category, shouldReconnect, backoffMs }` — properly handles code 515 (restartRequired) as recoverable, not fatal |
 | ⏱️ **Rate Limiter** | Anti-spam pacing calculator: enforces per-minute/hour/day caps, burst allowance, new-chat delays, identical-message dedup |
 | 🖼️ **Album Message** | Send multiple images/videos as a single WA album/grid, with per-item or top-level caption and `gifPlayback` support |
+| 🔘 **Horizontal Buttons** | Modern native-flow buttons that render on ALL clients — text, image, video, GIF headers + classic location map-card style + automatic group conversion |
 | 🤖 **AI Label Config** | `aiLabel: true/false` in socket config — controls whether outgoing messages carry the `biz_bot` attribute that WA uses to render the AI icon |
 | 🔎 **USync Username Protocol** | Username resolution baked into USync queries — resolve WA usernames alongside contacts in a single round-trip |
 | 📥 **Offline Node Processor** | Batch-processes pending stanzas received while offline, preventing message loss on reconnect |
@@ -413,6 +414,125 @@ await sock.sendMessage(jid, {
 
 ---
 
+## 🔘 Horizontal Buttons (Interactive Messages)
+
+> ⚡ **How it renders:** the `buttons` API sends the **classic ButtonsMessage** — the
+> only format WhatsApp renders as a true **horizontal button row**. Modern clients
+> render it when the message has a **header** (image / video / GIF / location map-card).
+> A **location header needs no media upload** — coordinates alone give the big map
+> card + horizontal row, and a **custom image or GIF** works with one media upload.
+> Set `{ nativeFlow: true }` for vertical native-flow quick_reply buttons instead.
+
+### Text + Horizontal Buttons (location header = zero uploads)
+
+```javascript
+await sock.sendMessage(jid, {
+    location: { degreesLatitude: 9.9312, degreesLongitude: 76.2673 }, // simple map card
+    text: 'Pong 9 Ms ⚡\nDeveloper: ISHAN-X × LOVELY',
+    footer: 'ISHAN-X MD PRO',
+    buttons: [
+        { buttonText: { displayText: 'menu' },  buttonId: 'menu',  type: 1 },
+        { buttonText: { displayText: 'owner' }, buttonId: 'owner', type: 1 }
+    ]
+})
+```
+
+### Custom Pic / GIF + Horizontal Buttons
+
+```javascript
+// Image header (one media upload, then horizontal row)
+await sock.sendMessage(jid, {
+    image: { url: './banner.jpg' },
+    caption: 'Welcome!',
+    footer: 'My Bot',
+    buttons: [
+        { buttonText: { displayText: 'menu' },  buttonId: 'menu',  type: 1 },
+        { buttonText: { displayText: 'owner' }, buttonId: 'owner', type: 1 }
+    ]
+})
+
+// Animated GIF header
+await sock.sendMessage(jid, {
+    gif: { url: './animation.gif' },
+    caption: 'Live preview!',
+    buttons: [ /* ... */ ]
+})
+
+// Video header (gifPlayback = loop like a GIF)
+await sock.sendMessage(jid, {
+    video: { url: './clip.mp4' },
+    gifPlayback: true,
+    caption: 'Watch this',
+    buttons: [ /* ... */ ]
+})
+```
+
+### Location Map-Card + Buttons (custom name/address)
+
+```javascript
+await sock.sendMessage(jid, {
+    location: {
+        degreesLatitude: 9.9312,
+        degreesLongitude: 76.2673,
+        name: 'ISHAN-X MD PRO',           // bold title under the map
+        address: 'Select an option below', // 📍 subtitle
+        // jpegThumbnail: buffer — custom map image (optional)
+    },
+    text: 'Pong 9 Ms ⚡',
+    buttons: [ /* ... */ ]
+})
+```
+
+### Text-only (TEXT header, best-effort) & native flow escape hatch
+
+```javascript
+// text-only: TEXT headerType — some clients still show the row vertically;
+// for a guaranteed horizontal row attach image/gif/location as above.
+await sock.sendMessage(jid, {
+    text: 'Pong 9 Ms ⚡', footer: 'ISHAN-X',
+    buttons: [ { buttonText: { displayText: 'menu' }, buttonId: 'menu', type: 1 } ]
+})
+
+// vertical native-flow quick_reply buttons (renders on all modern clients)
+await sock.sendMessage(jid, {
+    text: 'Menu?', nativeFlow: true,
+    buttons: [ { buttonText: { displayText: 'menu' }, buttonId: 'menu', type: 1 } ]
+})
+```
+
+### Handling Button Clicks
+
+Button replies arrive in `messages.upsert` — native flow uses
+`interactiveResponseMessage`, classic uses `buttonsResponseMessage`:
+
+```javascript
+sock.ev.on('messages.upsert', async ({ messages, type }) => {
+    if (type !== 'notify') return
+    const msg = messages[0]
+    if (!msg.message || msg.key.fromMe) return
+
+    let clickedId = msg.message.buttonsResponseMessage?.selectedButtonId
+    const native = msg.message.interactiveResponseMessage?.nativeFlowResponseMessage
+    if (!clickedId && native?.paramsJson) {
+        try { clickedId = JSON.parse(native.paramsJson).id } catch {}
+    }
+
+    if (clickedId === 'menu')  await sock.sendMessage(msg.key.remoteJid, { text: '📋 MENU...' })
+    if (clickedId === 'owner') await sock.sendMessage(msg.key.remoteJid, { text: '👑 Owner...' })
+})
+```
+
+> **Notes**
+> - Groups: `listMessage` / `buttonsMessage` / `templateMessage` are auto-converted to
+>   interactive native flow on send — buttons work in groups too.
+> - WhatsApp Web and very old clients don't render native flow cards — mobile clients
+>   (recent Android/iOS) render them fully.
+> - Full working demo: [`examples/ping-buttons.js`](examples/ping-buttons.js)
+>   (`.ping` → image + horizontal buttons + click handling) and a visual preview in
+>   [`banner-preview.html`](banner-preview.html).
+
+---
+
 ## 🚫 Ban Checker
 
 4-factor ban detection against WhatsApp's own servers — no third-party API:
@@ -576,6 +696,9 @@ sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
 
 Anti-ban pacing calculator — wire into your send path before each `sendMessage`:
 
+> ⚡ **Fixed in this fork:** `RateLimiter` and `classifyDisconnect` are now properly
+> exported from the package root (the files existed but were never re-exported).
+
 ```javascript
 import { RateLimiter } from 'ishumdz-bail'
 

package/lib/Utils/index.js

@@ -20,4 +20,7 @@ export * from './companion-reg-client-utils.js';
 export * from './identity-change-handler.js';
 export * from './stanza-ack.js';
 export * from './message-composer.js';
+// PATCH: export anti-ban utilities (files existed but were never re-exported)
+export * from './rate-limiter.js';
+export * from './classify-disconnect.js';
 //# sourceMappingURL=index.js.map

package/lib/Utils/messages.js

@@ -517,6 +517,13 @@ const applyContextInfoAndMentions = (interactiveMessage, message) => {
 		}
 	}
 }
+// PATCH: 1x1 transparent PNG — text-only buttons attach this as an invisible
+// IMAGE header so modern clients render the horizontal row (classic requires
+// a header), with no map card and no "version doesn't support it" error.
+const BUTTONS_INVISIBLE_PNG = () => Buffer.from(
+	'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=',
+	'base64'
+)
 export const generateWAMessageContent = async (message, options) => {
     var _a, _b;
     let m = {};
@@ -589,48 +596,124 @@ export const generateWAMessageContent = async (message, options) => {
         m = { interactiveMessage };
     }
 	else if ('buttonsMessage' in message && !!message.buttonsMessage) {
-		// PATCH: raw buttonsMessage pass-through — classic horizontal buttons (reference: Case X Plugin case.js).
-		// Fully-formed ButtonsMessage with any header (location/image/video/
-		// document), contentText, footerText, headerType and buttons[].
-		// type:1 buttons render in one horizontal row; nativeFlowInfo
-		// single_select opens a list sheet on tap.
+		// PATCH: raw buttonsMessage — always classic pass-through. Modern clients
+		// render the horizontal row when a header exists (image/video/document/
+		// location) or when a thumbnail header is attached; text-only without any
+		// header is the "version doesn't support it" case. Add a header in that
+		// situation, or use the `buttons` API which auto-adds one.
 		m = { buttonsMessage: proto.Message.ButtonsMessage.create(message.buttonsMessage) };
 	}
 	else if ('buttons' in message && !!message.buttons) {
-        const buttonsMessage = {
-            buttons: message.buttons.map(b => ({ ...b, type: proto.Message.ButtonsMessage.Button.Type.RESPONSE }))
-        };
-        if ('text' in message) {
-            buttonsMessage.contentText = message.text;
-            buttonsMessage.headerType = ButtonType.EMPTY;
+        // PATCH: `buttons` API — HORIZONTAL button row via classic ButtonsMessage
+        // with a header (modern clients only render classic horizontal buttons
+        // when a header exists: image/video/gif/location, or an embedded
+        // thumbnail for text-only). Set { nativeFlow: true } to opt out and get
+        // vertical native-flow quick_reply buttons instead.
+        if (message.nativeFlow === true) {
+            const flowButtons = message.buttons.map(b => ({
+                name: 'quick_reply',
+                buttonParamsJson: JSON.stringify({
+                    display_text: b.buttonText?.displayText || b.displayText || b.text || '',
+                    id: b.buttonId || b.id || b.buttonText?.displayText || ''
+                })
+            }));
+            const interactiveMessage = {
+                nativeFlowMessage: {
+                    buttons: flowButtons,
+                    messageParamsJson: '',
+                    messageVersion: 1
+                }
+            };
+            if ('text' in message) {
+                interactiveMessage.body = { text: message.text };
+            } else if ('caption' in message) {
+                interactiveMessage.body = { text: message.caption };
+            }
+            if ('footer' in message && !!message.footer) {
+                interactiveMessage.footer = { text: message.footer };
+            }
+            applyContextInfoAndMentions(interactiveMessage, message);
+            m = { interactiveMessage };
+        }
+        else if ('location' in message && !!message.location) {
+            const loc = message.location;
+            const buttonsMessage = {
+                buttons: message.buttons.map(b => ({ ...b, type: proto.Message.ButtonsMessage.Button.Type.RESPONSE })),
+                contentText: message.text || message.caption || '',
+                headerType: ButtonType.LOCATION,
+                locationMessage: {
+                    degreesLatitude: loc.degreesLatitude ?? loc.latitude ?? 0,
+                    degreesLongitude: loc.degreesLongitude ?? loc.longitude ?? 0,
+                    name: loc.name ?? null,
+                    address: loc.address ?? null,
+                    ...(loc.jpegThumbnail ? { jpegThumbnail: loc.jpegThumbnail } : {})
+                }
+            };
+            if ('footer' in message && !!message.footer) {
+                buttonsMessage.footerText = message.footer;
+            }
+            if (message.contextInfo || message.mentions) {
+                buttonsMessage.contextInfo = {
+                    ...(message.contextInfo || {}),
+                    ...(message.mentions ? { mentionedJid: message.mentions } : {})
+                };
+            }
+            m = { buttonsMessage: proto.Message.ButtonsMessage.create(buttonsMessage) };
         }
         else {
-            if ('caption' in message) {
-                buttonsMessage.contentText = message.caption;
+            const buttonsMessage = {
+                buttons: message.buttons.map(b => ({ ...b, type: proto.Message.ButtonsMessage.Button.Type.RESPONSE }))
+            };
+            if ('footer' in message && !!message.footer) {
+                buttonsMessage.footerText = message.footer;
+            }
+            if (message.contextInfo || message.mentions) {
+                buttonsMessage.contextInfo = {
+                    ...(message.contextInfo || {}),
+                    ...(message.mentions ? { mentionedJid: message.mentions } : {})
+                };
             }
-            // PATCH: prepare media headers for caption+buttons (fork bug fix).
-            // The media branch never ran before this point, so m is empty and
-            // getContentType(m) crashed. Build the header right here instead.
             if ('video' in message && !!message.video) {
                 const media = await prepareWAMessageMedia({ video: message.video }, options);
                 buttonsMessage.videoMessage = media.videoMessage;
                 if (message.gifPlayback) buttonsMessage.videoMessage.gifPlayback = true;
                 buttonsMessage.headerType = ButtonType.VIDEO;
+            } else if ('gif' in message && !!message.gif) {
+                const media = await prepareWAMessageMedia({ video: message.gif }, options);
+                buttonsMessage.videoMessage = media.videoMessage;
+                buttonsMessage.videoMessage.gifPlayback = true;
+                buttonsMessage.headerType = ButtonType.VIDEO;
             } else if ('image' in message && !!message.image) {
                 const media = await prepareWAMessageMedia({ image: message.image }, options);
                 buttonsMessage.imageMessage = media.imageMessage;
                 buttonsMessage.headerType = ButtonType.IMAGE;
             } else {
-                const contentType = getContentType(m);
-                const type = contentType.replace('Message', '').toUpperCase();
-                buttonsMessage.headerType = ButtonType[type];
-                Object.assign(buttonsMessage, m);
+                if ('text' in message || 'caption' in message) {
+                    const body = message.text ?? message.caption;
+                    buttonsMessage.contentText = body;
+                    // PATCH: text-only — invisible 1x1 PNG header so the horizontal
+                    // row renders on modern clients without a map card and without
+                    // the "doesn't support it" error. Upload failure falls back to
+                    // the TEXT header (may render vertical, still no error).
+                    try {
+                        const media = await prepareWAMessageMedia({ image: BUTTONS_INVISIBLE_PNG() }, options);
+                        buttonsMessage.imageMessage = media.imageMessage;
+                        buttonsMessage.headerType = ButtonType.IMAGE;
+                    } catch {
+                        buttonsMessage.text = (message.title || String(body).split('\n')[0] || '').slice(0, 60);
+                        buttonsMessage.headerType = ButtonType.TEXT;
+                    }
+                } else {
+                    buttonsMessage.headerType = ButtonType.EMPTY;
+                }
             }
+            if ('text' in message && (buttonsMessage.videoMessage || buttonsMessage.imageMessage)) {
+                // media header already carries the caption
+                if (buttonsMessage.videoMessage && 'caption' in message) buttonsMessage.videoMessage.caption = message.caption;
+                if (buttonsMessage.imageMessage && 'caption' in message) buttonsMessage.imageMessage.caption = message.caption;
+            }
+            m = { buttonsMessage: proto.Message.ButtonsMessage.create(buttonsMessage) };
         }
-        if ('footer' in message && !!message.footer) {
-            buttonsMessage.footerText = message.footer;
-        }
-        m = { buttonsMessage };
     }
     else if (hasNonNullishProperty(message, 'sections') || hasNonNullishProperty(message, 'productList')) {
         const isProductList = hasNonNullishProperty(message, 'productList');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ishumdz-bail",
-    "version": "1.0.17",
+    "version": "1.0.19",
     "description": "WhatsApp API Modification By Lovely",
     "keywords": [
         "whatsapp",