heathrow 0.7.0

data/docs/DISCORD_SETUP.md

@@ -0,0 +1,142 @@
+# Discord Setup Guide for Heathrow
+
+This guide will help you set up Discord as a source in Heathrow to monitor Discord channels and servers.
+
+## Prerequisites
+
+You need a Discord Bot Token. If you already have one (like from discord-irc), you can use it. Otherwise, follow the setup below.
+
+## Creating a Discord Bot
+
+### 1. Create a Discord Application
+
+1. Go to https://discord.com/developers/applications
+2. Click "New Application"
+3. Give it a name (e.g., "Heathrow Bot")
+4. Click "Create"
+
+### 2. Create the Bot
+
+1. In your application, go to the "Bot" section in the left sidebar
+2. Click "Add Bot"
+3. Under "Token", click "Copy" to copy your bot token
+4. **Save this token securely** - you'll need it for Heathrow
+
+### 3. Set Bot Permissions
+
+1. In the "Bot" section, configure:
+   - **Public Bot**: OFF (unless you want others to add your bot)
+   - **Requires OAuth2 Code Grant**: OFF
+   - **Message Content Intent**: ON (required to read message content)
+
+### 4. Invite Bot to Your Servers
+
+1. Go to "OAuth2" → "URL Generator" in the left sidebar
+2. Under "Scopes", select:
+   - `bot`
+3. Under "Bot Permissions", select:
+   - Read Messages/View Channels
+   - Read Message History
+4. Copy the generated URL
+5. Open the URL in your browser
+6. Select the server you want to add the bot to
+7. Click "Authorize"
+
+## Getting Channel and Server IDs
+
+### Enable Developer Mode
+
+1. Open Discord (app or web)
+2. Go to Settings → Advanced
+3. Enable "Developer Mode"
+
+### Get Channel IDs
+
+1. Right-click on any channel
+2. Click "Copy Channel ID"
+
+### Get Server/Guild IDs
+
+1. Right-click on any server icon
+2. Click "Copy Server ID"
+
+## Adding Discord to Heathrow
+
+1. In Heathrow, press 's' for Sources view
+2. Press 'a' to add a new source
+3. Choose "Discord"
+4. Fill in:
+   - **Account Name**: Any name you want (e.g., "My Discord")
+   - **Bot Token**: Your bot token (starts with MTM...)
+   - **Is Bot Token?**: Yes (leave checked)
+   - **Channel IDs**: Comma-separated list of channel IDs to monitor
+     - Example: `123456789012345678,234567890123456789`
+   - **Guild/Server IDs**: Optional - monitors all channels in these servers
+   - **Messages per fetch**: 20 (or adjust as needed)
+   - **Check interval**: 60 seconds (or adjust as needed)
+
+## Configuration Examples
+
+### Monitor Specific Channels Only
+```
+Channel IDs: 123456789012345678,234567890123456789
+Guild IDs: (leave empty)
+```
+
+### Monitor All Channels in a Server
+```
+Channel IDs: (leave empty)
+Guild IDs: 345678901234567890
+```
+
+### Monitor Mix of Both
+```
+Channel IDs: 123456789012345678
+Guild IDs: 456789012345678901
+```
+
+## Using an Existing discord-irc Bot
+
+If you already have discord-irc running (like in your weechat setup), you can reuse the same bot token:
+
+1. Find your discord-irc config (usually `~/.config/discord-irc.json`)
+2. Copy the `discordToken` value
+3. Note the channel IDs from `channelMapping`
+4. Use these in Heathrow
+
+## Troubleshooting
+
+### "403 Forbidden" Errors
+- The bot doesn't have permission to read that channel
+- Re-invite the bot with proper permissions
+- Check if the channel is private and the bot has access
+
+### No Messages Appearing
+- Check the bot has "Read Message History" permission
+- Verify the channel IDs are correct
+- Ensure the bot is actually in the server
+
+### "401 Unauthorized"
+- Your bot token is invalid or expired
+- Double-check you copied the complete token
+- Regenerate the token if needed
+
+## Security Notes
+
+- **Never share your bot token** - anyone with it can control your bot
+- Bot tokens don't expire unless you regenerate them
+- Consider using a separate bot for Heathrow if you use Discord bots elsewhere
+- The bot can only see channels it has access to
+
+## Rate Limits
+
+Discord has rate limits to prevent abuse:
+- Don't set polling interval below 30 seconds
+- The integration fetches max 100 messages per channel per request
+- If you hit rate limits, you'll see 429 errors - increase the polling interval
+
+## Privacy Considerations
+
+- The bot can see all messages in channels it has access to
+- Messages are stored locally in Heathrow's database
+- Consider informing server members if monitoring shared servers

