CF Workers Telegram Bot - v12.6.5

CF Workers Telegram Bot

Docs

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.

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

Copy the consumer directory:

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

Configure your bot: Update wrangler.toml with your worker name.
Set your Telegram Token: Get a token from @BotFather and add it to your worker:
```
npx wrangler secret put SECRET_TELEGRAM_API_TOKEN
```
Deploy:
```
npm run deploy
```
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

Install dependencies:
```
npm install
```
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

CF Workers Telegram Bot - v12.6.5