telegem 0.2.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc3dc81c673fa1128b108e02c3401f4bac483d7173759b4c901c3db625fa8dd8
-  data.tar.gz: 4cb6de9fa5d9b8c5babbbd83ff86b5b7f6c0161628e74dbb7416ee5eeaa10e70
+  metadata.gz: 6264779d02976cf1d0e711273fdc15764dcb1d3edf93ef45420de14e633c25d0
+  data.tar.gz: ab19b23511dc6e11c6c62d02d5b342071a8e44f4d1ed380293bf1870f8b7da6d
 SHA512:
-  metadata.gz: 32211bca88485aa5d19b41c8bc400b1af8b790de8ec4cf9761537a2f59de299e4ee6c5dca2de3e5561f58fe0280238c1452cff10429aa876d2fad2426556819d
-  data.tar.gz: fef73c4f8d976614ec815cee3c230409bf471564f38a46acb5fc7093c80d2154186a621f68068098cc1072cdb144184c92a683be83e42107f7ea409ea3175b5e
+  metadata.gz: 4cdc42ae03dc43d53b6920d0200443a0eb0ac4e665acd0f5511779f280f772a7d349951dddd5c4e3ecf236a31bdba506fe335e45e8ee83c0457a4d45f45567b9
+  data.tar.gz: 68a606074e574aca0aef136b45e1ab2d8b2c36f47dbf33a0b01a161935a02b14144fcf5f5d434d9497efbd7ab6326f22ecca977ca42397c35d939bafbfbf78e0

data/.replit

@@ -0,0 +1,13 @@
+run = "bundle exec ruby main.rb"
+hidden = [".bundle"]
+entrypoint = "main.rb"
+modules = ["ruby-3.2"]
+
+[nix]
+channel = "stable-24_05"
+
+[gitHubImport]
+requiredFiles = [".replit", "replit.nix"]
+
+[agent]
+expertMode = true

data/Contributing.md

