IRC-kosmi-relay/QUICKSTART.md

# 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`.