pokemon-stock-checker/SETUP_GUIDE.md

Pokemon Stock Monitor - Setup Guide

Overview

This monitor watches retail sites for Pokemon TCG restocks and new drops, sending Discord notifications when products become available.

Supported Sites:

• Target (working)
• PokemonCenter (requires special setup - see below)
• Walmart (planned)
• BestBuy (planned)

---

Prerequisites

• Python 3.10+
• Chrome/Chromium browser
• Discord server with webhook access
• ~500MB disk space (for browser)

---

Quick Start (5 minutes)

1. Clone/Copy the Project

# Copy the pokemon-stock-monitor folder to your server
cd pokemon-stock-monitor

2. Install Dependencies

pip install -r requirements.txt
playwright install chromium

3. Configure Discord Webhook

1. Open Discord → Your Server → Server Settings → Integrations → Webhooks
2. Click "New Webhook"
3. Name it "Pokemon Stock Monitor"
4. Copy the Webhook URL
5. Edit config.py:

DISCORD_WEBHOOK_URL = "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL_HERE"

4. Configure Sites to Monitor

Edit config.py:

# Enable the sites you want
SITES_ENABLED = ["target"]  # Add "pokemoncenter" after special setup

# Customize check interval (seconds)
CHECK_INTERVAL_SECONDS = 60

# For headless server, set to True
HEADLESS = True

5. Run the Monitor

python main.py

You should see:

==================================================
Pokemon Stock Monitor
==================================================
Monitoring: target
Check interval: 60 seconds
==================================================

Running initial check...

---

Running as a Background Service

Option A: Using Screen (Linux)

# Start a screen session
screen -S pokemon-monitor

# Run the monitor
python main.py

# Detach: Press Ctrl+A, then D
# Reattach later: screen -r pokemon-monitor

Option B: Using systemd (Linux)

Create /etc/systemd/system/pokemon-monitor.service:

[Unit]
Description=Pokemon Stock Monitor
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/path/to/pokemon-stock-monitor
ExecStart=/usr/bin/python3 main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable pokemon-monitor
sudo systemctl start pokemon-monitor

# Check status
sudo systemctl status pokemon-monitor

# View logs
journalctl -u pokemon-monitor -f

Option C: Using Task Scheduler (Windows)

1. Open Task Scheduler
2. Create Basic Task → Name: "Pokemon Monitor"
3. Trigger: "When the computer starts"
4. Action: Start a program
   • Program: python
   • Arguments: main.py
   • Start in: C:\path\to\pokemon-stock-monitor
5. Check "Run whether user is logged on or not"

---

PokemonCenter Setup (Special - Requires GUI)

PokemonCenter has strong bot protection (Imperva). To monitor it:

Method 1: Use Real Chrome Profile (Recommended)

This uses your actual Chrome browser with all its cookies/history, making it appear human.

1. Find your Chrome profile path:

   • Windows: C:\Users\USERNAME\AppData\Local\Google\Chrome\User Data
   • Linux: ~/.config/google-chrome
   • Mac: ~/Library/Application Support/Google/Chrome

2. Edit config.py:

# Add this line
CHROME_USER_DATA_DIR = "C:\\Users\\USERNAME\\AppData\\Local\\Google\\Chrome\\User Data"

# Enable PokemonCenter
SITES_ENABLED = ["target", "pokemoncenter"]

# Must be False to use Chrome profile
HEADLESS = False

3. Important: Close Chrome before running the monitor (can't use same profile twice)

4. First run: Manually solve any CAPTCHA that appears, then the session should stay valid

Method 2: VM with Desktop Environment

If running on a headless server, set up a VM with a desktop:

1. Install a lightweight desktop (XFCE, LXDE)
2. Install Chrome and browse PokemonCenter manually once
3. Run the monitor with HEADLESS = False
4. Use VNC/RDP to check on it occasionally

---

Configuration Reference

config.py Options

# Discord webhook URL (required)
DISCORD_WEBHOOK_URL = "https://discord.com/api/webhooks/..."

# Check interval in seconds (60 = 1 minute)
CHECK_INTERVAL_SECONDS = 60

# Sites to monitor
SITES_ENABLED = ["target"]  # Options: "target", "pokemoncenter"

# URLs to monitor per site
TARGET_URLS = [
    "https://www.target.com/s?searchTerm=pokemon+tcg",
]

POKEMON_CENTER_URLS = [
    "https://www.pokemoncenter.com/category/tcg-cards?sort=relevance",
]

# Keyword filtering (optional)
KEYWORD_FILTER_ENABLED = False
KEYWORDS = ["chaos rising", "booster", "etb", "elite trainer"]

# Browser settings
HEADLESS = True   # True for servers, False for desktop/VM
SLOW_MO = 0       # Slow down browser (ms) for debugging

# Logging level
LOG_LEVEL = "INFO"  # DEBUG, INFO, WARNING, ERROR

---

Troubleshooting

"No products found"

• Check debug_screenshot.png or debug_target.png in the project folder
• The site may have changed its HTML structure
• Try increasing wait times in browser.py

"Discord notification not sending"

• Verify webhook URL is correct in config.py
• Test webhook: python -c "from discord_notifier import test_webhook; test_webhook()"

"Browser failed to start"

# Reinstall Playwright browsers
playwright install chromium --force

# On Linux, install dependencies
playwright install-deps chromium

"Access denied" / Bot blocked

• PokemonCenter: Use the Chrome profile method above
• Target: Should work, try increasing CHECK_INTERVAL_SECONDS to 120+
• All sites: Don't run too frequently (rate limiting)

High CPU/Memory Usage

• Set HEADLESS = True (uses less resources)
• Increase CHECK_INTERVAL_SECONDS
• The browser stays open between checks (by design, for session persistence)

---

File Structure

pokemon-stock-monitor/
├── main.py              # Entry point - run this
├── config.py            # Configuration - edit this
├── browser.py           # Browser automation
├── discord_notifier.py  # Discord webhook
├── product_tracker.py   # Tracks products for restock detection
├── products.json        # Auto-generated product database
├── monitor.log          # Log file
├── scrapers/
│   ├── base.py          # Base scraper class
│   ├── pokemoncenter.py # PokemonCenter scraper
│   └── target.py        # Target scraper
└── requirements.txt     # Python dependencies

---

Adding More Sites

The scraper architecture is modular. To add a new site:

1. Create scrapers/newsite.py based on target.py
2. Add to scrapers/__init__.py
3. Add URL config to config.py
4. Add check function to main.py

---

Support

If you encounter issues:

1. Check monitor.log for errors
2. Check debug screenshots (debug_*.png)
3. Try running with LOG_LEVEL = "DEBUG" for more info