# Web-Dialog Integration mit `yourchat2`

Diese Doku beschreibt, wie eine Web-Applikation den Chat-Dialog mit dem Daemon `yourchat2` verbindet.
Sie ist absichtlich auf das Protokoll und die Client-Integration fokussiert (ohne Betriebs-/Startanleitung).

## Verbindung

- Transport: WebSocket
- Standard-Endpunkt: `ws://<host>:1235`
- Nachrichtenformat: JSON (ein JSON-Objekt pro WebSocket-Frame)

## Verbindungs- und Login-Flow

1. WebSocket verbinden
2. `init` senden
3. Token (`type: 1`) aus der Antwort speichern
4. Alle weiteren auth-pflichtigen Commands mit `token` senden

### `init` Beispiel

```json
{
  "type": "init",
  "name": "alice_1",
  "room": "lobby",
  "password": ""
}
```

## Wichtige Antworttypen

- Token:

```json
{"type":1,"message":"<token>"}
```

- Raumliste:

```json
{"type":3,"message":[{"name":"lobby","users":2}]}
```

- Raum betreten / Status:

```json
{"type":5,"message":"room_entered","to":"lobby"}
```

- Erzwungenes Logout bei Session-Ersatz (Reconnect mit gleichem Namen):

```json
{"type":5,"message":"logout","reason":"replaced_by_new_login"}
```

- Chatnachricht:

```json
{"type":"message","userName":"alice","message":"Hallo","color":"#33aaee"}
```

- Fehler:

```json
{"type":"error","message":"invalid_token"}
```

## Commands (WebSocket JSON)

Nach erfolgreichem `init` (mit `token`):

- Nachricht senden

```json
{"type":"message","message":"Hallo zusammen","token":"..."}
```

- Raum wechseln

```json
{"type":"join","room":"sports","password":"","token":"..."}
```

- Räume abfragen

```json
{"type":"rooms","token":"..."}
```

- Userliste des aktuellen Raums

```json
{"type":"userlist","token":"..."}
```

- Farbe setzen

```json
{"type":"color","value":"#33aaee","token":"..."}
```

- Aktionen

```json
{"type":"scream","message":"Hallo alle","token":"..."}
{"type":"do","message":"winkt","token":"..."}
{"type":"dice","message":"1d6","token":"..."}
{"type":"roll","value":4,"token":"..."}
```

- Dice-Game

```json
{"type":"start_dice_game","rounds":3,"token":"..."}
{"type":"end_dice_game","token":"..."}
```

- Räume neu laden

```json
{"type":"reload_rooms","token":"..."}
```

## Slash-Commands im Dialogtext

Wenn das Frontend nur `type:"message"` sendet, werden folgende Slash-Kommandos serverseitig erkannt:

- `/join <room> [password]`
- `/color <hex>`
- `/dice [expr]`
- `/roll [wert]`
- `/start_dice_game <runden>`
- `/end_dice_game`
- `/reload_rooms`
- `/do <aktion>`
- `/scream <text>`
- `/rooms`
- `/userlist`

Beispiel:

```json
{"type":"message","message":"/join lounge geheim","token":"..."}
```

## Minimales Browser-Beispiel (Vanilla JS)

```javascript
const ws = new WebSocket("ws://127.0.0.1:1235");
let token = null;

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "init",
    name: "alice_1",
    room: "lobby",
    password: ""
  }));
};

ws.onmessage = (ev) => {
  const msg = JSON.parse(ev.data);

  if (msg.type === 1) {
    token = msg.message;
    return;
  }

  if (msg.type === "error") {
    console.error("chat error:", msg.message);
    return;
  }

  if (msg.type === "message") {
    console.log(`${msg.userName}: ${msg.message}`);
    return;
  }

  console.log("chat event:", msg);
};

function sendMessage(text) {
  if (!token) return;
  ws.send(JSON.stringify({ type: "message", message: text, token }));
}
```

## Häufige Fehlercodes

- `missing_name`: `init` ohne `name`
- `invalid_username`: Username entspricht nicht den Regeln
- `user_not_allowed`: User nicht erlaubt (DB/Allowlist)
- `not_initialized`: Command vor `init`
- `missing_token`: Token fehlt
- `invalid_token`: Token stimmt nicht
- `room_not_found_or_join_failed`: Raumzugriff verweigert (Passwort/Alter/Regeln)
- `permission_denied`: fehlende Rechte (z. B. Dice-Admin-Operationen)

## Hinweise für Frontend-Implementierung

- Token zentral im Chat-State halten
- Reconnect-Strategie einbauen (neues `init`, neues Token); alte Session wird dabei serverseitig ersetzt
- Vor Senden auth-pflichtiger Commands Token prüfen
- UI sollte Fehler vom Typ `error` immer sichtbar machen
- Für Slash-Kommandos reicht normales `message`-Senden