Move troubleshooting and implementation docs to docs/

Relocate 30 non-essential .md files (investigation notes, fix summaries, implementation details, status reports) from the project root into docs/ to reduce clutter. Core operational docs (README, quickstart guides, configuration references) remain in the root. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-07 13:40:46 -05:00
parent 3b7a139606
commit db284d0677
30 changed files with 0 additions and 0 deletions
--- a/docs/INTEGRATION.md
+++ b/docs/INTEGRATION.md
@@ -0,0 +1,271 @@
+## 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)
+