heathrow 0.7.0

data/docs/REPLY_FORWARD.md

@@ -0,0 +1,182 @@
+# Reply, Forward, and Compose in Heathrow
+
+Heathrow provides full email-style reply, forward, and compose functionality using your system's $EDITOR, similar to mutt.
+
+## Features
+
+- **Reply** (`r`) - Reply to the sender
+- **Reply All** (`R`) - Reply to sender and all recipients
+- **Forward** (`f`) - Forward message to new recipients
+- **Compose** (`m`) - Create new message
+
+## How It Works
+
+1. Press the appropriate key while viewing a message
+2. Your $EDITOR (default: vim) opens with a pre-formatted template
+3. Edit the message, keeping the To: and Subject: headers
+4. Save and exit to send (`:wq` in vim)
+5. Exit without saving to cancel
+
+## SMTP Configuration
+
+Heathrow supports OAuth2 SMTP for Gmail and custom domains. Configure your domains in the `OAUTH2_DOMAINS` list inside `smtp_sender.rb`:
+- gmail.com
+- yourdomain.com (add your own)
+
+The SmtpSender module (`lib/heathrow/smtp_sender.rb`) automatically detects configured domains and routes mail through your OAuth2 SMTP command (configurable in settings).
+
+### OAuth2 Setup
+
+Your OAuth2 credentials are stored in:
+- `~/.heathrow/mail/[email].json` - Client credentials
+- `~/.heathrow/mail/[email].txt` - Refresh token
+
+The SMTP script handles token refresh automatically.
+
+### Other Email Accounts
+
+For non-OAuth2 accounts, configure SMTP settings when adding the source:
+- SMTP server address
+- SMTP port (usually 587 for TLS, 25 for plain)
+- Username and password
+
+## Message Templates
+
+### Reply Template
+```
+To: original-sender@example.com
+Subject: Re: Original Subject
+# Lines starting with # will be ignored
+# Write your message below this line
+#==================================================
+
+[Your reply here]
+
+On 2025-08-25, sender wrote:
+> Original message quoted
+> with > prefix
+```
+
+### Reply All Template
+```
+To: sender@example.com, recipient1@example.com, recipient2@example.com
+Subject: Re: Original Subject
+[Rest same as reply]
+```
+
+### Forward Template
+```
+To: [Enter recipients]
+Subject: Fwd: Original Subject
+# Lines starting with # will be ignored
+# Enter recipients and write your message
+#==================================================
+
+[Your introduction]
+
+---------- Forwarded message ----------
+From: original-sender@example.com
+Date: 2025-08-25
+Subject: Original Subject
+
+[Original message content]
+```
+
+## Supported Sources
+
+Sources with reply capability:
+- **Gmail** - Full OAuth2 support via configurable SMTP command
+- **IMAP** - Uses OAuth2 SMTP for supported domains or configured SMTP
+- **Discord** - Bot/user messages to channels
+- **Telegram** - Bot messages to chats
+
+## Key Bindings
+
+| Key | Action | Description |
+|-----|--------|-------------|
+| `r` | Reply | Reply to sender only |
+| `R` | Reply All | Reply to all recipients |
+| `f` | Forward | Forward to new recipients |
+| `m` | Mail/Compose | Create new message |
+| `Ctrl-R` | Refresh | Refresh all panes |
+
+## Editor Tips
+
+### Vim Configuration
+Your vim is configured with:
+```vim
+setlocal tw=0 fo-=tcal ff=unix
+```
+
+This ensures:
+- No automatic text wrapping
+- Unix line endings
+- Proper email formatting
+
+### Canceling a Message
+- Exit without saving: `:q!` in vim
+- Or make no changes and save (detected as cancel)
+
+## Troubleshooting
+
+### Message Not Sending
+
+1. Check `~/.heathrow/mail/.smtp.log` for errors
+2. Verify OAuth2 credentials exist for your email
+3. For new domains, add to `OAUTH2_DOMAINS` in `smtp_sender.rb`
+
+### OAuth2 Token Issues
+
+If you see token errors:
+```bash
+# Regenerate token
+oauth2.py --generate_oauth2_token \
+  --client_id=[your-client-id] \
+  --client_secret=[your-secret] \
+  --refresh_token=[your-refresh-token]
+```
+
+### SMTP Server Issues
+
+For non-OAuth2 accounts, verify:
+- SMTP server address is correct
+- Port is appropriate (587 for TLS, 25 for plain)
+- Username/password are correct
+- Firewall allows outgoing SMTP
+
+## Testing
+
+Test the SMTP module:
+```bash
+ruby test_smtp_module.rb
+```
+
+Test sending from a specific source:
+```bash
+ruby test_gmail_send.rb
+```
+
+## Implementation Details
+
+The reply/forward system consists of:
+
+1. **MessageComposer** (`lib/heathrow/message_composer.rb`)
+   - Creates templates
+   - Launches editor
+   - Parses composed messages
+
+2. **SmtpSender** (`lib/heathrow/smtp_sender.rb`)
+   - Routes to OAuth2 SMTP for configured domains
+   - Falls back to standard SMTP for others
+   - Handles error reporting
+
+3. **Source Integration**
+   - Each source implements `can_reply?` and `send_message`
+   - Threading headers (In-Reply-To, References) preserved
+
+## Security Notes
+
+- OAuth2 tokens stored in `~/.heathrow/mail/`
+- No passwords stored in Heathrow database for OAuth2 accounts
+- Temporary message files deleted after sending
+- SMTP passwords encrypted in source config

