# SDK

Librerie client ufficiali per l'API di Pocket Alert. Sono leggere e tipizzate: autenticazione, tipi di richiesta e risposta, classi di errore, retry e paginazione sono gestiti per te.

| Linguaggio | Pacchetto | Installazione | Sorgente |
|----------|---------|---------|--------|
| 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) |

Ogni SDK legge la chiave API dalla variabile d'ambiente `POCKETALERT_API_KEY` se non la passi tu. Crea una chiave nella pagina [API Keys](https://pocketalert.app/account/apikeys).

## Inviare un messaggio

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

## Cosa coprono gli SDK

| Risorsa | Metodi |
|----------|---------|
| Messaggi | send, list (con paginazione), iterate (paginazione automatica), get, delete, mark read, mark all read, stats, usage |
| Messaggi programmati | list, cancel |
| Applicazioni | list, get, create, update, delete |
| Dispositivi | list, get, update, delete |
| Webhook | list, get, create, update, delete, history |
| Chiavi API | list, create, delete |

`send` supporta tutte le funzionalità dei messaggi: [livelli](https://info.pocketalert.app/features/priority-levels.md), [pulsanti di azione](https://info.pocketalert.app/features/action-buttons.md), [invio programmato](https://info.pocketalert.app/features/scheduled-delivery.md) (`send_at` / `delay`) e allegati immagine (un URL o una stringa base64, oppure un caricamento di file).

## Errori

Le risposte diverse da 2xx generano errori tipizzati: `AuthenticationError` (401), `PermissionDeniedError` (403, ad esempio una funzionalità a pagamento sul piano gratuito), `NotFoundError` (404), `RateLimitError` (429, con `limit`, `used` e `resets_at` quando viene raggiunto il [limite giornaliero](https://info.pocketalert.app/features/daily-limits.md)), e così via. Go restituisce un `*APIError` con funzioni di utilità come `pocketalert.IsRateLimited(err)`; PHP lancia eccezioni da `PocketAlert\Exception`.

## Retry e idempotenza

Le richieste di lettura, aggiornamento ed eliminazione vengono ritentate fino a 2 volte in caso di errori di rete e risposte 5xx. L'invio di un messaggio non viene ritentato in questi casi, così una rete instabile non può consegnare due volte la stessa notifica push. Una risposta `429` con un `Retry-After` breve viene ritentata per ogni richiesta, dato che non è stato salvato nulla.

Ogni chiamata a `send` include l'header `Idempotency-Key`. Puoi passare una chiave tua per associare i retry nel tuo codice a un singolo messaggio.

## Timestamp

`created_at` e `deliver_at` vengono restituiti come stringhe leggibili nel fuso orario del tuo account (`DD.MM.YYYY HH:MM:SS`); gli SDK le mantengono come stringhe. `deliver_at_utc` e `resets_at` sono in formato RFC 3339.

## OpenAPI

Gli SDK sono testati sulla descrizione OpenAPI disponibile su [pocketalert.app/openapi.json](https://pocketalert.app/openapi.json). Usala per generare un client per qualsiasi altro linguaggio.
