telegem 3.3.0 → 3.4.0

data/docs/bot.md

@@ -0,0 +1,332 @@
+# Bot Configuration
+
+The `Telegem::Core::Bot` class is the main entry point for creating and configuring Telegram bots.
+
+## Initialization
+
+```ruby
+bot = Telegem.new(token, **options)
+```
+
+### Parameters
+
+- `token` (String): Your bot token from @BotFather
+- `options` (Hash): Configuration options
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `logger` | Logger | STDOUT logger | Logger instance for bot output |
+| `timeout` | Integer | 30 | HTTP request timeout in seconds |
+| `session_store` | Store | MemoryStore | Session storage backend |
+
+## Basic Configuration
+
+```ruby
+require 'telegem'
+
+bot = Telegem.new(
+  'YOUR_BOT_TOKEN',
+  logger: Logger.new('bot.log'),
+  timeout: 60,
+  session_store: Telegem::Session::RedisStore.new(redis_client)
+)
+```
+
+## Handler Registration
+
+### Commands
+
+```ruby
+bot.command('start') do |ctx|
+  ctx.reply("Welcome!")
+end
+
+bot.command('help') do |ctx|
+  ctx.reply("Help message")
+end
+```
+
+Commands automatically match `/command` or `/command@botname`.
+
+### Text Patterns
+
+```ruby
+# Exact match
+bot.hears('hello') do |ctx|
+  ctx.reply("Hi there!")
+end
+
+# Regular expressions
+bot.hears(/^hello/i) do |ctx|
+  ctx.reply("Hello to you too!")
+end
+
+# Any text
+bot.hears(/.+/) do |ctx|
+  ctx.reply("You said: #{ctx.message.text}")
+end
+```
+
+### Update Type Handlers
+
+```ruby
+# Callback queries
+bot.callback_query do |ctx|
+  # Handle button presses
+end
+
+# Inline queries
+bot.inline_query do |ctx|
+  # Handle inline search
+end
+
+# Media messages
+bot.photo do |ctx|
+  ctx.reply("Nice photo!")
+end
+
+bot.document do |ctx|
+  ctx.reply("Received document")
+end
+
+# Location messages
+bot.location do |ctx|
+  latitude = ctx.message.location.latitude
+  longitude = ctx.message.location.longitude
+  ctx.reply("Location: #{latitude}, #{longitude}")
+end
+
+# Contact messages
+bot.contact do |ctx|
+  contact = ctx.message.contact
+  ctx.reply("Contact: #{contact.first_name} #{contact.last_name}")
+end
+```
+
+### Generic Handlers
+
+```ruby
+# Handle specific update types
+bot.on(:message) do |ctx|
+  # Handle all messages
+end
+
+bot.on(:callback_query) do |ctx|
+  # Handle callback queries
+end
+
+# With filters
+bot.on(:message, chat_type: 'private') do |ctx|
+  # Only private messages
+end
+
+bot.on(:message, text: /^\/admin/) do |ctx|
+  # Messages starting with /admin
+end
+```
+
+## Middleware
+
+```ruby
+# Add middleware
+bot.use(MyMiddleware.new)
+
+# Multiple middleware
+bot.use AuthenticationMiddleware.new
+bot.use RateLimitMiddleware.new(limit: 10)
+bot.use LoggingMiddleware.new
+
+# Inline middleware
+bot.use do |ctx, next_middleware|
+  puts "Processing: #{ctx.update.type}"
+  next_middleware.call(ctx)
+end
+```
+
+## Scenes
+
+```ruby
+bot.scene :registration do
+  step :ask_name do |ctx|
+    ctx.reply("What's your name?")
+  end
+
+  step :save_name do |ctx|
+    ctx.session[:name] = ctx.message.text
+    ctx.reply("Hi #{ctx.session[:name]}!")
+    ctx.leave_scene
+  end
+end
+
+# Enter scene
+bot.command('register') do |ctx|
+  ctx.enter_scene(:registration)
+end
+```
+
+## Error Handling
+
+```ruby
+bot.error do |error, ctx|
+  puts "Error: #{error.message}"
+  ctx&.reply("Sorry, something went wrong!")
+end
+```
+
+## Starting the Bot
+
+### Polling Mode (Development)
+
+```ruby
+bot.start_polling(
+  timeout: 30,      # Long polling timeout
+  limit: 100,       # Max updates per request
+  allowed_updates: nil  # Update types to receive
+)
+```
+
+### Webhook Mode (Production)
+
+```ruby
+server = bot.webhook(
+  port: 3000,
+  host: '0.0.0.0'
+)
+
+server.run
+```
+
+## Bot Methods
+
+### Information
+
+```ruby
+bot.token      # Bot token
+bot.api        # API client instance
+bot.logger     # Logger instance
+bot.running?   # Is bot running?
+```
+
+### Control
+
+```ruby
+bot.start_polling   # Start polling
+bot.shutdown        # Stop bot gracefully
+```
+
+### Webhook Management
+
+```ruby
+bot.set_webhook(url: 'https://example.com/webhook')
+bot.delete_webhook
+bot.get_webhook_info
+```
+
+### Dynamic Handler Registration
+
+```ruby
+# Add handlers at runtime
+bot.command('dynamic') do |ctx|
+  ctx.reply("Dynamic command!")
+end
+
+# Remove handlers (not directly supported, recreate bot)
+```
+
+## Configuration Examples
+
+### Development Setup
+
+```ruby
+bot = Telegem.new(
+  ENV['BOT_TOKEN'],
+  logger: Logger.new(STDOUT),
+  session_store: Telegem::Session::MemoryStore.new
+)
+```
+
+### Production Setup
+
+```ruby
+require 'redis'
+
+redis = Redis.new(url: ENV['REDIS_URL'])
+bot = Telegem.new(
+  ENV['BOT_TOKEN'],
+  logger: Logger.new('log/bot.log'),
+  timeout: 60,
+  session_store: Telegem::Session::RedisStore.new(redis)
+)
+```
+
+### Custom Logger
+
+```ruby
+logger = Logger.new('bot.log')
+logger.level = Logger::INFO
+
+bot = Telegem.new(
+  ENV['BOT_TOKEN'],
+  logger: logger
+)
+```
+
+## Edge Cases and Considerations
+
+### Bot Token Validation
+
+- Token must be in format: `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`
+- Invalid tokens will cause API errors on first request
+
+### Handler Conflicts
+
+```ruby
+# This will match both handlers
+bot.hears(/.+/) do |ctx|
+  # Matches everything
+end
+
+bot.command('start') do |ctx|
+  # Never reached because regex matches first
+end
+```
+
+Solution: Order matters, more specific handlers first.
+
+### Memory Usage
+
+- Long-running bots accumulate session data
+- Use TTL on session stores
+- Monitor memory usage in production
+
+### Rate Limiting
+
+Telegram has rate limits:
+
+- 30 messages/second for broadcasting
+- 20 callbacks/second
+- Implement middleware for rate limiting
+
+### Update Processing
+
+- Updates are processed sequentially
+- Long-running handlers block subsequent updates
+- Use async operations for I/O
+
+### Error Recovery
+
+- Network errors cause polling retries
+- Handler errors don't stop the bot
+- Use error handlers for graceful degradation
+
+## Best Practices
+
+1. **Environment Variables**: Store tokens in environment variables
+2. **Logging**: Configure appropriate log levels
+3. **Error Handling**: Always implement error handlers
+4. **Testing**: Test handlers with different update types
+5. **Monitoring**: Monitor bot health and performance
+6. **Security**: Validate inputs and use HTTPS for webhooks</content>
+<parameter name="filePath">/home/slick/telegem/docs/bot.md

