seven_send/README.md

# seven-send

Kleine, wiederverwendbare **Library + CLI** zum Verschicken von **SMS** und
**TTS-Sprachanrufen** über die [seven.io](https://www.seven.io)-API. Bewusst
provider-fokussiert und schlank — als Baustein für beliebige Programme, Cron-Jobs
oder Monitoring-Alerts.

## Installation

```bash
pipx install git+https://kitux.de/forgejo/dschlueter/seven_send.git
# oder lokal zur Entwicklung:
pip install -e ".[dev]"
```

## CLI

```bash
export SEVEN_API_KEY=dein-key

seven-send sms   --to +4915112345678 --text "Hallo Welt"
seven-send sms   --to +4915112345678 --text "Hallo Welt" --from "MeineFirma"   # Absender/Titel
seven-send voice --to +4915112345678 --text "Dies wird vorgelesen." --voice de-de-female

seven-send --dry-run sms --to +49… --text "nur testen"      # nichts senden
seven-send --json    sms --to +49… --text "..."             # maschinenlesbar
```

**Absender/Titel:** Per `--from` setzbar (SMS: alphanumerischer Titel oder Nummer;
Voice: verifizierte Caller-ID). Ohne `--from` greift `$SEVEN_SMS_FROM` /
`$SEVEN_VOICE_FROM`, sonst der **Kontostandard-Absender** von seven.io — es gibt
**keinen** eingebauten Default-Absender.

Exit-Codes: `0` Erfolg · `1` Sendefehler · `2` Konfig-/Aufruf-Fehler.

## Library

```python
from seven_send import SevenClient

c = SevenClient(api_key, sms_from="MeineFirma", voice_name="de-de-female")

res = c.send_sms("+4915112345678", "Hallo")
if not res:                      # bool(res) == res.ok
    print("Fehler:", res.error)

c.send_voice("+4915112345678", "Achtung, dies ist eine Ansage.")
```

`SevenClient` ist **synchron**. Aus asynchronem Code:

```python
res = await asyncio.to_thread(c.send_sms, "+49…", "Hallo")
```

## Konfiguration

| Parameter | Default | Bedeutung |
|-----------|---------|-----------|
| `api_key` | – | seven.io API-Key (oder `$SEVEN_API_KEY` für die CLI) |
| `sms_from` | `None` | Absender-ID/Titel der SMS (alphanumerisch max. 11 Zeichen oder Nummer); leer = Kontostandard |
| `voice_from` | `None` | Caller-ID für Anrufe (verifizierte Nummer) |
| `voice_name` | `de-de-female` | SSML-Stimme für die Anruf-Ansage |
| `dry_run` | `False` | nichts senden, nur protokollieren |

## Test

```bash
pip install -e ".[dev]"
pytest -q
```

## Lizenz

MIT — siehe [LICENSE](LICENSE).