simple-auth working on test client, about to implement in main client
This commit is contained in:
cottongin
248
cmd/kosmi-client/README.md
Normal file
248
cmd/kosmi-client/README.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user