TestPostsBot/CHANGELOG.md

# Changelog - TestPostsBot

## Version 2.1.0 - Update Checker System

### New Features

#### 1. Update Checker System
- Bot now periodically checks for new versions from a centralized update server
- Automatically sends modmail notifications to subreddit modteam when updates are available
- Includes changelog URL in notification for easy reference
- 24-hour cooldown prevents spam (max 1 notification per day)
- Runs as a background daemon thread alongside main bot operations
- Tracks last update notification timestamp to file for persistence across restarts

#### 2. Version Management
- Bot version is now centralized at the top of `bot.py` in a dedicated section
- `BOT_VERSION` and `BOT_NAME` constants used throughout the bot
- Easy single-location reference for version updates
- Version automatically included in update checker calls and user agent string

#### 3. Infrastructure
- Created separate `update_server/` project for version management service
- Flask-based REST API serving version information via `/api/version/<bot_name>`
- `versions.json` file stores version details for all bots
- Docker support with Dockerfile for containerized deployment
- Includes comprehensive README with deployment options

### New Files
- **update_checker.py** - Background module that checks for and notifies about updates

### Modified Files

#### bot.py
- Added version constants section at top for easy reference
- Added import for `update_checker` module
- Added `start_update_checker()` call in `main()` function
- User agent now uses version constants: `{BOT_NAME}/{BOT_VERSION}`

#### requirements.txt
- Added `requests` library for HTTP requests to update server

#### docker-compose.yml

- Volume mounts for persistent `versions.json` and log files

### Configuration
Update checker timing is configurable in `update_checker.py`:
- `UPDATE_CHECK_INTERVAL = 60` seconds (check frequency)
- `UPDATE_COOLDOWN = 86400` seconds (24 hours between notifications)

### How It Works
1. On startup, bot creates background thread running update checker
2. Every hour, thread polls `https://updts.slfhstd.uk/api/version/TestPostsBot`
3. If version differs from current `BOT_VERSION`, and 24 hours have passed since last notification, sends modmail
4. Modmail includes current version, available version, and changelog URL
5. Last notification timestamp stored in `DB/.last_update_check.txt`

---

## Version 2.0.0 - Trigger-Based Redesign

### Overview
Complete refactor of TestPostsBot to be a continuously running, trigger-based posting bot that responds to moderator commands via chat messages.

## Major Features Added

### 1. Trigger-Based Posting System
- Bot now runs continuously and listens for chat messages instead of executing once and exiting
- Moderators can trigger posts by sending chat messages containing configured trigger keywords
- Each trigger can post one or multiple posts in sequence
- Posts are made with 2-second delays between submissions to respect rate limiting

### 2. YAML Configuration Format
- **Changed from:** JSON configuration format
- **Changed to:** YAML configuration format for better readability and maintainability
- New config structure supports nested trigger/post relationships
- Example YAML config provided in `example_config.yaml`

### 3. Chat Message Handler
- Added chat message watcher that runs as a background thread
- Listens for messages sent to the bot account by moderators
- Implements special `reload-config` command for validating wiki config without making posts
- Validates that sender is a moderator before processing commands
- Tracks processed message IDs to prevent duplicate processing

### 4. Configuration Validation
- New `validate_config_from_wiki()` function validates YAML format and required structure
- Validates that config has a `posts` key with proper trigger/post structure
- Prevents bot from running with invalid configuration
- `reload-config` command provides feedback on config validity

### 5. Enhanced Logging
- Added prefixed logging for different operations: `[STARTUP]`, `[POSTING]`, `[CHAT WATCH]`
- Detailed debug output showing:
  - Messages received and who sent them
  - Moderator status verification
  - Trigger matching and posting status
  - Config validation results
  - Error messages with full tracebacks

## File Changes

### New Files
- **example_config.yaml** - Comprehensive example showing trigger and post configuration with multiple scenarios
- **.gitignore** - Added to exclude common files
- **example.env** - Environment configuration template

### Modified Files

#### bot.py
**Old Behavior:**
- Ran once, fetched posts from hardcoded config, made posts, and exited
- No continuous operation
- No trigger system

