Metadata-Version: 2.4
Name: hidechat-bot
Version: 0.1.0
Summary: SDK für HideChat-Bots: gehostet über die Bot-Schnittstelle oder Ende-zu-Ende verschlüsselt mit eigenen Schlüsseln.
Author: Business Intelligence L.L.C-FZ
License: MIT
Keywords: hidechat,bot,sdk
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyNaCl>=1.5
Requires-Dist: websockets>=13
Dynamic: license-file

# hidechat-bot

SDK für Bots in [HideChat](https://hidechat.app) – für Python ab Version 3.10 (asyncio, mit Typ-Hinweisen). Abhängigkeiten nur `PyNaCl` und `websockets`.

- **Gehostet** (`HostedBot`): HideChat öffnet die Nachrichten an Deinen Bot und gibt sie über die Bot-Schnittstelle an Dein Programm weiter. Ereignisse per Long-Polling oder Webhook.
- **Ende-zu-Ende** (`E2eBot`): Dein Programm hat eigene Schlüssel und verbindet sich selbst mit dem Relay; HideChat kann die Nachrichten an Deinen Bot nicht lesen.

Das Paket verhält sich wie das JavaScript-SDK (`hidechat-bot` auf npm); Namen in snake_case (`answer_button` statt `answerButton`).

## Installieren

```sh
pip install https://hidechat.app/entwickler/sdk/hidechat_bot-0.1.0-py3-none-any.whl
```

Prüfsummen: [hidechat.app/entwickler/sdk/SHA256SUMS](https://hidechat.app/entwickler/sdk/SHA256SUMS). Das Paket auf PyPI folgt.

## Erster Bot (gehostet)

Den Bot-Schlüssel bekommst Du in der App unter «Meine Bots» oder in der Bot-Werkstatt. Er gehört nie in den Code, sondern in die Umgebungsvariable `HIDECHAT_BOT_TOKEN`.

```python
import os
from hidechat_bot import create_bot

bot = create_bot(mode="hosted", token=os.environ["HIDECHAT_BOT_TOKEN"])

@bot.command("start")
async def start(ev: dict) -> None:
    await bot.send(ev["chat"], "Willkommen!", buttons=[[{"text": "Hilfe", "data": "hilfe"}]])

@bot.on("button")
async def knopf(ev: dict) -> None:
    await bot.answer_button(ev["button_id"], text="Gern geschehen")

@bot.on("message")
async def echo(ev: dict) -> None:
    await bot.send(ev["chat"], f"Du hast geschrieben: {ev['text']}", reply_to=ev["mid"])

@bot.on_error
def fehler(e: BaseException) -> None:
    print("Fehler:", e)

bot.run()  # blockiert, bis Strg+C; in eigenem asyncio-Code: await bot.start() / await bot.stop()
```

`@bot.command("start")` gilt auch für den Start über einen Link `hidechat.app/b/<bot>?start=<wert>`; der Wert steht dann in `ev["param"]`.

## Ereignisse

Ereignisse sind `dict`s mit genau den Feldern der Bot-Schnittstelle: `message`, `command`, `start`, `stop`, `edited`, `deleted`, `reaction`, `button`, `vote`, `added_to_group`, `removed_from_group`, `inline_query`, `webapp_data`. Mit `@bot.on("*")` siehst Du alle. Handler dürfen `async def` oder gewöhnliche Funktionen sein.

Ein Ereignis gilt erst als erledigt, wenn alle Handler fertig sind. Fehler in Handlern gehen an `on_error`; der Bot läuft weiter.

## Methoden

`me`, `send`, `send_media`, `send_poll`, `close_poll`, `edit`, `delete`, `react`, `answer_button`, `typing`, `answer_inline`, `file`, `chat_info`, `members`, `leave`, `set_commands`, `set_profile`, `check_webapp_data`, `end_chat` (alle `async`) – im gehosteten Modus zusätzlich `set_webhook` und `delete_webhook`.

```python
await bot.send(chat, "Text", reply_to=None, buttons=None, keyboard=None, remove_keyboard=False, topic=None)  # → {"mid": …}
await bot.send_media(chat, "photo", daten, "image/png", name=None, caption="Bildtext", w=None, h=None, dur=None)
await bot.send_poll(chat, "Pizza?", ["Ja", "Nein"], multi=False)
await bot.edit(chat, mid, text="Neu", buttons=None)
await bot.answer_inline(inline_id, [{"id": "1", "title": "Pizza", "text": "Pizza!"}], next_offset=None)
daten = await bot.file(ev["media"]["file_id"])  # bytes
```

Fehler kommen als `HideChatError` mit `code` (z. B. `not_started`, `too_fast`, `bad_buttons`), `status`, `hint` (Erklärung auf Deutsch) und bei `too_fast` `retry_after`. Bei `too_fast` wiederholt das SDK einmal von selbst nach der verlangten Wartezeit (abschalten mit `retry=False`).

## Webhook

`bot.webhook_app(geheimnis)` ist ein einfacher ASGI-Aufrufer (ohne Fremdpaket); er läuft unter jedem ASGI-Server, zum Beispiel uvicorn:

```python
import os
from hidechat_bot import HostedBot

bot = HostedBot(os.environ["HIDECHAT_BOT_TOKEN"])

@bot.on("message")
async def angekommen(ev: dict) -> None:
    await bot.send(ev["chat"], "Angekommen")

# Einmalig: secret = (await bot.set_webhook("https://bot.example.com/hook"))["secret"] – Geheimnis sicher ablegen
app = bot.webhook_app(os.environ["HIDECHAT_WEBHOOK_SECRET"])
# uvicorn modul:app --port 8080
```

Der Aufrufer prüft die Signatur `X-HideChat-Signature` (sonst 401) und antwortet erst nach Deinen Handlern mit 200 (auch wenn ein Handler einen Fehler wirft; der Fehler geht an `on_error`). HideChat wartet höchstens 10 Sekunden auf die Antwort und wiederholt sonst später: **langsame Arbeit im Webhook-Handler asynchron erledigen**. Für eigene Server gibt es `verify_webhook(rohinhalt, kopf, geheimnis)`.

## Ende-zu-Ende

### Einrichten

```sh
export HIDECHAT_BOT_TOKEN=…                # Bot-Schlüssel
python -m hidechat_bot keys                # erzeugt hidechat-keys.json (überschreibt nie)
python -m hidechat_bot register            # beantragt Ende-zu-Ende
```

(Nach der Installation geht auch kurz `hidechat-bot keys` usw.) Danach bestätigst Du als Besitzer in der HideChat-App unter Einstellungen → Meine Bots → @<bot> → Betriebsart; vergleiche dort den Fingerabdruck mit der Anzeige des Programms. Vorher wirft `start()` den Fehler `not_e2e`. Zurück auf gehostet stellst Du nur als Besitzer in «Meine Bots» oder mit `/modus <bot> gehostet` in der Bot-Werkstatt um (`python -m hidechat_bot hosted` zeigt diesen Hinweis). Beim Umschalten gehen noch nicht abgeholte Ereignisse verloren.

Die Schlüsseldatei `hidechat-keys.json` gehört nie in Git (`.gitignore`) und nie in fremde Hände. Sie hat dasselbe Format wie beim JavaScript-SDK; beide lesen die Dateien des anderen. Fixture-Schlüssel (z. B. `sdk/fixtures/keys-js.TEST-ONLY.json`) sind nur für Tests – nie für echte Bots verwenden.

Im eigenen Code: `generate_keys(bot)`, `save_keys(pfad, k)`, `load_keys(pfad)`, `fingerprint(k["boxPub"], k["signPub"])` und `await register_keys(token, k)` (Ergebnis `{"mode": "pending" | "e2e", "fingerprint": …}`).

### Bot starten

```python
import os
from hidechat_bot import create_bot

bot = create_bot(
    mode="e2e",
    token=os.environ["HIDECHAT_BOT_TOKEN"],
    keys=os.environ.get("HIDECHAT_KEYS", "hidechat-keys.json"),
)

@bot.command("start")
async def start(ev: dict) -> None:
    await bot.send(ev["chat"], "Willkommen! Nur ich kann das lesen.")

bot.run()
```

Handler und Methoden sind dieselben wie im gehosteten Modus. Weitere Optionen: `state_dir` (Standard `./.hidechat-bot`), `rooms=False`, `previous_keys`, `base`. Unterschiede:

- Einzelchats öffnet und versiegelt Dein Programm selbst (Text, Knöpfe, Tastatur, Umfragen, Medien, Bearbeiten, Löschen, Reaktionen, Inline-Antworten). Räume und Kanäle (`s:…`), `typing`, `set_commands`, `set_profile`, `check_webapp_data` und `end_chat` gehen weiter über die Bot-Schnittstelle; Raum-Ereignisse holt das SDK nebenbei ab (`rooms=False` schaltet das aus).
- Private Gruppen (`g:…`) gibt es im Ende-zu-Ende-Modus nicht (`unsupported_chat`), ebenso den Baukasten.
- Ereignisnummern (`ev["id"]`) zählt das SDK lokal.
- Der Zustand liegt in `./.hidechat-bot/state.json`: Gerät, gesendete Nachrichten (für Knöpfe und Umfragen, 48 h), Schlüssel eingehender Dateien (7 Tage) usw. Er gehört wie die Schlüsseldatei nicht in Git. Bei einem Neustart mit demselben Ordner kommen wartende Nachrichten genau einmal an; Knöpfe und Umfragen von vorher gelten weiter. Eine beschädigte Datei wird nach `state.json.kaputt-<zeit>` verschoben, der Bot startet dann mit leerem Zustand.
- Jede Nachricht wird erst nach Deinen Handlern quittiert (mindestens einmal zugestellt, doppelte werden übersprungen). Scheitert die Verarbeitung (z. B. Verzeichnis kurz nicht erreichbar), versucht das SDK dieselbe Nachricht nach 1, 2, 5, 10 und 30 Sekunden erneut; die Reihenfolge bleibt.
- `send_media` verschlüsselt und lädt die Datei hoch, bevor das Relay die Zustellung prüft: Das Medien-Kontingent (600 MB pro Tag) zählt auch bei abgelehnter Zustellung (z. B. `not_started`); die Datei wird dann gleich wieder gelöscht.
- Den Zustand (`state.json`) und die Geräte-Kennung (`device.json`) im selben Ordner nicht löschen: Mit einer neuen Kennung kommen wartende Nachrichten nicht mehr an.
- Sobald Du einen Wechsel bestätigst (neue Schlüssel oder Umschalten der Betriebsart), verwirft HideChat alle Nachrichten, die beim Relay noch auf Dein Programm warten. Lass Dein Programm vorher laufen, bis es alles abgeholt hat.
- Nach einem Schlüsselwechsel (`keys` + `register` + Bestätigung) übergibst Du etwa 7 Tage lang den alten Schlüssel als `previous_keys`: Das hilft nur bei Nachrichten, die Personen nach dem Wechsel schicken, solange ihre App noch den alten Schlüssel gespeichert hat. Kann das Programm eine Nachricht nicht öffnen, bittet es die Person (höchstens einmal je 24 Stunden), sie noch einmal zu schicken.
- Die laufende Verbindung endet mit `HideChatError` `rekeyed` (neue Schlüssel oder zurück auf gehostet), `account_deleted` (Bot gelöscht), `banned`, `device_removed` oder `auth_failed`; bei Netzproblemen verbindet sich das SDK von selbst wieder. Mit `await bot.ready()` wartest Du, bis die Verbindung steht.

## Lizenz

MIT – Business Intelligence L.L.C-FZ