data/docs/changelog.md

@@ -0,0 +1,182 @@
+# Changelog
+
+All notable changes to Telegem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive documentation covering all features and edge cases
+- Error handling guide with recovery strategies
+- Deployment guides for various platforms (Heroku, Docker, AWS)
+- Testing framework with examples and best practices
+- Troubleshooting guide for common issues
+- Performance optimization tips
+- Security best practices
+- Plugin development guide
+- Async operation handling
+- Rate limiting middleware
+- Health check endpoints
+- Structured logging support
+- Connection pooling for better performance
+- Graceful degradation features
+- Input validation middleware
+- Monitoring and metrics collection
+
+### Changed
+- Improved error messages and user feedback
+- Enhanced session management with TTL support
+- Better async operation handling
+- More robust webhook server implementation
+- Improved plugin architecture
+
+### Fixed
+- Memory leaks in long-running processes
+- Race conditions in concurrent operations
+- File upload size validation
+- SSL certificate handling
+- Session persistence issues
+
+## [1.0.0] - 2024-01-15
+
+### Added
+- Initial release of Telegem framework
+- Core bot functionality with command and hears handlers
+- Telegram API client with automatic retries
+- Session management with memory and Redis stores
+- Scene system for multi-step conversations
+- Inline and reply keyboard DSL
+- Webhook and polling support
+- FileExtract plugin for document processing
+- Translate plugin for text translation
+- Middleware system for request processing
+- Type-safe API response handling
+- Comprehensive error handling
+- Async I/O support with Async gem
+- Rate limiting and timeout handling
+- SSL/TLS support for webhooks
+
+### Technical Details
+- Ruby 3.0+ requirement
+- Async gem for concurrency
+- Modular architecture with plugins
+- RESTful API design
+- Comprehensive test coverage
+- Production-ready deployment options
+
+---
+
+## Version History
+
+### Pre-1.0 Releases
+
+#### [0.5.0] - 2023-12-01
+- Beta release with core functionality
+- Basic bot operations
+- API client implementation
+- Handler system
+- Session management
+
+#### [0.3.0] - 2023-11-15
+- Alpha release
+- Basic Telegram API integration
+- Command parsing
+- Message handling
+
+#### [0.1.0] - 2023-10-01
+- Initial prototype
+- Basic bot framework structure
+- Proof of concept implementation
+
+## Migration Guide
+
+### Upgrading from 0.x to 1.0
+
+#### Breaking Changes
+1. **Handler Registration:**
+   ```ruby
+   # Old
+   bot.on('/start') { |ctx| ... }
+
+   # New
+   bot.command('start') { |ctx| ... }
+   ```
+
+2. **Session Store:**
+   ```ruby
+   # Old
+   bot.session_store = Redis.new
+
+   # New
+   bot.session_store = Telegem::Session::RedisStore.new(ENV['REDIS_URL'])
+   ```
+
+3. **Middleware:**
+   ```ruby
+   # Old
+   bot.middleware.add(MyMiddleware)
+
+   # New
+   bot.use MyMiddleware.new
+   ```
+
+#### New Features
+- Async operations support
+- Plugin system
+- Enhanced error handling
+- Webhook SSL support
+- Scene system improvements
+
+#### Migration Steps
+1. Update handler registrations
+2. Configure new session store format
+3. Update middleware usage
+4. Add error handling
+5. Test thoroughly
+
+## Future Plans
+
+### Version 1.1.0 (Planned)
+- [ ] Database session store
+- [ ] Message queue integration
+- [ ] Advanced rate limiting
+- [ ] Bot analytics dashboard
+- [ ] Multi-language support
+
+### Version 1.2.0 (Planned)
+- [ ] Voice message handling
+- [ ] Location services integration
+- [ ] Payment processing
+- [ ] Bot-to-bot communication
+- [ ] Advanced scene workflows
+
+### Version 2.0.0 (Planned)
+- [ ] GraphQL API support
+- [ ] Real-time updates with WebSocket
+- [ ] Machine learning integrations
+- [ ] Advanced NLP features
+- [ ] Multi-platform bot support
+
+## Contributing
+
+When contributing to Telegem, please:
+1. Update the changelog with your changes
+2. Follow the existing format
+3. Add entries under [Unreleased] section
+4. Categorize changes as Added, Changed, Fixed, or Removed
+
+## Categories
+
+- **Added** for new features
+- **Changed** for changes in existing functionality
+- **Deprecated** for soon-to-be removed features
+- **Removed** for now removed features
+- **Fixed** for any bug fixes
+- **Security** in case of vulnerabilities
+
+---
+
+This changelog follows the principles of [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and is automatically updated with each release.</content>
+<parameter name="filePath">/home/slick/telegem/docs/changelog.md