CassieahBoT 4.0+ (Dev)

CassieahBoT (formerly CassidySpectra, forked from CassidyRedux, originally CassidyBoT) is a multi-platform chatbot framework for Facebook, Discord, and web. Maintained by Liane Cagara (lianecagara on GitHub), it uses TypeScript for robust tooling and now includes napi-rs canvas for image generation because text-only output is outdated. This is the 4.0+ dev branch, so expect rough edges. If you break something, that’s on you.

Table of Contents

• Overview
• Features
• Changelog
• Getting Started
  • Prerequisites
  • Installation
  • Configuration
  • Deployment
• Writing Commands
  • Command Structure
  • Meta Options
  • Context Variables
  • Example Command
• Core Files
• License

Overview

CassieahBoT is a framework for building bots that work across Facebook (personal accounts and pages), Discord (partially), and web interfaces. It leverages TypeScript for type safety and includes napi-rs canvas for generating images dynamically. It’s extensible but not foolproof. If you don’t follow instructions, don’t expect it to work.

Features

• TypeScript Tooling: Strong typing and autocomplete. Use a proper IDE or deal with the consequences.
• Image Generation: Uses napi-rs canvas to create images like memes or charts. Text output alone won’t cut it anymore.
• Command Management: Define and manage commands with a clear structure.
• Multi-Platform: Supports Facebook (personal and pages), Discord (limited), and web.
• Premade Components: Templates like UTShop and GameSimulator for common tasks.
• Auto-Styling: Commands get formatted titles and lines automatically.
• MongoDB Abstraction: Simplified database interaction. Still requires a valid MongoDB URI.
• Idle Games: Built-in support for idle game mechanics.
• Plugins: Parallel plugin execution with promises. Better than the old system.
• User Management: Handles permissions, roles, and inventory systems.
• Custom Fonts: Unicode fonts styled like Markdown.
• API Integration: Connect to external APIs for additional functionality.

Changelog

• 4.0+ (Dev):
  • Added napi-rs canvas for image generation.
  • Improved plugin system with proper promise handling.
  • Simplified MongoDB abstraction.
  • Performance optimizations.
  • Discord support remains partial and undertested.
  • Fixed some bugs. New ones are probably lurking.

Getting Started

Follow these steps exactly. If the bot doesn’t work, check the logs first before asking for help.

Prerequisites

• GitHub account.
• Facebook Page (required for Messenger integration).
• Dummy Facebook account (don’t use your main one).
• Browser with extension support (e.g., Chrome, Edge, Kiwi).
• Cookie Editor or C3C FBState extension for exporting cookies.
• Railway account (railway.app).
• Node.js 23.7.0 or higher. Older versions will fail.
• MongoDB URI (e.g., from MongoDB Atlas).
• Basic understanding of JavaScript/TypeScript and command-line tools.

Installation

