LightZirconite/Microsoft-Rewards-Bot
1
1
Fork 0
mirror of https://github.com/LightZirconite/Microsoft-Rewards-Bot.git synced 2026-01-09 17:06:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refactor documentation and add new features

Browse Source 
- Updated index.md to simplify structure and focus on task-oriented guides.
- Revised notifications.md to streamline setup instructions and improve clarity.
- Added report-error.js for structured error reporting to Discord.
- Introduced account-creation.md and configuration.md for detailed guidance on account setup and bot configuration.
- Created dashboard.md, docker.md, error-reporting.md, modes.md, running.md, scheduling.md, setup.md, troubleshooting.md, and update.md for comprehensive documentation on respective features and usage.
- Updated package-lock.json and package.json to include peer dependencies.
This commit is contained in:
LightZirconite
2025-12-06 13:13:20 +01:00
parent a149c54013
commit 64352fa306
22 changed files with 377 additions and 3942 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/account-creation.md Normal file
View File

@@ -0,0 +1,14 @@
# Account Creation Mode
## What it does
Creates new Microsoft accounts and prepares them for Rewards.
## How to use
1. Make sure you accept the risk of new accounts being flagged if used immediately.
2. Run `npm run creator` for prompts, or add `-y` plus a recovery email for faster setup.
3. Let new accounts rest for a few weeks before earning points.
## Example
```bash
npm run creator -- -y backup@example.com
```

188
docs/accounts.md
View File

@@ -1,188 +0,0 @@
# 👤 Accounts & 2FA Setup
**Add your Microsoft accounts with secure TOTP authentication**
---
## 📍 Quick Start
### Basic Setup (No 2FA)
**Edit** `src/accounts.json`:
```json
{
"accounts": [
{
"email": "your@email.com",
"password": "your_password",
"recoveryEmail": "backup@email.com"
}
]
}
```
> ℹ️ `recoveryEmail` is **optional but recommended**. It lets the bot verify Microsoft's masked hint during login and alert you if the recovery address ever changes. Simply leave it empty (`""`) if not needed.
**That's it!** Run `npm start` to test.
---
## 🔐 Add 2FA/TOTP (Recommended)
### Why Use TOTP?
- ✅ **Automated login** — No manual code entry
- ✅ **More secure** — Better than SMS
- ✅ **Works 24/7** — Ready for external schedulers
### How to Get Your TOTP Secret
1. **Open** https://account.live.com/proofs/Manage/additional (Security → Advanced security options → Additional security).
2. Enable two-step verification and click **Next** until you see the setup wizard.
3. Click the blue link **"Set up a different authenticator app"**.
4. On the next screen click **"I can't scan the bar code"** to reveal the Base32 secret.
5. Scan the QR with your preferred authenticator (Google Authenticator recommended to keep data separate from Microsoft) **and** copy the secret:
- The same secret can stay in your app and be saved in this file (multiple authenticators can share it).
6. Enter the 6-digit code in Microsoft’s wizard to finish pairing.
7. **Add the secret to** `accounts.json`:
```json
{
"accounts": [
{
"email": "your@email.com",
"password": "your_password",
"recoveryEmail": "backup@email.com",
"totp": "JBSWY3DPEHPK3PXP"
}
]
}
```
---
## 🚫 Skip the Recovery Email (Advanced)
If an account genuinely has no recovery address or you prefer not to provide it, simply leave the `recoveryEmail` field empty:
```json
{
"accounts": [
{
"email": "example@outlook.com",
"password": "strong_password",
"recoveryEmail": ""
}
]
}
```
> ℹ️ The bot will automatically skip recovery validation when this field is empty. A warning will be logged during startup, but the bot will function normally.
---
## 🎯 Multiple Accounts
```json
{
"accounts": [
{
"email": "account1@email.com",
"password": "password1",
"recoveryEmail": "backup1@email.com",
"totp": "SECRET1"
},
{
"email": "account2@email.com",
"password": "password2",
"recoveryEmail": "backup2@email.com",
"totp": "SECRET2"
}
]
}
```
---
## 🌐 Per-Account Proxy (Optional)
```json
{
"accounts": [
{
"email": "your@email.com",
"password": "password",
"recoveryEmail": "backup@email.com",
"totp": "",
"proxy": {
"proxyAxios": true,
"url": "proxy.example.com",
"port": 8080,
"username": "proxyuser",
"password": "proxypass"
}
}
]
}
```
→ **[Full Proxy Guide](./proxy.md)**
---
## 🔒 Environment Variables (Docker/CI)
### Option 1: File Path
```bash
export ACCOUNTS_FILE=/path/to/accounts.json
```
### Option 2: Inline JSON
```bash
export ACCOUNTS_JSON='{"accounts":[{"email":"test@example.com","password":"pass"}]}'
```
---
## 🛠️ Troubleshooting
| Problem | Solution |
|---------|----------|
| **"accounts.json not found"** | Create file or set `ACCOUNTS_FILE` env var |
| **"2FA prompt not auto-filled"** | Check TOTP secret is valid Base32 |
| **"Invalid TOTP"** | Verify system time is correct |
| **"Account locked"** | Manually unlock in Microsoft Account |
| **"Login timeout"** | Check internet connection, try proxy |
### 2FA Not Working?
1. **Check secret format** — Should be Base32 (only letters/numbers, no spaces)
2. **Verify system time** — Must be accurate (NTP sync)
3. **Test manually** — Use authenticator app to verify code works
4. **Remove backup codes** — Some security settings block TOTP
---
## 🔒 Security Tips
- 🔐 **Use strong passwords** — Unique for each account
- 🔑 **Enable TOTP** — More secure than SMS
- 📁 **Restrict file permissions** — `chmod 600 accounts.json` (Linux)
- 🔄 **Rotate passwords** — Change every 90 days
- 🚫 **Never commit** — Add `accounts.json` to `.gitignore`
---
## 📚 Next Steps
**TOTP setup?**
→ **[Security Guide](./security.md)** for best practices
**Ready for automation?**
→ **[External Scheduling](./schedule.md)**
**Need proxies?**
→ **[Proxy Guide](./proxy.md)**
---
**[← Back to Hub](./index.md)** | **[Getting Started](./getting-started.md)**

288
docs/build-system.md
View File

