@itsreimau/ckptw-mod

ckptw-mod - Fork of @mengkodingan/ckptw

NOTE!

This package is a fork of @mengkodingan/ckptw with enhanced WhatsApp features via baileys-mod. All original ckptw functions remain intact—refer to the original docs for complete documentation. This README only covers additional/modified features.

Key Features

• ✨ Effortless - Simple and intuitive API
• 🧱 Builder - Build complex messages easily
• 🛒 Built-in Collector, Cooldown, Command Handle - Essential utilities included
• 🚀 Middleware System - Intercept and process messages
• 💽 Custom Auth Adapter - Flexible session storage options
• 🎉 And more! - Extensive WhatsApp feature support

Table of Contents

• Installation
• Quick Start
  • Basic Example
  • Using Events
• Client Configuration
• Command System
  • Command Options
  • Command Handler
• Middleware System
• Cooldown System
• Builders
  • Contact Builder
• Collectors
  • Message Collector
  • Awaited Messages
• Media Handling
• Events Reference
• Message Sending
• Text Formatting
• Message Editing
• Message Deletion
• Poll Messages
• Mentions
• Custom Authentication
• Group Management
• Newsletter Features
• Miscellaneous Utilities
• Acknowledgements

Installation

npm install @itsreimau/ckptw-mod

Quick Start

Basic Example

const { Client, Events, MessageType } = require("@itsreimau/ckptw-mod");

// Initialize client with basic configuration
const bot = new Client({
    prefix: "!",
    printQRInTerminal: true,
    readIncommingMsg: true
});

// Client ready event
bot.ev.once(Events.ClientReady, (m) => {
    console.log(`Bot ready as ${m.user.id}`);
});

// Basic commands
bot.command("ping", async (ctx) => ctx.reply({ text: "pong!" }));
bot.command("hi", async (ctx) => ctx.reply("Hello! String replies work too!"));

// Message handlers
bot.hears("test", async (ctx) => ctx.reply("test 1 2 3 beep boop..."));
bot.hears(MessageType.stickerMessage, async (ctx) => ctx.reply("Cool sticker!"));
bot.hears(["help", "menu"], async (ctx) => ctx.reply("Array matching works!"));
bot.hears(/(using\s?)?regex/, async (ctx) => ctx.reply("Regex matching works!"));

// Start the bot
bot.launch();

Using Events

const { Client, Events } = require("@itsreimau/ckptw-mod");

const bot = new Client({
    prefix: "!",
    printQRInTerminal: true,
    readIncommingMsg: true
});

// Client ready event
bot.ev.once(Events.ClientReady, (m) => {
    console.log(`Bot ready as ${m.user.id}`);
});

// Message handling via events
bot.ev.on(Events.MessagesUpsert, (m, ctx) => {
    if (m.key.fromMe) return;
    if (m.content === "hello") {
        ctx.reply("hi 👋");
    }
});

bot.launch();

Client Configuration

ClientOptions {
    prefix: Array<string> | string | RegExp; // Bot prefix(es)
    readIncommingMsg?: boolean; // Mark incoming messages as read (default: false)
    authDir?: string; // Path to auth directory (default: './state')
    printQRInTerminal?: boolean; // Display QR in terminal (default: false)
    qrTimeout?: number; // QR regeneration timeout in ms (default: 60000)
    markOnlineOnConnect?: boolean; // Mark online on connect (default: true)
    phoneNumber?: string; // Bot phone number with country code (e.g. '62xxx')
    usePairingCode?: boolean; // Use pairing code instead of QR (default: false)
    customPairingCode?: string; // Custom pairing code
    selfReply?: boolean; // Allow bot to respond to itself (default: false)
    WAVersion?: [number, number, number]; // Custom WhatsApp version
    autoMention?: boolean; // Auto-convert @mentions (default: false)
    autoAiLabel?: boolean; // Auto AI labels for bot messages (default: false)
    authAdapter?: Promise<any>; // Custom auth adapter
    browser?: WABrowserDescription; // Browser configuration
}

Command System

Command Options

Commands can be defined in two ways:

• Simple string command:

bot.command("ping", async (ctx) => ctx.reply("pong!"));