1. Fork or Generate the Repository:

   • Go to https://github.com/lianecagara/CassieahBoT.
   • Fork or use the template to create your own repo (https://github.com/your-username/CassieahBoT).
   • Template is better for private repos.

2. Clone the Repository:

   git clone https://github.com/your-username/CassieahBoT
   cd CassieahBoT
   

3. Run Update Command:

   • Before touching any files, run:

     npm run update
     

   • This ensures dependencies and configs are up to date. If you skip this and modify files, updates will break. Don’t say I didn’t warn you.

4. Install Dependencies:

   npm install
   

   • If this fails, verify Node.js version (23.7.0+).

5. Install napi-rs Canvas:

   npm install @napi-rs/canvas
   

   • Linux users may need additional packages (libcairo2-dev, libpango1.0-dev). Search for solutions if it fails.

6. Set Up Cookies:

   • Log in to your dummy Facebook account.
   • Use Cookie Editor or C3C FBState to export cookies in JSON format.
   • Replace the contents of cookie.json with your cookies.
   • Run node hidestate if using an .env file to secure appstate.
   • Warning: Never commit cookie.json to a public repo. Use environment variables.

Configuration

1. Facebook Messenger Setup:

   • Go to developers.facebook.com.
   • Create a Business app.
   • Add the Messenger product.
   • Link your Facebook Page and generate a Page Access Token.
   • Configure webhooks:
     • Callback URL: https://your-railway-url/webhook (set after deployment).
     • Verify Token: Create one (e.g., pagebot) and note it.
     • Subscribe to messages, messaging_optins, messaging_postbacks.
   • Update settings.json:

     {
       "pageAccessToken": "your-page-access-token",
       "pageVerifyToken": "your-verify-token",
       "discordBotToken": "",
       "discordClientID": ""
     }
     

   • Warning: Keep tokens secure. Use environment variables.

2. Discord (Optional):

   • Go to Discord Developer Portal.
   • Create a bot and copy its token.
   • Add to settings.json.
   • Discord support is partial. Test thoroughly or stick to Facebook.

3. Database:

   • Add your MongoDB URI to .env:

     MONGO_URI="your-mongodb-uri"
     

   • Get a URI from MongoDB Atlas if you don’t have one.

Deployment

1. Local Testing:

   npm start
   

   • If it fails, check cookie.json, settings.json, or logs.

2. Railway Deployment:

   • Log in to railway.app.
   • Create a new project and select your CassieahBoT repo.
   • Ensure the Dockerfile uses Node.js 23.7.0+.
   • Set environment variables:
     • MONGO_URI: Your MongoDB URI.
     • APPSTATE: Contents of cookie.json (or use the file).
   • Deploy to USA Oregon region. Other regions won’t work.
   • Get the Railway URL (e.g., https://your-project-name.up.railway.app).
   • Update Facebook webhook with /webhook (e.g., https://your-project-name.up.railway.app/webhook).

3. Testing:

   • Message your Facebook Page with “help” from a non-dummy account.
   • No response? Check Railway logs. It’s usually a misconfigured token or role.
   • Assign roles in developers.facebook.com under App Roles to allow specific accounts to interact.

Writing Commands

Command Structure

Commands are defined in JavaScript/TypeScript files. Here’s the format:

export const meta: CommandMeta = {
    name: "example",
    otherNames: ["ex", "test"],
    author: "Your Name",
    version: "1.0.0",
    description: "Basic command example.",
    usage: "{prefix}{name} [arg]",
    category: "Misc",
    role: 0,
    waitingTime: 5,
};

export async function entry({ input, output, args }: CommandContext) {
    output.reply(`You said: ${args[0] || "nothing"}`);
}

License

See the LICENSE file for details.

Credits

• MrKimstersDev (Symer Steve Berondo): Original tutorial.
• Liane Kaye Cagara: Creator and maintainer.

---

Important: Always run npm run update before editing any files, or updates will break. If the bot isn’t responding, check the logs (Railway or local). Most issues are due to misconfigured tokens, cookies, or roles. Don’t skip steps, and don’t expect it to work if you half-read this.

Ultimate Guide to Writing Commands in the CassieahBoT Messenger Bot Framework

(Current as of December 24, 2025 – Modern Best Practices Only)

This is the final, production-hardened reference.
Every pattern below is used daily in the largest CassieahBoT economies.
Prioritized from most critical to advanced.

---

1. ctx – The Core Context Object (Most Important)

ctx is passed to every command handler. It contains everything.

Always destructure directly in parameters (mandatory style):

async handler({ input, output, money }) {
  // Now use input, output, money directly
}

This is the cleanest, fastest, and most consistent way.

Do not do this:

async handler(ctx) {
  const { input, output, money } = ctx; // Verbose, unnecessary
}

Do not access via ctx.input.body — always destructure in params.

---

2. Command Metadata (meta: CommandMeta) – Required Fields

export const meta: CommandMeta = {
  name: "vault",
  otherNames: ["v", "safe"],
  description: "Secure storage with deposit/withdrawal fees",
  usage: "{prefix}{name} [deposit|withdraw|list]",
  category: "Economy",
  version: "4.0.0",
  icon: "🔒",
  waitingTime: 3,   // cooldown in seconds per user
  role: 0,          // 0=everyone, 1=thread admin+, 1.5=moderator+, 2=bot admin
};

waitingTime → automatic per-user cooldown
role → automatic block if insufficient

Read current user role:

input.role  // returns 0, 1, 1.5, or 2

---

3. Command Style – Simple & Powerful

export const style: CommandStyle = {
  title: "🔒 Vault System",   // string = auto-styled title
  contentFont: "fancy",
  lineDeco: "altar",          // or "x"
};

If style is exported, output.reply(text) and output.send(text) automatically apply it.

await output.reply("Styled automatically")
await output.send("Also styled", "thread123")

Only use replyStyled when overriding.

---

4. Command Backbone – Two Options

A. Simple (≤4 subcommands) → defineEntry

export const entry = defineEntry({
  async deposit({ input, output, money }) {
    // logic
  },
  async withdraw({ input, output, money }) {
    // logic
  },
  async list({ input, output, money }) {
    // logic
  },
});

B. Complex (5+ subcommands) → SpectralCMDHome

const home = new SpectralCMDHome({}, [
  {
    key: "deposit",
    aliases: ["dep"],
    async handler({ input, output, money }) {
      // logic
    }
  },
  {
    key: "withdraw",
    aliases: ["wd"],
    async handler({ input, output, money }) {
      // logic
    }
  },
]);

return home.runInContext(ctx);

---

5. input – Message Intelligence

input.body                     // full message
input.words                    // ["vault", "deposit", "1000"]
input.args                     // ["deposit", "1000"]
input.senderID                 // user ID
input.messageReply?.senderID   // replied user
input.mentions                 // { "@Name": "uid" }
Object.values(input.mentions)[0] // first @ UID
input.hasMentions              // true/false
input.role                     // 0–2
input.isGroup                  // group chat?

input.test(/all/i)             // regex
input.isMessage()              // text message
input.hasWordOR("all", "max")  // any word
input.hasWordAND("send", "money") // all words
input.equal("yes")             // exact
input.lower().body             // lowercase

// Detect target user (used in transfers, trades, duels)
const target = input.messageReply?.senderID || Object.values(input.mentions)[0];

---

6. output – Messaging Power

await output.reply("Auto-styled")
await output.send("To thread", "thread123")
await output.attach("Caption", "https://img.jpg")
await output.edit("Update", "mid123")
await output.unsend("mid123")
await output.reaction("❤️", "mid123")
await output.wentWrong()
await output.error(new Error("Fail"))

const msg = await output.reply("Question?");
m