BJS - Bots.Business JavaScript Development Kit

A comprehensive development toolkit and live execution engine for Bots.Business BJS (Bot JavaScript). It provides three main capabilities:

1. TypeScript Definitions (.d.ts): Gives you beautiful syntax validation and IntelliSense (autocompletions) inside modern text editors like VS Code.
2. Local VM Simulator (BJSSimulator): Allows you to run, dry-run, and unit-test your BJS scripts directly on your computer inside Node.js.
3. Live Telegram Bot Runner (BJSTelegramBot): Connects to the Telegram Bot API via long-polling to run your BJS command scripts locally as an actual working Telegram Bot!

📦 Installation

Initialize your project and install the module:

npm install @codewithshahil/bjs --save-dev

⚙️ Loading Bot Token via bot.txt

If a file named bot.txt containing your Telegram Bot API token is placed in your project's root folder, the toolkit will automatically load it and set it as bot.token in the BJS runtime.

🤖 Live Telegram Bot Execution (A to Z)

You can run your BJS commands as a live, fully functional Telegram Bot locally on your machine. Any calls to Bot.sendMessage, User.sendMessage, or Api wrappers will perform real HTTP requests to the Telegram Bot API and interact with real users.

Example: Running a Live Bot

Create a file named bot.txt in your project root containing your Telegram Bot token: 123456789:ABCdefGhIJKlmNoPQRstUVwxyZ

Create a file named index.js:

const { BJSTelegramBot } = require("@codewithshahil/bjs");

// 1. Initialize the Live Telegram Bot
const bot = new BJSTelegramBot();

// 2. Register BJS scripts for triggers
bot.registerCommand("/start", `
    Bot.sendMessage("Hello! Welcome to the BJS Live Bot running locally.");
`);

bot.registerCommand("/help", `
    Bot.sendMessage("Available commands: /start, /help, /info");
`);

// 3. Register a Master Command fallback for any other message
bot.registerCommand("*", `
    Bot.sendMessage("I received: " + message + ". Parameters: " + params);
`);

// 4. Start long-polling updates
bot.start();

Run your bot:

node index.js

💡 VS Code Autocomplete Setup (IntelliSense)

To enable autocompletions for all BJS namespaces (Bot, User, Api, HTTP, List, BBAdmin) and variables (tgUpdate, message, user, chat) in your bot repository:

1. Create a jsconfig.json at the root of your bot folder.
2. Configure it to include the @codewithshahil/bjs type declarations:

jsconfig.json:

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es2022",
    "checkJs": true
  },
  "include": [
    "node_modules/@codewithshahil/bjs/dist/src/bjs.d.ts",
    "**/*.js"
  ]
}

Now, when you type Bot. or Api. or reference tgUpdate inside any file in your project, VS Code will offer description tooltips, method signatures, and parameter autocompletions.

🚀 Running & Testing BJS Locally

You can run BJS code snippets locally in Node.js to assert and test functionality before pushing them to the Bots.Business cloud.

Basic Example

const { BJSSimulator } = require("@codewithshahil/bjs");

// 1. Initialize the BJS Simulator
const sim = new BJSSimulator();

// 2. Define your BJS command script
const code = `
    Bot.setProperty("total_clicks", Bot.getProperty("total_clicks", 0) + 1, "integer");
    Bot.sendMessage("Current clicks: " + Bot.getProperty("total_clicks"));
`;

// 3. Define execution context (overrides for user, chat, tgUpdate etc.)
const context = {
    user: { id: 101, telegramid: 998877, first_name: "John" },
    chat: { id: 505, chatid: -100112233, chat_type: "supergroup" }
};

// 4. Run the code
sim.run(code, context);

// 5. Assert states and side-effects
console.log("Global properties:", sim.globalProperties);
console.log("Sent Messages:", sim.sentMessages);

🛠️ Writing Test Suites (Unit Testing)

You can write automated unit tests for your commands using a testing library (like mocha, jest, or native node:assert).

test_start_command.js:

const assert = require("node:assert");
const { BJSSimulator } = require("@codewithshahil/bjs");

describe("Start Command Tests", () => {
    it("should welcome the user and increment count", () => {
        const sim = new BJSSimulator();
        const code = `
            Bot.sendMessage("Welcome to the bot, " + user.first_name + "!");
            Bot.setProperty("visits", Bot.getProperty("visits", 0) + 1, "integer");
        `;
        
        sim.run(code, {
            user: { id: 1, first_name: "Alice" }
        });
        
        // Assertions
        assert.strictEqual(sim.sentMessages[0].content, "Welcome to the bot, Alice!");
        assert.strictEqual(sim.globalProperties.get("visits"), 1);
    });
});

🚀 Publishing to NPM (A to Z Guide)

Follow these steps to publish this library under your own namespace or package name:

1. Register/Login to NPM

If you do not have an account, register at npmjs.com. Login to NPM from your command-line interface:

npm login

Provide your username, password, email, and one-time code (if 2FA is enabled).

2. Rename the Package (Optional)

Open package.json and change the "name" field to your desired name (e.g. @codewithshahil/bjs).

3. Build and Test Local Build

Compile the TypeScript code and run the test suite:

# Install package dependencies
npm install

# Compile TS and run tests
npm run build
npm test

4. Publish

Publish the package to the public registry:

npm publish --access public

👨‍💻 Creator & Author

Shahil440 (Telegram: @Shahil440)

📜 License

MIT