cheat sheet

pnpm add yaebal

import { createBot } from "yaebal";

export const bot = createBot(process.env.BOT_TOKEN!);
await bot.start();

import { createBot } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

bot.command("start", (ctx) => ctx.reply("hi"));
bot.hears(/buy (.+)/, (ctx) => ctx.reply("matched"));
bot.callbackQuery(/^page:(\d+)$/, (ctx) => ctx.answerCallbackQuery());
bot.on("message:text", (ctx) => ctx.text);
bot.on(":photo", (ctx) => ctx.reply("nice photo"));
bot.on("edited_message", (ctx) => ctx.reply("noticed the edit"));

import { createBot } from "yaebal";

const loadUser = async (id: number) => ({ id, name: "somebody" });
const bot = createBot(process.env.BOT_TOKEN!)
  .derive(async (ctx) => ({ user: await loadUser(ctx.from!.id) }))
  .decorate({ version: "1.0.0" })
  .on("message:text", (ctx) => {
    ctx.user;
    ctx.version;
    ctx.text;
  });

import { createBot, InlineKeyboard, callbackData } from "yaebal";

const vote = callbackData("vote", { id: Number });
const bot = createBot(process.env.BOT_TOKEN!);

bot.command("poll", (ctx) =>
  ctx.reply("pick", {
    reply_markup: new InlineKeyboard()
      .text("yes", vote.pack({ id: 1 }))
      .text("no", vote.pack({ id: 2 }))
      .build(),
  }),
);

import { html, format, bold, link, createBot } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);
const user = { name: "Ann" };

bot.command("hi", (ctx) => {
  ctx.send(html`<b>hello</b> ${user.name}`);
  ctx.send(format`${bold("safe entities")} ${link("docs", "https://yaebal.mom")}`);
});

import { createBot } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

bot.callbackQuery(/^refresh$/, async (ctx) => {
  await ctx.answerCallbackQuery(); // stop the client's loading spinner first
  await ctx.editText({ text: "refreshed @ " + new Date().toISOString() });
});

bot.command("cleanup", (ctx) => ctx.delete());

import type { MessageContext } from "yaebal";

// types flow only inside the chain — a helper extracted into its own function
// names its context type explicitly. handler contexts are structural supertypes
// of the per-update class, so ctx passes in with no casts.
async function eatMessage(ctx: MessageContext) {
  try {
    await ctx.delete();
  } catch {
    /* no rights or older than 48h — fine */
  }
}

// needs plugin-added fields? intersect them:
function greet(ctx: MessageContext & { session: { count: number } }) {
  return ctx.reply(`hi #${++ctx.session.count}`);
}

import { createBot } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

// every method is fully typed, generated straight from the Bot API schema —
// reach for this when there's no ctx shortcut yet, or you need a raw result.
await bot.api.call("sendChatAction", { chat_id: 123, action: "typing" });

import { createBot, TelegramError } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

bot.onError((error, ctx) => {
  if (error instanceof TelegramError && error.parameters?.retry_after) {
    console.warn("rate limited, retry after", error.parameters.retry_after);
    return;
  }
  console.error("update", ctx.update.update_id, "failed:", error);
});

import { createBot, media } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);

bot.command("pic", async (ctx) => {
  await ctx.sendPhoto(media.url("https://example.com/cat.jpg"));
  await ctx.sendDocument(media.path("./report.pdf"));
  await ctx.sendPhoto("AgACAgIAAx...");
});

import { createBot, session, i18n } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!)
  .install(session({ initial: () => ({ count: 0 }) }))
  .install(i18n({ defaultLocale: "en", locales: { en: { hi: "hello" } } }))
  .command("count", (ctx) => ctx.reply(String(++ctx.session.count)));

import { createBot } from "yaebal";
import { defineScene, scenes } from "@yaebal/scenes";
import { prompt } from "@yaebal/prompt";

const echo = defineScene({
  steps: [
    async (ctx) => {
      if (ctx.scene.firstTime) return ctx.send("say something");
      await ctx.send("you said: " + (ctx.text ?? ""));
      return ctx.scene.leave();
    },
  ],
});

const bot = createBot(process.env.BOT_TOKEN!)
  .install(scenes({ echo }))
  .install(prompt())
  .command("echo", (ctx) => ctx.scene.enter("echo"))
  .command("name", (ctx) => ctx.prompt("what's your name?", (ctx) => ctx.reply("hi, " + (ctx.text ?? ""))));

import { createBot, webhook } from "yaebal";

const bot = createBot(process.env.BOT_TOKEN!);
export default { fetch: webhook(bot, { secretToken: process.env.WEBHOOK_SECRET }) };

import { createTestEnv } from "@yaebal/test";
import { expect, test } from "vitest";
import { bot } from "./bot.js";

test("start", async () => {
  const env = createTestEnv(bot);
  const user = env.createUser({ firstName: "Linia" });

  await user.sendCommand("start");

  expect(env.lastApiCall("sendMessage")?.params?.text).toBeDefined();
});