• Full command object:

bot.command({
    name: "ping",
    aliases: ["p"], // Optional aliases
    code: async (ctx) => ctx.reply("pong!"),
});

Command Handler

For better organization, commands can be split into separate files:

Main File Setup

const { CommandHandler } = require("@itsreimau/ckptw-mod");
const path = require("path");

// ... client initialization ...

const cmd = new CommandHandler(bot, path.resolve(__dirname, "commands"));
cmd.load(true); // Set to false to suppress loading logs

Command File Structure

// commands/ping.js
module.exports = {
    name: "ping",
    code: async (ctx) => {
        ctx.reply("pong!");
    }
};

// commands/greeting.js (hears type example)
module.exports = {
    name: "greeting",
    type: "hears", // Can be 'command' or 'hears'
    code: async (ctx) => {
        ctx.reply("Hello there!");
    }
};

Middleware System

Middleware allows pre-processing of messages before command execution:

bot.use(async (ctx, next) => {
    console.log(`Received message: ${ctx.msg.content}`);

    // Example: Block messages from specific users
    if (ctx.sender.id === "[e-mail]") return ctx.reply("You are blocked!");

    await next(); // Continue processing
});

Key Notes:

• Middlewares execute in registration order
• Call next() to continue processing
• Return early to block command execution

Cooldown System

Prevent command spamming with cooldowns:

const { Cooldown } = require("@itsreimau/ckptw-mod");

bot.command("ping", async (ctx) => {
    const cd = new Cooldown(ctx, 8000); // 8 second cooldown

    if (cd.onCooldown) return ctx.reply(`Please wait ${cd.timeleft}ms before using this again`);

    ctx.reply("pong!");

    // Optional cooldown end handler
    cd.on("end", () => {
        console.log("Cooldown expired");
    });
});

Cooldown Properties:

• onCooldown: Boolean indicating if active
• timeleft: Remaining time in milliseconds

Builders

Contact Builder

Create and send contact cards:

const { VCardBuilder } = require("@itsreimau/ckptw-mod");

const vcard = new VCardBuilder()
    .setFullName("Ayanami Rei")
    .setOrg("NERV")
    .setNumber("621234567890")
    .build();

ctx.reply({ contacts: { displayName: "Rei", contacts: [{ vcard }] } });

Collectors

Collect messages with flexible filtering:

Message Collector

const col = ctx.MessageCollector({
    time: 10000, // 10 second timeout
    max: 5, // Max 5 messages
    filter: (m) => m.sender === ctx.sender.id // Only collect from sender
});

ctx.reply("Say something... (10s timeout)");

col.on("collect", (m) => {
    ctx.reply(`Collected: ${m.content}`);
});

col.on("end", (_, reason) => {
    ctx.reply(`Collection ended: ${reason}`);
});

Awaited Messages

Simplified message collection:

ctx.awaitMessages({ time: 10000 })
    .then((messages) => ctx.reply(`Got ${messages.length} messages`))
    .catch(() => ctx.reply("Timed out"));

Media Handling

Download and process media attachments:

const { MessageType } = require("@itsreimau/ckptw-mod");
const fs = require("fs");

bot.ev.on(Events.MessagesUpsert, async (m, ctx) => {
    if (ctx.getMessageType() === MessageType.imageMessage) {
        const buffer = await ctx.msg.media.toBuffer();
        fs.writeFileSync("image.jpeg", buffer);
        ctx.reply("Image saved!");
    }
});

Media Access Methods:

// Current message
ctx.msg.media.toBuffer();
ctx.msg.media.toStream();

// Quoted message
ctx.quoted?.media.toBuffer();
ctx.quoted?.media.toStream();

Events Reference

Available events for handling various WhatsApp activities:

const { Events } = require("@itsreimau/ckptw-mod");

// Example event usage
bot.ev.on(Events.MessagesUpsert, (m, ctx) => {
    console.log("New message:", m);
});

Available Events:

