# SDKs

Bibliotecas cliente oficiais para a API do Pocket Alert. Elas são leves e tipadas: autenticação, tipos de requisição e resposta, classes de erro, novas tentativas e paginação são tratados para você.

| Linguagem | Pacote | Instalação | Código-fonte |
|----------|---------|---------|--------|
| 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 os SDKs leem a chave de API da variável de ambiente `POCKETALERT_API_KEY` quando você não passa uma. Crie uma chave na página [Chaves de API](https://pocketalert.app/account/apikeys).

## Enviar uma mensagem

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

## O que os SDKs cobrem

| Recurso | Métodos |
|----------|---------|
| Mensagens | send, list (paginado), iterate (paginação automática), get, delete, mark read, mark all read, stats, usage |
| Mensagens agendadas | list, cancel |
| Aplicativos | list, get, create, update, delete |
| Dispositivos | list, get, update, delete |
| Webhooks | list, get, create, update, delete, history |
| Chaves de API | list, create, delete |

`send` oferece suporte a todos os recursos de mensagem: [níveis](https://info.pocketalert.app/features/priority-levels.md), [botões de ação](https://info.pocketalert.app/features/action-buttons.md), [envio agendado](https://info.pocketalert.app/features/scheduled-delivery.md) (`send_at` / `delay`) e anexos de imagem (uma URL ou string base64, ou um upload de arquivo).

## Erros

Respostas diferentes de 2xx lançam erros tipados: `AuthenticationError` (401), `PermissionDeniedError` (403, por exemplo um recurso pago no plano gratuito), `NotFoundError` (404), `RateLimitError` (429, com `limit`, `used` e `resets_at` quando o [limite diário](https://info.pocketalert.app/features/daily-limits.md) é atingido), e assim por diante. Go retorna um `*APIError` com funções auxiliares como `pocketalert.IsRateLimited(err)`; PHP lança exceções de `PocketAlert\Exception`.

## Novas tentativas e idempotência

Requisições de leitura, atualização e exclusão são repetidas até 2 vezes em erros de rede e respostas 5xx. O envio de uma mensagem não é repetido nesses erros, para que uma rede instável não entregue a mesma notificação push duas vezes. Um `429` com um `Retry-After` curto é repetido para todas as requisições, já que nada foi armazenado.

Cada chamada de `send` carrega um cabeçalho `Idempotency-Key`. Você pode passar sua própria chave para vincular as novas tentativas no seu código a uma única mensagem.

## Timestamps

`created_at` e `deliver_at` são retornados como strings de exibição no fuso horário da sua conta (`DD.MM.YYYY HH:MM:SS`); os SDKs as mantêm como strings. `deliver_at_utc` e `resets_at` seguem o RFC 3339.

## OpenAPI

Os SDKs são testados com a descrição OpenAPI disponível em [pocketalert.app/openapi.json](https://pocketalert.app/openapi.json). Use-a para gerar um cliente em qualquer outra linguagem.
