kyzz-baileys 1.0.0 → 1.0.2

package/README.md

@@ -1,119 +1,316 @@
 # Kyzz Baileys
 
-A lightweight, developer-friendly fork of [Baileys R14](https://github.com/WhiskeySockets/Baileys) (`v7.0.0-rc14`) featuring convenient built-in helpers while maintaining 100% core protocol and API compatibility.
+<p align="center">
+  <b>A lightweight, high-performance, developer-friendly WhatsApp automation library.</b><br>
+  Built on top of <b>Baileys R14</b> (<code>v7.0.0-rc14</code>) with modern protobuf definitions and built-in convenience helpers.
+</p>
 
 ---
 
-## Features
+## 🌟 Highlights
 
-- **100% Baileys R14 Core Compatibility**: All original Baileys methods, binary stanzas, and events work out-of-the-box.
-- **Built-in `sendText`**: Simple shortcut to send plain text messages.
-- **Built-in `reply`**: Reply directly to messages using native Baileys quoted context.
-- **Built-in `lidToJid`**: Helper to resolve LID (`@lid`) to the real phone number JID (`@s.whatsapp.net`).
-- **Built-in `downloadMedia`**: Fast media downloading helper supporting images, videos, audio/PTT, documents, and stickers.
-- **Simple Logger Toggle**: Set `logger: false` directly in socket options to disable logging cleanly.
-- **Zero Extra Dependencies**: Built using Baileys native internals.
+- **100% Baileys R14 Core Compatibility**: Complete retention of WhiskeySockets Baileys R14 architecture, binary nodes, Signal crypto, event buffering, and multi-device connection management.
+- **Modern Extended Protobuf Definitions**: Enhanced protobuf definitions supporting modern WhatsApp stanzas, interactive native flows, newsletters, and rich messages.
+- **Built-in Convenience Helpers**:
+  - `sock.sendText(jid, text, options?)`
+  - `sock.reply(jid, text, quotedMessage, options?)`
+  - `sock.lidToJid(lid)`
+  - `sock.downloadMedia(message, options?)`
+- **Modular Message Builder** (Zero Globals):
+  - Socket methods: `sock.sendButton()`, `sock.sendButtonV2()`, `sock.sendCarousel()`, `sock.sendAIRich()`
+  - Exported classes: `Button`, `ButtonV2`, `Carousel`, `AIRich`, `Toolkit`
+- **Clean Logger Configuration**: Supports `logger: false` directly in socket options.
+- **Zero Heavy External Dependencies**: Pure, lean, and optimized for bot development.
 
 ---
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install kyzz-baileys
 ```
 
+### Requirements
+- **Node.js**: `v18.0.0` or higher
+- **Module System**: ESM (`"type": "module"`) or TypeScript
+
 ---
 
-## Usage
+## 🚀 Quick Start
 
-### 1. Initializing Socket
+### Basic Connection Example (ESM)
 
 ```typescript
 import makeWASocket, { useMultiFileAuthState, DisconnectReason } from 'kyzz-baileys'
 
-const { state, saveCreds } = await useMultiFileAuthState('auth_info_baileys')
+async function connectToWhatsApp() {
+  const { state, saveCreds } = await useMultiFileAuthState('auth_session')
 
-const sock = makeWASocket({
-  auth: state,
-  logger: false // or use a custom pino logger instance
-})
+  const sock = makeWASocket({
+    auth: state,
+    logger: false, // cleanly disable verbose pino logs, or supply your own pino logger
+    printQRInTerminal: true
+  })
 
-sock.ev.on('creds.update', saveCreds)
+  sock.ev.on('creds.update', saveCreds)
 
-sock.ev.on('connection.update', (update) => {
-  const { connection, lastDisconnect } = update
-  if (connection === 'close') {
-    const shouldReconnect = (lastDisconnect?.error as any)?.output?.statusCode !== DisconnectReason.loggedOut
-    console.log('Connection closed, reconnecting:', shouldReconnect)
-  } else if (connection === 'open') {
-    console.log('Connected successfully!')
-  }
-})
+  sock.ev.on('connection.update', (update) => {
+    const { connection, lastDisconnect, qr } = update
+    if (connection === 'close') {
+      const shouldReconnect = (lastDisconnect?.error as any)?.output?.statusCode !== DisconnectReason.loggedOut
+      console.log('Connection closed. Reconnecting:', shouldReconnect)
+      if (shouldReconnect) connectToWhatsApp()
+    } else if (connection === 'open') {
+      console.log('✅ Connected to WhatsApp successfully!')
+    }
+  })
+
+  sock.ev.on('messages.upsert', async ({ messages, type }) => {
+    if (type !== 'notify') return
+    const msg = messages[0]
+    if (!msg.message || msg.key.fromMe) return
+
+    const jid = msg.key.remoteJid!
+    const text = msg.message.conversation || msg.message.extendedTextMessage?.text
+
+    if (text === '!ping') {
+      await sock.sendText(jid, 'Pong! 🏓')
+    }
+  })
+}
+
+connectToWhatsApp()
 ```
 
 ---
 
-### 2. Built-in Helpers
+## 🛠️ Built-in Socket Helpers
+
+### 1. `sock.sendText(jid, text, options?)`
+Sends a simple plain text message using Baileys' native pipeline.
 
-#### `sock.sendText(jid, text, options?)`
 ```typescript
-// Send simple text
-await sock.sendText('1234567890@s.whatsapp.net', 'Hello from Kyzz Baileys!')
+// Simple text
+await sock.sendText('628123456789@s.whatsapp.net', 'Hello from Kyzz Baileys!')
+
+// With custom send options (e.g. ephemeral expiration)
+await sock.sendText('628123456789@s.whatsapp.net', 'Hello with ephemeral expiration', {
+  ephemeralExpiration: 86400
+})
 ```
 
-#### `sock.reply(jid, textOrContent, quotedMessage, options?)`
+---
+
+### 2. `sock.reply(jid, textOrContent, quotedMessage, options?)`
+Replies directly to any received message with native quoted context.
+
 ```typescript
 sock.ev.on('messages.upsert', async ({ messages }) => {
   const msg = messages[0]
   if (!msg.message || msg.key.fromMe) return
 
-  // Reply with text
-  await sock.reply(msg.key.remoteJid!, 'Received your message!', msg)
+  const senderJid = msg.key.remoteJid!
+
+  // Reply with simple text
+  await sock.reply(senderJid, 'Got your message loud and clear!', msg)
+
+  // Or reply with AnyMessageContent object (e.g. media, formatted content)
+  await sock.reply(senderJid, {
+    text: 'Check this out with quoted context!'
+  }, msg)
 })
 ```
 
-#### `sock.lidToJid(lid)`
+---
+
+### 3. `sock.lidToJid(lid)`
+Resolves a WhatsApp LID (e.g., `12345678901234@lid`) to the corresponding phone number JID (`...01234@s.whatsapp.net`) using Baileys' internal Signal/LID store.
+
 ```typescript
-// Resolve a LID to a phone number JID
-const phoneJid = await sock.lidToJid('123456789@lid')
-console.log('Resolved JID:', phoneJid) // e.g. 628123456789@s.whatsapp.net
+const realJid = await sock.lidToJid('10293847561029@lid')
+console.log('Resolved user JID:', realJid) // e.g. "628987654321@s.whatsapp.net"
 ```
 
-#### `sock.downloadMedia(message, options?)`
+---
+
+### 4. `sock.downloadMedia(message, options?)`
+Extracts and downloads decrypted media buffer directly from any message type (images, videos, audio, voice notes, stickers, documents).
+
 ```typescript
 sock.ev.on('messages.upsert', async ({ messages }) => {
   const msg = messages[0]
   if (!msg.message || msg.key.fromMe) return
 
-  // Download media buffer (images, stickers, audio, video, documents)
   try {
     const buffer = await sock.downloadMedia(msg)
-    console.log('Downloaded media size:', buffer.length)
+    console.log('Downloaded media size:', buffer.length, 'bytes')
   } catch (err) {
-    // Not a media message or download error
+    // Not a media message or decryption error
   }
 })
 ```
 
 ---
 
-### 3. Standard Baileys API Compatibility
+## 🎨 Message Builder API
+
+Kyzz Baileys provides built-in message builders for interactive buttons, modern native flows, carousels, and rich AI cards. All builder classes are **100% modular, importable, and contain NO global variables**.
+
+### 1. Interactive Buttons (`sock.sendButton`)
+
+```typescript
+import { Button } from 'kyzz-baileys'
+
+// Using socket helper
+await sock.sendButton(jid, {
+  text: 'Select your preferred action:',
+  footer: 'Kyzz Baileys Bot',
+  buttons: [
+    Button.quickReply('btn_1', '🔘 Quick Reply'),
+    Button.url('🔗 Visit Website', 'https://github.com'),
+    Button.call('📞 Call Support', '+628123456789'),
+    Button.copy('📋 Copy Code', 'DISCOUNT2026')
+  ]
+})
+```
+
+---
+
+### 2. Native Flow Buttons V2 (`sock.sendButtonV2`)
+
+```typescript
+import { ButtonV2 } from 'kyzz-baileys'
+
+await sock.sendButtonV2(jid, {
+  text: 'Modern Native Flow Interactive Buttons',
+  footer: 'Powered by Kyzz Baileys',
+  buttons: [
+    ButtonV2.quickReply('id_v2_ping', '🏓 Ping V2'),
+    ButtonV2.url('🌐 Open Portal', 'https://example.com'),
+    ButtonV2.copy('🔑 Copy Token', 'AUTH_TOKEN_XYZ')
+  ]
+})
+```
+
+---
+
+### 3. Interactive Carousel (`sock.sendCarousel`)
+
+```typescript
+import { Carousel, ButtonV2 } from 'kyzz-baileys'
+
+await sock.sendCarousel(jid, {
+  text: 'Explore our features:',
+  footer: 'Swipe horizontally to view more',
+  cards: [
+    Carousel.createCard({
+      header: { title: 'Product A' },
+      body: 'High performance WhatsApp engine',
+      footer: 'Card 1 of 2',
+      buttons: [
+        ButtonV2.quickReply('card1_select', 'Select Product A')
+      ]
+    }),
+    Carousel.createCard({
+      header: { title: 'Product B' },
+      body: 'Extended Proto and zero globals',
+      footer: 'Card 2 of 2',
+      buttons: [
+        ButtonV2.quickReply('card2_select', 'Select Product B')
+      ]
+    })
+  ]
+})
+```
+
+---
+
+### 4. AI Rich Persona Card (`sock.sendAIRich`)
+
+```typescript
+import { AIRich } from 'kyzz-baileys'
+
+await sock.sendAIRich(jid, {
+  text: 'Hello! I am your AI Assistant powered by Kyzz Baileys.',
+  persona: 'Kyzz AI',
+  botJid: '13135550002@s.whatsapp.net'
+})
+```
+
+---
+
+### 5. Direct MessageBuilder Classes
 
-All standard Baileys functions remain fully functional:
+You can also use the builder classes directly without the socket wrappers to generate standard `AnyMessageContent` objects:
+
+```typescript
+import { Button, ButtonV2, Carousel, AIRich, Toolkit } from 'kyzz-baileys'
+
+// Generate button payload
+const buttonPayload = Button.build({
+  text: 'Hello World',
+  footer: 'Footer note',
+  buttons: [Button.quickReply('id1', 'Click Me')]
+})
+
+// Send using standard Baileys sendMessage
+await sock.sendMessage(jid, buttonPayload)
+```
+
+---
+
+## ⚡ Original Baileys API Compatibility
+
+All original Baileys methods are preserved and completely unchanged:
 
 ```typescript
 // Standard sendMessage
-await sock.sendMessage(jid, { text: 'Standard Baileys message' })
+await sock.sendMessage(jid, { text: 'Regular message' })
+
+// Sending media with caption
+await sock.sendMessage(jid, {
+  image: { url: './assets/photo.jpg' },
+  caption: 'Here is a photo'
+})
 
-// Standard media sending
+// Reactions
 await sock.sendMessage(jid, {
-  image: { url: './image.png' },
-  caption: 'Hello World'
+  react: { text: '❤️', key: msg.key }
 })
+
+// Group operations
+const group = await sock.groupCreate('My Group', ['628123456789@s.whatsapp.net'])
+await sock.groupParticipantsUpdate(group.id, ['628123456789@s.whatsapp.net'], 'promote')
 ```
 
 ---
 
-## License
+## 📋 API Reference
+
+| Method / Symbol | Description | Type |
+|---|---|---|
+| `sock.sendText(jid, text, options?)` | Convenience method to send plain text | Helper |
+| `sock.reply(jid, textOrContent, quoted, options?)` | Convenience method to reply with quoted context | Helper |
+| `sock.lidToJid(lid)` | Resolves WhatsApp LID to standard user JID | Helper |
+| `sock.downloadMedia(message, options?)` | Downloads media buffer from any message | Helper |
+| `sock.sendButton(jid, payload, options?)` | Sends interactive button message | UI Builder |
+| `sock.sendButtonV2(jid, payload, options?)` | Sends native flow V2 button message | UI Builder |
+| `sock.sendCarousel(jid, payload, options?)` | Sends interactive carousel message | UI Builder |
+| `sock.sendAIRich(jid, payload, options?)` | Sends rich AI persona card | UI Builder |
+| `Button`, `ButtonV2`, `Carousel`, `AIRich`, `Toolkit` | Modular message builder classes | Exports |
+| `proto` | Protobuf definitions | Proto |
+| `makeWASocket(config)` | Factory for creating WhatsApp socket instance | Core |
+
+---
+
+## 🤝 Special Thanks & Credits (TQTO)
+
+- [WhiskeySockets/Baileys](https://github.com/WhiskeySockets/Baileys) — Original Baileys R14 multi-device library & protocol engine.
+- **nixcode (nixel) / Valdaz** ([ValdazGT](https://gist.github.com/ValdazGT)) — For the Message Builder reference & interactive component designs.
+- 📢 **Official WhatsApp Channel**: [Join Here](https://whatsapp.com/channel/0029VbCV1ck8fewpdNb2TY2k)
+
+---
+
+## 📄 License
 
 MIT License. WhiskeySockets/Baileys copyright belongs to its original authors.