# SDKs

Offizielle Client-Bibliotheken für die Pocket Alert API. Sie sind schlank und typisiert: Authentifizierung, Request-/Response-Typen, Fehlerklassen, Wiederholungen und Pagination übernehmen sie für dich.

| Sprache | Paket | Installation | Quellcode |
|----------|---------|---------|--------|
| Node.js / TypeScript | `pocketalert` | `npm install pocketalert` | [pocketalert-node](https://github.com/PocketAlert/pocketalert-node) |
| Python | `pocketalert` | `pip install pocketalert` | [pocketalert-python](https://github.com/PocketAlert/pocketalert-python) |
| Go | `github.com/PocketAlert/pocketalert-go` | `go get github.com/PocketAlert/pocketalert-go` | [pocketalert-go](https://github.com/PocketAlert/pocketalert-go) |
| PHP | `pocketalert/pocketalert-php` | `composer require pocketalert/pocketalert-php` | [pocketalert-php](https://github.com/PocketAlert/pocketalert-php) |

Jedes SDK liest den API-Schlüssel aus der Umgebungsvariable `POCKETALERT_API_KEY`, wenn du keinen übergibst. Erstelle einen Schlüssel auf der Seite [API-Schlüssel](https://pocketalert.app/account/apikeys).

## Eine Push-Nachricht senden

**Node.js**

```ts
import PocketAlert from 'pocketalert';

const client = new PocketAlert(); // reads POCKETALERT_API_KEY

await client.messages.send({
  title: 'Deploy finished',
  message: 'v1.4.2 is live',
  level: 'high',
});
```

**Python**

```python
from pocketalert import PocketAlert

client = PocketAlert()  # reads POCKETALERT_API_KEY

client.messages.send(
    title="Deploy finished",
    message="v1.4.2 is live",
    level="high",
)
```

**Go**

```go
client, err := pocketalert.NewClient() // reads POCKETALERT_API_KEY
if err != nil {
	log.Fatal(err)
}

_, err = client.Messages.Send(ctx, pocketalert.SendMessageParams{
	Title:   "Deploy finished",
	Message: "v1.4.2 is live",
	Level:   pocketalert.LevelHigh,
})
```

**PHP**

```php
use PocketAlert\Client;
use PocketAlert\Level;

$client = new Client(); // reads POCKETALERT_API_KEY

$client->messages->send(
    title: 'Deploy finished',
    message: 'v1.4.2 is live',
    level: Level::High,
);
```

## Was die SDKs abdecken

| Ressource | Methoden |
|----------|---------|
| Nachrichten | send, list (paginiert), iterate (automatische Pagination), get, delete, mark read, mark all read, stats, usage |
| Geplante Nachrichten | list, cancel |
| Anwendungen | list, get, create, update, delete |
| Geräte | list, get, update, delete |
| Webhooks | list, get, create, update, delete, history |
| API-Schlüssel | list, create, delete |

`send` unterstützt alle Nachrichten-Funktionen: [Prioritätsstufen](https://info.pocketalert.app/features/priority-levels.md), [Aktionsbuttons](https://info.pocketalert.app/features/action-buttons.md), [geplanter Versand](https://info.pocketalert.app/features/scheduled-delivery.md) (`send_at` / `delay`) und Bildanhänge (eine URL oder ein Base64-String oder ein Datei-Upload).

## Fehler

Antworten mit einem Status außerhalb von 2xx lösen typisierte Fehler aus: `AuthenticationError` (401), `PermissionDeniedError` (403, z. B. eine kostenpflichtige Funktion im kostenlosen Tarif), `NotFoundError` (404), `RateLimitError` (429, mit `limit`, `used` und `resets_at`, wenn das [Tageslimit](https://info.pocketalert.app/features/daily-limits.md) erreicht ist), und so weiter. Go gibt einen `*APIError` zurück, mit Hilfsfunktionen wie `pocketalert.IsRateLimited(err)`; PHP wirft Exceptions aus `PocketAlert\Exception`.

## Wiederholungen und Idempotenz

Lese-, Update- und Lösch-Requests werden bei Netzwerkfehlern und 5xx-Antworten bis zu 2-mal wiederholt. Beim Senden einer Nachricht erfolgt bei diesen Fehlern keine Wiederholung, damit eine instabile Verbindung dieselbe Push-Benachrichtigung nicht zweimal zustellt. Ein `429` mit kurzem `Retry-After` wird für jeden Request wiederholt, da nichts gespeichert wurde.

Jeder `send`-Aufruf enthält einen `Idempotency-Key`-Header. Du kannst deinen eigenen Schlüssel übergeben, um Wiederholungen in deinem Code einer einzelnen Nachricht zuzuordnen.

## Zeitstempel

`created_at` und `deliver_at` werden als Anzeige-Strings in der Zeitzone deines Kontos zurückgegeben (`DD.MM.YYYY HH:MM:SS`); die SDKs behalten sie als Strings bei. `deliver_at_utc` und `resets_at` sind RFC 3339.

## OpenAPI

Die SDKs werden gegen die OpenAPI-Beschreibung unter [pocketalert.app/openapi.json](https://pocketalert.app/openapi.json) getestet. Nutze sie, um einen Client für eine andere Sprache zu generieren.
