Microsoft-Rewards-Script/docs/ntfy.md

📱 NTFY Push Notifications

🔔 Real-time push notifications to your devices
Stay informed wherever you are

---

🎯 What is NTFY?

NTFY is a simple HTTP-based pub-sub notification service that sends push notifications to your phone, desktop, or web browser. Perfect for real-time alerts about script events and errors.

Key Features

• 📱 Mobile & Desktop — Push to any device
• 🆓 Free & Open Source — No vendor lock-in
• 🏠 Self-hostable — Complete privacy control
• ⚡ Real-time delivery — Instant notifications
• 🔒 Authentication support — Secure topics

Official Links

• Website — ntfy.sh
• Documentation — docs.ntfy.sh
• GitHub — binwiederhier/ntfy

---

⚙️ Configuration

Basic Setup

{
  "notifications": {
    "ntfy": {
      "enabled": true,
      "url": "https://ntfy.sh",
      "topic": "rewards-script",
      "authToken": ""
    }
  }
}

Configuration Options

Setting	Description	Example
enabled	Enable NTFY notifications	true
url	NTFY server URL	"https://ntfy.sh"
topic	Notification topic name	"rewards-script"
authToken	Authentication token (optional)	"tk_abc123..."

---

🚀 Setup Options

Option 1: Public Service (Easiest)

{
  "notifications": {
    "ntfy": {
      "enabled": true,
      "url": "https://ntfy.sh",
      "topic": "your-unique-topic-name"
    }
  }
}

Pros:

• ✅ No server setup required
• ✅ Always available
• ✅ Free to use

Cons:

• ❌ Public server (less privacy)
• ❌ Rate limits apply
• ❌ Dependent on external service

Option 2: Self-Hosted (Recommended)

{
  "notifications": {
    "ntfy": {
      "enabled": true,
      "url": "https://ntfy.yourdomain.com",
      "topic": "rewards",
      "authToken": "tk_your_token_here"
    }
  }
}

Self-Hosted Setup:

# docker-compose.yml
version: '3.8'
services:
  ntfy:
    image: binwiederhier/ntfy
    container_name: ntfy
    ports:
      - "80:80"
    volumes:
      - ./data:/var/lib/ntfy
    command: serve

---

🔒 Authentication

When You Need Auth

Authentication tokens are optional but required for:

• 🔐 Private topics with username/password
• 🏠 Private NTFY servers with authentication
• 🛡️ Preventing spam on your topic

Getting an Auth Token

Method 1: Command Line

ntfy token

Method 2: Web Interface

