# SDK

Bibliotecas cliente oficiales para la API de Pocket Alert. Son ligeras y tipadas: la autenticación, los tipos de solicitud y respuesta, las clases de error, los reintentos y la paginación se gestionan por ti.

| Lenguaje | Paquete | Instalación | Código fuente |
|----------|---------|-------------|---------------|
| 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) |

Todos los SDK leen la clave de API de la variable de entorno `POCKETALERT_API_KEY` si no la pasas tú. Crea una clave en la página [Claves de API](https://pocketalert.app/account/apikeys).

## Enviar un mensaje

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

## Qué cubren los SDK

| Recurso | Métodos |
|---------|---------|
| Mensajes | send, list (paginado), iterate (paginación automática), get, delete, mark read, mark all read, stats, usage |
| Mensajes programados | list, cancel |
| Aplicaciones | list, get, create, update, delete |
| Dispositivos | list, get, update, delete |
| Webhooks | list, get, create, update, delete, history |
| Claves de API | list, create, delete |

`send` admite todas las funciones de mensaje: [prioridades](https://info.pocketalert.app/features/priority-levels.md), [botones de acción](https://info.pocketalert.app/features/action-buttons.md), [envío programado](https://info.pocketalert.app/features/scheduled-delivery.md) (`send_at` / `delay`) y adjuntos de imagen (una URL o una cadena base64, o la subida de un archivo).

## Errores

Las respuestas distintas de 2xx lanzan errores tipados: `AuthenticationError` (401), `PermissionDeniedError` (403, por ejemplo, una función de pago en el plan gratuito), `NotFoundError` (404), `RateLimitError` (429, con `limit`, `used` y `resets_at` cuando se alcanza el [límite diario](https://info.pocketalert.app/features/daily-limits.md)), y así sucesivamente. Go devuelve un `*APIError` con funciones auxiliares como `pocketalert.IsRateLimited(err)`; PHP lanza excepciones de `PocketAlert\Exception`.

## Reintentos e idempotencia

Las solicitudes de lectura, actualización y eliminación se reintentan hasta 2 veces ante errores de red y respuestas 5xx. Enviar un mensaje no se reintenta ante esos errores, para que una red inestable no pueda entregar la misma notificación push dos veces. Un `429` con un `Retry-After` corto se reintenta en todas las solicitudes, ya que no se almacenó nada.

Cada llamada a `send` incluye la cabecera `Idempotency-Key`. Puedes pasar tu propia clave para vincular los reintentos de tu código a un solo mensaje.

## Marcas de tiempo

`created_at` y `deliver_at` se devuelven como cadenas de texto legibles en la zona horaria de tu cuenta (`DD.MM.YYYY HH:MM:SS`); los SDK las mantienen como cadenas. `deliver_at_utc` y `resets_at` están en RFC 3339.

## OpenAPI

Los SDK se prueban con la descripción OpenAPI disponible en [pocketalert.app/openapi.json](https://pocketalert.app/openapi.json). Úsala para generar un cliente en cualquier otro lenguaje.
