IRC-kosmi-relay/cmd/kosmi-client/README.md

# Kosmi Client - Standalone CLI Chat Client

A simple, standalone command-line client for Kosmi that demonstrates WebSocket communication, GraphQL operations, and real-time chat functionality.

## Features

- ✅ Manual JWT token authentication
- ✅ Email/password authentication with browser automation
- ✅ Interactive CLI for sending/receiving messages
- ✅ Real-time message subscription
- ✅ Graceful shutdown (Ctrl+C)

## Prerequisites

- Go 1.21 or higher
- A Kosmi account (for authenticated access)
- JWT token from your browser session

## Installation

```bash
cd cmd/kosmi-client
go mod download
go build
```

## Getting Your JWT Token

To use this client, you need to extract your JWT token from the Kosmi web application:

### Method 1: Browser DevTools (Recommended)

1. Open [https://app.kosmi.io](https://app.kosmi.io) in your browser
2. Log in to your account
3. Open Developer Tools (F12 or Right-click → Inspect)
4. Go to the **Console** tab
5. Type the following command and press Enter:
   ```javascript
   localStorage.getItem('token')
   ```
6. Copy the token (it will be a long string starting with `eyJ...`)

### Method 2: Network Tab

1. Open [https://app.kosmi.io](https://app.kosmi.io) in your browser
2. Open Developer Tools (F12)
3. Go to the **Network** tab
4. Filter by "WS" (WebSocket)
5. Look for the connection to `engine.kosmi.io`
6. Click on it and view the **Messages** tab
7. Find the `connection_init` message
8. Copy the token from the payload

## Usage

### Basic Usage

**Option 1: Email/Password (Recommended)**
```bash
./kosmi-client --email "your@email.com" --password "yourpassword" --room "@hyperspaceout"
```

**Option 2: Manual Token**
```bash
./kosmi-client --token "YOUR_JWT_TOKEN" --room "@hyperspaceout"
```

### Command-Line Options

| Flag | Description | Required | Example |
|------|-------------|----------|---------|
| `--token` | JWT authentication token | Yes* | `--token "eyJ..."` |
| `--room` | Room ID to join | Yes | `--room "@hyperspaceout"` |
| `--email` | Email for login | Yes* | `--email "user@example.com"` |
| `--password` | Password for login | Yes* | `--password "secret"` |

\* Either `--token` OR both `--email` and `--password` are required

### Interactive Commands

Once connected, you can use these commands:

- **Send a message**: Just type your message and press Enter
- `/help` - Show available commands
- `/quit` or `/exit` - Exit the client
- **Ctrl+C** - Graceful shutdown

### Example Session

```
$ ./kosmi-client --email "email@email.com" --password "password" --room "@hyperspaceout"

Connecting to Kosmi WebSocket...
Sending connection_init...
✓ Connection acknowledged
Querying current user...
✓ Logged in as: John Doe (@johndoe) [Anonymous: false]
Joining room: @hyperspaceout...
✓ Successfully joined room
Subscribing to new messages...
✓ Subscription active
Connection setup complete!

============================================================
Connected! Type messages and press Enter to send.
Press Ctrl+C to exit.
============================================================

> Hello, world!
> [14:23:45] Jane Smith: Hey there!
> How are you?
> [14:24:01] Jane Smith: I'm good, thanks!
> /quit
Exiting...
Closing Kosmi client...
✓ Client closed
Goodbye!
```

## Architecture

The client consists of three main components:

### 1. `auth.go` - Authentication Management

- `GetToken()` - Retrieves token (manual or via chromedp)
- `loginWithChromedp()` - Browser automation for email/password login

### 2. `client.go` - WebSocket Client

- `KosmiClient` - Main client struct
- `Connect()` - Establishes connection and performs GraphQL handshake
- `SendMessage()` - Sends messages to the room
- `listenForMessages()` - Receives messages in real-time
- `Close()` - Graceful shutdown

### 3. `main.go` - CLI Interface

- Command-line argument parsing
- Interactive message input/output
- Signal handling for graceful shutdown

## GraphQL Operations

The client uses these minimal GraphQL operations:

1. **connection_init** - Authenticate with JWT token
2. **ExtendedCurrentUserQuery** - Get current user info
3. **JoinRoom** - Join the specified room
4. **NewMessageSubscription** - Subscribe to new messages
5. **SendMessage2** - Send messages to the room

## Troubleshooting

### "Authentication error: no authentication method provided"

You must provide either `--token` or both `--email` and `--password`.

### "Connection error: failed to connect to WebSocket"

- Check your internet connection
- Verify the Kosmi service is accessible
- Ensure you're not behind a restrictive firewall

### "expected connection_ack, got: connection_error"

Your JWT token is likely invalid or expired. Get a fresh token from your browser.

### Messages not appearing

- Verify you've joined the correct room ID
- Check that the room exists and you have access to it
- Ensure your token has the necessary permissions

## Helper Tools

### `cmd/get-kosmi-token` - Standalone Token Extractor

A separate utility for extracting JWT tokens without running the full client:

```bash
cd cmd/get-kosmi-token
go run main.go --email "your@email.com" --password "yourpassword"
```

Options:
- `--email` - Your Kosmi email
- `--password` - Your Kosmi password
- `--headless` - Run browser in headless mode (default: true)
- `--verbose` - Enable verbose logging

The token will be printed to stdout, making it easy to capture:
```bash
TOKEN=$(go run main.go --email "your@email.com" --password "yourpassword" 2>/dev/null)
./kosmi-client --token "$TOKEN" --room "@hyperspaceout"
```

## Future Enhancements

### Additional Features (Ideas)

- [ ] Room chat history retrieval (`RoomChatQuery`)
- [ ] Member join/leave notifications
- [ ] Typing indicators
- [ ] File/image upload support
- [ ] Multiple room support
- [ ] Persistent token storage
- [ ] Reconnection with exponential backoff
- [ ] Message editing and deletion
- [ ] Reactions and emojis

## Development

### Running from Source

```bash
go run . --token "YOUR_TOKEN" --room "@hyperspaceout"
```

### Building

```bash
go build -o kosmi-client
```

### Dependencies

- `github.com/gorilla/websocket` - WebSocket client library
- `github.com/chromedp/chromedp` - Browser automation (for future use)

## License

This is a proof-of-concept demonstration client. Use responsibly and in accordance with Kosmi's Terms of Service.

## Contributing

This is a standalone proof of concept. Feel free to fork and extend it for your own use cases!

## Support

For issues related to:
- **Kosmi service**: Contact Kosmi support
- **This client**: Check the code comments and implementation details

---

**Note**: This client is not officially affiliated with or endorsed by Kosmi. It's an independent implementation for educational and development purposes.