miti99bot

My Telegram bot — a plug-n-play bot framework for Cloudflare Workers.

Modules are added or removed via a single MODULES env var. Each module registers its own commands with three visibility levels (public / protected / private). Data lives in Cloudflare KV behind a thin KVStore interface, so swapping the backend later is a one-file change.

Why

• Drop-in modules. Write a single file, list the folder name in MODULES, redeploy. No registration boilerplate, no manual command wiring.
• Three visibility levels out of the box. Public commands show in Telegram's / menu and /help; protected show only in /help; private are hidden slash-command easter eggs. One namespace, loud conflict detection.
• Dual storage backends. Modules talk to a small KVStore interface (Cloudflare KV for simple state) or SqlStore interface (D1 for relational data, scans, leaderboards). Swappable with one-file changes.
• Scheduled jobs. Modules declare cron-based cleanup, stats refresh, or maintenance tasks — registered via wrangler.toml and dispatched automatically.
• Zero admin surface. No in-Worker /admin/* routes, no admin secret. setWebhook + setMyCommands run at deploy time from a local node script.
• Tested. 105+ vitest unit tests cover registry, storage, dispatcher, cron validation, help renderer, validators, HTML escaping, and the trading module.

How a request flows

Telegram sends update
        │
        ▼
POST /webhook  ◄── grammY validates X-Telegram-Bot-Api-Secret-Token (401 on miss)
        │
        ▼
getBot(env) ──► first call only: installDispatcher(bot, env)
        │                │
        │                ├── loadModules(env.MODULES.split(","))
        │                ├── per module: init({ db: createStore(name, env), env })
        │                ├── build publicCommands / protectedCommands / privateCommands
        │                │     + unified allCommands map (conflict check)
        │                └── for each entry: bot.command(name, handler)
        ▼
bot.handleUpdate(update) ──► grammY routes /cmd → registered handler
        │
        ▼
handler reads/writes via db.getJSON / db.putJSON (auto-prefixed as "module:key")
        │
        ▼
ctx.reply(...) → response back to Telegram

Architecture snapshot

src/
├── index.js             # fetch + scheduled handlers: POST /webhook + cron triggers
├── bot.js               # memoized grammY Bot, lazy dispatcher + registry install
├── types.js             # JSDoc typedefs (central: Env, Module, Command, Cron, etc.)
├── db/
│   ├── kv-store-interface.js    # KVStore contract (JSDoc)
│   ├── cf-kv-store.js           # Cloudflare KV implementation
│   ├── create-store.js          # KV per-module prefixing factory
│   ├── sql-store-interface.js   # SqlStore contract (JSDoc)
│   ├── cf-sql-store.js          # Cloudflare D1 implementation
│   └── create-sql-store.js      # D1 per-module prefixing factory
├── modules/
│   ├── index.js             # static import map — register new modules here
│   ├── registry.js          # load, validate, build command + cron tables
│   ├── dispatcher.js        # wires every command via bot.command()
│   ├── cron-dispatcher.js   # dispatches cron handlers by schedule match
│   ├── validate-command.js  # command contract validator
│   ├── validate-cron.js     # cron contract validator
│   ├── util/                # /info, /help (fully implemented)
│   ├── trading/             # paper trading — VN stocks (D1 storage, daily cron)
│   │   └── migrations/
│   │       └── 0001_trades.sql
│   ├── wordle/              # stub — proves plugin system
│   ├── loldle/              # stub
│   └── misc/                # stub (KV storage)
└── util/
    └── escape-html.js

scripts/
├── register.js              # post-deploy: setWebhook + setMyCommands
├── migrate.js               # discover + apply D1 migrations
└── stub-kv.js               # no-op KV binding for deploy-time registry build

tests/
└── fakes/
    ├── fake-kv-namespace.js
    ├── fake-d1.js           # in-memory SQL for testing
    ├── fake-bot.js
    └── fake-modules.js

Command visibility

Level	In / menu	In /help	Callable
public	yes	yes	yes
protected	no	yes	yes
private	no	no	yes (hidden slash command — easter egg)

All three are slash commands. Private commands are just hidden from both surfaces. They're not access control — anyone who knows the name can invoke them.

Command names must match ^[a-z0-9_]{1,32}$ (Telegram's slash-command limit). Conflict detection is unified across all visibility levels — two modules cannot register the same command name no matter the visibility. Registry build throws at load time.

Prereqs

• Node.js ≥ 20.6 (for node --env-file)
• A Cloudflare account with Workers + KV
• A Telegram bot token from @BotFather

Setup

1. Install dependencies

   npm install
   

2. Create KV namespaces (production + preview)

   npx wrangler kv namespace create miti99bot-kv
   npx wrangler kv namespace create miti99bot-kv --preview
   

   Paste the returned IDs into wrangler.toml under [[kv_namespaces]], replacing both REPLACE_ME placeholders.

3. Set Worker runtime secrets (stored in Cloudflare, used by the deployed Worker)

   npx wrangler secret put TELEGRAM_BOT_TOKEN
   npx wrangler secret put TELEGRAM_WEBHOOK_SECRET
   

   TELEGRAM_WEBHOOK_SECRET can be any high-entropy string — e.g. openssl rand -hex 32. It gates incoming webhook requests; grammY validates it on every update.

4. Create .dev.vars for local development

   cp .dev.vars.example .dev.vars
   # fill in the same TELEGRAM_BOT_TOKEN + TELEGRAM_WEBHOOK_SECRET values
   

   Used by wrangler dev. Gitignored.

5. Create .env.deploy for the post-deploy register script

   cp .env.deploy.example .env.deploy
   # fill in: token, webhook secret, WORKER_URL (known after first deploy), MODULES
   

   Gitignored. The TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET values MUST match what you set via wrangler secret put — mismatch means every incoming webhook returns 401.

Local dev

npm run dev         # wrangler dev — runs the Worker at http://localhost:8787
npm run lint        # biome check + eslint
npm test            # vitest
npm run db:migrate  # apply D1 migrations (--local for local dev, --dry-run to preview)

The local wrangler dev server exposes GET / (health), POST /webhook (Telegram), and /__scheduled?cron=... (cron simulation). For end-to-end testing you'd ngrok/cloudflared the local port and point a test bot's setWebhook at it — but pure unit tests (npm test) cover the logic seams without Telegram.

Deploy

Single command, idempotent:

npm run deploy

That runs wrangler deploy, applies D1 migrations, then scripts/register.js, which calls Telegram's setWebhook + setMyCommands using values from .env.deploy.

First-time deploy flow:

1. Create D1 database: npx wrangler d1 create miti99bot-db and paste ID into wrangler.toml.
2. Run wrangler deploy once to learn the *.workers.dev URL printed at the end.
3. Paste it into .env.deploy as WORKER_URL.
4. Apply migrations: npm run db:migrate.
5. Preview the register payloads without calling Telegram:

   npm run register:dry
   

6. Run the real deploy:

   npm run deploy
   

Subsequent deploys: just npm run deploy.

Adding a module

See docs/adding-a-module.md for the full guide.

TL;DR:

1. Create src/modules/<name>/index.js with a default export { name, commands, init? }.
2. Add a line to src/modules/index.js static map.
3. Add <name> to MODULES in both wrangler.toml [vars] and .env.deploy.
4. npm test + npm run deploy.

Troubleshooting

Symptom	Cause
401 on every webhook	TELEGRAM_WEBHOOK_SECRET differs between wrangler secret and .env.deploy.
/help is missing a module's section	Module has no public or protected commands — private-only modules are hidden.
Module loads but no commands respond	MODULES does not list the module. Check wrangler.toml AND .env.deploy.
command conflict: /foo ... at deploy	Two modules register the same command name. Rename one.
npm run register exits missing env: X	Add X to .env.deploy.
--env-file flag not recognized	Node < 20.6. Upgrade Node.

Further reading

• docs/architecture.md — deeper dive: cold-start, module lifecycle, KV + D1 storage, cron dispatch, deploy flow, design tradeoffs.
• docs/adding-a-module.md — step-by-step guide to authoring a new module (commands, KV storage, D1 + migrations, crons).
• docs/using-d1.md — when to use D1, writing migrations, SQL API reference, worked examples.
• docs/using-cron.md — scheduling syntax, handler signature, wrangler.toml registration, local testing, worked examples.
• docs/deployment-guide.md — D1 + KV setup, migration, secret rotation, rollback.
• plans/260415-1010-d1-cron-infra/ — phased implementation plan for D1 + cron support (6 phases + reports).
• plans/260411-0853-telegram-bot-plugin-framework/ — original plugin framework implementation plan (9 phases + reports).