swan-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cauê Samonek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Message.js

@@ -0,0 +1,82 @@
+import fs from 'fs'
+import axios from 'axios'
+
+import MessageMedia from './MessageMedia.js'
+import { downloadContentFromMessage } from '@whiskeysockets/baileys'
+
+// Wrapper class for baileys API message object
+export default class Message { 
+    // each Message stores its socket, chat/user information and context
+    constructor(socket, baileysMessage){
+        // saves socket and original message object
+        this.socket = socket;
+        this.baileysMsg = baileysMessage;
+
+        // simplify subsequent access
+        const m = this.baileysMsg.message;
+        const k = this.baileysMsg.key;
+
+        // simplify and standardize attribute names
+        this.fromId = k.remoteJid;
+        this.fromMe = k.fromMe;
+        this.author = k.participant || k.remoteJid;
+        this.fromName = this.baileysMsg.pushName;
+        this.type = Object.keys(m)[0].replace("Message","").toLowerCase() || 'conversation'        
+        this.text = m.conversation || m.extendedTextMessage?.text || m.imageMessage?.caption || m.videoMessage?.caption || '';
+
+        this.media = m.imageMessage || m.videoMessage || m.documentMessage || m.stickerMessage;
+    
+        // build the quoted message, if any
+        this.quoted = null;
+        const ctx = m.extendedTextMessage?.contextInfo;
+        if (ctx?.quotedMessage){
+            this.quoted = new Message(socket, {
+                key: {remoteJid: this.fromId, fromMe: ctx.participant === socket.user.id},
+                message: ctx.quotedMessage
+            });
+        }
+    }
+
+    // Returns the attached media as a MessageMedia object, or null if none exists
+    async downloadMedia() {
+        if (!this.media) return null;
+        const stream = await downloadContentFromMessage(this.media, this.type);
+
+        const chunks = [];
+        for await (const chunk of stream)
+            chunks.push(chunk);
+        const buffer = Buffer.concat(chunks);
+
+        return new MessageMedia(buffer, this.media.mimetype);
+    }
+
+    // returns the sender's name and phone number
+    async getContact() {
+        const jid = this.fromMe ? this.socket.user.id : this.author;
+        const number = jid.split('@')[0];
+        return {name: this.fromName, number}
+    }
+
+    // get chat name and if it is a group or not
+    async getChat(){
+        const isGroup = this.fromId.endsWith("@g.us");
+        let name = this.fromName;
+
+        if (isGroup) {
+            const metadata = await this.socket.groupMetadata(this.fromId);
+            name = metadata.subject;
+        }
+
+        return {name, isGroup}
+    }
+
+    // send message as a reply by adding 'quoted' in the options and call 'send()'
+    async reply(content, options = {}){
+        return this.send(content, {...options, quoted: this.baileysMsg})
+    }
+
+    // calls the socket's send function
+    async send(content, options = {}){
+        return this.socket.send(this.fromId, content, options)
+    }
+}

package/MessageMedia.js

@@ -0,0 +1,25 @@
+import fs from 'fs'
+import axios from 'axios'
+import mime from 'mime-types'
+
+// Wrapper for media content
+export default class MessageMedia {
+    // stores data and mimetype
+    constructor(data, mimetype) {
+        this.data = data
+        this.mimetype = mimetype;
+    }
+
+    // Creates MessageMedia from a local file
+    static fromFile(path) {
+        const buffer = fs.readFileSync(path)
+        const mimetype = mime.lookup(path);
+        return new MessageMedia(buffer, mimetype)
+    }
+
+    // Creates MessageMedia from a URL (must point to a valid media file)
+    static async fromUrl(url) {
+        const res = await axios.get(url, { responseType: 'arraybuffer' })
+        return new MessageMedia(Buffer.from(res.data), res.headers['content-type'])
+    }
+}

package/README.md

