🔍 PreWatch: Scene Release Monitoring Made Easy 🚀

Monitor scene releases in real-time and get instant Discord notifications for your favorite content!

---

🌟 Welcome to PreWatch!

PreWatch is a Discord bot that monitors scene releases from the PreDB in real-time. Subscribe to search queries and get instant notifications when matching releases are found, built with discordx and discord.js v14.

🎮 Features That Power PreWatch

🔍 Smart Query Monitoring Subscribe to search queries and get notified when matching scene releases appear.	⚡ Real-time WebSocket Stream Live connection for instant release notifications as they happen.
🎯 Intelligent Matching Fuzzy matching algorithm optimized for scene releases with similarity detection.	💾 Lightweight Database Keyv with SQLite backend for persistent subscription storage without SQL complexity.
🎨 Rich Discord Components Beautiful Discord Components for all interactions with buttons and styled messages.	🔔 Flexible Notifications Choose between DM or channel notifications with one-click unsubscribe buttons.

🚀 Requirements

• Bun v1.4.0 - Fast JavaScript runtime tested in CI
• Discord Bot Application with bot token
• Access to Predb.ovh API (default endpoint)

🛠️ Setup Guide

1. Download the latest release (click on 'Source code (zip)').

2. Extract and move the files to your desired location.

3. Install Bun:

   • Mac/Linux:

     curl -fsSL https://bun.sh/install | bash

   • Windows:

     powershell -c "irm bun.sh/install.ps1 | iex"

4. Navigate to your project folder:

   cd /path/to/your/extracted/source

5. Rename .env.example to .env and configure your settings:

   • Required: Bot token, API URL, notification channel/mode
   • Bot Token Guide
   • Channel ID Guide

6. Install dependencies:

   bun install

7. Start the bot:

   bun start

🎯 Commands

• /add <query> - Subscribe to a search query for release notifications
• /list - View and manage your active subscriptions
• /setalertschannel - Choose this server's release alerts channel (Manage Server permission)
• /help - Display all available commands
• /ping - Check bot status and performance

Monitoring and Recovery

The release stream reconnects automatically after connection failures, including when the API is unavailable during startup. HTTP requests and WebSocket handshakes have a 15-second timeout.

Set POLLING_ENABLED=true to recover releases missed during an outage. Polling is disabled by default. POLLING_INTERVAL_SECONDS controls the base interval, and requests are paced at 30 per minute per cluster. Catch-up reads all pages back to the recovery boundary before advancing its cursor; incomplete requests and failed notifications are retried. A five-minute overlap accounts for delayed API indexing.

Delivery receipts are stored for seven days so distinct releases with the same timestamp and out-of-order live events can be delivered independently. Subscription updates are serialized per guild and restored after a failed storage mutation. Storage recovery still depends on the database remaining available.

Similar-query confirmations expire after 15 minutes. Notification unsubscribe buttons use compact query identifiers and continue to work across query case variants.

Development Checks

Run the same checks used in CI:

bun install --frozen-lockfile
bun run lint
bun run test
bun run audit

Tests use mocked Discord and API connections, temporary SQLite databases, and a local HTTP proxy. They do not log in to Discord or contact PreDB.

Security overrides select patched tar and @tootallnate/once versions. Compatibility tests cover SQLite archive extraction, node-gyp's streaming extraction API, and HTTP proxy requests.

The transitive braces v3.0.3 dependency has no upstream fix for GHSA-vfj7-8cjw-p6xm. The committed Bun patch rejects nesting at a depth of 128 in parsing, compilation, expansion, and stringification, including caller-provided ASTs. Regression tests verify the mitigation. bun run audit excludes only this locally patched advisory because registry scanners still identify the original package version. Retire the patch and exception when an upstream fixed version becomes available.

📸 Screenshots

Adding Subscriptions	Release Notifications
Subscription Management	Similarity Detection Smart detection prevents duplicate subscriptions

🤝 Contributing

We welcome contributions to improve PreWatch! If you'd like to contribute:

1. Fork the repository
2. Create a new branch for your feature or bug fix:

   git checkout -b feature/your-feature-name

3. Make your changes and commit them with a clear, descriptive message:

   git commit -m 'Add feature: brief description of your changes'

4. Push your changes to your fork:

   git push origin feature/your-feature-name

5. Open a Pull Request against the main repository's main branch

Please ensure your code follows the existing patterns and include clear descriptions in your Pull Request. Focus on performance and user experience improvements.

📜 License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details. (It's mostly "Share the love, and keep it open!")

🙏 Acknowledgements

• PredDB for the awesome scene release tracking
• discord.js for the powerful Discord API wrapper
• discordx for the decorator-based command framework
• Bun for the blazing fast JavaScript runtime
• Keyv for simple key-value storage

📬 Support & Community

Got questions or need help? Join our Discord server for support and to connect with other PreWatch users!

---

💻 Crafted with ❤️ by Valhalla-Development Built on the ValkyrieCore Discord bot template.

🐛 Spotted an issue? | 💡 Got an idea? | 🤔 Need help?

🔝 Back to Top