{"id":30851513,"url":"https://github.com/vlymar1/hamster-code-generator","last_synced_at":"2025-09-07T07:11:51.109Z","repository":{"id":255752704,"uuid":"838804714","full_name":"vlymar1/Hamster-code-generator","owner":"vlymar1","description":"Hamster code keys generator (Генератор ключей кодов Hamster Combat) is a bot designed for automatic promo code farming and distribution via Telegram. It includes an admin panel for management and a notification system for user updates.","archived":false,"fork":false,"pushed_at":"2025-09-01T20:28:25.000Z","size":4897,"stargazers_count":11,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-07T01:33:28.966Z","etag":null,"topics":["aiogram","alembic","asyncio","bot","code","combat","generator","hamster","keys","kombat","postgresql","promo","python","redis","ruff","telegram"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vlymar1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-06T11:29:11.000Z","updated_at":"2025-07-20T09:49:37.000Z","dependencies_parsed_at":"2025-04-05T23:22:47.304Z","dependency_job_id":"448318e0-dfa6-4cbb-a9dd-24b5474da238","html_url":"https://github.com/vlymar1/Hamster-code-generator","commit_stats":null,"previous_names":["dev-lymar/hamster-code-generator","vlymar-dev/hamster-code-generator","vlymar1/hamster-code-generator"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/vlymar1/Hamster-code-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2FHamster-code-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2FHamster-code-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2FHamster-code-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2FHamster-code-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vlymar1","download_url":"https://codeload.github.com/vlymar1/Hamster-code-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlymar1%2FHamster-code-generator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274006441,"owners_count":25206145,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aiogram","alembic","asyncio","bot","code","combat","generator","hamster","keys","kombat","postgresql","promo","python","redis","ruff","telegram"],"created_at":"2025-09-07T07:11:47.863Z","updated_at":"2025-09-07T07:11:51.099Z","avatar_url":"https://github.com/vlymar1.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hamster Keys Generator\n\n[![Lint and Test](https://github.com/vlymar-dev/Hamster-code-generator/actions/workflows/lint-and-test.yaml/badge.svg)](https://github.com/vlymar-dev/Hamster-code-generator/actions/workflows/lint-and-test.yaml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python](https://img.shields.io/badge/Python-3.12.5-3776AB?style=flat\u0026logo=Python\u0026logoColor=yellow)](https://www.python.org/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16.8-336791?style=flat\u0026logo=PostgreSQL\u0026logoColor=white)](https://www.postgresql.org/)\n[![Redis](https://img.shields.io/badge/Redis-5.2.1-DC382D?style=flat\u0026logo=Redis\u0026logoColor=white)](https://redis.io/)\n[![Docker](https://img.shields.io/badge/Docker-24.0-2496ED?style=flat\u0026logo=Docker\u0026logoColor=white)](https://www.docker.com/)\n[![SQLAlchemy](https://img.shields.io/badge/SQLAlchemy-2.0-D71F00?style=flat\u0026logo=sqlalchemy\u0026logoColor=white)](https://www.sqlalchemy.org/)\n[![aiogram](https://img.shields.io/badge/aiogram-3.10.0-3776AB?style=flat\u0026logo=telegram\u0026logoColor=white)](https://aiogram.dev/)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)\n\n\n![Hamster code](./static/image.png)\n\n## Table of Contents\n- [Project Description](#project-description)\n- [Main Features](#main-features)\n- [Quick Setup and Running](#quick-setup-and-running)\n- [Bot Commands](#bot-commands)\n- [Contributing](#contributing)\n- [Security](#security)\n- [License](#license)\n- **Additional Resources**\n  - [Documentation](#documentation)\n\n\n## Project Description\n\n**Hamster Keys Generator** is an automated system for generating and managing promo codes for games,\nintegrated with a Telegram bot for user interaction. It leverages `PostgreSQL` for storing promo codes,\n`Redis` for session management and caching, and `aiohttp` for asynchronous API requests.\nProxy support ensures reliable game API access, while a multilingual interface enhances user experience.\n\n*⭐ Star this repository to support the project!*\n\u003e *Note: Multilingual support is currently under refactoring. Only English is available for now. Contributions are welcome!*\n\n## Main Features\n\n### Telegram Bot\n- **Promo Code Distribution**: Users claim keys via a user-friendly multilingual interface.\n- **Admin Tools**: Manage users, settings, and multilingual notifications with image support and detailed reports.\n- **Rate-Limiting**: Prevents abuse by limiting promo code requests per user.\n- **Donation System**: Supports Telegram Stars with fixed/custom amounts, payment confirmation, and refund options.\n- **Referral Links**: Users can promote projects and earn bonuses via referral invites.\n- **Achievements**: Tracks user activity and rewards progress with special bonuses.\n- **Boosted Key Counts(`POPULARITY_COEFFICIENT`)**: Increases displayed key counts to enhance user engagement.\n\n\n### Keygen\n- **Automated Code Generation**: Generates promo codes for multiple games and stores them in PostgreSQL.\n- **Reliable API Access**: Uses proxies to bypass geographical restrictions and rate limits.\n- **Robust Logging**: Logs all generation stages with automatic restarts on errors.\n\n### Flexible Startup\n- Run the Telegram bot, keygen, or both using configurable startup methods.\n\n\n## Quick Setup and Running\n*Follow these steps to set up and run **Hamster Keys Generator** for development or production.*\n\n### Requirements\n- Python 3.12+\n- PostgreSQL 16.8+\n- Redis 5.2.1+\n- Docker (optional for local development, recommended for production)\n\n### Steps:\n1. **Clone the Repository**:\n    ```sh\n    git clone https://github.com/vlymar-dev/Hamster-code-generator\n    cd Hamster-code-generator\n\n2. **Set up environment variables**:\n    ```sh\n    cp .env.example .env\n\n*Edit `.env` to set database, Redis, Telegram bot token, and proxy settings. See [Environment Setup](docs/ENV_SETUP.md) for details.*\n\n3. **Install dependencies**:\n    For production:\n   ```sh\n   pip install -r requirements.txt\n   ```\n   *For development (includes testing and linting tools)*:\n   ```sh\n   pip install -r requirements-dev.txt\n   ```\n\n4. **Set Up Proxies** (Optional):\n\n*Add proxy servers to `.proxies.txt` for API requests. See [Proxy Setup](docs/PROXIES.md) for formatting and usage.*\n\n5. **Start Services**:\n    ```sh\n    make local-up\n    ```\n\n6. Apply database migrations:\n    ```sh\n    make migrate-apply\n\n7. **Run the Application**:\nStart the bot, keygen, or both:\n    ```sh\n    python main.py\n    ```\n*Configure `STARTUP_METHOD` in `.env`*:\n- `0` (KeygenAndBot): Run both bot and keygen.\n- `1` (OnlyKeygen): Run keygen only.\n- `2` (OnlyBot): Run bot only.\n\n\n### Development Setup\n- **Install pre-commit hooks** for linting and formatting:\n    ```sh\n    pre-commit install\n    ```\n\n- **Run tests** to verify setup:\n  ```sh\n  make tests-run\n  ```\n\n- **Check Makefile** for additional development commands:\n  ```sh\n  make help\n  ```\n\n### Logging\nLogs are saved in `var/logs`, rotated daily, with a 10-day retention period.\n\n### Stopping Services\n- Stop Docker services:\n    ```sh\n    make local-down\n    ```\n\n## Bot Commands\nConfigure these commands in [BotFather](https://t.me/BotFather).\n\n### User Commands\n- `/start`: Start the bot.\n- `/change_language`: Switch language (English-only currently).\n- `/paysupport`: Donate via Telegram Stars.\n\n### Admin Commands\n- `/admin`: Access the admin panel.\n\n\n## Project Structure\n  ```cmd\n  .\n  ├── bot/            # Telegram bot logic\n  ├── keygen/         # Promo code generation logic\n  ├── infrastructure/ # Config, DB, and utilities\n  ├── tests/          # Unit tests\n  ├── main.py         # Application entry point\n  └── Makefile        # Development commands\n  ```\n*See [Project Structure Documentation](docs/PROJECT_STRUCTURE.md) for details.*\n\n## Contributing\nWe welcome contributions to Hamster-code-generator. To contribute:\n\n1. Fork the repository.\n2. Create a new branch for your changes.\n3. Make your changes and commit them to your branch.\n4. Update your branch from the main repository:\n    ```sh\n    git fetch upstream\n    git merge upstream/main\n    ```\n5. Submit a pull request.\n\nWe will review your pull request and provide feedback as needed.\n\n## Security\n- **Environment Variables**: Store sensitive data (API keys, tokens) in .env, not in code.\n- **Encryption**: Promo codes and user data are encrypted in transit and at rest.\n- **Access Control**: Admin commands use role-based access.\n- **Proxies**: Secure API requests with proxy support.\nReport security issues via [GitHub Issues](https://github.com/dev-lymar/Hamster-code-generator/issues) or email (add contact).\n\n\n## License\nThis project is licensed under the [MIT License](LICENSE).\n\n## Documentation\n- [Environment Setup](docs/ENV_SETUP.md)\n- [Project Structure](docs/PROJECT_STRUCTURE.md)\n- [Proxy Setup](docs/PROXIES.md)\n- [Testing](docs/TESTING.md)\n- [Makefile Commands](docs/MAKEFILE.md)\n- [CI/CD Configuration](docs/CICD.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlymar1%2Fhamster-code-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvlymar1%2Fhamster-code-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlymar1%2Fhamster-code-generator/lists"}