data/docs/GMAIL_OAUTH_SETUP.md

@@ -0,0 +1,120 @@
+# Gmail OAuth2 Setup Guide for Heathrow
+
+To use Gmail as a source in Heathrow, you need to set up OAuth2 authentication. This is required because Gmail no longer supports simple username/password authentication for third-party apps.
+
+## Prerequisites
+
+1. **oauth2.py script**: Download from https://github.com/google/gmail-oauth2-tools/blob/master/python/oauth2.py
+   - Save it to `~/bin/oauth2.py` (or another location you prefer)
+   - Make it executable: `chmod +x ~/bin/oauth2.py`
+
+2. **Python 3**: The oauth2.py script requires Python 3
+
+3. **Safe directory**: Create a directory for your OAuth files (e.g., `~/.heathrow/mail`)
+   - This directory will store your credentials and refresh token
+   - Make sure it's only readable by you: `chmod 700 ~/.heathrow/mail`
+
+## Setup Steps
+
+### 1. Create a Google Cloud Project
+
+1. Go to https://console.cloud.google.com/
+2. Create a new project (e.g., "heathrow-mail")
+3. Note the project name for later
+
+### 2. Configure OAuth Consent Screen
+
+1. In the Google Cloud Console, go to "APIs & Services" → "OAuth consent screen"
+2. Choose "External" as the user type
+3. Fill in the required fields:
+   - App name: "Heathrow Mail Fetcher" (or your preference)
+   - User support email: Your email address
+   - Developer contact: Your email address
+4. Click "Save and Continue"
+5. Add scope: `https://mail.google.com/`
+6. Click "Save and Continue" (skip test users)
+7. Click "Back to Dashboard"
+
+### 3. Enable Gmail API
+
+1. Go to "APIs & Services" → "Library"
+2. Search for "Gmail API"
+3. Click on it and press "Enable"
+
+### 4. Create OAuth2 Credentials
+
+1. Go to "APIs & Services" → "Credentials"
+2. Click "+ CREATE CREDENTIALS" → "OAuth client ID"
+3. Choose "Web application" as the application type
+4. Name it (e.g., "Heathrow OAuth")
+5. Under "Authorized redirect URIs", add: `https://oauth2.dance/`
+6. Click "Create"
+7. Download the JSON file
+
+### 5. Save Credentials
+
+1. Rename the downloaded JSON file to match your email address:
+   - Example: `youremail@gmail.com.json`
+2. Move it to your safe directory:
+   - `mv ~/Downloads/client_secret_*.json ~/.heathrow/mail/youremail@gmail.com.json`
+
+### 6. Generate Refresh Token
+
+1. Run the oauth2.py script with your credentials:
+   ```bash
+   cd ~/.heathrow/mail
+   oauth2.py --generate_oauth2_token \
+     --client_id=YOUR_CLIENT_ID \
+     --client_secret=YOUR_CLIENT_SECRET \
+     --scope=https://mail.google.com/
+   ```
+   
+2. The script will give you a URL - open it in your browser
+3. Authorize the application
+4. Copy the authorization code from the redirect page
+5. Paste it into the terminal
+6. The script will output a refresh token
+
+### 7. Save Refresh Token
+
+1. Create a text file with your email name:
+   - Example: `youremail@gmail.com.txt`
+2. Put ONLY the refresh token in this file (no other text)
+3. Save it in your safe directory
+
+## File Structure
+
+After setup, your safe directory should contain:
+```
+~/.heathrow/mail/
+├── youremail@gmail.com.json  # OAuth2 credentials from Google
+└── youremail@gmail.com.txt   # Refresh token (single line)
+```
+
+## Adding to Heathrow
+
+Now you can add Gmail as a source in Heathrow:
+
+1. Press 's' to go to Sources view
+2. Press 'a' to add a new source
+3. Choose "Gmail (OAuth2)"
+4. Fill in:
+   - Account Name: Any name you want
+   - Gmail Address: youremail@gmail.com
+   - Safe Directory: ~/.heathrow/mail
+   - OAuth2 Script: ~/bin/oauth2.py
+   - Leave other fields as default
+
+## Troubleshooting
+
+- **"Token retrieval failed"**: Check that both .json and .txt files exist and are named correctly
+- **"Authentication failed"**: Your refresh token may have expired - regenerate it
+- **No new messages**: Gmail might already be marked as read by another client
+- **SSL errors**: Make sure you have the gmail_xoauth gem installed: `gem install gmail_xoauth`
+
+## Security Notes
+
+- Keep your safe directory secure (`chmod 700`)
+- Never share your refresh token or credentials JSON
+- The refresh token doesn't expire unless you revoke it
+- You can revoke access at https://myaccount.google.com/permissions