@@ -1,288 +0,0 @@
# Build System Documentation
## 📋 Overview
The Microsoft Rewards Bot uses a **clean, automated build system** that handles TypeScript compilation and browser installation automatically.
## 🚀 Quick Start
### First Time Setup
```bash
npm install
```
**This command does everything:**
- ✅ Installs all Node.js dependencies
- ✅ Compiles TypeScript to JavaScript
- ✅ Installs Chromium browser automatically
### Run the Bot
```bash
npm start
```
**No build step needed!** The bot is ready to run immediately after `npm install`.
## 📦 Available Commands
| Command | Description | Use When |
|---------|-------------|----------|
| `npm install` | **Complete setup** (deps + build + browser) | First time, after updates |
| `npm start` | **Run the bot** (production) | Normal usage |
| `npm run build` | Compile TypeScript + install browser | Manual rebuild needed |
| `npm run dev` | **Dev mode** (TypeScript directly, hot reload) | Development only |
| `npm run creator` | Account creation wizard | Creating new accounts |
| `npm run dashboard` | Web dashboard (production) | Remote monitoring |
| `npm run dashboard-dev` | Web dashboard (dev mode) | Dashboard development |
| `npm run typecheck` | Type checking only (no build) | Quick validation |
| `npm run test` | Run test suite | Development |
| `npm run clean` | Delete compiled files | Before fresh rebuild |
| `npm run kill-chrome` | Kill all Chrome processes | Cleanup after crashes |
## 🔄 Build Workflow (Automatic)
### When you run `npm install`:
```
1. npm installs dependencies
↓
2. postinstall hook triggers
↓
3. npm run build executes
↓
4. prebuild hook checks for Chromium
↓
5. If Chromium missing: npx playwright install chromium
↓
6. TypeScript compilation (tsc)
↓
7. postbuild hook shows success message
```
**Result:** Bot is ready to use!
### When you run `npm run build`:
```
1. prebuild hook checks for Chromium
↓
2. If missing: Install Chromium automatically
↓
3. Compile TypeScript (src/ → dist/)
↓
4. Show success message
```
### When you run `npm start`:
```
1. Run compiled JavaScript (dist/index.js)
↓
2. No build check (already done by npm install)
```
## 🐳 Docker Workflow
### Docker Build Process
```bash
npm run docker:build
```
**What happens:**
1. **Stage 1 (Builder):**
- Install all dependencies
- Build TypeScript
- Reinstall production-only dependencies
- Install Chromium Headless Shell
- Clean up build artifacts
2. **Stage 2 (Runtime):**
- Copy compiled code (`dist/`)
- Copy production dependencies (`node_modules/`)
- **Copy Chromium browser** (`node_modules/@playwright/`)
- Install minimal system libraries
- Configure cron for scheduling
### Docker Run
```bash
npm run docker:run
```
Or with Docker Compose:
```bash
cd docker
docker compose up -d
```
### Environment Variables (Docker)
| Variable | Default | Description |
|----------|---------|-------------|
| `PLAYWRIGHT_BROWSERS_PATH` | `0` | Use browsers in node_modules (required) |
| `FORCE_HEADLESS` | `1` | Run in headless mode (required for Docker) |
| `TZ` | `UTC` | Container timezone |
| `CRON_SCHEDULE` | **Required** | Cron schedule (e.g., `0 9 * * *`) |
| `RUN_ON_START` | `false` | Run immediately on container start |
| `SKIP_RANDOM_SLEEP` | `false` | Skip random delay before execution |
## 🔧 Development Workflow
### Hot Reload Development
```bash
npm run dev
```
- Runs TypeScript directly (no compilation needed)
- Auto-reloads on file changes
- Uses `-dev` flag (loads `accounts.dev.json` if it exists)
### Type Checking
```bash
npm run typecheck
```
- Validates TypeScript types without compiling
- Faster than full build
- Use before committing code
### Testing
```bash
npm run test
```
- Runs all unit tests in `tests/` directory
- Uses Node.js native test runner
### Clean Build
```bash
npm run clean
npm run build
```
- Deletes `dist/` folder
- Rebuilds everything from scratch
## 🛠️ Troubleshooting
### "Chromium not installed" Error
**Symptoms:**
```
[ERROR] DESKTOP [BROWSER] Chromium not installed. Run "npm run pre-build" or set AUTO_INSTALL_BROWSERS=1
```
**Solution:**
```bash
npx playwright install chromium --with-deps
```
**Or set environment variable:**
```bash
# Windows (PowerShell)
$env:AUTO_INSTALL_BROWSERS="1"
npm start
# Linux/Mac
export AUTO_INSTALL_BROWSERS=1
npm start
```
### Docker: "Chromium not installed" After First Run
**Root Cause:** Chromium browser files not copied from builder stage.
**Solution:** Rebuild Docker image with fixed Dockerfile:
```bash
docker build --no-cache -t microsoft-rewards-bot -f docker/Dockerfile .
```
The updated Dockerfile now includes:
```dockerfile
COPY --from=builder /usr/src/microsoft-rewards-bot/node_modules/@playwright ./node_modules/@playwright
```
### "Build not found" on Every `npm start`
**Root Cause:** Old version had unnecessary `prestart` hook that checked for build on every start.
**Solution:** Update to latest version. The `prestart` hook has been removed - build happens automatically during `npm install`.
### TypeScript Compilation Errors
**Check for missing dependencies:**
```bash
npm install
```
**Verify tsconfig.json is valid:**
```bash
npm run typecheck
```
**Clean rebuild:**
```bash
npm run clean
npm run build
```
## 📁 Directory Structure
```
Microsoft-Rewards-Bot/
├── src/ # TypeScript source code
│ ├── index.ts # Main entry point
│ ├── config.jsonc # User configuration
│ ├── accounts.jsonc # Account credentials (gitignored)
│ └── ...
├── dist/ # Compiled JavaScript (generated)
│ ├── index.js # Compiled entry point
│ └── ...
├── node_modules/ # Dependencies
│ └── @playwright/ # Chromium browser files
├── docker/ # Docker configuration
│ ├── Dockerfile # Multi-stage Docker build
│ ├── compose.yaml # Docker Compose config
│ ├── entrypoint.sh # Container initialization
│ ├── run_daily.sh # Daily execution script
│ └── crontab.template # Cron schedule template
├── package.json # Dependencies + scripts
├── tsconfig.json # TypeScript configuration
└── README.md # Main documentation
```
## 🔐 Environment Variables
### General
| Variable | Description | Example |
|----------|-------------|---------|
| `NODE_ENV` | Runtime environment | `production`, `development` |
| `DEBUG_REWARDS_VERBOSE` | Enable verbose logging | `1` |
| `FORCE_HEADLESS` | Force headless browser | `1` |
| `AUTO_INSTALL_BROWSERS` | Auto-install Chromium if missing | `1` |
| `SKIP_RANDOM_SLEEP` | Skip random delays | `true` |
### Docker-Specific
| Variable | Description | Required |
|----------|-------------|----------|
| `CRON_SCHEDULE` | Cron expression for scheduling | ✅ Yes |
| `TZ` | Timezone (e.g., `America/New_York`) | ❌ No (default: UTC) |
| `RUN_ON_START` | Run immediately on container start | ❌ No (default: false) |
| `PLAYWRIGHT_BROWSERS_PATH` | Browser location (must be `0`) | ✅ Yes (set in Dockerfile) |
## 📚 Related Documentation
- **Getting Started:** [docs/getting-started.md](getting-started.md)
- **Configuration:** [docs/config.md](config.md) (via inline comments in `src/config.jsonc`)
- **Accounts:** [docs/accounts.md](accounts.md)
- **Scheduling:** [src/scheduler/README.md](../src/scheduler/README.md)
- **Docker Deployment:** [docker/README.md](../docker/README.md) (if exists)
## ✅ Best Practices
1. **Always use `npm install` for initial setup** - It does everything automatically
2. **Use `npm start` for normal runs** - No manual build needed
3. **Use `npm run dev` for development** - Faster iteration with hot reload
4. **Clean rebuild if weird errors occur** - `npm run clean && npm run build`
5. **Docker users: Rebuild image after Dockerfile changes** - `docker build --no-cache`
6. **Set `AUTO_INSTALL_BROWSERS=1` if Chromium issues persist** - Automatic fallback
## 🆘 Getting Help
- **Discord:** https://discord.gg/k5uHkx9mne
- **GitHub Issues:** https://github.com/LightZirconite/Microsoft-Rewards-Bot/issues
- **Documentation:** [docs/index.md](index.md)
---
**Last Updated:** November 2025
**Applies To:** v2.56.7+

