quest-bot

---

Project Description 📝

quest-bot is a highly resilient and feature-rich Discord automation and gamification service engineered using modern TypeScript best practices. Designed for environments requiring complex state management and high reliability, the bot features a comprehensive architecture that supports multiple data persistence layers (MongoDB via Mongoose, and relational options like MySQL/SQLite3 via TypeORM), ensuring data integrity and deployment flexibility across diverse infrastructure setups.

The core strength of quest-bot lies in its ability to handle dynamic, scheduled tasks and generate rich media content on the fly. It integrates advanced media processing via fluent-ffmpeg and dynamic image manipulation through sharp and canvas to create custom graphics, embeds, and quest completion certificates, enhancing user engagement significantly. Furthermore, the use of node-cron and node-schedule guarantees precise execution of time-gated activities, daily resets, and maintenance tasks.

To maintain production stability, the system incorporates enterprise-grade logging via Winston and Logtail, providing real-time external monitoring and rotational file management. For external API interactions—crucial for fetching quest data or processing payments—it employs axios alongside proxy-agent to manage reliability, handle rate limits gracefully, and support geo-restricted operations. quest-bot serves as a robust platform for community engagement, offering both standard bot functionality and specialized self-bot operations where required, all while rigorously tracking performance using pidusage.

Key Features ✨

• Advanced Data Persistence: Multi-database support utilizing TypeORM for relational data (MySQL, SQLite3) and Mongoose for flexible NoSQL document storage (MongoDB), ensuring maximum deployment versatility.
• Dynamic Media Generation: High-performance image and graphic manipulation capabilities powered by sharp and canvas to dynamically render rich Discord embeds, user profile cards, quest progress bars, and reward graphics (as suggested by the extensive emoji/image asset library).
• Scheduled Automation Engine: Implementation of both node-cron and node-schedule for highly accurate, time-zone-aware scheduling of recurring events, quest resets, daily rewards, and maintenance routines.
• Robust Logging and Monitoring: Professional logging pipeline using Winston and winston-daily-rotate-file locally, complemented by external observability integration via @logtail/node for remote diagnostics and production health monitoring.
• Media and Video Processing: Integration with fluent-ffmpeg allows for advanced handling of audio/video streams and media assets within the Discord environment, supporting features like clip generation or dynamic content playback.
• Flexible Deployment Modes: Supports standard bot operations via discord.js alongside specialized, high-volume automation tasks using discord.js-selfbot-v13.
• API and Service Reliability: Uses axios for external calls, augmented by proxy-agent for managing proxy rotation and enhanced network reliability when interacting with third-party APIs.
• System Performance Tracking: Real-time process monitoring using pidusage to track CPU, memory, and resource consumption, aiding in performance optimization and bottleneck detection.

Installation & Running Locally 🚀

This guide assumes you have Node.js (v16+) and npm installed. You must also have access to a database (MongoDB recommended for initial setup, or configure TypeORM for MySQL/SQLite).

1. Clone the Repository

git clone https://github.com/yourusername/quest-bot.git

cd quest-bot

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a configuration file (e.g., .env or config.ini) based on the project's requirements, ensuring all necessary tokens (Discord, database credentials, Logtail API key) are populated.

4. Database Synchronization (TypeORM/Mongoose)

Depending on your chosen configuration (e.g., TypeORM with MySQL), you may need to run initial migrations or synchronization scripts.

5. Run in Development Mode (with Watcher)

Use ts-node and nodemon for hot reloading during development, orchestrated by concurrently.

npm run dev

6. Build and Run for Production

First, compile the TypeScript source files into JavaScript:

npm run build

Then, execute the compiled code:

npm start

How to Contribute 🤝

We welcome high-quality contributions, feature suggestions, and bug reports. Please adhere to the following guidelines:

1. Fork the Repository: Start by forking the quest-bot repository to your personal GitHub account.
2. Create a Feature Branch: Branch off the main or development branch for all new features or bug fixes. Use descriptive names (e.g., feat/add-new-quest-type or fix/database-connection-leak).
3. Code Standards: Ensure your code adheres to the project's TypeScript standards. Run linting and formatting before committing.
4. Testing: All new features or fixes must be accompanied by relevant unit or integration tests where applicable.
5. Commit Messages: Write clear, concise, and descriptive commit messages following the Conventional Commits specification (e.g., feat: Added dynamic embed template using Nunjucks).
6. Pull Requests (PRs): Submit your work via a Pull Request targeting the development branch. Include a detailed description of the changes, the motivation, and any associated issue numbers. PRs will be reviewed by a core maintainer before merging.

