GitHub - alcayaga/djs-site-watcher: A Discord bot that alerts you when (a selectable part of) a website changes.

site-watcher

A Discord bot that alerts you when (part of) a website changes.

Features

Notify you in Discord when a website changes:

List of features of the site-watcher bot:

Add multiple sites to watcher
Remove site from watcher
Monitoring specified elements of a site, to not get notified on dynamic elements (ex. ads)
Checking on a specified interval (1-60 minutes, default 5).
Show list of tracked sites
Monitor Apple Carrier Bundles (Carrier)
Monitor Apple Pay Configurations (ApplePay)
Monitor Apple eSIM Carrier Support (AppleEsim)
Monitor Apple Feature Availability (AppleFeature)
Monitor Solotodo Deals (Deal)
Modular Channel Handlers for specialized channel behavior (Moderation, Q&A)
Open source!

Install

1. Create a Discord Application

Go to the Discord Developer Portal.
Click New Application and give it a name.
Navigate to the Bot tab:
- Reset/Copy the Bot Token (you'll need this later).
- Under the Privileged Gateway Intents section, enable the Message Content Intent.
Navigate to the OAuth2 tab, then the URL Generator sub-menu:
- Scopes: Select bot and applications.commands from the list.
- Bot Permissions: Once bot is selected, a permission list will appear. Select the following:
  - General Permissions: View Channels.
  - Text Permissions: Send Messages, Send Messages in Threads, Create Public Threads, Manage Messages, Embed Links, Attach Files, Read Message History, and Use Slash Commands.
- Copy the generated URL at the bottom and use it to invite the bot to your server.

2. Project Setup

Make sure you have git and Node.js (v16.11.0 or higher) installed.

Clone the repository:

git clone https://github.com/alcayaga/djs-site-watcher.git
cd djs-site-watcher

Install dependencies:
```
npm install
```

3. Configuration

Create a .env file from the .env.example:
```
cp .env.example .env
```
Fill in the required fields in .env:
- DISCORDJS_BOT_TOKEN: Your bot token from step 1.
- DISCORDJS_CLIENT_ID: Found in the "General Information" tab of your application.
Configure the bot in config/settings.json:
- defaultChannelId: The ID of the channel where notifications will be sent.
- monitors: Customize channelId and apiDelay for specific monitors.
- channels: Configure specific IDs and delays for Q&A or Deals moderation.
- interval: The refresh rate in minutes (default 5).

_{Note: Using settings.json is the recommended way to manage configuration.}

Usage

Starting the Bot

Register Slash Commands: Run this once or whenever commands are updated:
```
npm run deploy
```
Start the Bot:
```
npm start
```

Using the Bot

Once the bot is online:

In Discord, use the /add command to start monitoring a website.
By default, only users with Manage Server permission can use the bot's commands. You can customize this in Server Settings → Integrations.
Use /help to see all available commands.

_{Note: The default watch interval is 5 minutes. You can change it globally with /interval or per-monitor if configured in config/settings.json.}

For all other options, see Commands.

Commands

`/help`

Show all the available commands.

`/add`

Adds a website to the list by opening a form.

The form will ask for:

URL: The website address to monitor.
CSS Selector (Optional): Specifies which part of the site to track. By default, the <head> is tracked. To avoid false alerts from dynamic content like ads, it's best to provide a specific selector.
Force add (Optional): If you enter yes, the site will be added even if the bot cannot currently fetch it (e.g., it returns a 404). This is useful for monitoring sites that are not yet live.

_{Tip: In Chrome, you can get a selector by right-clicking the part of the site you want to track and selecting Inspect. In the developer view, right-click the highlighted element and select Copy → Copy selector.}

Example
/add This opens the pop-up form.

`/remove`

Removes a website from the list by opening an interactive dropdown menu.

Example
/remove This opens a dropdown where you can select the site to remove.

`/list` (Alias: `/show`)

Shows the list of websites being watched. Includes a button to quickly remove sites.

`/interval minutes: <MINUTES>`

Set the interval/refresh rate of the watcher. Default 5 minutes.

Parameters
minutes: The interval in minutes (minimum of 1, maximum of 60).

Example
/interval minutes:10 Sets the interval to 10 minutes.

`/monitor <subcommand> [name]`

Manage the monitors.

Subcommands

start: Start a monitor.
stop: Stop a monitor.
status: Show status.
check: Trigger a manual check.

Parameters name (Optional): The name of the monitor (e.g., Site, Carrier, AppleEsim, ApplePay, AppleFeature). Defaults to all. Autocomplete is enabled.

Example /monitor status Shows the status of all monitors. /monitor check name:Carrier Triggers a check for the Carrier monitor.

Channel Handlers

The bot includes a modular system to handle messages in specific channels differently.

Q&A (`QA`)

Automatically responds to messages matching regex patterns defined in config/responses.json.

Trigger: Configured via channelId in config/settings.json.
Behavior: Sends text or image replies based on triggers.

Deals Moderation (`Deals`)

Enforces a "deals-only" policy in a specific channel.

Trigger: Configured via channelId in config/settings.json.
Behavior:
- Allows messages containing a link or an image.
- Deletes all other messages and sends a private message to the user asking them to use threads for discussion.

Migration to v3.1.0

Version 3.1.0 moves advanced configuration (channel IDs and delays) from environment variables to config/settings.json.

Centralized Config: Use config/settings.json to manage all monitor and channel settings.
Legacy Support: Environment variables like DISCORDJS_TEXTCHANNEL_ID, DISCORDJS_APCHANNEL_ID, and DISCORDJS_DEALS_CHANNEL_ID are now deprecated and will be removed in future versions.
Automatic Backfill: If settings.json is missing these values, the bot will still attempt to use the legacy environment variables if they are set.

Migration from v2 to v3

Version 3.0.0 introduces Discord Slash Commands.

Client ID: You must add DISCORDJS_CLIENT_ID= to your .env file. Find this in the Discord Developer Portal under "General Information".
Deploy Commands: Run npm run deploy to register the new slash commands with Discord.
Command Prefix: The ! prefix is removed. Use slash commands (e.g., /help) instead.

Migration from v1

Version 2.0.0 introduces a new configuration structure.

Automatic Migration: The bot will automatically attempt to move your legacy JSON configuration files from src/ to the new config/ directory upon the first run of v2.0.0. It will also patch the internal file paths in settings.json.

Manual Migration (Optional): If you prefer to migrate manually:

Create a config/ directory at the project root.
Move all .json files from src/ to config/.
In config/settings.json, update any "file": "./src/..." entries to "file": "./config/...".

Troubleshooting

Debugging Deal Alerts

If you suspect false positive alerts (e.g., "Back to Historic Low" when the price never changed), check the logs for: [DealMonitor] Price change for ... This log entry records every price movement (up or down), including the product ID, name, old price, new price, and stored minimum.

Phantom Spike: You will see a price INCREASE log followed immediately by a price DECREASE log in the next check cycle.
Legitimate Change: The price will stabilize at the new value.

License

This project is licensed under the MIT License - see the LICENSE file for details

Name		Name	Last commit message	Last commit date
Latest commit History 359 Commits
.gemini		.gemini
.github		.github
.vscode		.vscode
__mocks__		__mocks__
config		config
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
ecosystem.config.js		ecosystem.config.js
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

site-watcher

Features

Install

1. Create a Discord Application

2. Project Setup

3. Configuration

Usage

Starting the Bot

Using the Bot

Commands

`/help`

`/add`

`/remove`

`/list` (Alias: `/show`)

`/interval minutes: <MINUTES>`

`/monitor <subcommand> [name]`

Channel Handlers

Q&A (`QA`)

Deals Moderation (`Deals`)

Migration to v3.1.0

Migration from v2 to v3

Migration from v1

Troubleshooting

Debugging Deal Alerts

License

About

Uh oh!

Releases 12

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

site-watcher

Features

Install

1. Create a Discord Application

2. Project Setup

3. Configuration

Usage

Starting the Bot

Using the Bot

Commands

/help

/add

/remove

/list (Alias: /show)

/interval minutes: <MINUTES>

/monitor <subcommand> [name]

Channel Handlers

Q&A (QA)

Deals Moderation (Deals)

Migration to v3.1.0

Migration from v2 to v3

Migration from v1

Troubleshooting

Debugging Deal Alerts

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`/help`

`/add`

`/remove`

`/list` (Alias: `/show`)

`/interval minutes: <MINUTES>`

`/monitor <subcommand> [name]`

Q&A (`QA`)

Deals Moderation (`Deals`)

Packages