**New Behavior:**
- Runs continuously in infinite loop
- Spawns chat message watcher as background daemon thread
- Loads triggers from wiki config dynamically
- Only posts when a moderator sends a matching trigger
- Implements `reload-config` special command
- Validates config on startup
- Graceful shutdown on KeyboardInterrupt

**Key Functions:**
- `chat_message_watcher()` - Monitors inbox stream for moderator messages
- `make_posts()` - Posts to subreddit with rate limit delays
- `main()` - Continuous operation loop with thread management

#### config.py
**Old Behavior:**
- Fetched JSON config from wiki
- Simple error handling with fallback empty dict

**New Behavior:**
- Uses `yaml.safe_load()` instead of `json.loads()`
- `fetch_config_from_wiki()` - Fetches and parses YAML config
- `validate_config_from_wiki()` - Validates config format and required keys
- `get_trigger_posts()` - Retrieves posts associated with specific trigger
- Better error messages for YAML parsing failures

#### requirements.txt
**Added:**
- `PyYAML` - Required for YAML config parsing

#### README.md
**Complete Rewrite:**
- Added comprehensive documentation for trigger-based system
- Documented new YAML config format with examples
- Explained how moderators trigger posts
- Added setup instructions for environment variables
- Documented `reload-config` command
- Added Docker and standalone running instructions
- Clarified that only moderators can trigger posts

#### docker-compose.yml
**Updated:**
- Environment variables now leverage .env file
- Updated service configuration for continuous operation

#### Dockerfile
**Updated:**
- Adjusted for continuous operation mode
- Ensures proper signal handling for graceful shutdown

### Configuration Examples

**Old Format (JSON):**
```json
{
  "posts": [
    {"title": "Test Post 1", "body": "Body for post 1"},
    {"title": "Test Post 2", "body": "Body for post 2"}
  ]
}
```

**New Format (YAML):**
```yaml
posts:
  - trigger: "test"
    posts:
      - title: "Test Post 1"
        body: "Body for post 1"
      - title: "Test Post 2"
        body: "Body for post 2"

  - trigger: "weekly-thread"
    posts:
      - title: "Weekly Thread 1"
        body: "Content"
      - title: "Weekly Thread 2"
        body: "Content"
```

## Operational Changes

### Before (V1)
- Bot runs, posts hardcoded posts, exits
- Single execution cycle
- Config loaded once at startup
- No way to trigger posts without restarting bot

### After (V2)
- Bot runs continuously
- Moderators send chat messages to trigger posts
- Config is fetched fresh for each trigger (allows live updates)
- Special `reload-config` command validates configuration
- Background thread handles message monitoring
- Main thread keeps bot alive indefinitely

## Chat Commands

### Trigger Posts
Send chat message containing trigger keyword (e.g., "modtestposts", "weekly-thread")
- Bot fetches configured posts for that trigger
- Posts them to the subreddit in sequence
- Replies with confirmation of posts made

### Reload Config
Send chat message containing "reload-config"
- Bot validates wiki config YAML format
- Replies with success/failure status
- Useful for verifying config before using triggers

## Technical Improvements

1. **Concurrency:** Uses threading for background message monitoring while keeping main thread alive
2. **Deduplication:** Tracks processed message IDs in `DB/chat_wiki_requests.txt` to prevent duplicate processing
3. **Recovery:** Graceful error handling with continue on failures in message stream
4. **Validation:** Comprehensive config validation before any operations
5. **Logging:** Detailed logging for debugging and monitoring

## Compatibility Notes

- Requires `praw` and `PyYAML` packages
- PRAW version should support `inbox.stream()` method
- Reddit bot account must be moderator of target subreddit
- Reddit bot account must be added to chat conversations where triggers will be sent

## Upgrade Path from V1

1. Update wiki config from JSON to YAML format
2. Restructure config to use triggers (see `example_config.yaml`)
3. Redeploy bot with updated code
4. Send "reload-config" to verify new config works
5. Use trigger keywords to post instead of restarting bot

---

**Version:** 2.0  
**Date:** March 11, 2026  
**Status:** Production Ready