balebaazoo

Modern, type-safe TypeScript SDK for the Bale Bot API.

Full documentation: docs/usage.md · Docs site: https://hadimardanian.github.io/baleBaazooSDK/usage.html

Install

npm install balebaazoo

Requires Node.js 18+.

Quick start

import { Bot, InlineKeyboard, setupGracefulShutdown } from "balebaazoo";

const bot = new Bot(process.env.BOT_TOKEN!);

setupGracefulShutdown(bot);

bot.command("start", (ctx) =>
  ctx.reply("Hello! Welcome to my bot.", {
    reply_markup: new InlineKeyboard().text("About", "about"),
  }),
);

bot.on("callback_query:data", async (ctx) => {
  await ctx.answerCallbackQuery();
  await ctx.reply("More info...");
});

void bot.start({
  onStart: (me) => console.log(`Running as @${me.username ?? me.id}`),
  onError: (error) => console.error(error),
});

bot.start() blocks until bot.stop(). Use onStart for post-init logging, not code after await bot.start().

TypeScript setup

If you see error TS1295 (import in a CommonJS file), your project needs ESM config:

package.json

{
  "type": "module"
}

tsconfig.json

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "verbatimModuleSyntax": true,
    "types": ["node"]
  }
}

Starter template: templates/starter

TS2322 with ctx.reply

Since v1.0.1, handlers may return ctx.reply() directly:

bot.command("start", (ctx) => ctx.reply("Hello!"));

nodemon + TypeScript

{
  "watch": ["src"],
  "ext": "ts,json",
  "exec": "tsx src/bot.ts"
}

Features

• Full Bale Bot API client with TypeScript types
• Bot framework: middleware, filters, commands, composers
• Lifecycle: onStart, setupGracefulShutdown, dropPendingUpdates, launch()
• Telegraf-style parity: bot.telegram, bot.botInfo, context shortcuts
• Sessions and scenes (session(), Scene, Stage)
• Polling (with concurrency and AbortSignal) and webhook support
• bot.catch() and errorHandler middleware
• Wallet payments, askReview, inquireTransaction
• Zero runtime dependencies

Examples

• examples/echo-bot.ts
• examples/inline-keyboard.ts
• examples/payment-bot.ts
• examples/webhook-server.ts
• examples/session-bot.ts
• examples/wizard-bot.ts

npm run example:echo

Development

npm install
npm run build
npm test
npm run docs:dev

License

GPL-3.0-or-later