moved docs

docs/API-QUICKSTART.md

@@ -0,0 +1,172 @@
+# Paarrot API Quick Start
+
+A local HTTP API server for controlling Paarrot from external devices like Stream Deck, scripts, and automation tools.
+
+## 🚀 Getting Started
+
+The API server starts automatically when you run Paarrot. It listens on `http://127.0.0.1:33384`.
+
+### Test the API
+
+**Option 1: Using Postman**
+
+Import the Postman collection for easy testing:
+1. Open Postman
+2. Click **Import** → **File**
+3. Select `paarrot-api.postman_collection.json`
+4. All endpoints will be ready to use!
+
+The collection is automatically updated on git push.
+
+**Option 2: Using the test script**
+```bash
+node test-api.js
+```
+
+**Option 3: Using curl**
+```bash
+./test-api.sh
+```
+
+**Option 4: Manual curl commands**
+```bash
+# Health check
+curl http://127.0.0.1:33384/health
+
+# Toggle mute
+curl -X POST http://127.0.0.1:33384/mute/toggle
+
+# Send message
+curl -X POST http://127.0.0.1:33384/message/current \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Hello from API!"}'
+```
+
+## 📝 Quick Reference
+
+### Common Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Check if API is running |
+| `/status` | GET | Get app status (mute, deafen, etc.) |
+| `/mute/toggle` | POST | Toggle microphone mute |
+| `/deafen/toggle` | POST | Toggle deafen |
+| `/channels` | GET | Get list of rooms |
+| `/channel` | POST | Switch to a room |
+| `/message/current` | POST | Send message to current room |
+
+## 🎮 Stream Deck Integration
+
+1. Install the "API Ninja" or "HTTP Request" plugin
+2. Create buttons with these settings:
+
+**Mute Toggle Button:**
+- URL: `http://127.0.0.1:33384/mute/toggle`
+- Method: POST
+
+**Quick Message Button:**
+- URL: `http://127.0.0.1:33384/message/current`
+- Method: POST
+- Body: `{"message": "BRB!"}`
+
+## 🔧 Integration with Paarrot
+
+To enable full functionality, you need to implement the action handlers in the Cinny frontend:
+
+1. Import the API handler in your app initialization:
+```typescript
+import { initPaarrotAPI } from './app/paarrot-api';
+
+// After Matrix client is initialized
+initPaarrotAPI(matrixClient);
+```
+
+2. Implement the TODO items in `cinny/src/app/paarrot-api.ts`:
+   - Mute/unmute logic (WebRTC audio)
+   - Deafen logic (WebRTC audio output)
+   - Navigation to rooms (router integration)
+   - Get current room from URL/state
+
+## 📖 Full Documentation
+
+See [API.md](API.md) for complete API documentation including:
+- All available endpoints
+- Request/response formats
+- Error handling
+- Code examples in multiple languages
+- Detailed integration guide
+
+## 🛠️ Configuration
+
+Edit `electron/api-server.js` to customize:
+- Port number (default: 33384)
+- Timeout duration (default: 10s)
+- CORS settings
+
+## 🐛 Troubleshooting
+
+**API not responding:**
+1. Check if Paarrot is running
+2. Look for "Paarrot API server listening" in console logs
+3. Verify port 33384 is not in use: `lsof -i :33384`
+
+**Actions not working:**
+1. Check browser console for errors
+2. Ensure `initPaarrotAPI()` is called in your app
+3. Implement the TODO items in `paarrot-api.ts`
+
+**Port in use:**
+Edit `electron/api-server.js` and change the port number in the constructor.
+
+## 📦 Files
+
+- `electron/api-server.js` - API server implementation
+- `cinny/src/app/paarrot-api.ts` - Client-side handler (needs implementation)
+- `test-api.js` - Node.js test script
+- `test-api.sh` - Bash test script
+- `API.md` - Full documentation
+
+## 🔐 Security
+
+- API only listens on localhost (127.0.0.1)
+- Not accessible from network
+- No authentication required (local only)
+- CORS enabled for all origins (safe since localhost only)
+
+## 💡 Examples
+
+**Python Script:**
+```python
+import requests
+
+def toggle_mute():
+    r = requests.post('http://127.0.0.1:33384/mute/toggle')
+    print(r.json())
+
+toggle_mute()
+```
+
+**JavaScript:**
+```javascript
+async function sendQuickMessage(msg) {
+  const res = await fetch('http://127.0.0.1:33384/message/current', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message: msg })
+  });
+  return res.json();
+}
+```
+
+## 🎯 Next Steps
+
+1. Run Paarrot: `npm run dev`
+2. Test the API: `node test-api.js`
+3. Integrate the handler: Import and call `initPaarrotAPI()`
+4. Implement the TODO items in `paarrot-api.ts`
+5. Create Stream Deck buttons or automation scripts!
+
+---
+
+For more details, see [API.md](API.md)