data/docs/WHATSAPP_TELEGRAM_SETUP.md

@@ -0,0 +1,306 @@
+# WhatsApp and Telegram Setup Guide for Heathrow
+
+This guide helps you set up WhatsApp and Telegram sources in Heathrow to receive messages from these platforms.
+
+## WhatsApp Setup
+
+WhatsApp integration requires a separate API server that implements the WhatsApp Web protocol.
+
+### Prerequisites
+
+1. **Go Language** - Required for the WhatsApp API server
+   ```bash
+   sudo apt install golang-go
+   ```
+
+2. **WhatsApp API Server** - A REST API wrapper for WhatsApp Web
+   - The server needs to be running before setting up the source
+   - Default port: 8080
+
+### Quick Setup
+
+1. Start the WhatsApp API server (in a separate terminal):
+   ```bash
+   # Clone and run the server
+   git clone [whatsmeow-api-repo]
+   cd whatsmeow-api
+   go run main.go
+   ```
+
+2. Run the WhatsApp setup script:
+   ```bash
+   ruby setup_whatsapp.rb
+   ```
+
+3. Choose authentication method:
+   - **QR Code** (default): Scan with WhatsApp mobile app
+   - **Pairing Code**: Enter code in WhatsApp settings
+
+### Authentication Methods
+
+#### QR Code Method
+1. Open WhatsApp on your phone
+2. Go to Settings → Linked Devices
+3. Tap "Link a Device"
+4. Scan the QR code displayed in terminal
+
+#### Pairing Code Method
+1. Provide your phone number during setup
+2. Receive an 8-digit pairing code
+3. In WhatsApp: Settings → Linked Devices → Link with phone number
+4. Enter the pairing code
+
+### Configuration
+
+The WhatsApp source supports these settings:
+
+```ruby
+{
+  api_url: 'http://localhost:8080',  # API server URL
+  device_id: 'unique_device_id',     # Device identifier
+  fetch_limit: 50,                   # Messages per fetch
+  incremental_sync: true,            # Only fetch new messages
+  use_pairing_code: false,           # Use QR code by default
+  phone_number: '1234567890',        # For pairing code only
+  polling_interval: 60               # Check every minute
+}
+```
+
+### Message Types Supported
+
+- Text messages
+- Images, videos, audio
+- Documents and files
+- Location sharing
+- Contact cards
+- Stickers
+- Group messages
+
+## Telegram Setup
+
+Telegram offers two integration methods: Bot API (simple) or User Account (full access).
+
+### Method 1: Telegram Bot (Recommended for Start)
+
+#### Creating a Bot
+
+1. Open Telegram and search for **@BotFather**
+2. Send `/newbot` command
+3. Choose a name for your bot
+4. Choose a username (must end in 'bot')
+5. Copy the bot token provided
+
+#### Setup
+
+Run the Telegram setup script:
+```bash
+ruby setup_telegram.rb
+```
+
+Choose option 1 (Bot) and enter your bot token.
+
+#### Bot Limitations
+
+- Only receives messages sent directly to the bot
+- Cannot access your personal chats
+- Users must start conversation with `/start`
+- Cannot see messages in groups unless mentioned
+
+### Method 2: User Account (Full Access)
+
+#### Prerequisites
+
+1. Get API credentials from https://my.telegram.org:
+   - Log in with your phone number
+   - Go to "API development tools"
+   - Create an app (if needed)
+   - Copy the **api_id** and **api_hash**
+
+2. For full functionality, you need an MTProto proxy server (advanced)
+
+#### Setup
+
+Run the setup script and choose option 2:
+```bash
+ruby setup_telegram.rb
+```
+
+Provide:
+- API ID
+- API Hash
+- Phone number (with country code)
+
+#### Authentication Process
+
+1. You'll receive a code in your Telegram app
+2. Enter the code when prompted
+3. If you have 2FA enabled, enter your password
+4. Session is saved for future use
+
+### Configuration Options
+
+#### Bot Configuration
+```ruby
+{
+  bot_token: 'YOUR_BOT_TOKEN',
+  fetch_limit: 100,
+  polling_interval: 60
+}
+```
+
+#### User Account Configuration
+```ruby
+{
+  api_id: 'YOUR_API_ID',
+  api_hash: 'YOUR_API_HASH',
+  phone_number: '+1234567890',
+  session_string: 'saved_after_auth',
+  mtproto_api_url: 'http://localhost:8081'
+}
+```
+
+### Message Types Supported
+
+- Text messages
+- Photos and videos
+- Voice messages and audio
+- Documents and files
+- Stickers and GIFs
+- Location sharing
+- Contact cards
+- Channel posts
+- Group messages
+
+## Testing the Sources
+
+After setup, test your sources:
+
+1. In Heathrow, press `s` to view sources
+2. Navigate to WhatsApp or Telegram source
+3. Press `t` to test connection
+4. Check for success message
+
+## Troubleshooting
+
+### WhatsApp Issues
+
+**"API server not running"**
+- Ensure the WhatsApp API server is running on port 8080
+- Check with: `curl http://localhost:8080/health`
+
+**"Device not authenticated"**
+- Re-run the setup script
+- Try QR code method if pairing code fails
+- Ensure your phone has internet connection
+
+**"No messages fetched"**
+- WhatsApp Web must stay connected
+- Check phone's internet connection
+- Verify in WhatsApp: Settings → Linked Devices
+
+### Telegram Issues
+
+**Bot not receiving messages**
+- Users must start conversation with `/start`
+- In groups, bot needs to be admin or mentioned
+- Check bot token is correct
+
+**User account authentication fails**
+- Verify api_id and api_hash are correct
+- Phone number must include country code
+- Code expires after 5 minutes
+- 2FA password is case-sensitive
+
+**"Session expired"**
+- Re-run authentication process
+- Session strings expire after long inactivity
+
+## Security Notes
+
+### WhatsApp
+- Messages are end-to-end encrypted
+- Device sessions persist until manually disconnected
+- Each device has unique encryption keys
+- Disconnect unused devices from WhatsApp settings
+
+### Telegram
+- Bot tokens should be kept secret
+- API credentials are sensitive - don't share
+- Session strings grant full account access
+- Use environment variables for credentials in production
+
+## Advanced Configuration
+
+### Running API Servers as Services
+
+#### WhatsApp API Service
+Create `/etc/systemd/system/whatsmeow-api.service`:
+```ini
+[Unit]
+Description=WhatsApp API Server
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+WorkingDirectory=/path/to/whatsmeow-api
+ExecStart=/usr/bin/go run main.go
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+#### Start the service:
+```bash
+sudo systemctl enable whatsmeow-api
+sudo systemctl start whatsmeow-api
+```
+
+### Multiple Accounts
+
+You can add multiple WhatsApp or Telegram sources:
+- Use different device_ids for WhatsApp
+- Use different bot tokens or phone numbers for Telegram
+- Each source syncs independently
+
+### Filtering and Rules
+
+Configure message filtering in Heathrow:
+- Create views for specific contacts
+- Filter by sender or group
+- Set up notifications for important messages
+
+## API Server Requirements
+
+### WhatsApp (whatsmeow)
+- Go 1.19 or higher
+- SQLite for session storage
+- ~50MB RAM per connected device
+- Persistent storage for media cache
+
+### Telegram (MTProto)
+- Python 3.8+ or Go 1.19+
+- Session storage (file or database)
+- ~30MB RAM per session
+- Optional media download storage
+
+## Rate Limits
+
+### WhatsApp
+- No official rate limits for receiving
+- Sending limited to prevent spam
+- Reconnection backoff on disconnects
+
+### Telegram
+- Bot API: 30 messages/second
+- MTProto: Adaptive rate limiting
+- Respect flood wait errors
+
+## Next Steps
+
+1. Start Heathrow and verify sources appear
+2. Monitor initial message sync
+3. Configure polling intervals as needed
+4. Set up views for different platforms
+5. Consider running API servers as background services

data/heathrow.gemspec

@@ -0,0 +1,34 @@
+require_relative 'lib/heathrow/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'heathrow'
+  spec.version       = Heathrow::VERSION
+  spec.authors       = ['Geir Isene', 'Claude Code']
+  spec.email         = ['g@isene.com']
+
+  spec.summary       = 'Communication Hub In The Terminal'
+  spec.description   = 'A unified TUI application for managing all your communication sources in one place. Brings together emails, WhatsApp, Discord, Reddit, RSS feeds, and more into a single, efficient terminal interface.'
+  spec.homepage      = 'https://github.com/isene/heathrow'
+  spec.license       = 'Unlicense'
+
+  spec.required_ruby_version = '>= 2.7.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/isene/heathrow'
+  spec.metadata['changelog_uri'] = 'https://github.com/isene/heathrow/blob/master/CHANGELOG.md'
+
+  # Specify which files should be added to the gem
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:test|spec|features)/})
+    end
+  end
+
+  spec.bindir        = 'bin'
+  spec.executables   = ['heathrow']
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies - keep it simple!
+  spec.add_runtime_dependency 'rcurses', '>= 5.0'
+  spec.add_runtime_dependency 'sqlite3', '>= 1.4'
+end

data/heathrowd.service

@@ -0,0 +1,21 @@
+[Unit]
+Description=Heathrow Daemon - Communication Hub Polling Service
+After=network.target
+
+[Service]
+Type=simple
+User=%i
+ExecStart=/usr/local/bin/heathrowd start --daemon --interval 30
+ExecStop=/usr/local/bin/heathrowd stop
+Restart=always
+RestartSec=10
+
+# Security settings
+NoNewPrivileges=yes
+PrivateTmp=yes
+ProtectSystem=strict
+ProtectHome=yes
+ReadWritePaths=%h/.heathrow
+
+[Install]
+WantedBy=multi-user.target

data/img/heathrow.svg

@@ -0,0 +1,95 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#1a1a2e"/>
+      <stop offset="100%" style="stop-color:#0f0f1a"/>
+    </linearGradient>
+    <linearGradient id="glow" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#e2b714"/>
+      <stop offset="100%" style="stop-color:#c49000"/>
+    </linearGradient>
+  </defs>
+
+  <style>
+    @keyframes pulse { 0%,100% { opacity: 0.5; } 50% { opacity: 1; } }
+    @keyframes spin { from { transform-origin: 128px 128px; transform: rotate(0deg); } to { transform-origin: 128px 128px; transform: rotate(360deg); } }
+    @keyframes dot-travel {
+      0% { opacity: 0; }
+      10% { opacity: 1; }
+      90% { opacity: 1; }
+      100% { opacity: 0; }
+    }
+    .hub-ring { animation: pulse 3s ease-in-out infinite; }
+    .outer-ring { animation: spin 30s linear infinite; }
+    .dot1 { animation: dot-travel 2.5s ease-in-out infinite; }
+    .dot2 { animation: dot-travel 2.5s ease-in-out 0.4s infinite; }
+    .dot3 { animation: dot-travel 2.5s ease-in-out 0.8s infinite; }
+    .dot4 { animation: dot-travel 2.5s ease-in-out 1.2s infinite; }
+    .dot5 { animation: dot-travel 2.5s ease-in-out 1.6s infinite; }
+    .dot6 { animation: dot-travel 2.5s ease-in-out 2.0s infinite; }
+  </style>
+
+  <!-- Background circle -->
+  <circle cx="128" cy="128" r="120" fill="url(#bg)" stroke="#e2b714" stroke-width="3"/>
+
+  <!-- Outer decorative ring (slow spin) -->
+  <circle class="outer-ring" cx="128" cy="128" r="95" fill="none" stroke="#e2b714" stroke-width="0.5" stroke-dasharray="8 12" opacity="0.3"/>
+
+  <!-- Hub ring (pulsing) -->
+  <circle class="hub-ring" cx="128" cy="128" r="38" fill="none" stroke="url(#glow)" stroke-width="3"/>
+  <!-- Hub center dot -->
+  <circle cx="128" cy="128" r="6" fill="#e2b714" opacity="0.9"/>
+
+  <!-- Spokes with traveling dots -->
+
+  <!-- Top: Email (gold) -->
+  <line x1="128" y1="90" x2="128" y2="52" stroke="#e2b714" stroke-width="1.5" opacity="0.4"/>
+  <circle class="dot1" cx="128" cy="70" r="2" fill="#e2b714"/>
+  <rect x="116" y="34" width="24" height="16" rx="2" fill="none" stroke="#e2b714" stroke-width="2"/>
+  <polyline points="116,36 128,44 140,36" fill="none" stroke="#e2b714" stroke-width="1.5"/>
+
+  <!-- Top-right: Chat (blue) -->
+  <line x1="155" y1="100" x2="185" y2="66" stroke="#39c" stroke-width="1.5" opacity="0.4"/>
+  <circle class="dot2" cx="170" cy="83" r="2" fill="#39c"/>
+  <rect x="178" y="48" width="24" height="17" rx="4" fill="none" stroke="#39c" stroke-width="2"/>
+  <circle cx="186" cy="57" r="1.5" fill="#39c"/>
+  <circle cx="190" cy="57" r="1.5" fill="#39c"/>
+  <circle cx="194" cy="57" r="1.5" fill="#39c"/>
+
+  <!-- Right: RSS (orange) -->
+  <line x1="166" y1="128" x2="206" y2="128" stroke="#f80" stroke-width="1.5" opacity="0.4"/>
+  <circle class="dot3" cx="186" cy="128" r="2" fill="#f80"/>
+  <circle cx="220" cy="128" r="3" fill="#f80"/>
+  <path d="M212,119 A14,14 0 0,1 228,135" fill="none" stroke="#f80" stroke-width="2.5"/>
+  <path d="M208,113 A22,22 0 0,1 234,139" fill="none" stroke="#f80" stroke-width="1.5"/>
+
+  <!-- Bottom-right: Discord (purple) -->
+  <line x1="155" y1="156" x2="184" y2="188" stroke="#77d" stroke-width="1.5" opacity="0.4"/>
+  <circle class="dot4" cx="170" cy="172" r="2" fill="#77d"/>
+  <text x="186" y="200" font-family="sans-serif" font-size="22" font-weight="bold" fill="#77d">#</text>
+
+  <!-- Bottom: Terminal (green) -->
+  <line x1="128" y1="166" x2="128" y2="204" stroke="#4c4" stroke-width="1.5" opacity="0.4"/>
+  <circle class="dot5" cx="128" cy="186" r="2" fill="#4c4"/>
+  <rect x="110" y="206" width="36" height="24" rx="3" fill="none" stroke="#4c4" stroke-width="2"/>
+  <text x="116" y="224" font-family="monospace" font-size="12" fill="#4c4">&gt;_</text>
+
+  <!-- Bottom-left: Phone (teal) -->
+  <line x1="101" y1="156" x2="72" y2="188" stroke="#5b5" stroke-width="1.5" opacity="0.4"/>
+  <circle class="dot6" cx="86" cy="172" r="2" fill="#5b5"/>
+  <rect x="58" y="188" width="18" height="28" rx="3" fill="none" stroke="#5b5" stroke-width="2"/>
+  <circle cx="67" cy="212" r="2" fill="#5b5"/>
+
+  <!-- Left: Forum (red) -->
+  <line x1="90" y1="128" x2="50" y2="128" stroke="#e55" stroke-width="1.5" opacity="0.4"/>
+  <circle cx="38" cy="128" r="12" fill="none" stroke="#e55" stroke-width="2"/>
+  <circle cx="34" cy="124" r="2" fill="#e55"/>
+  <circle cx="42" cy="124" r="2" fill="#e55"/>
+  <path d="M33,131 Q38,136 43,131" fill="none" stroke="#e55" stroke-width="1.5"/>
+
+  <!-- Top-left: Web (lavender) -->
+  <line x1="101" y1="100" x2="72" y2="68" stroke="#a8e" stroke-width="1.5" opacity="0.4"/>
+  <circle cx="60" cy="56" r="14" fill="none" stroke="#a8e" stroke-width="2"/>
+  <ellipse cx="60" cy="56" rx="6" ry="14" fill="none" stroke="#a8e" stroke-width="1"/>
+  <line x1="46" y1="56" x2="74" y2="56" stroke="#a8e" stroke-width="1"/>
+</svg>

data/lib/heathrow/address_book.rb

@@ -0,0 +1,42 @@
+module Heathrow
+  class AddressBook
+    attr_reader :aliases
+
+    def initialize(path = File.expand_path('~/setup/addressbook'))
+      @aliases = {}
+      parse(path) if File.exist?(path)
+    end
+
+    def parse(path)
+      File.readlines(path).each do |line|
+        next unless line =~ /^alias\s+(\S+)\s+(.+)/
+        @aliases[$1] = $2.strip
+      end
+    end
+
+    # Search aliases and addresses by query string
+    def lookup(query)
+      query_down = query.downcase
+      @aliases.select { |k, v| k.include?(query_down) || v.downcase.include?(query_down) }
+    end
+
+    # Expand an alias name to full address, or return input unchanged
+    def expand(name)
+      @aliases[name] || name
+    end
+
+    # Get all alias names
+    def names
+      @aliases.keys.sort
+    end
+
+    # Get completion candidates for a partial string
+    def complete(partial)
+      return [] if partial.nil? || partial.empty?
+      partial_down = partial.downcase
+      @aliases.select { |k, v|
+        k.start_with?(partial_down) || v.downcase.include?(partial_down)
+      }.map { |k, v| "#{k} → #{v}" }
+    end
+  end
+end