@@ -0,0 +1,183 @@
+# SWAN
+
+**SWAN** (**S**imple **W**hatsApp **A**PI for **N**ode) is a lightweight wrapper around the Baileys library that provides a simpler and more intuitive interface for building WhatsApp bots in Node.js.
+
+
+
+## Features
+
+- Simple socket management with automatic reconnection.
+- QR code authentication.
+- Easy message sending.
+- Built-in reply support.
+- Media download and upload.
+- Sticker creation from images and videos.
+- Convenient wrappers for contacts, chats and messages.
+- Minimal API with no unnecessary abstractions.
+
+## Installation
+
+```bash
+npm install swan-api
+```
+## Usage
+
+### Basic bot
+
+```javascript
+import {Socket} from "swan-api";
+
+const socket = new Socket();
+
+socket.on("ready", () => console.log('Socket Ready!'))
+
+socket.on("newMessage", async (msg) => {
+    if (msg.text.toLowerCase() === "ping")
+        await msg.reply("pong!");
+});
+```
+
+### Media and message handling
+
+```javascript
+import {Socket, MessageMedia} from "swan-api";
+
+const socket = new Socket();
+
+socket.on("ready", () => {
+    console.log("Bot connected!");
+});
+
+socket.on("newMessage", async (msg) => {
+    // Avoids infinite loop
+    if (msg.fromMe)
+        return;
+
+    console.log(`Message from ${msg.author}: ${msg.text}`);
+
+    await msg.reply("Processing your message...");
+
+    // If an image was sent, sends it back as a sticker
+    const media = await msg.downloadMedia();
+    if (media)
+        await msg.reply(media, {asSticker: true});
+});
+```
+
+## API
+
+### Socket
+
+Creates and manages the WhatsApp connection.
+
+```javascript
+const socket = new Socket();
+```
+
+#### Events
+
+| Event | Description |
+| ------ | ----------- |
+| `ready` | Fired after a successful connection. |
+| `newMessage` | Fired whenever a new message is received. |
+
+### Message
+
+Represents a received WhatsApp message.
+
+#### Properties
+
+| Property | Description |
+| -------- | ----------- |
+| `text` | Message text. |
+| `type` | Message type. |
+| `fromId` | Chat JID. |
+| `fromName` | Sender push name. |
+| `fromMe` | Whether the message was sent by the current user. |
+| `author` | Sender JID. |
+| `media` | Attached media information, if any. |
+| `quoted` | Quoted `Message`, if present. |
+
+#### Methods
+
+##### `reply(content, options?)`
+
+Replies to the current message.
+
+```javascript
+await msg.reply("Hi!");
+```
+
+##### `send(content, options?)`
+
+Sends a message to the current chat.
+
+```javascript
+await msg.send("Hello everyone!");
+```
+
+##### `downloadMedia()`
+
+Downloads the attached media.
+
+```javascript
+const media = await msg.downloadMedia();
+```
+
+##### `getContact()`
+
+Returns sender information.
+
+```javascript
+const contact = await msg.getContact();
+
+console.log(contact.name);
+console.log(contact.number);
+```
+
+##### `getChat()`
+
+Returns chat information.
+
+```javascript
+const chat = await msg.getChat();
+
+console.log(chat.name);
+console.log(chat.isGroup);
+```
+
+---
+
+### MessageMedia
+
+Represents a media file.
+
+#### Static methods
+
+##### `MessageMedia.fromFile(path)`
+
+```javascript
+const media = MessageMedia.fromFile("./photo.jpg");
+```
+
+##### `MessageMedia.fromUrl(url)`
+
+```javascript
+const media = await MessageMedia.fromUrl("https://example.com/image.png");
+```
+
+---
+
+## Exports
+
+```javascript
+import {  
+    Socket,
+    Message,
+    MessageMedia
+} from "swan-api";
+```
+
+## License
+
+MIT

package/Socket.js

