Skip to content

feat: Add Admin Panel pattern for Telegram bots #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 27, 2025

Conversation

talkstream
Copy link
Owner

Summary

This PR adds a production-ready Admin Panel pattern for Telegram bots running on Cloudflare Workers. The pattern provides a secure web-based interface for bot administration without external dependencies.

Features

  • 🔐 Telegram-based 2FA: Secure authentication using Telegram bot messages
  • 🌐 HTML-based UI: No build tools required, works directly on Cloudflare Workers
  • 🔑 Session Management: Secure sessions using KV storage
  • 🛡️ Middleware Pattern: Protected routes with authentication middleware
  • 📊 Dashboard Template: Ready-to-use dashboard with customizable statistics
  • 🧪 Type-safe Testing: Helper functions for mocking D1 database in tests

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Web Browser   │────▶│  Admin Routes   │────▶│   KV Storage    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                         │
         │                       ▼                         │
         │              ┌─────────────────┐               │
         └─────────────▶│  Auth Handler   │◀──────────────┘
                        └─────────────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │  Telegram Bot   │
                        └─────────────────┘

Usage

  1. Bot owner uses /admin command
  2. Bot generates temporary auth code (5 min TTL)
  3. Admin opens web panel and enters ID + code
  4. Session created with 24-hour expiration
  5. Access to dashboard and management features

Example

See src/patterns/admin-panel/example/bot-with-admin.ts for a complete implementation.

Test plan

  • All tests pass
  • TypeScript strict mode compliance
  • No domain-specific dependencies
  • Comprehensive documentation
  • Review by maintainers

- Added contribution review checklist for maintainers
- Created successful contributions gallery with examples
- Enhanced contribute.ts with PR conflict detection
- Added GitHub Action for automated PR validation
- Created auto-labeling configuration for PRs
- Updated CONTRIBUTING.md with links to new resources

This improves the contribution workflow by:
1. Providing clear review criteria
2. Showcasing successful contributions
3. Preventing PR conflicts early
4. Automating validation checks
5. Auto-labeling PRs for better organization

Based on experience processing contributions from the community.
- Web-based admin panel for Telegram bots on Cloudflare Workers
- Telegram-based 2FA authentication
- Session management using KV storage
- Protected routes with middleware pattern
- Dashboard with customizable statistics
- User management interface
- Type-safe test helpers for D1 mocks
- Complete example implementation
- Comprehensive documentation

This pattern provides a secure, production-ready admin interface
for Telegram bots without external dependencies.
- Fix environment variable type safety in bot example
- Add null checks for optional dashboard stats
- Fix cookie value handling in auth middleware
fix: TypeScript errors in Admin Panel
@talkstream talkstream merged commit 19bc50b into main Jul 27, 2025
2 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant