@yaebal/commands

pnpm add @yaebal/commands

import { Bot } from "@yaebal/core";
import { commands } from "@yaebal/commands";

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

const cmd = commands()
  .add("start", "start the bot", async (ctx) => {
    await ctx.reply(`welcome! args: ${ctx.args.join(", ")}`);
  })
  .add("help", "show help", async (ctx) => {
    await ctx.reply("available commands: /start, /help");
  });

// wire the handlers onto the bot
bot.install(cmd.plugin());

// push the /command menu — only the menus that changed
await cmd.sync(bot.api);

bot.start();

import type { Context } from "@yaebal/core";
import { session } from "@yaebal/session";

type MyContext = Context & { session: { count: number } };

const cmd = commands<MyContext>().add("count", "count up", async (ctx) => {
  // ctx.session (from the session plugin) and ctx.args are fully typed
  await ctx.reply(`count: ${++ctx.session.count}, args: ${ctx.args.length}`);
});

// the bot must provide MyContext before install — checked by the compiler
bot.install(session({ initial: () => ({ count: 0 }) })).install(cmd.plugin());

const cmd = commands()
  .add("start", { default: "start the bot", ru: "запустить бота" }, handler)
  .add("help", { default: "show help", ru: "показать помощь" }, handler);

// pushes the default menu + one menu per locale;
// commands missing a locale fall back to their default text
await cmd.register(bot.api);

const cmd = commands().add("start", "start the bot", handler);

cmd.scoped({ type: "all_chat_administrators" })
  .add("ban", "ban a user", banHandler)
  .add("unban", "unban a user", unbanHandler);

await cmd.register(bot.api);
// everyone's menu: /start
// admins' menu:    /start /ban /unban

const cmd = commands().add("start", "start the bot", handler);
cmd.scoped({ type: "all_private_chats" })
  .add("start", "start the bot (dm)", dmHandler);

await cmd.register(bot.api);
// default menu:        /start (generic text)
// private-chats menu:  /start (dm text)

const cmd = commands()
  // ["name", ...aliases] — every name is handled, only the first shows in the menu
  .add(["settings", "prefs"], "open settings", handler)
  // handled but never shown in any menu (debug/admin commands)
  .hidden("debug", async (ctx) => ctx.reply("debug info"))
  // menu-only: no handlers — the command is handled elsewhere (a router, a scene)
  .add("report", "file a report");

import { ephemeral } from "@yaebal/ephemeral";

// is_ephemeral in the menu (bot api 10.2+): telegram shows the /stats invocation
// only to its sender and expects an answer within ~15 seconds — answer it
// ephemerally too, so nothing lands in the group's history.
const cmd = commands().ephemeral("stats", "your personal stats", async (ctx) => {
  await ctx.replyEphemeral(`you: ${await stats(ctx.from.id)}`);
});

bot.install(ephemeral()).install(cmd.plugin());
await cmd.sync(bot.api); // the flag is diffed — flipping it repushes the menu

cmd.list();                          // default menu: { command, description }[]
cmd.list({ languageCode: "ru" });    // ru menu, falling back to default text
cmd.list({ scope: { type: "all_chat_administrators" } });
cmd.menus();                         // every (scope, language) menu register() would push

// a /help text from the same source of truth
bot.command("help", (ctx) =>
  ctx.reply(cmd.list().map((c) => `/${c.command} — ${c.description}`).join("\n")),
);

await cmd.register(bot.api);                         // push every menu
await cmd.register(bot.api, { languageCode: "ru" }); // push a single menu
const { pushed, skipped } = await cmd.sync(bot.api); // push only what changed
await cmd.unregister(bot.api);                       // deleteMyCommands for every menu

import { createTestEnv } from "@yaebal/test";

const env = createTestEnv(new Composer<Context>().install(cmd.plugin()));
await env.createUser().sendCommand("start");
env.lastApiCall("sendMessage"); // assert the reply

await cmd.register(env.api); // menu pushes are recorded too
env.callsTo("setMyCommands");