389
docs/commands.md
View File

@@ -1,389 +0,0 @@
# NPM Commands Reference
This guide explains all available npm commands and when to use them.
## ⚡ **NEW - Ultimate Command** (v2.60.0)
### `npm run go` ⭐
**THE simplest way to run the bot** - Does EVERYTHING automatically!
```bash
npm install # Install dependencies (first time only)
npm run go # Does EVERYTHING else!
```
**What it does:**
1. ✅ Checks if Chromium browser is installed → Installs if missing
2. ✅ Checks if project is built (`dist/`) → Builds if missing
3. ✅ Starts the bot immediately
**When to use:**
- **First time setup** (after `npm install`)
- **After git pull** (ensures browser + build are ready)
- **Daily use** (simplest command)
- **When unsure** (it checks everything!)
---
## 🚀 Essential Commands
### `npm start`
**Start the bot** - Use this to run the Microsoft Rewards Bot after setup.
```bash
npm start
```
**What it does:**
- Runs the compiled JavaScript from `dist/index.js`
- Checks for automatic updates (if enabled)
- Executes reward earning tasks
- Fastest way to run the bot
**When to use:**
- Daily bot execution
- After setup is complete
- When you want to earn points
---
### `npm run setup`
**First-time installation** - Run this only once when setting up the project.
```bash
npm run setup
```
**What it does:**
1. Creates `accounts.jsonc` from template
2. Guides you through account configuration
3. Installs dependencies (`npm install`)
4. Builds TypeScript (`npm run build`)
5. Installs Playwright browsers
**When to use:**
- First time installing the bot
- After fresh git clone
- To reconfigure accounts
**Important:** This does NOT start the bot automatically. After setup, run `npm start`.
---
## 🔨 Development Commands
### `npm run build`
**Build TypeScript to JavaScript** - Compiles the project.
```bash
npm run build
```
**What it does:**
- Compiles `src/*.ts` files to `dist/*.js`
- Generates source maps for debugging
- Required before running `npm start`
**When to use:**
- After modifying TypeScript source code
- Before starting the bot with `npm start`
- After pulling updates from git
---
### `npm run dev`
**Development mode** - Run TypeScript directly without building.
```bash
npm run dev
```
**What it does:**
- Runs TypeScript files directly with `ts-node`
- No build step required
- Slower but convenient for development
- Includes `-dev` flag for debug features
**When to use:**
- During development/testing
- When making code changes
- Quick testing without full build
---
### `npm run ts-start`
**TypeScript direct execution** - Like `dev` but without debug flags.
```bash
npm run ts-start
```
**When to use:**
- Alternative to `npm run dev`
- Running TypeScript without full build
---
## 🧹 Maintenance Commands
### `npm run clean`
**Remove build artifacts** - Deletes the `dist` folder.
```bash
npm run clean
```
**When to use:**
- Before fresh rebuild
- To clear stale compiled code
- Troubleshooting build issues
---
### `npm run install-deps`
**Install all dependencies** - Fresh installation of dependencies and browsers.
```bash
npm run install-deps
```
**What it does:**
- Runs `npm install` to install Node.js packages
- Installs Playwright Chromium browser
**When to use:**
- After deleting `node_modules`
- Setting up on new machine
- Troubleshooting dependency issues
---
### `npm run typecheck`
**Check TypeScript types** - Validates code without building.
```bash
npm run typecheck
```
**When to use:**
- Checking for type errors
- Before committing code
- Part of CI/CD pipeline
---
## 🧪 Testing & Quality
### `npm test`
**Run unit tests** - Execute test suite.
```bash
npm test
```
**When to use:**
- Verifying code changes
- Before submitting pull requests
- Continuous integration
---
### `npm run lint`
**Check code style** - ESLint validation.
```bash
npm run lint
```
**When to use:**
- Checking code formatting
- Before commits
- Maintaining code quality
---
## 📊 Dashboard Commands
### `npm run dashboard`
**Start web dashboard only** - Web interface without bot execution.
```bash
npm run dashboard
```
**What it does:**
- Launches web interface on http://localhost:3000
- Provides monitoring and control panel
- Does NOT start reward earning
**When to use:**
- Monitoring bot status
- Viewing logs remotely
- Configuring settings via UI
---
### `npm run dashboard-dev`
**Dashboard development mode** - TypeScript version of dashboard.
```bash
npm run dashboard-dev
```
**When to use:**
- Dashboard development/testing
- Quick dashboard testing without build
---
## 🤖 Account Creation
### `npm run creator`
**Account creation wizard** - Create new Microsoft accounts.
```bash
# Interactive mode
npm run creator
# With auto-accept and recovery email (copy-paste URL directly from Microsoft)
npm run creator -- -y backup@gmail.com "https://rewards.bing.com/welcome?rh=YOUR_CODE"
```
**When to use:**
- Creating new Microsoft accounts
- Bulk account creation
- Testing account setup
---
## 🐳 Docker Commands
### `npm run create-docker`
**Build Docker image** - Create containerized version.
```bash
npm run create-docker
```
**When to use:**
- Deploying with Docker
- Creating container image
- Testing Docker setup
---
## 🆘 Troubleshooting Commands
### `npm run kill-chrome-win` (Windows only)
**Force close Chrome browsers** - Kill stuck browser processes.
```bash
npm run kill-chrome-win
```
**When to use:**
- Browser processes stuck
- Windows only
- Before restarting bot
---
## 📝 Command Comparison
| Command | Speed | Purpose | When to Use |
|---------|-------|---------|-------------|
| `npm start` | ⚡ Fast | Run bot | Daily use |
| `npm run dev` | 🐌 Slow | Development | Code changes |
| `npm run build` | ⏱️ Medium | Compile TS | Before start |
| `npm run setup` | ⏱️ Medium | First install | Once only |
---
## Common Workflows
### First-Time Setup
```bash
# 1. Run setup wizard
npm run setup
# 2. Start the bot
npm start
```
### Daily Usage
```bash
npm start
```
### After Code Changes
```bash
# Method 1: Build then run (faster)
npm run build
npm start
# Method 2: Direct run (slower)
npm run dev
```
### After Pulling Updates
```bash
# If dependencies changed
npm install
# Rebuild
npm run build
# Start bot
npm start
```
### Troubleshooting
```bash
# Clean install
npm run clean
rm -rf node_modules package-lock.json
npm run install-deps
# Rebuild
npm run build
# Test
npm start
```
---
## ❓ FAQ
### Why does `npm run start` trigger updates?
The bot automatically checks for updates on startup (configurable in `config.jsonc`). To disable:
```jsonc
{
"update": {
"enabled": false
}
}
```
### What's the difference between `npm start` and `npm run start`?
**No functional difference** - both run the same command. `npm start` is a shorthand for `npm run start`.
### Should I use `npm start` or `npm run dev`?
- **Production/Daily use:** `npm start` (faster)
- **Development:** `npm run dev` (no build needed)
### How do I completely reset the project?
```bash
npm run clean
rm -rf node_modules package-lock.json dist
npm run setup
```
---
## Need Help?
- **Getting Started:** [docs/getting-started.md](getting-started.md)
- **Configuration:** [docs/config.md](config.md)
- **Troubleshooting:** [docs/troubleshooting.md](troubleshooting.md)
- **Discord:** https://discord.gg/k5uHkx9mne