1. Visit your NTFY server (e.g., https://ntfy.sh)
2. Go to Account section
3. Generate new access token

Method 3: API

curl -X POST -d '{"label":"rewards-script"}' \
  -H "Authorization: Bearer YOUR_LOGIN_TOKEN" \
  https://ntfy.sh/v1/account/tokens

Token Format

• Tokens start with tk_ (e.g., tk_abc123def456...)
• Use Bearer authentication format
• Tokens are permanent until revoked

---

📲 Receiving Notifications

Mobile Apps

• Android — NTFY on Google Play
• iOS — NTFY on App Store
• F-Droid — Available for Android

Desktop Options

• Web Interface — Visit your NTFY server URL
• Desktop Apps — Available for Linux, macOS, Windows
• Browser Extension — Chrome/Firefox extensions

Setup Steps

1. Install NTFY app on your device
2. Add subscription to your topic name
3. Enter server URL (if self-hosted)
4. Test with a manual message

---

🔔 Notification Types

Error Notifications

Priority: Max 🚨 | Trigger: Script errors and failures

[ERROR] DESKTOP [LOGIN] Failed to login: Invalid credentials

Warning Notifications

Priority: High ⚠️ | Trigger: Important warnings

[WARN] MOBILE [SEARCH] Didn't gain expected points from search

Info Notifications

Priority: Default 🏆 | Trigger: Important milestones

[INFO] MAIN [TASK] Started tasks for account user@email.com

Buy Mode Notifications

Priority: High 💳 | Trigger: Point spending detected

💳 Spend detected (Buy Mode)
Account: user@email.com
Spent: -500 points
Current: 12,500 points
Session spent: 1,200 points

Conclusion Summary

End-of-run summary with rich formatting:

🎯 Microsoft Rewards Summary
Accounts: 3 • 0 with issues
Total: 15,230 -> 16,890 (+1,660)
Average Duration: 8m 32s
Cumulative Runtime: 25m 36s

---

🤝 Integration with Discord

Complementary Setup

Use both NTFY and Discord for comprehensive monitoring:

{
  "notifications": {
    "webhook": {
      "enabled": true,
      "url": "https://discord.com/api/webhooks/..."
    },
    "conclusionWebhook": {
      "enabled": true,
      "url": "https://discord.com/api/webhooks/..."
    },
    "ntfy": {
      "enabled": true,
      "url": "https://ntfy.sh",
      "topic": "rewards-script"
    }
  }
}

Coverage Comparison

Feature	NTFY	Discord
Mobile push	✅ Instant	❌ App required
Rich formatting	❌ Text only	✅ Embeds + colors
Desktop alerts	✅ Native	✅ App notifications
Offline delivery	✅ Queued	❌ Real-time only
Self-hosted	✅ Easy	❌ Complex

---

🎛️ Advanced Configuration

Custom Topic Names

Use descriptive, unique topic names:

{
  "topic": "rewards-production-server1"
}
{
  "topic": "msn-rewards-home-pc"  
}
{
  "topic": "rewards-dev-testing"
}

Environment-Specific

{
  "notifications": {
    "ntfy": {
      "enabled": true,
      "url": "https://ntfy.internal.lan",
      "topic": "homelab-rewards",
      "authToken": "tk_homelab_token"
    }
  }
}

---

🧪 Testing & Debugging

Manual Test Message

# Public server (no auth)
curl -d "Test message from rewards script" https://ntfy.sh/your-topic

# With authentication
curl -H "Authorization: Bearer tk_your_token" \
     -d "Authenticated test message" \
     https://ntfy.sh/your-topic

Script Debug Mode

$env:DEBUG_REWARDS_VERBOSE=1; npm start

Server Health Check

# Check NTFY server status
curl -s https://ntfy.sh/v1/health

# List your topics (with auth)
curl -H "Authorization: Bearer tk_your_token" \
     https://ntfy.sh/v1/account/topics

---

🛠️ Troubleshooting

Problem	Solution
No notifications	Check topic spelling; verify app subscription
Auth failures	Verify token format (tk_); check token validity
Wrong server	Test server URL in browser; check HTTPS/HTTP
Rate limits	Switch to self-hosted; reduce notification frequency

Common Fixes

• ✅ Topic name — Must match exactly between config and app
• ✅ Server URL — Include https:// and check accessibility
• ✅ Token format — Must start with tk_ for authentication
• ✅ Network — Verify firewall/proxy settings

---

🏠 Homelab Integration

Official Support

NTFY is included in:

• Debian Trixie (testing)
• Ubuntu (latest versions)

Popular Integrations

• Sonarr/Radarr — Download completion notifications
• Prometheus — Alert manager integration
• Home Assistant — Automation notifications
• Portainer — Container status alerts

Docker Stack Example

version: '3.8'
services:
  ntfy:
    image: binwiederhier/ntfy
    container_name: ntfy
    ports:
      - "80:80"
    volumes:
      - ./ntfy-data:/var/lib/ntfy
    environment:
      - NTFY_BASE_URL=https://ntfy.yourdomain.com
    command: serve
    
  rewards:
    build: .
    depends_on:
      - ntfy
    environment:
      - NTFY_URL=http://ntfy:80

---

🔒 Privacy & Security

Public Server (ntfy.sh)

• ⚠️ Messages pass through public infrastructure
• ⚠️ Topic names visible in logs
• ✅ Suitable for non-sensitive notifications

Self-Hosted Server

• ✅ Complete control over data
• ✅ Private network deployment possible
• ✅ Recommended for sensitive information

Best Practices

• 🔐 Use unique, non-guessable topic names
• 🔑 Enable authentication for sensitive notifications
• 🏠 Use self-hosted server for maximum privacy
• 🔄 Regularly rotate authentication tokens

Data Retention

• 📨 Messages are not permanently stored
• ⏱️ Delivery attempts retried for short periods
• 🗑️ No long-term message history

---

⚡ Performance Impact

Script Performance

• ✅ Minimal overhead — Fire-and-forget notifications
• ✅ Non-blocking — Failed notifications don't affect script
• ✅ Asynchronous — No execution delays

Network Usage

• 📊 Low bandwidth — Text-only messages
• ⚡ HTTP POST — Simple, efficient protocol
• 🔄 Retry logic — Automatic failure recovery

---

🔗 Related Guides

• Discord Webhooks — Rich notification embeds
• Getting Started — Initial setup and configuration
• Buy Mode — Manual purchasing notifications
• Security — Privacy and data protection