zaileys 1.1.29 → 1.1.31

package/README.md

@@ -1,64 +1,52 @@
-<div align="center">
-  <img alt="Zaileys - Simplified WhatsApp Node.js API" src="https://socialify.git.ci/zeative/zaileys/image?description=1&descriptionEditable=Zaileys%20is%20a%20simplified%20version%20of%20the%20Baileys%20package%20%0Awhich%20is%20easier%20and%20faster.&font=KoHo&forks=1&issues=1&language=1&name=1&owner=1&pattern=Circuit%20Board&pulls=1&stargazers=1&theme=Auto">
-</div>
-
 <h1 align="center">Zaileys - Simplified WhatsApp Node.js API</h1>
 
 <div align="center">
-  <a href="https://www.npmjs.com/package/zaileys">
-    <img src="https://img.shields.io/npm/v/zaileys.svg" alt="NPM Version">
-  </a>
-  <a href="https://www.npmjs.com/package/zaileys">
-    <img src="https://img.shields.io/npm/dw/zaileys?label=npm&color=%23CB3837" alt="NPM Downloads">
-  </a>
-  <a href="https://github.com/zeative/zaileys">
-    <img src="https://img.shields.io/github/languages/code-size/zeative/zaileys" alt="GitHub Code Size">
-  </a>
-  <a href="https://github.com/zeative/zaileys">
-    <img src="https://img.shields.io/github/license/zeative/zaileys" alt="GitHub License">
-  </a>
-  <a href="https://github.com/zeative/zaileys">
-    <img src="https://img.shields.io/github/stars/zeative/zaileys" alt="GitHub Stars">
-  </a>
-  <a href="https://github.com/zeative/zaileys">
-    <img src="https://img.shields.io/github/forks/zeative/zaileys" alt="GitHub Forks">
-  </a>
+  <img alt="Zaileys - Simplified WhatsApp Node.js API" src="https://socialify.git.ci/zeative/zaileys/image?description=1&descriptionEditable=Zaileys%20is%20a%20simplified%20version%20of%20the%20Baileys%20package%20%0Awhich%20is%20easier%20and%20faster.&font=KoHo&forks=1&issues=1&language=1&name=1&owner=1&pattern=Circuit%20Board&pulls=1&stargazers=1&theme=Auto">
+  <br>
+  <a href="https://www.npmjs.com/package/zaileys"><img src="https://img.shields.io/npm/v/zaileys.svg" alt="NPM Version"></a>
+  <a href="https://www.npmjs.com/package/zaileys"><img src="https://img.shields.io/npm/dw/zaileys?label=npm&color=%23CB3837" alt="NPM Downloads"></a>
+  <a href="https://github.com/zeative/zaileys"><img src="https://img.shields.io/github/languages/code-size/zeative/zaileys" alt="GitHub Code Size"></a>
+  <a href="https://github.com/zeative/zaileys"><img src="https://img.shields.io/github/license/zeative/zaileys" alt="GitHub License"></a>
+  <a href="https://github.com/zeative/zaileys"><img src="https://img.shields.io/github/stars/zeative/zaileys" alt="GitHub Stars"></a>
+  <a href="https://github.com/zeative/zaileys"><img src="https://img.shields.io/github/forks/zeative/zaileys" alt="GitHub Forks"></a>
 </div>
 