quest-bot

---

Project Description 📝

quest-bot 是一个高性能、功能强大的自动化任务与奖励系统机器人，专为复杂的社区管理和用户激励场景而设计。该项目充分利用了现代 Node.js 生态系统的优势，结合 TypeScript 提供的类型安全保障，确保了系统的高度稳定性和可维护性。

作为一个综合性的 Discord 机器人解决方案，quest-bot 不仅能够处理实时交互和事件驱动的逻辑，还集成了复杂的持久化层（支持 MongoDB, MySQL, SQLite）以及强大的媒体处理能力。这使其能够动态生成用户资料卡、处理活动状态更新（如游戏、流媒体），并管理细致入微的奖励发放和等级系统。

项目的架构高度模块化，通过使用 Express 作为 API 接口、Winston/Logtail 进行生产级可观测性、以及 Cron/Schedule 进行精确的定时任务管理，使得 quest-bot 能够应对高并发的事件负载，并在需要时通过代理（Proxy Agent）实现灵活的网络访问，是构建企业级或大型社区自动化平台的理想选择。

Key Features ✨

• 多源数据库支持与抽象 (Mongoose/TypeORM): 提供对 NoSQL (MongoDB) 和 SQL (MySQL/SQLite) 的全面支持，允许开发者根据部署环境灵活选择最合适的持久化策略。
• 高级媒体与图像处理 (Sharp/Canvas/FFmpeg): 能够实时渲染和处理复杂的图像资产（如用户奖励徽章、服务器加速等级图标等），并支持媒体流操作。
• 实时状态与活动跟踪: 通过集成 Discord API，精确监控用户的跨平台活动状态（包括游戏、流媒体观看等），并根据这些状态触发相应的任务或奖励机制。
• 全面的任务与奖励系统 (Quests & Rewards): 包含用户登记（enroll）、领取奖励（claim）、经验/货币管理（coins.gif），以及基于服务器加速等级（boost_level_1-9）的动态激励结构。
• 生产级日志与监控 (Winston & Logtail): 采用 winston-daily-rotate-file 确保日志归档的健壮性，并通过 @logtail/node 实现集中的、可观测的错误追踪。
• 灵活的调度机制: 利用 node-cron 和 node-schedule 库，实现高精度的周期性维护任务、数据清理和定时奖励发放。
• 模块化模板引擎 (Nunjucks): 使用 Nunjucks 驱动的模板系统，使得通知消息、嵌入式内容或动态生成的报告具有高度的可定制性。

Installation & Running Locally 🚀

请确保您的环境中已安装 Node.js (推荐 v18+)、npm 或 yarn，以及 MongoDB 或 MySQL 数据库实例。

1. 克隆仓库:

git clone https://github.com/YourUsername/quest-bot.git
cd quest-bot

2. 安装依赖:

npm install

3. 配置环境变量:

创建 .env 文件或配置您的项目文件（例如 config.ini 或 config.json），配置数据库连接字符串、Discord Bot Token 和其他必要的 API 密钥。

# 示例配置 (假设使用 .env)
DISCORD_TOKEN="YOUR_BOT_TOKEN"
MONGO_URI="mongodb://localhost:27017/questdb"
LOGTAIL_SOURCE_TOKEN="YOUR_LOGTAIL_TOKEN"
# ... 其他配置

4. 启动开发环境:

使用 ts-node 和 nodemon 实现热重载开发模式。

npm run dev

5. 启动生产环境:

编译 TypeScript 代码并使用 Node.js 运行。

npm run build
npm start

How to Contribute 🤝

我们热烈欢迎所有形式的贡献，包括功能添加、错误修复、文档改进和性能优化。

1. Fork 项目: 将本仓库 Fork 到您的 GitHub 账户。
2. 创建分支: 为您的更改创建一个新的功能分支 (git checkout -b feature/AmazingFeature)。
3. 提交更改: 确保您的代码符合现有的代码规范和 TypeScript 最佳实践。

   git commit -m 'feat: Add AmazingFeature functionality'

4. 推送至分支:

   git push origin feature/AmazingFeature

5. 创建 Pull Request (PR): 提交 PR，并清晰描述您所做的更改、解决的问题以及引入的新功能。

注意: 所有提交都应通过 npm run lint 和 npm run test (如果可用) 的检查。对于新功能，请考虑添加相应的单元测试。