@@ -0,0 +1,113 @@
+import makeWASocket, { useMultiFileAuthState, fetchLatestBaileysVersion, DisconnectReason } from '@whiskeysockets/baileys'
+
+import P from 'pino'
+import qrcode from 'qrcode-terminal'
+import { EventEmitter } from "node:events";
+import { Sticker } from 'wa-sticker-formatter'
+
+import Message from './Message.js';
+import MessageMedia from './MessageMedia.js';
+
+//Wrapper Class For Baileys Socket
+export default class Socket extends EventEmitter {
+    // creates a socket instance
+    constructor() {
+        super();
+        this.connect();
+    }
+
+    // tries to authenticate and bind default events
+    async connect() {
+        await this.authenticate();
+        this.bindEvents();
+    }
+
+    //creates new baileys socket and authenticate
+    async authenticate(){
+        const { state, saveCreds } = await useMultiFileAuthState('auth')
+        const { version } = await fetchLatestBaileysVersion()
+
+        this.socket = makeWASocket({version, auth: state, logger: P({level: 'silent'})});
+        this.user = this.socket.user;
+        this.socket.ev.on('creds.update', saveCreds)
+    }
+
+    //bind events from baileys to default treatment functions
+    bindEvents(){
+        //each new message emits a 'newMessage' event and a 'Message' object
+        this.socket.ev.on('messages.upsert', ({messages}) => {
+            for (const msg of messages){
+                if (!msg.message)
+                    continue;
+                this.emit("newMessage", new Message(this, msg));
+            }
+        });
+        
+        //emits 'ready' when opens connection
+        //on connnection lost, tries to reconnect
+        this.socket.ev.on('connection.update', (update) => {
+            const { connection, lastDisconnect, qr } = update;
+            if (qr)
+                qrcode.generate(qr, {small: true})
+
+            if (connection == "close"){
+                const shouldReconnect = lastDisconnect?.error?.output?.statusCode
+                                                    !== DisconnectReason.loggedOut;
+                if (shouldReconnect)
+                    this.connect();
+            } else if (connection == 'open')
+                this.emit('ready');
+        });
+    }
+
+
+    // send message wrapper function
+    async send(jid, content, opts = {}){
+        // replies text messages directly
+        if (typeof content === 'string')
+            return this.socket.sendMessage(jid, {text: content}, opts)
+
+        // from this point on 'content' must be 'MessageMedia'
+        if (!(content instanceof MessageMedia))
+            throw new Error(`SWAN send(): invalid content type: ${typeof(content)}`);
+
+        // simplify data access
+        const buffer = content.data
+        const mimetype = content.mimetype
+        
+        // parse media for sticker creation
+        if (opts.asSticker){
+            const isVideo = mimetype?.startsWith('video') || mimetype === 'image/gif'
+            // video proportion must be 'full' to not get corrupted frames
+            if (isVideo)
+                opts.stickerProportion = 'full'
+
+            // tries to create the sticker at the highest quality,
+            // if the resulting file exceeds WhatsApp's 1MB limit
+            // the quality is reduced by 10% and retried
+            // throws an exception if quality goes below 0%
+            let final_quality = 1;
+            while (final_quality >= 0) {
+                const sticker = new Sticker(buffer, {
+                    pack: opts.stickerName,
+                    author: opts.stickerAuthor,
+                    type: opts.stickerProportion,
+                    quality: final_quality,
+                });
+
+                const webp = await sticker.toBuffer();
+                const size = (webp.length/1024)/1024;
+                if (size >= 1)
+                    final_quality -= 0.1;
+                else
+                    return await this.socket.sendMessage(jid, {sticker: webp}, opts)
+            }
+
+        }
+
+        //send regular files
+        for (const type of ['image', 'video', 'application'])
+             if (mimetype.startsWith(`${type}/`))
+                 return this.socket.sendMessage(jid, {[type]: buffer, mimetype}, opts)
+    }
+}

package/index.js

@@ -0,0 +1,3 @@
+export { default as Socket } from './Socket.js';
+export { default as Message } from './Message.js';
+export { default as MessageMedia } from './MessageMedia.js';

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "swan-api",
+  "version": "1.0.0",
+  "description": "Simple WhatsApp API for Node",
+  "keywords": [
+    "whatsapp",
+    "baileys",
+    "bot",
+    "api",
+    "wrapper",
+    "node"
+  ],
+  "homepage": "https://github.com/cauesamonek/SWAN",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cauesamonek/SWAN.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cauesamonek/SWAN/issues"
+  },
+  "license": "MIT",
+  "author": "Cauê Mateus Gonçalves Venturin Samonek",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "Socket.js",
+    "Message.js",
+    "MessageMedia.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@whiskeysockets/baileys": "^6.7.18",
+    "axios": "^1.11.0",
+    "pino": "^9.7.0",
+    "mime-types": "^3.0.1",
+    "qrcode-terminal": "^0.12.0",
+    "wa-sticker-formatter": "^4.4.4"
+  }
+}