-> [!NOTE]
-> Join our [WhatsApp Channel](https://whatsapp.com/channel/0029VazENbmInlqHIWzgn33h) for updates and support.
+#
+**Zaileys** is a lightweight, user-friendly wrapper around the [Baileys](https://github.com/WhiskeySockets/Baileys) library, designed to simplify building WhatsApp bots and integrations with TypeScript or ESM JavaScript. It offers a streamlined API, robust multi-device support, and seamless database integration for session management.
 
-**Zaileys** is a lightweight, high-performance wrapper around the Baileys library for building WhatsApp bots and integrations using TypeScript or ESM JavaScript. Designed for simplicity, speed, and scalability.
+> **Note**: Stay updated and get support by joining our [WhatsApp Channel](https://whatsapp.com/channel/0029VazENbmInlqHIWzgn33h).
 
-> [!WARNING]
-> Pairing code authentication is currently experiencing issues and is not supported. Use QR code authentication instead.
+> **Warning**: Pairing code authentication is currently not supported due to issues. Use QR code authentication instead.
 
 ## 📋 Table of Contents
 
-1. [🚀 Features](#features)
-2. [💻 Installation](#installation)
-3. [⚡ Quick Start](#quick-start)
-   - [Simplify Version](#simplify-version)
-4. [🔍 Core Concepts](#core-concepts)
-5. [📢 Event Handling](#event-handling)
-6. [👾 Worker Actions](#worker-actions)
-7. [🐞 Issues & Feedback](#issues--feedback)
-8. [❤️ Support](#support)
-9. [📄 License](#license)
-10. [🙏 Acknowledgements](#acknowledgements)
-
-## 🚀 Features
-
-- 🎯 **Simplified API**: Minimal setup for rapid development.
-- 🔒 **Secure Multi-Device**: Full multi-device support via Baileys.
-- ⚙️ **Modular Design**: Extensible with middleware and storage layers.
-- 📟 **QR Code Authentication**: Seamless QR-based login in terminal.
-- 🛠️ **TypeScript/ESM Only**: Full type definitions and ESM support.
-- 💾 **Database-Driven**: SQLite, PostgreSQL, or MySQL for session storage.
-
-## 💻 Installation
-
-Install via your preferred package manager:
+1. [✨ Features](#features)
+2. [📦 Installation](#installation)
+3. [🚀 Quick Start](#quick-start)
+4. [🛠 Core Concepts](#core-concepts)
+5. [📡 Event Handling](#event-handling)
+6. [📩 Sending Messages](#sending-messages)
+7. [🖼 Sending Media](#sending-media)
+8. [🔧 Advanced Actions](#advanced-actions)
+9. [🐛 Issues & Feedback](#issues--feedback)
+10. [❤️ Support](#support)
+11. [📜 License](#license)
+12. [🙌 Acknowledgements](#acknowledgements)
+
+## ✨ Features
+
+- **Simplified API**: Minimal setup for rapid bot development.
+- **Multi-Device Support**: Full compatibility with WhatsApp’s multi-device feature via Baileys.
+- **Modular & Extensible**: Easily integrate middleware and custom storage solutions.
+- **QR Code Authentication**: Hassle-free login with terminal-based QR codes.
+- **TypeScript & ESM**: Full type safety and modern JavaScript support.
+- **Database Integration**: Supports SQLite, PostgreSQL, or MySQL for session persistence.
+- **Rate Limiting**: Built-in spam detection to prevent abuse.
+- **Webhooks Support**: Handle external events with a dynamically provided URL during runtime.
+
+## 📦 Installation
+
+Install Zaileys using your preferred package manager:
 
 ```bash
 npm install zaileys
@@ -68,27 +56,39 @@ yarn add zaileys
 pnpm add zaileys
 ```
 
-> [!IMPORTANT]
->
-> - Requires **Node.js >= 18**.
-> - Only supports **ESM** and **TypeScript** (no CommonJS).
-> - QR code authentication only (pairing code not supported).
-> - Deno and Bun are not supported at runtime due to `better-sqlite3` incompatibility.
+**Requirements**:
+
+- **Node.js**: Version 18 or higher.
+- **Module System**: ESM or TypeScript only (no CommonJS).
+- **Authentication**: QR code only (pairing code not supported).
+- **Unsupported Runtimes**: Deno and Bun (due to `better-sqlite3` incompatibility).
+
+## 🚀 Quick Start
+
+Explore the `/examples` folder for practical use cases:
 
-## ⚡ Quick Start
+- [Simple Setup](https://github.com/zeative/zaileys/blob/main/examples/simple.ts): A minimal setup for quick prototyping.
+- [Citation Example](https://github.com/zeative/zaileys/blob/main/examples/citation.ts): Demonstrates custom metadata with the citation mechanism.
+- [Rate Limiting Example](https://github.com/zeative/zaileys/blob/main/examples/limiter.ts): Shows how to implement spam detection.
+- [AI Integration with Groq](https://github.com/zeative/zaileys/blob/main/examples/llms.ts): Integrates AI capabilities using Groq.
+- [Webhooks Integration](https://github.com/zeative/zaileys/blob/main/examples/webhooks.ts): Handles webhook-based interactions.
+- [Voice Note with AI](https://github.com/zeative/zaileys/blob/main/examples/speech.ts): Interacts with AI using voice notes.
 
-For a complete example, see [`/test/example.ts`](https://github.com/zeative/zaileys/blob/main/test/example.ts).
+### Basic Example
 
 ```ts
 import { Client } from "zaileys";
 
+// default configuration
 const wa = new Client({
-  prefix: "/", // Command prefix
-  ignoreMe: true, // Ignore bot's own messages
-  autoRead: true, // Auto-mark messages as read
-  autoOnline: true, // Auto-set status to online
-  autoPresence: true, // Auto-manage presence (typing/recording)
-  autoRejectCall: true, // Auto-reject incoming calls
+  prefix: "/",
+  ignoreMe: true,
+  showLogs: true,
+  autoRead: true,
+  autoOnline: true,
+  autoPresence: true,
+  autoRejectCall: true,
+  loadLLMSchemas: false,
   database: {
     type: "sqlite",
     connection: { url: "./session/zaileys.db" },
@@ -100,31 +100,25 @@ wa.on("messages", async (ctx) => {
     await wa.text("Hello!", { roomId: ctx.roomId });
   }
 });
-
-wa.on("connection", (ctx) => {
-  console.log("Connection status:", ctx.status);
-});
 ```
 
-### Simplify Version
+### Minimal Example
 
 ```ts
 import { Client } from "zaileys";
 
-const wa = new Client({
-  authType: "qr",
-});
+const wa = new Client({ authType: "qr" });
 
 wa.on("messages", (ctx) => {
   wa.text("Hello", { roomId: ctx.roomId });
 });
 ```
 
-## 🔍 Core Concepts
+## 🛠 Core Concepts
 
 ### Sessions & Authentication
 
-Zaileys uses QR code authentication and stores session data in a database (SQLite, PostgreSQL, or MySQL) for seamless reconnections without repeated QR scans.
+Zaileys uses QR code authentication and stores sessions in a database to avoid repeated QR scans.
 
 ```ts
 import { Client } from "zaileys";
@@ -139,7 +133,7 @@ const wa = new Client({
 
 ### Citation Mechanism
 
-Define custom metadata providers in the `citation` option. Each key generates a boolean on `ctx.citation` (e.g., `isKeyName`).
+Define custom metadata providers for dynamic boolean flags in `ctx.citation`. See [citation.ts](https://github.com/zeative/zaileys/blob/main/examples/citation.ts).
 
 ```ts
 const wa = new Client({
@@ -156,117 +150,298 @@ wa.on("messages", (ctx) => {
 });
 ```
 
-## 📢 Event Handling
+### Rate Limiting
+
+Detect and prevent spam with the built-in limiter. See [limiter.ts](https://github.com/zeative/zaileys/blob/main/examples/limiter.ts).
+
+```ts
+const wa = new Client({
+  authType: "qr",
+
+  // max 10 messages on 10 seconds
+  limiter: {
+    durationMs: 10000,
+    maxMessages: 5,
+  },
+});
+
+wa.on("messages", (ctx) => {
+  if (ctx.isSpam) {
+    wa.text("You're spamming!!", { roomId: ctx.roomId });
+    return;
+  }
+
+  wa.text("Hello!", { roomId: ctx.roomId });
+});
+```
+
+### Webhooks
+
+Configure webhooks to handle external events. The URL is dynamically provided in the CLI upon running the app. See [webhooks.ts](https://github.com/zeative/zaileys/blob/main/examples/webhooks.ts).
+
+```ts
+const wa = new Client({
+  authType: "qr",
+  webhooks: {
+    url: "https://your-webhook-url.com",
+  },
+});
+
+wa.on("webhooks", (ctx) => {
+  console.log(ctx.data.query); // Query params
+  console.log(ctx.data.json); // JSON body
+  console.log(ctx.data.form); // Form data
+  console.log(ctx.data.raw); // Raw body
+});
+```
+
+**Webhook Access**: Displayed in CLI on startup (e.g., `http://xxx.xxx.x.xxx:4135/webhooks`, Port: 4135, Methods: GET, POST).
+
+## 📡 Event Handling
+
+### Connection Events
+
+Monitor connection status changes.
 
 ```ts
 wa.on("connection", (ctx) => {
-  console.log("Connection:", ctx.status);
+  console.log(`Connection: ${ctx.status}`);
 });
+```
+
+### Message Events
 
+```ts
 wa.on("messages", (ctx) => {
-  console.log("Message:", ctx.text);
+  console.log(ctx);
 });
+```
+
+Schemas output of `ctx` type:
+
+```json
+{
+  "chatId": "string",
+  "channelId": "string",
+  "uniqueId": "string",
+  "receiverId": "string",
+  "receiverName": "string",
+  "roomId": "string",
+  "roomName": "string",
+  "senderId": "string",
+  "senderName": "string",
+  "senderDevice": "string",
+  "chatType": "string",
+  "timestamp": "number",
+  "mentions": "array",
+  "text": "string",
+  "links": "array",
+  "isPrefix": "boolean",
+  "isSpam": "boolean",
+  "isFromMe": "boolean",
+  "isTagMe": "boolean",
+  "isGroup": "boolean",
+  "isStory": "boolean",
+  "isViewOnce": "boolean",
+  "isEdited": "boolean",
+  "isDeleted": "boolean",
+  "isPinned": "boolean",
+  "isUnPinned": "boolean",
+  "isChannel": "boolean",
+  "isBroadcast": "boolean",
+  "isEphemeral": "boolean",
+  "isForwarded": "boolean",
+  "citation": "object",
+  "media": {
+    ...
+    "buffer": "function",
+    "stream": "function"
+  },
+  "replied": "object (same schema as ctx)",
+  "message": "function"
+}
+```
+
+### Call Events
+
+Handle incoming calls.
 
+```ts
 wa.on("calls", (ctx) => {
-  wa.rejectCall(ctx);
+  console.log(ctx);
 });
 ```
 
-## 👾 Worker Actions
+### Webhook Events
 
-### Sending Messages
+Handle external webhook requests.
+
+```ts
+wa.on("webhooks", (ctx) => {
+  console.log(ctx.data.query); // Query params
+  console.log(ctx.data.json); // JSON body
+  console.log(ctx.data.form); // Form data
+  console.log(ctx.data.raw); // Raw body
+});
+```
+
+**Webhook Access**: Displayed in CLI on startup (e.g., `http://xxx.xxx.x.xxx:4135/webhooks`, Port: 4135, Methods: GET, POST).
+
+## 📩 Sending Messages
+
+### Basic Text Messages
+
+Send simple or advanced text messages with options like replies or forwarding.
 
 ```ts
 const roomId = ctx.roomId;
 const message = ctx.message;
 
+/* sending text  */
 wa.text("Hello", { roomId });
+
+/* sending reply  */
 wa.text("Reply", { roomId, quoted: message });
+
+/* sending forwarded  */
 wa.text("Forwarded", { roomId, asForwarded: true });
+
+/* fake verified (just work on reply message only!)  */
 wa.text("Verified reply", { roomId, quoted: message, verifiedReply: "whatsapp" });
+
+/* mark as ai (just work on private message only!)  */
+wa.text("Mark AI Message!", { roomId, asAI: true });
+
+/* sending view once */
 wa.text({ image: "https://example.com/image.png", text: "View once" }, { roomId, asViewOnce: true });
+```
+
+### Message Reactions, Edits, and Deletion
+
+Add reactions, edit, or delete messages.
+
+```ts
+/* sending reaction */
 wa.reaction("👍", { message });
-wa.edit("Edited", { message: await wa.text("Original", { roomId })?.message });
-wa.delete("Deleted", { message: await wa.text("To delete", { roomId })?.message });
-wa.location({ latitude: 24.121231, longitude: 55.1121221 }, { roomId });
-wa.contact({ fullname: "Kejaa", whatsAppNumber: 628123456789 }, { roomId });
+
+/* sending edit */
+const original = await wa.text("Will edit", { roomId });
+wa.edit("Edited", { message: original?.message });
+
+/* sending delete */
+const original = await wa.text("Will delete", { roomId });
+wa.delete("Deleted", { message: original?.message });
+```
+
+### Polls
+
+Create interactive polls.
+
+```ts
+/* sending polling */
 wa.poll({ name: "Do you love me?", answers: ["Yes", "Maybe", "No"] }, { roomId });
 ```
 
-### Sending Media
+### Contacts
+
+Share contact information.
+
+```ts
+/* sending contact */
+wa.contact({ fullname: "Kejaa", whatsAppNumber: 628123456789 }, { roomId });
+```
+
+### Location
 
-Supports URLs and local files (via Buffer).
+Share geographic coordinates.
+
+```ts
+/* sending location */
+wa.location({ latitude: 24.121231, longitude: 55.1121221 }, { roomId });
+```
+
+## 🖼 Sending Media
+
+### Images and Stickers
+
+Send images or stickers from URLs or local files.
 
 ```ts
 import fs from "fs";
 
-// Image (URL or file)
-wa.text({ image: "https://example.com/image.png", text: "Image" }, { roomId });
+/* sending by url */
+wa.text({ image: "https://github.com/zeative.png", text: "Image" }, { roomId });
+
+/* sending by file */
 wa.text({ image: fs.readFileSync("example/image.png"), text: "Image" }, { roomId });
 
-// Sticker
-wa.text({ sticker: "https://example.com/sticker.png" }, { roomId });
-wa.text({ sticker: fs.readFileSync("example/sticker.png") }, { roomId });
+/* sending sticker */
+wa.text({ sticker: "https://github.com/zeative.png" }, { roomId });
+```
 
-// GIF
-wa.text({ gif: "https://example.com/video.mp4" }, { roomId });
-wa.text({ gif: fs.readFileSync("example/video.mp4") }, { roomId });
+### Videos and GIFs
 
-// Video
+Send videos or GIFs with optional captions.
+
+```ts
+/* sending video */
 wa.text({ video: "https://example.com/video.mp4", text: "Video" }, { roomId });
-wa.text({ video: fs.readFileSync("example/video.mp4"), text: "Video" }, { roomId });
 
-// Video Note
-wa.text({ videoNote: "https://example.com/video.mp4" }, { roomId });
-wa.text({ videoNote: fs.readFileSync("example/video.mp4") }, { roomId });
+/* sending video as circle */
+wa.text({ note: "https://example.com/video.mp4", text: "Video" }, { roomId });
 
-// Audio (use .ogg for better compatibility)
+/* sending gif */
+wa.text({ gif: "https://example.com/video.mp4" }, { roomId });
+```
+
+### Audio and Voice Notes
+
+Send audio files or voice notes (use `.ogg` for compatibility).
+
+```ts
+/* sending audio (recommended use .ogg format) */
 wa.text({ audio: "https://example.com/audio.ogg" }, { roomId });
-wa.text({ audio: fs.readFileSync("example/audio.ogg") }, { roomId });
 
-// Voice Note (use .ogg for better compatibility)
-wa.text({ audioNote: "https://example.com/audio.ogg" }, { roomId });
-wa.text({ audioNote: fs.readFileSync("example/audio.ogg") }, { roomId });
+/* sending voice note (recommended use .ogg format) */
+wa.text({ voice: "https://example.com/audio.ogg" }, { roomId });
 ```
 
-### Presence Update
+## 🔧 Advanced Actions
+
+### Presence Updates
+
+Update the bot’s presence status in a chat.
 
 ```ts
 wa.presence("typing", { roomId }); // Options: typing, recording, online, offline, paused
 ```
 
-### Get Profile
+### Profile Retrieval
+
+Fetch user or group profiles.
 
 ```ts
 wa.profile("628123456789@s.whatsapp.net"); // User profile
 wa.profile("1209999@g.us"); // Group profile
 ```
 
-### Reject Call
-
-```ts
-wa.on("calls", (ctx) => {
-  wa.rejectCall({ callId: ctx.callId, callerId: ctx.callerId });
-});
-```
-
-## 🐞 Issues & Feedback
+## 🐛 Issues & Feedback
 
-Report issues or request features at [GitHub Issues](https://github.com/zeative/zaileys/issues).
+Encounter a bug or have a feature request? Submit it on our [GitHub Issues](https://github.com/zeative/zaileys/issues) page.
 
 ## ❤️ Support
 
-Support the project:
+Show your support for Zaileys:
 
 - [Buy me a coffee ☕](https://saweria.co/zaadevofc)
-- ⭐ Star the repo on [GitHub](https://github.com/zeative/zaileys).
+- ⭐ Star the repository on [GitHub](https://github.com/zeative/zaileys)
 
-## 📄 License
+## 📜 License
 
-[MIT License](https://github.com/zeative/zaileys/blob/main/LICENSE).
+Zaileys is licensed under the [MIT License](https://github.com/zeative/zaileys/blob/main/LICENSE).
 
-## 🙏 Acknowledgements
+## 🙌 Acknowledgements
 
-Built on [Baileys](https://github.com/WhiskeySockets/Baileys) by Whiskey Sockets.
+Powered by [Baileys](https://github.com/WhiskeySockets/Baileys) from Whiskey Sockets.
 
-> Happy coding! 🚀
+Happy coding! 🚀