A lightweight, type-safe Telegram Bot framework for Cloudflare Workers.

Installation

npm install @codebam/cf-workers-telegram-bot

Quick Start

import TelegramBot, { TelegramExecutionContext } from '@codebam/cf-workers-telegram-bot';

export interface Env {
	SECRET_TELEGRAM_API_TOKEN: string;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const bot = new TelegramBot(env.SECRET_TELEGRAM_API_TOKEN);

		await bot
			.command('start', async (ctx) => {
				await ctx.reply('Hello! I am running on Cloudflare Workers.');
			})
			.onMessage(async (ctx) => {
				await ctx.reply(`You said: ${ctx.text}`);
			})
			.handle(request);

		return new Response('ok');
	},
};

Features

• Type-safe: Built with TypeScript for a better developer experience.
• Middleware support: Run logic before your handlers.
• Built-in Webhook Management: Easily set your webhook with a simple URL.
• Lightweight: Zero dependencies (other than type definitions).

Using the Consumer Template

The consumer directory in this repository serves as a template for new projects. It is included as a git submodule.

1. Clone the repository with submodules:

   git clone --recursive https://github.com/codebam/cf-workers-telegram-bot.git

   Or, if you've already cloned it:

   git submodule update --init --recursive

2. Copy the consumer directory:

   cp -r consumer my-new-bot
   cd my-new-bot
   npm install

3. Configure your bot: Update wrangler.toml with your worker name.

4. Set your Telegram Token: Get a token from @BotFather and add it to your worker:

   npx wrangler secret put SECRET_TELEGRAM_API_TOKEN

5. Deploy:

   npm run deploy

6. Set Webhook: Visit the following URL in your browser to register your worker with Telegram: https://<your-worker>.<your-subdomain>.workers.dev/<SECRET_TELEGRAM_API_TOKEN>/setWebhook

Deployment

Manual Deployment

Use Wrangler to deploy:

npx wrangler deploy

GitHub Actions

To automate deployments, use the Wrangler Action or Cloudflare's built-in GitHub integration.

Structure

This is a monorepo containing:

• Root: Core library @codebam/cf-workers-telegram-bot
• ai-workflow: A Cloudflare Workflow for handling long-running AI tasks
• webapp: A Svelte 5 web application for interacting with the bot
• consumer: A minimal consumer of the library

Development

You can use the root Makefile to run common tasks across all projects:

make build   # Build all projects
make test    # Run tests for all projects
make lint    # Lint all projects
make format  # Format all projects

Setup

1. Install dependencies:

   npm install

2. Set up Git hooks: This project uses custom Git hooks for quality control. Run the following script to enable them:

   ./setup_hooks.sh

Scripts

• npm run lint: Run ESLint on the source code.
• npm run format: Format the code using Prettier.
• npm run build: Compile TypeScript and run type checks.
• npm run test: Run unit tests with Vitest.
• npm run lint:all: Run linting for the root project and all subprojects.
• npm run build:all: Run build for the root project and all subprojects.
• npm run test:all: Run tests for the root project and all subprojects.

The pre-commit hook automatically runs formatting and linting on staged files (via lint-staged), followed by a full project type check and tests before every commit.

API Documentation

Detailed API documentation is available at cf-workers-telegram-bot.codebam.ca.

License

Apache-2.0