@roidev/kachina-md 2.1.0 → 2.1.2

package/lib/helpers/database.js

@@ -3,7 +3,27 @@ import { JSONFile } from 'lowdb/node';
 import fs from 'fs';
 import path from 'path';
 
+/**
+ * @typedef {Object} DatabaseOptions
+ * @property {string} [path='./database'] - Path to database directory
+ */
+
+/**
+ * Simple JSON-based database wrapper using LowDB
+ * Provides key-value storage organized by collections
+ * Each collection is stored as a separate JSON file
+ *
+ * @class Database
+ * @example
+ * const db = new Database({ path: './data' });
+ * await db.set('users', 'john', { name: 'John', age: 30 });
+ * const user = await db.get('users', 'john');
+ */
 export class Database {
+    /**
+     * Creates a new Database instance
+     * @param {DatabaseOptions} [options={}] - Database configuration
+     */
     constructor(options = {}) {
         this.path = options.path || './database';
         this.collections = new Map();
@@ -14,6 +34,17 @@ export class Database {
         }
     }
 
+    /**
+     * Get or create a collection (LowDB instance)
+     * @async
+     * @param {string} name - Collection name (becomes filename)
+     * @param {Object} [defaultData={}] - Default data if collection doesn't exist
+     * @returns {Promise<Low>} LowDB instance
+     * @example
+     * const usersDb = await db.collection('users');
+     * usersDb.data.john = { name: 'John' };
+     * await usersDb.write();
+     */
     async collection(name, defaultData = {}) {
         if (this.collections.has(name)) {
             return this.collections.get(name);
@@ -31,12 +62,34 @@ export class Database {
         return db;
     }
 
+    /**
+     * Get a value from collection
+     * @async
+     * @template T
+     * @param {string} collection - Collection name
+     * @param {string} key - Key to retrieve
+     * @param {T} [defaultValue=null] - Default value if key doesn't exist
+     * @returns {Promise<T>} Value or default value
+     * @example
+     * const user = await db.get('users', 'john', { name: 'Unknown' });
+     */
     async get(collection, key, defaultValue = null) {
         const db = await this.collection(collection, {});
         await db.read();
         return db.data[key] ?? defaultValue;
     }
 
+    /**
+     * Set a value in collection
+     * @async
+     * @template T
+     * @param {string} collection - Collection name
+     * @param {string} key - Key to set
+     * @param {T} value - Value to store
+     * @returns {Promise<T>} The value that was set
+     * @example
+     * await db.set('users', 'john', { name: 'John', age: 30 });
+     */
     async set(collection, key, value) {
         const db = await this.collection(collection, {});
         await db.read();
@@ -45,12 +98,32 @@ export class Database {
         return value;
     }
 
+    /**
+     * Check if key exists in collection
+     * @async
+     * @param {string} collection - Collection name
+     * @param {string} key - Key to check
+     * @returns {Promise<boolean>} True if key exists
+     * @example
+     * if (await db.has('users', 'john')) {
+     *   console.log('User exists');
+     * }
+     */
     async has(collection, key) {
         const db = await this.collection(collection, {});
         await db.read();
         return key in db.data;
     }
 
+    /**
+     * Delete a key from collection
+     * @async
+     * @param {string} collection - Collection name
+     * @param {string} key - Key to delete
+     * @returns {Promise<boolean>} True if successful
+     * @example
+     * await db.delete('users', 'john');
+     */
     async delete(collection, key) {
         const db = await this.collection(collection, {});
         await db.read();
@@ -59,12 +132,29 @@ export class Database {
         return true;
     }
 
+    /**
+     * Get all data from collection
+     * @async
+     * @param {string} collection - Collection name
+     * @returns {Promise<Object>} All collection data
+     * @example
+     * const allUsers = await db.all('users');
+     * console.log(Object.keys(allUsers)); // ['john', 'jane', ...]
+     */
     async all(collection) {
         const db = await this.collection(collection, {});
         await db.read();
         return db.data;
     }
 
+    /**
+     * Clear all data from collection
+     * @async
+     * @param {string} collection - Collection name
+     * @returns {Promise<boolean>} True if successful
+     * @example
+     * await db.clear('users'); // Removes all users
+     */
     async clear(collection) {
         const db = await this.collection(collection, {});
         db.data = {};
@@ -72,6 +162,19 @@ export class Database {
         return true;
     }
 
+    /**
+     * Update a value in collection
+     * @async
+     * @param {string} collection - Collection name
+     * @param {string} key - Key to update
+     * @param {Function|Object} updater - Function that receives old value and returns new value, or object to merge
+     * @returns {Promise<*>} Updated value
+     * @example
+     * // Using function
+     * await db.update('users', 'john', (user) => ({ ...user, age: 31 }));
+     * // Using object merge
+     * await db.update('users', 'john', { age: 31 });
+     */
     async update(collection, key, updater) {
         const db = await this.collection(collection, {});
         await db.read();
@@ -86,6 +189,20 @@ export class Database {
         return db.data[key];
     }
 
+    /**
+     * Increment a numeric field in a stored object
+     * @async
+     * @param {string} collection - Collection name
+     * @param {string} key - Key of object to update
+     * @param {string} field - Field name to increment
+     * @param {number} [amount=1] - Amount to increment by
+     * @returns {Promise<Object>} Updated object
+     * @example
+     * // Increment user score by 10
+     * await db.increment('users', 'john', 'score', 10);
+     * // Increment by 1 (default)
+     * await db.increment('users', 'john', 'loginCount');
+     */
     async increment(collection, key, field, amount = 1) {
         return await this.update(collection, key, (data) => {
             data = data || {};
@@ -94,6 +211,18 @@ export class Database {
         });
     }
 
+    /**
+     * Push a value to an array
+     * @async
+     * @param {string} collection - Collection name
+     * @param {string} key - Key of array to update
+     * @param {*} value - Value to push
+     * @returns {Promise<Array>} Updated array
+     * @example
+     * await db.push('chats', 'john', 'Hello');
+     * await db.push('chats', 'john', 'How are you?');
+     * // chats.john = ['Hello', 'How are you?']
+     */
     async push(collection, key, value) {
         return await this.update(collection, key, (data) => {
             data = data || [];
@@ -104,6 +233,17 @@ export class Database {
         });
     }
 
+    /**
+     * Remove a value from an array
+     * @async
+     * @param {string} collection - Collection name
+     * @param {string} key - Key of array to update
+     * @param {*} value - Value to remove
+     * @returns {Promise<Array>} Updated array
+     * @example
+     * await db.pull('chats', 'john', 'Hello');
+     * // Removes 'Hello' from the array
+     */
     async pull(collection, key, value) {
         return await this.update(collection, key, (data) => {
             if (Array.isArray(data)) {

package/lib/helpers/index.js

@@ -4,10 +4,27 @@ export { Logger } from './logger.js';
 export * from './sticker.js';
 
 // Utility functions
+
+/**
+ * Sleep for specified milliseconds
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ * @example
+ * await sleep(1000); // Sleep for 1 second
+ */
 export function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+/**
+ * Format seconds into human-readable time string
+ * @param {number} seconds - Seconds to format
+ * @returns {string} Formatted time string (e.g., "1d 2h 30m" or "5m 30s")
+ * @example
+ * formatTime(90); // "1m 30s"
+ * formatTime(3661); // "1h 1m 1s"
+ * formatTime(90000); // "1d 1h 0m"
+ */
 export function formatTime(seconds) {
     const days = Math.floor(seconds / 86400);
     const hours = Math.floor((seconds % 86400) / 3600);
@@ -20,6 +37,15 @@ export function formatTime(seconds) {
     return `${secs}s`;
 }
 
+/**
+ * Format bytes into human-readable size string
+ * @param {number} bytes - Bytes to format
+ * @returns {string} Formatted size string (e.g., "1.5 MB", "500 KB")
+ * @example
+ * formatBytes(1024); // "1 KB"
+ * formatBytes(1536000); // "1.46 MB"
+ * formatBytes(0); // "0 B"
+ */
 export function formatBytes(bytes) {
     if (bytes === 0) return '0 B';
     const k = 1024;
@@ -28,6 +54,16 @@ export function formatBytes(bytes) {
     return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
 }
 
+/**
+ * Parse command from text message
+ * @param {string} text - Text to parse
+ * @param {string} [prefix='!'] - Command prefix
+ * @returns {{command: string, args: Array<string>, text: string}|null} Parsed command object or null if no command
+ * @example
+ * parseCommand('!help me', '!');
+ * // { command: 'help', args: ['me'], text: 'me' }
+ * parseCommand('hello'); // null
+ */
 export function parseCommand(text, prefix = '!') {
     if (!text.startsWith(prefix)) return null;
 
@@ -39,15 +75,39 @@ export function parseCommand(text, prefix = '!') {
     };
 }
 
+/**
+ * Check if text is a URL
+ * @param {string} text - Text to check
+ * @returns {boolean} True if text is a URL
+ * @example
+ * isUrl('https://example.com'); // true
+ * isUrl('hello world'); // false
+ */
 export function isUrl(text) {
     return /^https?:\/\//i.test(text);
 }
 
+/**
+ * Extract all URLs from text
+ * @param {string} text - Text to extract URLs from
+ * @returns {Array<string>} Array of URLs found
+ * @example
+ * extractUrls('Visit https://example.com and http://test.com');
+ * // ['https://example.com', 'http://test.com']
+ */
 export function extractUrls(text) {
     const urlRegex = /https?:\/\/[^\s]+/gi;
     return text.match(urlRegex) || [];
 }
 
+/**
+ * Generate random alphanumeric string
+ * @param {number} [length=10] - Length of string
+ * @returns {string} Random string
+ * @example
+ * randomString(5); // "aB3xZ"
+ * randomString(); // "a1B2c3D4e5" (10 chars)
+ */
 export function randomString(length = 10) {
     const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
     let result = '';
@@ -57,14 +117,39 @@ export function randomString(length = 10) {
     return result;
 }
 
+/**
+ * Generate random number in range
+ * @param {number} min - Minimum value (inclusive)
+ * @param {number} max - Maximum value (inclusive)
+ * @returns {number} Random number
+ * @example
+ * randomNumber(1, 10); // Random number between 1 and 10
+ */
 export function randomNumber(min, max) {
     return Math.floor(Math.random() * (max - min + 1)) + min;
 }
 
+/**
+ * Pick random element from array
+ * @template T
+ * @param {Array<T>} array - Array to pick from
+ * @returns {T} Random element
+ * @example
+ * pickRandom(['red', 'blue', 'green']); // One of the colors
+ */
 export function pickRandom(array) {
     return array[Math.floor(Math.random() * array.length)];
 }
 
+/**
+ * Split array into chunks of specified size
+ * @template T
+ * @param {Array<T>} array - Array to chunk
+ * @param {number} size - Chunk size
+ * @returns {Array<Array<T>>} Array of chunks
+ * @example
+ * chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+ */
 export function chunk(array, size) {
     const chunks = [];
     for (let i = 0; i < array.length; i += size) {

package/lib/helpers/logger.js

@@ -1,6 +1,25 @@
 import chalk from 'chalk';
 
+/**
+ * @typedef {Object} LoggerOptions
+ * @property {'debug'|'info'|'success'|'warn'|'error'} [level='info'] - Minimum log level to display
+ * @property {string} [prefix=''] - Prefix for all log messages
+ */
+
+/**
+ * Colored console logger with different log levels
+ * @class Logger
+ * @example
+ * const logger = new Logger({ prefix: 'MyBot', level: 'debug' });
+ * logger.info('Bot started');
+ * logger.success('Connected successfully');
+ * logger.error('Connection failed');
+ */
 export class Logger {
+    /**
+     * Creates a new Logger instance
+     * @param {LoggerOptions} [options={}] - Logger configuration
+     */
     constructor(options = {}) {
         this.level = options.level || 'info';
         this.prefix = options.prefix || '';
@@ -13,46 +32,96 @@ export class Logger {
         };
     }
 
+    /**
+     * Check if message should be logged based on log level
+     * @private
+     * @param {string} level - Log level to check
+     * @returns {boolean} True if should log
+     */
     shouldLog(level) {
         return this.levels[level] >= this.levels[this.level];
     }
 
+    /**
+     * Format log message with timestamp and prefix
+     * @private
+     * @param {string} level - Log level
+     * @param {...*} args - Arguments to format
+     * @returns {string} Formatted message
+     */
     format(level, ...args) {
         const timestamp = new Date().toLocaleTimeString();
         const prefix = this.prefix ? `[${this.prefix}] ` : '';
         return `${chalk.gray(timestamp)} ${prefix}${args.join(' ')}`;
     }
 
+    /**
+     * Log debug message (gray)
+     * @param {...*} args - Values to log
+     * @example
+     * logger.debug('Debugging info', { data: 'value' });
+     */
     debug(...args) {
         if (this.shouldLog('debug')) {
             console.log(chalk.gray('[DEBUG]'), this.format('debug', ...args));
         }
     }
 
+    /**
+     * Log info message (blue)
+     * @param {...*} args - Values to log
+     * @example
+     * logger.info('Bot started successfully');
+     */
     info(...args) {
         if (this.shouldLog('info')) {
             console.log(chalk.blue('[INFO]'), this.format('info', ...args));
         }
     }
 
+    /**
+     * Log success message (green)
+     * @param {...*} args - Values to log
+     * @example
+     * logger.success('Connected to WhatsApp');
+     */
     success(...args) {
         if (this.shouldLog('success')) {
             console.log(chalk.green('[SUCCESS]'), this.format('success', ...args));
         }
     }
 
+    /**
+     * Log warning message (yellow)
+     * @param {...*} args - Values to log
+     * @example
+     * logger.warn('Rate limit approaching');
+     */
     warn(...args) {
         if (this.shouldLog('warn')) {
             console.log(chalk.yellow('[WARN]'), this.format('warn', ...args));
         }
     }
 
+    /**
+     * Log error message (red)
+     * @param {...*} args - Values to log
+     * @example
+     * logger.error('Connection failed:', error);
+     */
     error(...args) {
         if (this.shouldLog('error')) {
             console.error(chalk.red('[ERROR]'), this.format('error', ...args));
         }
     }
 
+    /**
+     * Log command execution (cyan)
+     * @param {string} command - Command name
+     * @param {string} from - Sender information
+     * @example
+     * logger.command('!ping', 'User@s.whatsapp.net');
+     */
     command(command, from) {
         console.log(
             chalk.cyan('[CMD]'),

package/lib/helpers/serialize.js

@@ -1,6 +1,43 @@
 import { downloadMediaMessage, getContentType } from 'baileys';
 import { fileTypeFromBuffer } from 'file-type';
 
+/**
+ * @typedef {Object} SerializedMessage
+ * @property {Object} key - Message key
+ * @property {string} chat - Chat JID (remoteJid)
+ * @property {boolean} fromMe - Whether message is from bot
+ * @property {string} id - Message ID
+ * @property {boolean} isGroup - Whether chat is a group
+ * @property {string} sender - Sender JID
+ * @property {string} pushName - Sender push name
+ * @property {string} type - Message type (e.g., 'conversation', 'imageMessage')
+ * @property {Object} message - Raw message object
+ * @property {string} body - Message text content
+ * @property {SerializedMessage} [quoted] - Quoted/replied message
+ * @property {string} caption - Media caption
+ * @property {string} mimetype - Media mime type
+ * @property {number} fileSize - Media file size
+ * @property {Array<string>} mentions - Mentioned JIDs
+ * @property {Function} reply - Reply to message
+ * @property {Function} react - React to message with emoji
+ * @property {Function} download - Download media from message
+ * @property {Function} delete - Delete message
+ * @property {Function} forward - Forward message
+ * @property {Function} copyNForward - Copy and forward message
+ */
+
+/**
+ * Serialize raw Baileys message into standardized format with helper methods
+ * @async
+ * @param {Object} msg - Raw Baileys message object
+ * @param {Object} sock - WhatsApp socket instance
+ * @returns {Promise<SerializedMessage>} Serialized message object
+ * @example
+ * const m = await serialize(rawMessage, sock);
+ * console.log(m.body); // Message text
+ * await m.reply('Hello!'); // Reply to message
+ * await m.react('👍'); // React with emoji
+ */
 export async function serialize(msg, sock) {
     if (!msg) return msg;
 
@@ -86,6 +123,12 @@ export async function serialize(msg, sock) {
     return m;
 }
 
+/**
+ * Extract text body from various message types
+ * @private
+ * @param {Object} message - Message object
+ * @returns {string} Extracted text content
+ */
 function getBody(message) {
     if (!message) return '';
 

package/lib/helpers/sticker.js

@@ -1,10 +1,28 @@
 import { Sticker, StickerTypes } from 'wa-sticker-formatter';
 
+/**
+ * @typedef {Object} StickerOptions
+ * @property {string} [pack='Sticker'] - Sticker pack name
+ * @property {string} [author='Kachina Bot'] - Sticker author name
+ * @property {string} [type] - Sticker type (DEFAULT, FULL, CROPPED, CIRCLE, ROUNDED)
+ * @property {Array<string>} [categories=[]] - Sticker categories
+ * @property {string} [id=''] - Sticker ID
+ * @property {number} [quality=50] - Image quality (1-100)
+ * @property {string} [background='transparent'] - Background color
+ */
+
 /**
  * Create sticker from image/video buffer
- * @param {Buffer} buffer - Image or video buffer
- * @param {Object} options - Sticker options
- * @returns {Promise<Buffer>} Sticker buffer
+ * @async
+ * @param {Buffer|string} buffer - Image or video buffer, or file path/URL
+ * @param {StickerOptions} [options={}] - Sticker configuration options
+ * @returns {Promise<Buffer>} Sticker buffer ready to send
+ * @example
+ * const stickerBuffer = await createSticker(imageBuffer, {
+ *   pack: 'My Stickers',
+ *   author: 'My Bot',
+ *   type: StickerTypes.FULL
+ * });
  */
 export async function createSticker(buffer, options = {}) {
     const sticker = new Sticker(buffer, {
@@ -21,7 +39,16 @@ export async function createSticker(buffer, options = {}) {
 }
 
 /**
- * Create full sticker (no crop)
+ * Create full sticker without cropping (preserves original aspect ratio)
+ * @async
+ * @param {Buffer|string} buffer - Image or video buffer, or file path/URL
+ * @param {StickerOptions} [options={}] - Sticker configuration options
+ * @returns {Promise<Buffer>} Full sticker buffer
+ * @example
+ * const sticker = await createFullSticker(imageBuffer, {
+ *   pack: 'My Pack',
+ *   author: 'Bot'
+ * });
  */
 export async function createFullSticker(buffer, options = {}) {
     return await createSticker(buffer, {
@@ -31,7 +58,13 @@ export async function createFullSticker(buffer, options = {}) {
 }
 
 /**
- * Create cropped sticker
+ * Create cropped sticker (1:1 aspect ratio, center-cropped)
+ * @async
+ * @param {Buffer|string} buffer - Image or video buffer, or file path/URL
+ * @param {StickerOptions} [options={}] - Sticker configuration options
+ * @returns {Promise<Buffer>} Cropped sticker buffer
+ * @example
+ * const sticker = await createCroppedSticker(imageBuffer);
  */
 export async function createCroppedSticker(buffer, options = {}) {
     return await createSticker(buffer, {
@@ -41,7 +74,13 @@ export async function createCroppedSticker(buffer, options = {}) {
 }
 
 /**
- * Create circle sticker
+ * Create circle-shaped sticker
+ * @async
+ * @param {Buffer|string} buffer - Image or video buffer, or file path/URL
+ * @param {StickerOptions} [options={}] - Sticker configuration options
+ * @returns {Promise<Buffer>} Circle sticker buffer
+ * @example
+ * const sticker = await createCircleSticker(profilePicBuffer);
  */
 export async function createCircleSticker(buffer, options = {}) {
     return await createSticker(buffer, {
@@ -51,7 +90,13 @@ export async function createCircleSticker(buffer, options = {}) {
 }
 
 /**
- * Create rounded sticker
+ * Create sticker with rounded corners
+ * @async
+ * @param {Buffer|string} buffer - Image or video buffer, or file path/URL
+ * @param {StickerOptions} [options={}] - Sticker configuration options
+ * @returns {Promise<Buffer>} Rounded sticker buffer
+ * @example
+ * const sticker = await createRoundedSticker(imageBuffer);
  */
 export async function createRoundedSticker(buffer, options = {}) {
     return await createSticker(buffer, {