• ClientReady: Bot initialization complete
• MessagesUpsert: New message received
• QR: QR code generated
• GroupsJoin: Bot joined a group
• UserJoin: User joined a group
• UserLeave: User left a group
• Poll: Poll created
• PollVote: Poll vote received
• Reactions: Message reaction
• Call: Incoming/outgoing call
• ConnectionUpdate: Connection status change

Message Sending

Various message types can be sent:

// Text message
ctx.reply("Hello world!");

// Image with caption
ctx.reply({ image: { url: "https://example.com/image.jpg" }, caption: "Check this out!" });

// Audio message
ctx.reply({ audio: { url: "./sound.mp3" }, mimetype: "audio/mp4", ptt: true /* Send as voice note */ });

// Video message
const fs = require("fs");
ctx.reply({ video: fs.readFileSync("./video.mp4"), caption: "Watch this!", gifPlayback: false });

// Sticker
ctx.reply({ sticker: { url: "./sticker.webp" } });

For buttons and interactive messages, refer to baileys-mod documentation.

Text Formatting

Format messages with WhatsApp's text styles:

const { bold } = require("@itsreimau/ckptw-mod");

ctx.reply(bold("Does this impact the lore?"));

Supported formatting functions:

• bold(text)
• italic(text)
• strikethrough(text)
• quote(text)
• inlineCode(text)
• monospace(text)
• smallCaps(text)

Message Editing

Edit sent messages:

const sentMsg = await ctx.reply("Does this impact the lore?");
ctx.editMessage(sentMsg.key, "Yes Rei, it does.");

Message Deletion

Delete messages:

const sentMsg = await ctx.reply("Third Impact!");
ctx.deleteMessage(sentMsg.key);

Poll Messages

Create polls:

ctx.sendPoll(ctx.id, { name: "Does this impact the lore?", values: ["Yes Rei, it does.", "No!"], singleSelect: true /* Allow only one selection */ });

Mentions

Manual Mentions

ctx.reply({ text: "Get in the EVA, @1234!", mentions: ["[e-mail]"] /* Full JID required */ });

Auto Mentions

Enable in client config:

const bot = new Client({
    autoMention: true // Enable automatic mention conversion
});

// Now @mentions will work automatically
ctx.reply("Get in the EVA, @62812345678!"); // No need for mentions array

Get Mentions

Extract mentioned users from message:

ctx.reply({ text: "Get in the EVA, @1234!", mentions: ctx.getMentioned() /* Returns array of JIDs like ["[e-mail]"] */ });

Custom Authentication

Use alternative auth storage adapters:

const { useMySQLAuthState } = require("mysql-baileys");

const bot = new Client({
    authAdapter: useMySQLAuthState({
        session: "botwangsap",
        password: "admin#123",
        database: "baileys"
    })
    // ... other options
});

Group Management

Comprehensive group control:

// Create group
ctx.groups.create("NERV", ["[e-mail]"]);

// Group utilities
const group = ctx.group(); // Current group or specify JID

// Common operations
group.inviteCode(); // Get invite code
group.revokeInviteCode(); // Reset invite code
group.leave(); // Bot leaves group
group.updateSubject("NERV"); // Rename group
group.add(["[e-mail]"]); // Add members
group.kick(["[e-mail]"]); // Remove members
group.promote(["[e-mail]"]); // Make admin
group.demote(["[e-mail]"]); // Remove admin

Miscellaneous Utilities

// Message reactions
ctx.react(ctx.id, "👍");

// Get message details
ctx.args; // Command arguments array
ctx.sender; // Message sender info
ctx.quoted; // Quoted message
ctx.me; // Bot user info

// Presence updates
ctx.simulateTyping();
ctx.simulateRecording();

// Profile management
bot.bio("GOD'S IN HIS HEAVEN, ALL'S RIGHT WITH THE WORLD"); // Update bot bio
bot.fetchBio("[e-mail]"); // Get user's bio

// Block management
bot.block("[e-mail]");
bot.unblock("[e-mail]");

// Utility methods
ctx.isGroup(); // Check if chat is group
ctx.getDevice("[e-mail]"); // Get user device info
ctx.getPushname("[e-mail]"); // Get push name

Acknowledgements

Special thanks to:

• @JastinXyz for original work
• baileys & baileys-mod development team
• All contributors and users of this package