working v1

2025-10-31 16:17:04 -04:00
parent e41402a963
commit 020daea391
71 changed files with 14793 additions and 1 deletions
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -0,0 +1,301 @@
+# Quick Start Guide
+
+Get the Kosmi-IRC bridge running in minutes!
+
+## Prerequisites
+
+- Go 1.21 or higher
+- Chrome/Chromium browser installed (for headless browser automation)
+- Access to a Kosmi room
+- (Optional) IRC server access for full relay
+
+## Step 1: Test Kosmi Connection
+
+First, verify the bridge can connect to Kosmi:
+
+```bash
+# Build the test program
+go build -o test-kosmi ./cmd/test-kosmi
+
+# Run with your Kosmi room URL
+./test-kosmi -room "https://app.kosmi.io/room/@hyperspaceout" -debug
+```
+
+You should see output like:
+```
+INFO[...] Starting Kosmi bridge test
+INFO[...] Launching headless Chrome for Kosmi connection
+INFO[...] Injecting WebSocket interceptor (runs before page load)...
+INFO[...] Navigating to Kosmi room: https://app.kosmi.io/room/@hyperspaceout
+INFO[...] ✓ WebSocket hook confirmed installed
+INFO[...] Status: WebSocket connection intercepted
+INFO[...] Successfully connected to Kosmi via Chrome
+INFO[...] Listening for messages... Press Ctrl+C to exit
+```
+
+**Test it**: Send a message in the Kosmi room from your browser. You should see it appear in the terminal like:
+```
+INFO[...] Received message: [00:02:51] username: [Kosmi] <username> your message here
+```
+
+## Step 2: Integrate with Full Matterbridge
+
+### Option A: Copy into Existing Matterbridge
+
+If you already have Matterbridge:
+
+```bash
+# Navigate to your Matterbridge directory
+cd /path/to/matterbridge
+
+# Copy the Kosmi bridge
+cp -r /path/to/irc-kosmi-relay/bridge/kosmi bridge/
+
+# Copy the bridge registration
+cp /path/to/irc-kosmi-relay/gateway/bridgemap/bkosmi.go gateway/bridgemap/
+
+# Add dependencies
+go get github.com/chromedp/chromedp@v0.11.2
+go mod tidy
+
+# Build
+go build
+```
+
+### Option B: Use This Repository
+
+This repository has a minimal Matterbridge structure. To add IRC support:
+
+1. Copy IRC bridge from Matterbridge:
+   ```bash
+   # From the Matterbridge repo
+   cp -r bridge/irc /path/to/irc-kosmi-relay/bridge/
+   cp gateway/bridgemap/birc.go /path/to/irc-kosmi-relay/gateway/bridgemap/
+   ```
+
+2. Update dependencies:
+   ```bash
+   cd /path/to/irc-kosmi-relay
+   go mod tidy
+   ```
+
+## Step 3: Configure
+
+Edit `matterbridge.toml`:
+
+```toml
+# Kosmi configuration
+[kosmi.hyperspaceout]
+RoomURL="https://app.kosmi.io/room/@hyperspaceout"
+
+# IRC configuration
+[irc.libera]
+Server="irc.libera.chat:6667"
+Nick="kosmi-bot"
+UseTLS=false
+
+# Gateway to connect them
+[[gateway]]
+name="kosmi-irc-relay"
+enable=true
+
+[[gateway.inout]]
+account="kosmi.hyperspaceout"
+channel="main"
+
+[[gateway.inout]]
+account="irc.libera"
+channel="#your-channel"
+```
+
+**Important**: Replace:
+- `https://app.kosmi.io/room/@hyperspaceout` with your Kosmi room URL
+- `#your-channel` with your IRC channel
+
+## Step 4: Run
+
+```bash
+./matterbridge -conf matterbridge.toml
+```
+
+Or with debug logging:
+```bash
+./matterbridge -conf matterbridge.toml -debug
+```
+
+## Step 5: Test the Relay
+
+1. **Kosmi → IRC**: Send a message in Kosmi. It should appear in IRC as:
+   ```
+   [Kosmi] <username> your message here
+   ```
+
+2. **IRC → Kosmi**: Send a message in IRC. It should appear in Kosmi as:
+   ```
+   [IRC] <username> your message here
+   ```
+
+## Troubleshooting
+
+### Test program doesn't connect
+
+**Check**:
+- Is Chrome/Chromium installed and accessible?
+- Is the room URL correct?
+- Can you access `app.kosmi.io` from your network?
+- Try with `-debug` flag for more details
+
+**Solution**:
+```bash
+# Test Chrome installation
+which google-chrome chromium chromium-browser
+
+# Test network connectivity
+curl -I https://app.kosmi.io
+
+# Run with debug
+./test-kosmi -room "YOUR_ROOM_URL" -debug
+```
+
+### Messages not relaying
+
+**Check**:
+- Are both bridges connected? Look for "Successfully connected" in logs
+- Is the gateway configuration correct?
+- Are the channel names correct?
+
+**Solution**:
+```bash
+# Run with debug to see message flow
+./matterbridge -conf matterbridge.toml -debug
+
+# Look for lines like:
+# "Received message from Kosmi"
+# "Forwarding to Matterbridge"
+# "Sending to IRC"
+```
+
+### "Room ID extraction failed"
+
+**Check**: Room URL format
+
+**Supported formats**:
+- `https://app.kosmi.io/room/@roomname`
+- `https://app.kosmi.io/room/roomid`
+- `@roomname`
+- `roomid`
+
+**Solution**: Use the full URL from your browser's address bar
+
+### Messages not appearing from Kosmi
+
+**Check**:
+- Is the WebSocket hook installed? Look for "✓ WebSocket hook confirmed installed"
+- Is the WebSocket connection detected? Look for "Status: WebSocket connection intercepted"
+- Are messages being captured? Enable debug logging to see message processing
+
+**Solution**:
+The bridge uses headless Chrome with a WebSocket interceptor that runs **before page load**. This is critical for capturing messages. The implementation uses `Page.addScriptToEvaluateOnNewDocument` to ensure the hook is installed before any page JavaScript executes.
+
+If messages still aren't appearing:
+1. Check Chrome console logs in debug mode
+2. Verify the room URL is correct
+3. Try sending a test message and watch the debug output
+
+### Cannot send messages to Kosmi
+
+The send functionality uses the headless Chrome instance to inject messages into the Kosmi chat input field.
+
+**To debug**:
+1. Enable debug logging with `-debug` flag
+2. Look for "Sending message to Kosmi" in logs
+3. Check for any JavaScript errors in the browser console logs
+
+## Next Steps
+
+- **Customize message format**: Edit the format strings in `kosmi.go`
+- **Add more bridges**: Matterbridge supports Discord, Slack, Telegram, etc.
+- **Set up as a service**: Use systemd or similar to run automatically
+- **Monitor logs**: Set up log rotation and monitoring
+
+## Getting Help
+
+- Check `INTEGRATION.md` for detailed integration steps
+- Check `README.md` for architecture details
+- Enable debug logging for detailed troubleshooting
+- Review the chrome extension code in `.examples/` for API details
+
+## Common Use Cases
+
+### Home Server Setup
+
+```toml
+# Bridge your Kosmi room with your home IRC server
+[kosmi.gamenight]
+RoomURL="https://app.kosmi.io/room/@gamenight"
+
+[irc.home]
+Server="irc.home.local:6667"
+Nick="kosmi-relay"
+UseTLS=false
+
+[[gateway]]
+name="gamenight"
+enable=true
+
+[[gateway.inout]]
+account="kosmi.gamenight"
+channel="main"
+
+[[gateway.inout]]
+account="irc.home"
+channel="#gamenight"
+```
+
+### Multiple Rooms
+
+```toml
+# Bridge multiple Kosmi rooms
+[kosmi.room1]
+RoomURL="https://app.kosmi.io/room/@room1"
+
+[kosmi.room2]
+RoomURL="https://app.kosmi.io/room/@room2"
+
+[irc.libera]
+Server="irc.libera.chat:6667"
+Nick="kosmi-bot"
+
+# Gateway for room1
+[[gateway]]
+name="gateway1"
+enable=true
+
+[[gateway.inout]]
+account="kosmi.room1"
+channel="main"
+
+[[gateway.inout]]
+account="irc.libera"
+channel="#room1"
+
+# Gateway for room2
+[[gateway]]
+name="gateway2"
+enable=true
+
+[[gateway.inout]]
+account="kosmi.room2"
+channel="main"
+
+[[gateway.inout]]
+account="irc.libera"
+channel="#room2"
+```
+
+## Success!
+
+If you see messages flowing both ways, congratulations! Your Kosmi-IRC bridge is working. 🎉
+
+For advanced configuration and features, see the full documentation in `README.md` and `INTEGRATION.md`.
+