23
docs/configuration.md Normal file
View File

@@ -0,0 +1,23 @@
# Configuration
## What it does
Controls how the bot behaves through `src/config.jsonc`.
## How to use
- Open `src/config.jsonc` and edit only the fields you need.
- Keep `humanization.enabled` true to mimic real usage.
- Adjust `workers` to enable or disable search, quizzes, and promotions.
- Set `scheduling.enabled` to automate runs.
## Example
```jsonc
{
"humanization": { "enabled": true },
"workers": {
"doDesktopSearch": true,
"doMobileSearch": true,
"doDailySet": true
},
"scheduling": { "enabled": false }
}
```

14
docs/dashboard.md Normal file
View File

@@ -0,0 +1,14 @@
# Dashboard
## What it does
Shows live status and logs in a simple web page.
## How to use
1. Run `npm run dashboard`.
2. Open http://localhost:3000 in your browser.
3. Stop the dashboard with Ctrl+C when finished.
## Example
```bash
npm run dashboard
```

482
docs/docker-deployment.md
View File

@@ -1,482 +0,0 @@
# Docker Deployment Guide
Complete guide for containerized deployment with built-in scheduling.
## 📂 Docker File Structure
```
Microsoft-Rewards-Bot/
├── docker/ # All Docker-related files
│ ├── Dockerfile # Multi-stage build configuration
│ ├── compose.yaml # Service definition
│ ├── entrypoint.sh # Container initialization
│ ├── run_daily.sh # Daily execution wrapper + locking
│ └── crontab.template # Cron job template
├── src/
│ ├── accounts.jsonc # Your accounts (volume mount)
│ └── config.jsonc # Bot configuration (volume mount)
└── package.json # Build scripts
```
**Important:** All Docker files are in the `docker/` folder, but the build context is the **project root** (to access `src/`, `package.json`, etc.)
---
## 🚀 Quick Start
### 1. Build the Image
**Option A: Using npm script (recommended)**
```bash
# From project root
npm run docker:build
```
**Option B: Direct Docker command**
```bash
# From project root
docker build -f docker/Dockerfile -t microsoft-rewards-bot .
```
**Why from root?** The Dockerfile needs access to `src/`, `package.json`, `tsconfig.json`. Docker can't copy files outside the build context.
### 2. Configure Environment
Edit `docker/compose.yaml`:
```yaml
environment:
TZ: "America/New_York" # Your timezone
CRON_SCHEDULE: "0 9 * * *" # Daily at 9 AM
RUN_ON_START: "true" # Run immediately on start
```
### 3. Start the Container
**Option A: Using npm script**
```bash
npm run docker:compose
```
**Option B: Direct docker compose command**
```bash
docker compose -f docker/compose.yaml up -d
```
**Note:** Volumes in `compose.yaml` use relative paths from `docker/`:
- `./src/` → `docker/../src/` (goes to project root)
- `./sessions/` → `docker/sessions/` (local to docker folder)
## 📋 Configuration Files
The container needs access to your configuration files via volume mounts:
```yaml
volumes:
# Read-only mounts for configuration (prevents accidental container edits)
- ../src/accounts.jsonc:/usr/src/microsoft-rewards-bot/accounts.jsonc:ro
- ../src/config.jsonc:/usr/src/microsoft-rewards-bot/config.jsonc:ro
# Read-write mount for persistent login sessions
- ../sessions:/usr/src/microsoft-rewards-bot/sessions
```
**Paths explained:**
- `../src/accounts.jsonc` = `docker/../src/accounts.jsonc` (relative from compose.yaml location, goes to project root)
- `../sessions` = `docker/../sessions/` (project root sessions folder)
**Before starting:**
1. Create `src/accounts.jsonc` (copy from `src/accounts.example.jsonc`)
2. Edit `src/config.jsonc` with your settings
3. (Optional) Create `sessions/` directory at project root for persistent login
---
## 🏗️ Architecture & Build Process
### Two-Stage Docker Build
**Stage 1: Builder**
```dockerfile
FROM node:22-slim AS builder
# 1. Install dependencies + dev dependencies
# 2. Compile TypeScript → JavaScript (dist/)
# 3. Install Playwright Chromium
# 4. Remove dev dependencies (keep only production)
```
**Stage 2: Runtime**
```dockerfile
FROM node:22-slim AS runtime
# 1. Install minimal system libraries for Chromium
# 2. Copy compiled code + dependencies from builder
# 3. Copy runtime scripts (entrypoint.sh, run_daily.sh)
# 4. Configure cron daemon
```
**Why two stages?**
- Smaller final image (~800 MB vs 1.5 GB)
- No build tools in production
- Security: no dev dependencies
### Build Context Explained
```bash
# ❌ WRONG: Building from docker/ folder
cd docker
docker build -t bot .
# Error: Cannot find package.json, src/, etc.
# ✅ CORRECT: Build from root, specify Dockerfile location
cd /path/to/Microsoft-Rewards-Bot
docker build -f docker/Dockerfile -t bot .
# Success: Access to all project files
```
**The Dockerfile copies files relative to project root:**
```dockerfile
COPY package.json tsconfig.json ./ # From project root
COPY src/ ./src/ # From project root
COPY docker/run_daily.sh ./docker/ # Subfolder
```
---
## 🔧 Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `CRON_SCHEDULE` | ✅ Yes | N/A | Cron expression (e.g., `0 9 * * *`) |
| `TZ` | ❌ No | `UTC` | Timezone (e.g., `America/New_York`) |
| `RUN_ON_START` | ❌ No | `false` | Run immediately on container start |
| `SKIP_RANDOM_SLEEP` | ❌ No | `false` | Skip random delay before execution |
| `MIN_SLEEP_MINUTES` | ❌ No | `5` | Minimum random delay (minutes) |
| `MAX_SLEEP_MINUTES` | ❌ No | `50` | Maximum random delay (minutes) |
| `STUCK_PROCESS_TIMEOUT_HOURS` | ❌ No | `8` | Kill stuck processes after N hours |
| `PLAYWRIGHT_BROWSERS_PATH` | 🔒 Fixed | `0` | Use browsers in node_modules (DO NOT CHANGE) |
| `FORCE_HEADLESS` | 🔒 Fixed | `1` | Headless mode (DO NOT CHANGE) |
| `NODE_ENV` | 🔒 Fixed | `production` | Production environment (DO NOT CHANGE) |
## 📅 Scheduling Examples
Use [crontab.guru](https://crontab.guru) to create cron expressions.
| Schedule | Cron Expression | Description |
|----------|----------------|-------------|
| Daily at 9 AM | `0 9 * * *` | Once per day |
| Every 6 hours | `0 */6 * * *` | 4 times daily |
| Twice daily (9 AM, 9 PM) | `0 9,21 * * *` | Morning & evening |
| Weekdays at 8 AM | `0 8 * * 1-5` | Monday-Friday only |
| Random time (7-8 AM) | `0 7 * * *` + random sleep | Use `MIN_SLEEP_MINUTES`/`MAX_SLEEP_MINUTES` |
**Example with Random Delay:**
```yaml
environment:
CRON_SCHEDULE: "0 7 * * *" # Start scheduling at 7 AM
MIN_SLEEP_MINUTES: "0" # No minimum delay
MAX_SLEEP_MINUTES: "60" # Up to 1 hour delay
# Result: Runs between 7:00 AM - 8:00 AM randomly
```
## 🔍 Monitoring
### View Logs
```bash
docker logs -f microsoft-rewards-bot
```
### Check Container Status
```bash
docker ps -a | grep microsoft-rewards-bot
```
### Health Check
```bash
docker inspect microsoft-rewards-bot --format='{{.State.Health.Status}}'
```
Expected output: `healthy`
### Execute Commands Inside Container
```bash
# Check cron status
docker exec microsoft-rewards-bot crontab -l
# Check timezone
docker exec microsoft-rewards-bot date
# List running processes
docker exec microsoft-rewards-bot ps aux
```
## 🛠️ Troubleshooting
### ❌ Build Error: "Cannot find module 'package.json'"
**Cause:** Wrong build context - building from `docker/` instead of project root.
**Solution:**
```bash
# ❌ WRONG
cd docker
docker build -t bot .
# ✅ CORRECT (from project root)
docker build -f docker/Dockerfile -t bot .
# Or use npm script
npm run docker:build
```
### ❌ Build Error: "COPY failed: file not found: docker/run_daily.sh"
**Cause:** `.dockerignore` file excludes `docker/` folder.
**Solution:** Check `.dockerignore` - it should NOT contain `docker/`:
```ignore
# ❌ BAD
docker/
# ✅ GOOD (current config)
scripts/installer/
```
### ❌ "Chromium not installed" After First Run
**Symptoms:**
- Bot works on first run
- Fails on subsequent scheduled runs with "Chromium not installed"
**Root Cause:**
Fixed in v2.56.7+! Chromium browser files are now copied correctly from builder stage.
**Solution:**
```bash
# Rebuild with latest Dockerfile (includes fix)
npm run docker:build
docker compose -f docker/compose.yaml down
docker compose -f docker/compose.yaml up -d
```
**Verification:**
Check that Chromium is present in the container:
```bash
docker exec microsoft-rewards-bot ls -la /usr/src/microsoft-rewards-bot/node_modules/@playwright/
```
You should see `browser-chromium/` directory.
### ❌ Container Exits Immediately
**Check logs:**
```bash
docker logs microsoft-rewards-bot
```
**Common causes:**
1. **Missing CRON_SCHEDULE:** Set environment variable in compose.yaml
```yaml
environment:
CRON_SCHEDULE: "0 9 * * *" # Required!
```
2. **Invalid cron expression:** Validate at https://crontab.guru
3. **Script not executable:** Dockerfile should handle this automatically
```dockerfile
COPY --chmod=755 docker/entrypoint.sh /usr/local/bin/entrypoint.sh
```
**Fix:**
```bash
# Update compose.yaml with correct CRON_SCHEDULE
docker compose -f docker/compose.yaml down
docker compose -f docker/compose.yaml up -d
```
### ❌ "Permission denied: entrypoint.sh"
**Cause:** Script not executable or Windows CRLF line endings.
**Solution:** The Dockerfile handles both automatically:
```dockerfile
COPY --chmod=755 docker/entrypoint.sh /usr/local/bin/entrypoint.sh
RUN sed -i 's/\r$//' /usr/local/bin/entrypoint.sh # Convert CRLF → LF
```
If still failing, manually fix line endings:
```bash
# Linux/Mac
dos2unix docker/entrypoint.sh docker/run_daily.sh
# Or with sed
sed -i 's/\r$//' docker/entrypoint.sh
sed -i 's/\r$//' docker/run_daily.sh
```
### ❌ Volumes Not Mounting
### ❌ Volumes Not Mounting
**Check if files exist:**
```bash
# From docker/ folder
ls -la ../src/accounts.jsonc ../src/config.jsonc
# Or from project root
ls -la src/accounts.jsonc src/config.jsonc
```
**Verify volume paths in running container:**
```bash
docker inspect microsoft-rewards-bot | grep -A 10 Mounts
```
**Fix paths in compose.yaml:**
```yaml
# Paths are relative to compose.yaml location (docker/)
volumes:
- ../src/accounts.jsonc:/usr/src/microsoft-rewards-bot/accounts.jsonc:ro
# This resolves to: docker/../src/accounts.jsonc (project root)
# Note: Files mount to project root, NOT dist/ (Load.ts searches multiple locations)
```
---
## 📚 Complete File Reference
### `docker/Dockerfile`
Multi-stage build configuration:
- **Builder stage:** Compiles TypeScript, installs Playwright
- **Runtime stage:** Minimal image with only production dependencies
### `docker/compose.yaml`
Service definition with:
- Build context (points to project root)
- Volume mounts (configuration files)
- Environment variables (scheduling, timezone)
- Resource limits (CPU, memory)
- Health checks (cron daemon monitoring)
### `docker/entrypoint.sh`
Container initialization script:
1. Configures timezone from `TZ` env var
2. Validates `CRON_SCHEDULE` is set
3. Optionally runs bot immediately (`RUN_ON_START=true`)
4. Templates cron job with environment variables
5. Starts cron daemon in foreground
### `docker/run_daily.sh`
Daily execution wrapper:
- File-based locking (prevents concurrent runs)
- Self-healing lockfile validation
- Random sleep delay (anti-detection)
- Stuck process killer (timeout after N hours)
- Executes `npm start`
### `docker/crontab.template`
Cron job template with variable interpolation:
```bash
${CRON_SCHEDULE} TZ=${TZ} /bin/bash /usr/src/microsoft-rewards-bot/docker/run_daily.sh >> /proc/1/fd/1 2>&1
```
Expanded by `entrypoint.sh` using `envsubst`.
---
## 🎯 Build & Deployment Checklist
### Pre-Build Checklist
- [ ] Files exist: `src/accounts.jsonc`, `src/config.jsonc`
- [ ] Docker installed and running
- [ ] At project root (not in `docker/` folder)
- [ ] `.dockerignore` does NOT exclude `docker/` folder
### Build Steps
```bash
# 1. Clean previous builds (optional)
docker rmi microsoft-rewards-bot
# 2. Build image
npm run docker:build
# Or: docker build -f docker/Dockerfile -t microsoft-rewards-bot .
# 3. Verify image created
docker images | grep microsoft-rewards-bot
```
### Deployment Steps
```bash
# 1. Configure compose.yaml
# - Set CRON_SCHEDULE (required)
# - Set TZ (optional, default UTC)
# - Set RUN_ON_START (optional, default false)
# 2. Start container
npm run docker:compose
# Or: docker compose -f docker/compose.yaml up -d
# 3. Verify running
docker ps | grep microsoft-rewards-bot
# 4. Check logs
docker logs -f microsoft-rewards-bot
# 5. Verify health
docker inspect microsoft-rewards-bot --format='{{.State.Health.Status}}'
```
---
## 🔍 Debugging Commands
### Check Build Context
```bash
# List files Docker can see during build
docker build -f docker/Dockerfile -t test . --progress=plain 2>&1 | grep "COPY"
```
### Inspect Running Container
```bash
# Shell access
docker exec -it microsoft-rewards-bot bash
# Check environment variables
docker exec microsoft-rewards-bot env
# Check cron jobs
docker exec microsoft-rewards-bot crontab -l
# Check timezone
docker exec microsoft-rewards-bot date
# Check Playwright browsers
docker exec microsoft-rewards-bot ls -la node_modules/@playwright/
# Check running processes
docker exec microsoft-rewards-bot ps aux
```
### Test Scripts Manually
```bash
# Test entrypoint
docker exec microsoft-rewards-bot /usr/local/bin/entrypoint.sh
# Test run_daily (bypass lock)
docker exec microsoft-rewards-bot bash -c "rm -f /tmp/run_daily.lock && docker/run_daily.sh"
# Test bot directly
docker exec microsoft-rewards-bot npm start
```
---
## 📖 Additional Resources
- **Build System:** [docs/build-system.md](build-system.md)
- **Scheduling:** [src/scheduler/README.md](../src/scheduler/README.md)
- **Configuration:** [src/config.jsonc](../src/config.jsonc) (inline comments)
- **Accounts:** [docs/accounts.md](accounts.md)
---
**Last Updated:** November 2025
**Applies To:** v2.56.7+

14
docs/docker.md Normal file
View File

@@ -0,0 +1,14 @@
# Docker
## What it does
Runs the bot in a container with bundled scheduling and browser setup.
## How to use
- Ensure `src/accounts.jsonc` and `src/config.jsonc` are present before starting.
- Run `npm run docker:compose` to build and start the container.
- View logs with `docker logs -f microsoft-rewards-bot` or the compose service name.
## Example
```bash
npm run docker:compose
```

16
docs/error-reporting.md Normal file
View File

@@ -0,0 +1,16 @@
# Error Reporting API
## What it does
Accepts structured error reports and forwards them to Discord in a clean format.
## How to use
- Set `DISCORD_WEBHOOK_URL` in your environment.
- Send a POST request to `/api/report-error` with JSON that includes at least `error`.
- Optional fields: `summary`, `type`, `metadata` (object), `environment` (string or object with `name`).
## Example
```bash
curl -X POST https://your-deployment.vercel.app/api/report-error \
-H "Content-Type: application/json" \
-d '{"error":"Search job failed","type":"search","metadata":{"account":"user@contoso.com"}}'
```

1512
docs/getting-started.md
View File

File diff suppressed because it is too large Load Diff

231
docs/index.md
View File

@@ -1,215 +1,16 @@
<div align="center"><div align="center">
<img src="../assets/logo.png" alt="Microsoft Rewards Bot Logo" width="150"/># 📚 Documentation
# 📚 Documentation Hub**Complete guide for Microsoft Rewards Bot**
**Complete guides for Microsoft Rewards Bot**[← Back to Main](../README.md)
[← Back to Main](../README.md)</div>
</div>---
---## 🚀 Quick Start (3 Steps)
## 🚀 Getting Started1. **[Setup Accounts](accounts.md)** — Add credentials + 2FA
2. **[Configure Bot](config.md)** — Essential settings
**New to the bot?** Start with these guides in order:3. **[Schedule Runs](schedule.md)** — Use OS-level automation
| Step | Guide | What You'll Learn |**Done!** The bot will run automatically.
|------|-------|-------------------|
| **1** | **[📘 Getting Started](getting-started.md)** | Installation, account setup, first run |---
| **2** | **[👤 Accounts & 2FA](accounts.md)** | Add accounts, enable TOTP authentication |
| **3** | **[⚙️ Configuration](config.md)** | Customize bot behavior and features |## ✨ Feature Guides
| **4** | **[⏰ Scheduling](schedule.md)** | Automate daily runs with cron/Task Scheduler |
| Feature | Description |
**That's all you need to get started!** The guides above cover everything for basic usage.|---------|-------------|
| **[Configuration](config.md)** | All settings explained |
---| **[External Scheduling](schedule.md)** | Automate with cron or Task Scheduler |
| **[Humanization](humanization.md)** | Anti-detection system |
## 📖 Feature Guides| **[Webhooks](conclusionwebhook.md)** | Discord notifications |
| **[Error Reporting](ERROR_REPORTING.md)** | 🆕 Automatic error reporting |
Explore advanced features and customization options:| **[NTFY Alerts](ntfy.md)** | Mobile push notifications |
| **[Proxy Setup](proxy.md)** | IP rotation (optional) |
### Core Features
| Guide | Description |
|-------|-------------|
| **[🔔 Notifications](notifications.md)** | Discord webhooks and mobile push alerts |
| **[📊 Dashboard](../src/dashboard/README.md)** | Web interface for monitoring and control |
| **[🌐 Proxy Setup](proxy.md)** | Configure proxies for privacy |
| **[🤖 Humanization](humanization.md)** | Anti-detection and natural behavior patterns |
### Deployment
| Guide | Description |
|-------|-------------|
| **[🐳 Docker](docker-deployment.md)** | Containerized deployment with Docker Compose |
| **[☁️ Cloud Deployment](cloud-deployment.md)** | Deploy to VPS, Raspberry Pi, or cloud services |**Need help?** → [Discord Community](https://discord.gg/k5uHkx9mne)
### Advanced---
| Guide | Description |[← Back to Main](../README.md)
|-------|-------------|
| **[🔧 Advanced Configuration](advanced-config.md)** | Power user settings and optimization |
| **[🛡️ Security Best Practices](security.md)** | Account protection and risk management |
---
## 🆕 Account Creator
**Create new Microsoft accounts with the built-in account creator:**
| Guide | Description |
|-------|-------------|
| **[🎯 Account Creator Guide](../src/account-creation/README.md)** | Create accounts with 2FA and referral links |
| **[💰 Referral System](referrals.md)** | Earn 7,500 points/month per referral |
**Quick command:**
```bash
npm run creator -- -y backup@gmail.com "https://rewards.bing.com/welcome?rh=YOUR_CODE"
```
---
## 🆘 Help & Troubleshooting
Having issues? Check these resources:
### Common Issues
| Problem | Solution |
|---------|----------|
| **Bot not starting** | [Troubleshooting Guide](troubleshooting.md) |
| **Login failures** | [Accounts & 2FA Setup](accounts.md#troubleshooting) |
| **Account banned** | [Security Guide](security.md) |
| **Configuration errors** | [Config Reference](config.md) |
### Support Resources
- 💬 **[Discord Community](https://discord.gg/k5uHkx9mne)** — Get help from the community
- 🐛 **[GitHub Issues](https://github.com/LightZirconite/Microsoft-Rewards-Bot/issues)** — Report bugs
- 📖 **[FAQ](FAQ.md)** — Frequently asked questions
- 🔍 **[Diagnostics Guide](diagnostics.md)** — Debug and capture logs
---
## 📚 Reference Documentation
Technical references and detailed information:
### Configuration
| Document | Description |
|----------|-------------|
| **[Config Reference](config.md)** | Complete `config.jsonc` options |
| **[Accounts Reference](accounts.md)** | Complete `accounts.jsonc` schema |
| **[Environment Variables](environment-variables.md)** | Available env vars for CI/Docker |
### Technical
| Document | Description |
|----------|-------------|
| **[API Documentation](../src/dashboard/README.md)** | Dashboard REST API endpoints |
| **[Error Reporting](ERROR_REPORTING.md)** | Automatic error reporting system |
| **[Changelog](../CHANGELOG.md)** | Version history and changes |
---
## 🎓 Guides by Topic
### For Beginners
1. [Getting Started](getting-started.md) — Start here!
2. [Accounts & 2FA](accounts.md) — Setup your accounts
3. [First Run](getting-started.md#-first-run) — Test the bot
4. [Scheduling](schedule.md) — Automate daily runs
### For Raspberry Pi Users
1. [Getting Started](getting-started.md) — Installation steps
2. [Scheduling](schedule.md) — Setup cron for daily runs
3. [Notifications](notifications.md) — Get mobile alerts
4. [Cloud Deployment](cloud-deployment.md) — Run 24/7
### For Docker Users
1. [Docker Guide](docker-deployment.md) — Setup Docker Compose
2. [Environment Variables](environment-variables.md) — Configure via env vars
3. [Notifications](notifications.md) — Monitor container runs
### For Multiple Accounts
1. [Accounts & 2FA](accounts.md) — Manage multiple accounts
2. [Proxy Setup](proxy.md) — Use different IPs per account
3. [Advanced Config](advanced-config.md) — Parallel execution
4. [Referrals](referrals.md) — Earn bonus points
---
## 🔗 External Resources
- **[Microsoft Rewards](https://rewards.bing.com/)** — Official Microsoft Rewards site
- **[Playwright Docs](https://playwright.dev/)** — Browser automation framework
- **[Node.js](https://nodejs.org/)** — JavaScript runtime
- **[TypeScript](https://www.typescriptlang.org/)** — Programming language
---
## 🤝 Contributing
Want to help improve the bot?
- 📖 **[Contributing Guide](../CONTRIBUTING.md)** — How to contribute
- 🐛 **[Report Bugs](https://github.com/LightZirconite/Microsoft-Rewards-Bot/issues)** — Found an issue?
- 💡 **[Feature Requests](https://github.com/LightZirconite/Microsoft-Rewards-Bot/issues)** — Suggest new features
- 📝 **[Improve Docs](https://github.com/LightZirconite/Microsoft-Rewards-Bot/tree/main/docs)** — Help with documentation
---
<div align="center">
**Need help?** [Join our Discord](https://discord.gg/k5uHkx9mne)
[← Back to Main](../README.md)
</div>
# Microsoft Rewards Bot Docs
This folder contains short, task-focused guides. Pick what you need and keep runs simple.
- `setup.md` — prerequisites and preparing account files.
- `running.md` — commands to start the bot.
- `modes.md` — what each mode does and when to use it.
- `configuration.md` — adjust the core settings file.
- `account-creation.md` — create new accounts safely.
- `dashboard.md` — view progress in the web panel.
- `scheduling.md` — automate runs on a schedule.
- `notifications.md` — send alerts to Discord or other webhooks.
- `error-reporting.md` — send structured error reports to Discord.
- `docker.md` — run the bot in a container.
- `update.md` — keep the project up to date.
- `troubleshooting.md` — quick fixes for common issues.

16
docs/modes.md Normal file
View File

@@ -0,0 +1,16 @@
# Modes
## What it does
Lists the main modes and when to pick them.
## How to use
- **Default** — run daily tasks once: `npm start`.
- **Dashboard** — view progress in a web panel: `npm run dashboard` then open http://localhost:3000.
- **Dev** — quick restarts while editing: `npm run dev`.
- **Account creation** — create new accounts cautiously: `npm run creator`.
- **Docker** — containerized run with scheduling: `npm run docker:compose`.
## Example
```bash
npm run dashboard
```

363
docs/notifications.md
View File

@@ -1,358 +1,15 @@
# 🔔 Notifications
# Notifications
**Get alerts when the bot completes its run**
## What it does
Sends run summaries and issues to your preferred webhook.
[← Back to Documentation](index.md)
## How to use
- Set `DISCORD_WEBHOOK_URL` in your environment for Discord alerts.
- Keep `humanization.enabled` true to avoid unsafe behavior in production.
- Start the bot normally; alerts send automatically when configured.
---
## 📋 Table of Contents
- [Discord Webhooks](#-discord-webhooks)
- [NTFY Mobile Alerts](#-ntfy-mobile-alerts)
- [Comparison](#-comparison)
- [Examples](#-examples)
---
## 💬 Discord Webhooks
Get detailed run summaries sent to your Discord server.
### Setup
#### 1. Create Webhook in Discord
1. Open your Discord server
2. Go to **Server Settings** → **Integrations** → **Webhooks**
3. Click **New Webhook**
4. Name it (e.g., "Microsoft Rewards Bot")
5. Choose a channel
6. Click **Copy Webhook URL**
#### 2. Add to Configuration
Edit `src/config.jsonc`:
```jsonc
{
"conclusionWebhook": {
"enabled": true,
"webhookUrl": "https://discord.com/api/webhooks/123456789/AbCdEfGhIjKlMnOpQrStUvWxYz"
}
}
```
### What You'll Receive
**Rich embeds with**:
- ✅ Total points earned
- 📊 Per-account breakdown
- ⏱️ Run duration
- 🎯 Completion status
- ⚠️ Errors and warnings
**Example message**:
```
🎉 Microsoft Rewards Summary
Total Points: 450
Duration: 12 minutes
Accounts Processed: 3/3
✅ account1@outlook.com: 150 points (45s)
✅ account2@outlook.com: 150 points (48s)
✅ account3@outlook.com: 150 points (42s)
```
### Advanced Options
```jsonc
{
"conclusionWebhook": {
"enabled": true,
"webhookUrl": "YOUR_WEBHOOK_URL",
"username": "Rewards Bot", // Custom bot name
"avatar": "https://example.com/avatar.png", // Custom avatar
"color": 3447003, // Embed color (decimal)
"onlyOnError": false, // Send only when errors occur
"pingOnError": true // @mention on errors
}
}
```
### Multiple Webhooks
Send to different channels:
```jsonc
{
"conclusionWebhook": {
"enabled": true,
"webhookUrl": "WEBHOOK_FOR_SUCCESS",
"errorWebhookUrl": "WEBHOOK_FOR_ERRORS" // Separate channel for errors
}
}
```
---
## 📱 NTFY Mobile Alerts
Get **instant push notifications** on your phone with [ntfy.sh](https://ntfy.sh/).
### Setup
#### 1. Install NTFY App
- **Android**: [Google Play Store](https://play.google.com/store/apps/details?id=io.heckel.ntfy)
- **iOS**: [App Store](https://apps.apple.com/us/app/ntfy/id1625396347)
- **Web**: https://ntfy.sh/app
#### 2. Choose a Topic
Pick a **unique topic name** (acts as your channel):
- Examples: `rewards-bot-john`, `msrewards-12345`
- Keep it secret to avoid spam!
#### 3. Subscribe in App
1. Open NTFY app
2. Tap **+** or **Subscribe**
3. Enter your topic name
4. Save
#### 4. Add to Configuration
Edit `src/config.jsonc`:
```jsonc
{
"ntfy": {
"enabled": true,
"topic": "your-unique-topic-name", // From step 2
"priority": 3, // 1-5 (3 = default, 5 = urgent)
"tags": ["robot", "money"] // Optional emojis
}
}
```
### What You'll Receive
**Simple push notifications**:
- ✅ Bot completion status
- 📊 Total points earned
- ⚠️ Error alerts
- ⏱️ Run duration
**Example notification**:
```
🤖 Rewards Bot Complete
✅ 3 accounts processed
💰 450 points earned
⏱️ 12 minutes
```
### Priority Levels
| Priority | Behavior | When to Use |
|----------|----------|-------------|
| 1 | Min | Background only, no sound |
| 2 | Low | Vibrate only |
| 3 | **Default** | Normal notification |
| 4 | High | Makes sound |
| 5 | Max | Critical alert, repeats |
**Recommended**: Priority 3 or 4 for most use cases.
### Custom NTFY Server
Using your own NTFY server:
```jsonc
{
"ntfy": {
"enabled": true,
"server": "https://ntfy.yourdomain.com", // Your server
"topic": "your-topic",
"priority": 3
}
}
```
### Advanced Options
```jsonc
{
"ntfy": {
"enabled": true,
"topic": "your-topic",
"priority": 4,
"tags": ["robot", "chart_increasing"], // Emojis in notification
"title": "Rewards Bot", // Custom title
"clickUrl": "https://rewards.bing.com", // URL to open on click
"attachUrl": "https://example.com/image.png", // Attach image
"onlyOnError": false, // Send only on errors
"email": "you@example.com" // Also send email
}
}
```
### Available Tags (Emojis)
Common ones:
- `robot`, `money`, `chart`, `check`, `warning`, `fire`
- Full list: https://ntfy.sh/docs/emojis/
---
## ⚖️ Comparison
| Feature | Discord Webhooks | NTFY |
|---------|------------------|------|
| **Setup** | Medium (need server) | Easy (just install app) |
| **Detail** | Rich embeds with full stats | Simple text notifications |
| **Speed** | Fast | Instant |
| **Mobile** | Requires Discord app | Dedicated notifications app |
| **Free** | ✅ Yes | ✅ Yes |
| **Privacy** | Data goes to Discord | Self-hostable |
| **Best For** | Detailed reports | Quick alerts |
**Recommendation**: Use **both**!
- Discord for detailed daily reports
- NTFY for instant mobile alerts
---
## 📝 Examples
### Both Enabled (Recommended)
```jsonc
{
"conclusionWebhook": {
"enabled": true,
"webhookUrl": "YOUR_DISCORD_WEBHOOK"
},
"ntfy": {
"enabled": true,
"topic": "your-unique-topic",
"priority": 3,
"tags": ["robot", "money"]
}
}
```
### Errors Only
```jsonc
{
"conclusionWebhook": {
"enabled": true,
"webhookUrl": "YOUR_DISCORD_WEBHOOK",
"onlyOnError": true // Only send when something goes wrong
},
"ntfy": {
"enabled": true,
"topic": "your-topic",
"priority": 5, // Max priority for errors
"onlyOnError": true
}
}
```
### Different Priorities for Success/Error
```jsonc
{
"ntfy": {
"enabled": true,
"topic": "your-topic",
"priority": 3, // Normal for success
"priorityOnError": 5, // Urgent for errors
"tags": ["robot"],
"tagsOnError": ["warning", "fire"] // Different emoji on error
}
}
```
### Custom Formatting
```jsonc
{
"conclusionWebhook": {
"enabled": true,
"webhookUrl": "YOUR_WEBHOOK",
"username": "🤖 Rewards Bot",
"color": 3066993, // Green color (decimal)
"footer": "Powered by Microsoft Rewards Bot",
"timestamp": true // Show timestamp
}
}
```
---
## 🔧 Troubleshooting
### Discord webhook not working
**Check**:
1. Webhook URL is correct (starts with `https://discord.com/api/webhooks/`)
2. Webhook still exists in Discord server settings
3. Bot has permissions to send webhooks
4. Check console for error messages
**Test manually**:
## Example
```bash
curl -X POST "YOUR_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-d '{"content": "Test message"}'
set DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
npm start
```
### NTFY notifications not arriving
**Check**:
1. Topic name is correct (case-sensitive!)
2. Subscribed in app with same topic
3. App has notification permissions
4. Internet connection is stable
5. Not using a banned/common topic name
**Test manually**:
```bash
curl -d "Test notification" "https://ntfy.sh/your-topic"
```
Or visit in browser: https://ntfy.sh/your-topic
### Rate limiting
If sending too many notifications:
```jsonc
{
"conclusionWebhook": {
"enabled": true,
"webhookUrl": "YOUR_WEBHOOK",
"debounceMs": 5000 // Wait 5s between messages
}
}
```
---
## 🆘 Need Help?
- 💬 **[Discord Community](https://discord.gg/k5uHkx9mne)** — Get support
- 📖 **[Configuration Guide](config.md)** — All config options
- 🐛 **[Report Issue](https://github.com/LightZirconite/Microsoft-Rewards-Bot/issues)** — Found a bug?
---
<div align="center">
[← Back to Documentation](index.md)
</div>

16
docs/running.md Normal file
View File

@@ -0,0 +1,16 @@
# Running the Bot
## What it does
Explains the basic commands to start the bot.
## How to use
- `npm start` — builds if needed and runs once.
- `npm run dev` — runs from source while you edit.
- `npm run dashboard` — starts the web dashboard.
- `npm run creator` — opens account creation mode.
- `npm run docker:compose` — runs inside Docker with the provided compose file.
## Example
```bash
npm start
```

19
docs/scheduling.md Normal file
View File

@@ -0,0 +1,19 @@
# Scheduling
## What it does
Runs the bot automatically at set times.
## How to use
- Turn on scheduling in `src/config.jsonc` under `scheduling.enabled`.
- Choose a time using the cron or Task Scheduler fields already in the config.
- Leave the machine or container running so the schedule can trigger.
## Example
```jsonc
{
"scheduling": {
"enabled": true,
"cron": { "schedule": "0 9 * * *" }
}
}
```

22
docs/setup.md Normal file
View File

@@ -0,0 +1,22 @@
# Setup
Get the bot ready before running it.
## What it does
Creates a safe baseline so your accounts and config are ready.
## How to use
1. Install Node.js 20 or newer.
2. Copy `src/accounts.example.jsonc` to `src/accounts.jsonc` and fill in your accounts.
3. Review `src/config.jsonc`; defaults work for most people.
4. (Optional) set `DISCORD_WEBHOOK_URL` in your environment for alerts.
## Example
```jsonc
[
{
"email": "you@example.com",
"password": "your-password"
}
]
```

18
docs/troubleshooting.md Normal file
View File

@@ -0,0 +1,18 @@
# Troubleshooting
## What it does
Quick fixes for common problems.
## How to use
- If a run fails, rerun with `npm start` after closing all browser windows.
- If builds fail, delete `node_modules` and `dist`, then run `npm install` followed by `npm run build`.
- Ensure `DISCORD_WEBHOOK_URL` is set if you expect alerts.
- Check that `accounts.jsonc` has valid emails and passwords.
## Example
```bash
npx rimraf node_modules dist
npm install
npm run build
npm start
```

14
docs/update.md Normal file
View File

@@ -0,0 +1,14 @@
# Updating
## What it does
Keeps the bot current with the official release.
## How to use
- Run `npm run update` to download and apply the latest version.
- Re-run `npm install` if prompted.
- Start the bot again after the update finishes.
## Example
```bash
npm run update
```