@yaebal/router

pnpm add @yaebal/router

routes/
  use/
    logger.ts            # → bot.use(handler) — mounted first, in file order
  commands/
    start.ts              # → defineCommand("start", ...)
    admin/
      _guard.ts            # → defineGuard(...) gates everything under admin/
      ban.ts               # → defineCommand("ban", ...) — still just "/ban", nesting is organizational
  hears/
    ping.ts                # → defineHears("ping", ...)
  on/
    message.text.ts        # → defineOn("message:text", ...) — dots become ":"
    callback_query.data.ts

// routes/commands/start.ts
import { defineCommand } from "@yaebal/router";

export default defineCommand("start", { description: "start the bot" }, async (ctx) => {
  await ctx.reply(`welcome! args: ${ctx.args.join(", ")}`);
});

// routes/on/message.text.ts
import { defineOn } from "@yaebal/router";

export default defineOn("message:text", async (ctx) => {
  await ctx.reply(`you said: ${ctx.text}`); // ctx.text: string — narrowed, not optional
});

// routes/hears/ping.ts
import { defineHears } from "@yaebal/router";

export default defineHears("ping", async (ctx) => {
  await ctx.reply(`pong (matched: ${ctx.match})`);
});

// routes/use/logger.ts
import { defineUse } from "@yaebal/router";

export default defineUse((ctx, next) => {
  console.log(`update #${ctx.update.update_id}`);
  return next();
});

import { Bot } from "@yaebal/core";
import { loadRoutes } from "@yaebal/router";
import { fileURLToPath } from "node:url";

const bot = new Bot(process.env.BOT_TOKEN!);
const routesDir = fileURLToPath(new URL("./routes", import.meta.url));

const result = await loadRoutes(bot, routesDir);
console.log(result.routes.map((r) => `${r.kind}:${r.trigger}`));
// ["use:logger", "command:start", "command:ban", "hears:ping", "on:message:text", ...]

bot.start();

// routes/router.ts — bind define*() to your bot's own accumulated context once
import type { ContextOf } from "@yaebal/router";
import { createRouter } from "@yaebal/router";
import { bot } from "../bot.js";

export const { defineCommand, defineOn, defineHears, defineUse, defineGuard } =
  createRouter<ContextOf<typeof bot>>();

// routes/commands/start.ts — import the bound helper instead of the bare package
import { defineCommand } from "../router.js";

export default defineCommand("start", async (ctx) => {
  // sees every derive()/decorate() field this bot has, not just the bare Context
  await ctx.reply(ctx.session ? "welcome back" : "welcome");
});

// routes/commands/admin/_guard.ts
import { defineGuard } from "@yaebal/router";

export default defineGuard((ctx) => ctx.from?.id === ADMIN_ID);
// gates every route under commands/admin/ — a failing guard stops the update right there,
// exactly like Composer.guard(): nothing registered after it runs for that update

// strict (the default): a bad route throws at load time, before the bot ever starts —
// nothing silently registers a handler that can never match.
await loadRoutes(bot, routesDir);
// Error: @yaebal/router: "mesage" is not a telegram update type — did you mean "message"?
//   (in on-query "mesage:text") (in on/mesage.text.js)

// strict: false collects the same failures as warnings instead, and keeps loading the rest —
// handy while iterating with watchRoutes(), where a mid-edit file is expected, not exceptional.
const result = await loadRoutes(bot, routesDir, { strict: false });
result.warnings;
// [{ message: '"mesage" is not a telegram update type — did you mean "message"? ...', file: "on/mesage.text.js" }]

// bare — LoadResult.commands is a ready BotCommand[] for the default menu
// (menu-visible: has a meta.description, not hidden, no scope — scoped/localized menus need
// the bridge below)
const result = await loadRoutes(bot, routesDir);
await bot.api.call("setMyCommands", { commands: result.commands });

// full power (scopes, locales, diff-aware sync) via the optional @yaebal/commands peer dependency
import { commands } from "@yaebal/commands";

const registry = commands();
await loadRoutes(bot, routesDir, { commands: registry });
// add your own scoped/localized entries too, then push everything in one sync
registry.scoped({ type: "all_chat_administrators" }).add("audit", "view the audit log");
await registry.sync(bot.api);

// or let router run the sync itself — no separate @yaebal/commands import needed
await loadRoutes(bot, routesDir, { syncCommands: true });          // uses target.api
await loadRoutes(bot, routesDir, { syncCommands: { api: otherApi } });

import { watchRoutes } from "@yaebal/router";

// dev only — keeps watching routesDir and hot-swaps the route set on every change, no restart
const stop = await watchRoutes(bot, routesDir, {
  onReload: (result) => console.log("routes reloaded:", result.routes.length),
  onError: (error) => console.error("route reload failed, keeping the last good set:", error),
});

process.once("SIGINT", async () => {
  await stop();
  await bot.stop();
});

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

const bot = new Bot(process.env.BOT_TOKEN!);
await loadRoutes(bot, routesDir);

const env = createTestEnv(bot);
await env.createUser().sendCommand("start");
env.lastApiCall("sendMessage"); // assert the reply from routes/commands/start.ts