IRC-kosmi-relay/INTEGRATION.md

## Integrating Kosmi Bridge into Full Matterbridge

This document explains how to integrate the Kosmi bridge into the full Matterbridge codebase.

## Current Status

The Kosmi bridge has been implemented as a standalone module with the following components:

### Implemented Features ✅

1. **WebSocket Connection**: Full GraphQL-WS protocol implementation
2. **Message Reception**: Subscribes to Kosmi chat messages and forwards to Matterbridge
3. **Message Sending**: Sends messages to Kosmi via GraphQL mutations
4. **Bridge Registration**: Properly registered in the bridgemap
5. **Configuration Support**: TOML configuration with room URL and server settings

### File Structure

```
bridge/
├── bridge.go           # Bridge interface and config (minimal implementation)
├── config/
│   └── config.go       # Message and channel structures
└── kosmi/
    ├── kosmi.go        # Main bridge implementation
    └── graphql.go      # GraphQL WebSocket client

gateway/
└── bridgemap/
    ├── bridgemap.go    # Bridge factory registry
    └── bkosmi.go       # Kosmi bridge registration

cmd/
└── test-kosmi/
    └── main.go         # Standalone test program

matterbridge.toml       # Example configuration
go.mod                  # Go module dependencies
```

## Integration Steps

To integrate this into the full Matterbridge project:

### Option 1: Copy into Existing Matterbridge

1. **Copy the Kosmi bridge files**:
   ```bash
   # From the matterbridge repository root
   cp -r /path/to/irc-kosmi-relay/bridge/kosmi bridge/kosmi
   cp /path/to/irc-kosmi-relay/gateway/bridgemap/bkosmi.go gateway/bridgemap/
   ```

2. **Update go.mod** (if needed):
   ```bash
   go get github.com/gorilla/websocket@v1.5.1
   go mod tidy
   ```

3. **Build Matterbridge**:
   ```bash
   go build
   ```

4. **Configure** (add to your matterbridge.toml):
   ```toml
   [kosmi.hyperspaceout]
   RoomURL="https://app.kosmi.io/room/@hyperspaceout"
   
   [[gateway]]
   name="kosmi-irc"
   enable=true
   
   [[gateway.inout]]
   account="kosmi.hyperspaceout"
   channel="main"
   
   [[gateway.inout]]
   account="irc.libera"
   channel="#your-channel"
   ```

5. **Run**:
   ```bash
   ./matterbridge -conf matterbridge.toml
   ```

### Option 2: Use as Standalone (Current Setup)

The current implementation can work standalone but requires the full Matterbridge gateway logic. To use it standalone:

1. **Test the Kosmi connection**:
   ```bash
   ./test-kosmi -room "https://app.kosmi.io/room/@hyperspaceout" -debug
   ```

2. **Implement a simple gateway** (you would need to add):
   - IRC bridge implementation (or copy from Matterbridge)
   - Gateway routing logic to relay messages between bridges
   - Main program that initializes both bridges

## Testing the Bridge

### Test 1: Kosmi Connection Only

```bash
# Build and run the test program
go build -o test-kosmi ./cmd/test-kosmi
./test-kosmi -room "https://app.kosmi.io/room/@hyperspaceout" -debug
```

Expected output:
```
INFO[...] Starting Kosmi bridge test
INFO[...] Room URL: https://app.kosmi.io/room/@hyperspaceout
INFO[...] Connecting to Kosmi...
INFO[...] Connecting to Kosmi GraphQL WebSocket: wss://engine.kosmi.io/gql-ws
INFO[...] WebSocket connection established
INFO[...] Sent connection_init message
INFO[...] Received connection_ack
INFO[...] GraphQL WebSocket handshake completed
INFO[...] Subscribed to messages in room: hyperspaceout
INFO[...] Successfully connected to Kosmi!
INFO[...] Starting message listener
INFO[...] Listening for messages... Press Ctrl+C to exit
```

When someone sends a message in the Kosmi room, you should see:
```
INFO[...] Received message: [15:04:05] Username: [Kosmi] <Username> message text
```

### Test 2: Full Integration with IRC

Once integrated into full Matterbridge:

1. **Start Matterbridge** with Kosmi configured
2. **Send a message in Kosmi** → Should appear in IRC as `[Kosmi] <username> message`
3. **Send a message in IRC** → Should appear in Kosmi as `[IRC] <username> message`

## Reverse Engineering Notes

### GraphQL API Details

The Kosmi bridge uses the following GraphQL operations:

**Subscription** (implemented and tested):
```graphql
subscription {
  newMessage(roomId: "roomId") {
    body
    time
    user {
      displayName
      username
    }
  }
}
```

**Mutation** (implemented but needs testing):
```graphql
mutation {
  sendMessage(roomId: "roomId", body: "message text") {
    id
  }
}
```

### Potential Issues

1. **Message Sending**: The `sendMessage` mutation is based on common GraphQL patterns but may need adjustment based on Kosmi's actual API. If sending doesn't work:
   - Use browser DevTools to capture the actual mutation
   - Update `graphql.go` SendMessage() method with correct mutation format

2. **Room ID Format**: The bridge supports both `@roomname` and `roomid` formats. If connection fails:
   - Check the actual room ID in browser DevTools
   - Update `extractRoomID()` function in `kosmi.go`

3. **Authentication**: Currently connects anonymously. If Kosmi adds authentication:
   - Add auth token configuration
   - Update `Connect()` to include auth headers

## Browser-Based Testing

To verify the GraphQL API structure:

1. **Open Kosmi room** in browser
2. **Open DevTools** → Network tab
3. **Filter by WS** (WebSocket)
4. **Click on the WebSocket connection** to `engine.kosmi.io`
5. **View messages** to see the exact GraphQL format

Example messages you might see:
```json
// Outgoing subscription
{
  "id": "1",
  "type": "start",
  "payload": {
    "query": "subscription { newMessage(roomId: \"...\") { ... } }"
  }
}

// Incoming message
{
  "type": "next",
  "id": "1",
  "payload": {
    "data": {
      "newMessage": {
        "body": "Hello!",
        "time": 1730349600,
        "user": {
          "displayName": "User",
          "username": "user123"
        }
      }
    }
  }
}
```

## Next Steps

1. **Test message sending**: Send a test message from the bridge to verify the mutation works
2. **Add IRC bridge**: Either integrate into full Matterbridge or implement a minimal IRC bridge
3. **Test bidirectional relay**: Verify messages flow both ways correctly
4. **Add error handling**: Improve reconnection logic and error recovery
5. **Add features**:
   - User presence/join/leave events
   - File/image sharing (if supported by Kosmi)
   - Message editing/deletion
   - Typing indicators

## Troubleshooting

### "Connection refused" or "dial tcp: lookup engine.kosmi.io"
- Check network connectivity
- Verify DNS resolution
- Check firewall rules

### "Connection closed unexpectedly"
- Enable debug logging: `-debug` flag
- Check if Kosmi API has changed
- Verify room ID is correct

### "Messages not appearing"
- Check message format in logs
- Verify subscription is active
- Test with browser DevTools to compare

### "Cannot send messages"
- The mutation may need adjustment
- Check browser DevTools for actual mutation format
- Update `SendMessage()` in `graphql.go`

## Contributing

To improve the bridge:

1. **Test thoroughly** with actual Kosmi rooms
2. **Document any API changes** you discover
3. **Add unit tests** for critical functions
4. **Improve error handling** and logging
5. **Add reconnection logic** for network issues

## License

Same as Matterbridge (Apache 2.0)