# SDK

Bibliothèques clientes officielles pour l’API Pocket Alert. Elles sont légères et typées : l’authentification, les types de requêtes et de réponses, les classes d’erreurs, les nouvelles tentatives et la pagination sont gérés pour vous.

| Langage | Paquet | Installation | Source |
|----------|---------|---------|--------|
| 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) |

Chaque SDK lit la clé API depuis la variable d’environnement `POCKETALERT_API_KEY` si vous n’en passez pas une. Créez une clé sur la page [Clés API](https://pocketalert.app/account/apikeys).

## Envoyer un message

**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,
);
```

## Ce que couvrent les SDK

| Ressource | Méthodes |
|----------|---------|
| Messages | send, list (paginée), iterate (pagination automatique), get, delete, mark read, mark all read, stats, usage |
| Messages programmés | list, cancel |
| Applications | list, get, create, update, delete |
| Appareils | list, get, update, delete |
| Webhooks | list, get, create, update, delete, history |
| Clés API | list, create, delete |

`send` prend en charge toutes les fonctionnalités des messages : [niveaux](https://info.pocketalert.app/features/priority-levels.md), [boutons d’action](https://info.pocketalert.app/features/action-buttons.md), [envoi programmé](https://info.pocketalert.app/features/scheduled-delivery.md) (`send_at` / `delay`) et pièces jointes image (une URL ou une chaîne base64, ou un téléversement de fichier).

## Erreurs

Les réponses non 2xx lèvent des erreurs typées : `AuthenticationError` (401), `PermissionDeniedError` (403, par exemple une fonctionnalité payante sur l’offre gratuite), `NotFoundError` (404), `RateLimitError` (429, avec `limit`, `used` et `resets_at` lorsque la [limite quotidienne](https://info.pocketalert.app/features/daily-limits.md) est atteinte), et ainsi de suite. Go renvoie un `*APIError` accompagné d’utilitaires tels que `pocketalert.IsRateLimited(err)` ; PHP lève des exceptions de `PocketAlert\Exception`.

## Nouvelles tentatives et idempotence

Les requêtes de lecture, de mise à jour et de suppression sont relancées jusqu’à 2 fois en cas d’erreur réseau et de réponses 5xx. L’envoi d’un message n’est pas relancé sur ces erreurs, afin qu’un réseau instable ne puisse pas délivrer deux fois la même notification push. Une réponse `429` accompagnée d’un `Retry-After` court est relancée pour toutes les requêtes, car rien n’a été enregistré.

Chaque appel à `send` transmet un en-tête `Idempotency-Key`. Vous pouvez passer votre propre clé pour lier les nouvelles tentatives de votre code à un seul message.

## Horodatages

`created_at` et `deliver_at` sont renvoyés sous forme de chaînes d’affichage dans le fuseau horaire de votre compte (`DD.MM.YYYY HH:MM:SS`) ; les SDK les conservent sous forme de chaînes. `deliver_at_utc` et `resets_at` sont au format RFC 3339.

## OpenAPI

Les SDK sont testés avec la description OpenAPI disponible sur [pocketalert.app/openapi.json](https://pocketalert.app/openapi.json). Utilisez-la pour générer un client dans n’importe quel autre langage.