@@ -0,0 +1,553 @@
+🤝 Contributing to Telegem
+
+Welcome! We're excited you want to contribute to Telegem. This guide will help you get started, whether you're fixing a bug, adding a feature, or improving documentation.
+
+---
+
+🎯 First Time Contributor?
+
+Start here! We welcome contributions of all sizes:
+
+· 🐛 Bug fixes - Found an issue? Help us fix it!
+· ✨ New features - Have an idea? Let's build it!
+· 📚 Documentation - Can something be clearer? Improve it!
+· 🧪 Tests - Help us make Telegem more reliable
+· 🌍 Examples - Share how you're using Telegem
+
+No contribution is too small! Even fixing a typo is appreciated.
+
+---
+
+📋 Table of Contents
+
+1. Code of Conduct
+2. Getting Started
+3. Development Setup
+4. Project Structure
+5. Making Changes
+6. Pull Request Process
+7. Coding Standards
+8. Testing
+9. Documentation
+10. Community
+
+---
+
+📜 Code of Conduct
+
+We are committed to providing a friendly, safe, and welcoming environment for all. By participating, you agree to:
+
+· Be respectful and inclusive
+· Give and receive constructive feedback gracefully
+· Focus on what's best for the community
+· Show empathy towards other community members
+
+Harassment of any kind will not be tolerated. If you experience or witness unacceptable behavior, please contact the maintainers.
+
+---
+
+🚀 Getting Started
+
+Find Something to Work On
+
+Good First Issues:
+Look for issues tagged with:
+
+· good first issue - Perfect for newcomers
+· help wanted - Need community help
+· documentation - Docs need improvement
+
+Want to suggest a feature?
+
+1. Check if it already exists in issues
+2. If not, open an issue to discuss first
+3. Get feedback before writing code
+
+Communication
+
+· Discuss first - For significant changes, open an issue to discuss
+· Ask questions - Don't hesitate to ask for clarification
+· Be patient - Maintainers are volunteers with limited time
+
+---
+
+🛠️ Development Setup
+
+1. Fork & Clone
+
+```bash
+# Fork on GitLab
+# Then clone your fork
+git clone https://gitlab.com/YOUR_USERNAME/telegem.git
+cd telegem
+```
+
+2. Install Dependencies
+
+```bash
+# Install Ruby (3.0+ required)
+ruby --version
+
+# Install Bundler if needed
+gem install bundler
+
+# Install gem dependencies
+bundle install
+```
+
+3. Set Up Your Environment
+
+```bash
+# Create a test bot token
+# Get one from @BotFather on Telegram
+export TEST_BOT_TOKEN="your_test_token_here"
+
+# Optional: Set up test Redis for session tests
+export REDIS_URL="redis://localhost:6379"
+```
+
+4. Verify Setup
+
+```bash
+# Run tests to ensure everything works
+bundle exec rake spec
+
+# Build the gem locally
+gem build telegem.gemspec
+
+# Test installation
+gem install ./telegem-*.gem
+```
+
+---
+
+🏗️ Project Structure
+
+```
+telegem/
+├── lib/
+│   ├── telegem.rb              # Main entry point
+│   ├── api/                    # Telegram API client
+│   │   ├── client.rb
+│   │   └── types.rb
+│   ├── core/                   # Core bot framework
+│   │   ├── bot.rb
+│   │   ├── context.rb
+│   │   ├── composer.rb
+│   │   └── scene.rb
+│   ├── session/                # Session management
+│   │   ├── middleware.rb
+│   │   └── memory_store.rb
+│   └── markup/                 # Keyboard builders
+│       └── keyboard.rb
+├── webhook/                    # Webhook server
+│   └── server.rb
+├── spec/                       # Tests
+│   ├── unit/
+│   ├── integration/
+│   └── spec_helper.rb
+├── examples/                   # Example bots
+│   ├── pizza_bot.rb
+│   └── echo_bot.rb
+├── docs/                       # Documentation
+│   ├── How_to_use.md
+│   ├── usage.md
+│   ├── cookbook.md
+│   └── API.md
+├── Gemfile
+├── telegem.gemspec
+└── Rakefile
+```
+
+---
+
+🔧 Making Changes
+
+1. Create a Branch
+
+```bash
+# Always work on a branch, never on main
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/issue-description
+# or
+git checkout -b docs/improve-readme
+```
+
+2. Make Your Changes
+
+Follow our coding standards. Write tests for new functionality.
+
+3. Test Your Changes
+
+```bash
+# Run all tests
+bundle exec rake spec
+
+# Run specific test file
+bundle exec rspec spec/core/bot_spec.rb
+
+# Run with coverage
+bundle exec rspec --format progress --coverage
+```
+
+4. Update Documentation
+
+· Update relevant documentation
+· Add examples if adding new features
+· Update API reference if changing public API
+
+5. Commit Your Changes
+
+```bash
+# Use descriptive commit messages
+git commit -m "Add feature: description of change
+
+- Detail 1 about the change
+- Detail 2 about the change
+- Fixes #123 (if applicable)"
+```
+
+Commit Message Guidelines:
+
+· First line: Summary (50 chars or less)
+· Blank line
+· Detailed description (wrap at 72 chars)
+· Reference issues: Fixes #123, Closes #456
+
+---
+
+🔄 Pull Request Process
+
+1. Push Your Branch
+
+```bash
+git push origin your-branch-name
+```
+
+2. Create a Merge Request
+
+On GitLab:
+
+1. Click "Merge Requests" → "New Merge Request"
+2. Select your branch
+3. Fill in the template
+4. Request review from maintainers
+
+3. Merge Request Template
+
+```markdown
+## Description
+<!-- What does this PR do? Why is it needed? -->
+
+## Type of Change
+- [ ] Bug fix (non-breaking change)
+- [ ] New feature (non-breaking change)  
+- [ ] Breaking change (fix/feature causing existing functionality to break)
+- [ ] Documentation update
+- [ ] Example/test addition
+
+## Testing
+- [ ] Added tests for new functionality
+- [ ] Updated existing tests
+- [ ] All tests pass locally
+- [ ] Manual testing completed
+
+## Documentation
+- [ ] Updated API documentation
+- [ ] Updated usage examples
+- [ ] Updated README if needed
+
+## Checklist
+- [ ] Code follows project standards
+- [ ] Self-reviewed my own code
+- [ ] Added comments for complex logic
+- [ ] No new warnings generated
+```
+
+4. Review Process
+
+· Maintainers will review within a few days
+· Address any feedback requested
+· Tests must pass
+· Keep discussions constructive
+
+5. After Approval
+
+· Maintainer will merge your PR
+· Your contribution will be in the next release!
+· You'll be added to contributors list
+
+---
+
+📏 Coding Standards
+
+Ruby Style
+
+Follow Ruby Style Guide with these specifics:
+
+```ruby
+# Good
+def send_message(text, parse_mode: nil)
+  # ...
+end
+
+# Bad  
+def sendMessage(text, parse_mode = nil)
+  # ...
+end
+```
+
+Naming
+
+· Modules/Classes: CamelCase
+· Methods/Variables: snake_case
+· Constants: SCREAMING_SNAKE_CASE
+
+Async Patterns
+
+```ruby
+# Use Async.do for I/O operations
+def fetch_data
+  Async do
+    await api.call('method', params)
+  end
+end
+
+# Handle errors properly
+Async do
+  begin
+    await risky_operation
+  rescue => e
+    logger.error("Failed: #{e.message}")
+    raise
+  end
+end
+```
+
+Documentation
+
+```ruby
+# Document public methods
+# @param [String] text The message to send
+# @option options [String] :parse_mode "HTML", "Markdown", or "MarkdownV2"
+# @return [Async::Task] Async task that sends the message
+def reply(text, **options)
+  Async do
+    # ...
+  end
+end
+```
+
+---
+
+🧪 Testing
+
+Writing Tests
+
+```ruby
+# spec/core/bot_spec.rb
+RSpec.describe Telegem::Core::Bot do
+  describe "#command" do
+    it "registers a command handler" do
+      bot = described_class.new("test_token")
+      bot.command('test') { |ctx| ctx.reply("Working") }
+      
+      expect(bot.handlers[:message].size).to eq(1)
+    end
+  end
+end
+```
+
+Test Structure
+
+· Unit tests - Test individual components
+· Integration tests - Test component interactions
+· Async tests - Test async behavior properly
+
+Running Tests
+
+```bash
+# All tests
+bundle exec rake spec
+
+# Specific test type
+bundle exec rspec spec/unit
+bundle exec rspec spec/integration
+
+# With verbose output
+bundle exec rspec --format documentation
+
+# Watch mode (development)
+bundle exec guard
+```
+
+---
+
+📚 Documentation
+
+Documentation Types
+
+1. API Reference (docs/API.md) - Complete method documentation
+2. Usage Guides (docs/usage.md) - Advanced patterns
+3. Tutorials (docs/How_to_use.md) - Beginner guides
+4. Cookbook (docs/cookbook.md) - Copy-paste recipes
+5. Examples (examples/) - Working bot examples
+
+Writing Documentation
+
+· Use clear, simple language
+· Include code examples
+· Show both simple and advanced usage
+· Update when changing functionality
+
+Building Examples
+
+```bash
+# Test your examples work
+cd examples
+ruby pizza_bot.rb --test-mode
+```
+
+---
+
+🌍 Community
+
+Getting Help
+
+· Issues - Bug reports and feature requests
+· Merge Requests - Code contributions
+· Discussions - Questions and ideas
+· Chat - Telegram group for quick questions
+
+Recognition
+
+All contributors are recognized in:
+
+· README.md contributors section
+· Release notes
+· Project documentation
+
+Becoming a Maintainer
+
+Consistent contributors may be invited to become maintainers. We look for:
+
+· Quality contributions over time
+· Helpful community participation
+· Understanding of project goals
+· Willingness to review others' work
+
+---
+
+🐛 Reporting Bugs
+
+Before Reporting
+
+1. Check if issue already exists
+2. Update to latest version
+3. Try to reproduce with minimal code
+
+Bug Report Template
+
+```markdown
+## Description
+<!-- Clear description of the bug -->
+
+## Steps to Reproduce
+1. 
+2. 
+3. 
+
+## Expected Behavior
+<!-- What should happen -->
+
+## Actual Behavior  
+<!-- What actually happens -->
+
+## Environment
+- Telegem version:
+- Ruby version:
+- OS:
+- Telegram Bot API token: (use test token)
+
+## Code Example
+```ruby
+# Minimal code to reproduce
+```
+
+Logs/Errors
+
+<!-- Any error messages or logs -->```
+
+---
+
+## 💡 Suggesting Features
+
+### Feature Request Template
+```markdown
+## Problem
+<!-- What problem does this solve? -->
+
+## Solution
+<!-- Describe your proposed solution -->
+
+## Alternatives
+<!-- Any alternative solutions considered -->
+
+## Use Cases
+<!-- Who needs this and how will they use it? -->
+
+## Implementation Ideas
+<!-- Technical implementation thoughts -->
+```
+
+---
+
+🏷️ Release Process
+
+Versioning
+
+We follow Semantic Versioning:
+
+· MAJOR - Breaking changes
+· MINOR - New features (backwards compatible)
+· PATCH - Bug fixes (backwards compatible)
+
+Release Checklist
+
+· All tests pass
+· Documentation updated
+· Examples tested
+· Changelog updated
+· Version bumped in lib/telegem.rb
+· Git tag created
+· Gem pushed to RubyGems
+· Release notes published
+
+---
+
+🙏 Acknowledgments
+
+Thank you for contributing! Your work helps make Telegem better for everyone.
+
+Quick Start Recap
+
+1. Fork & clone
+2. Create branch
+3. Make changes
+4. Write tests
+5. Update docs
+6. Submit MR
+
+Remember: Every contribution matters. Whether you're fixing a typo or adding a major feature, you're helping build something awesome!
+
+---
+
+❓ Still Have Questions?
+
+· Read the documentation
+· Check existing issues
+· Ask in discussions
+· Join our Telegram group
+
+Happy coding! 🎉

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.0'
+  gem 'pry', '~> 0.14.0'
+end

data/Gemfile.lock

@@ -0,0 +1,11 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+
+BUNDLED WITH
+   2.4.10

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 šłîçk phäñtøm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.