# SDK

Официальные клиентские библиотеки для API Pocket Alert. Они лёгкие и типизированные: аутентификация, типы запросов и ответов, классы ошибок, повторные попытки и пагинация выполняются за вас.

| Язык | Пакет | Установка | Исходный код |
|----------|---------|---------|--------|
| 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) |

Каждый SDK читает API-ключ из переменной окружения `POCKETALERT_API_KEY`, если вы не передали ключ явно. Создать ключ можно на странице [API-ключи](https://pocketalert.app/account/apikeys).

## Отправка сообщения

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

## Что покрывают SDK

| Ресурс | Методы |
|----------|---------|
| Сообщения | send, list (с пагинацией), iterate (автоматическая пагинация), get, delete, mark read, mark all read, stats, usage |
| Отложенные сообщения | list, cancel |
| Приложения | list, get, create, update, delete |
| Устройства | list, get, update, delete |
| Вебхуки | list, get, create, update, delete, history |
| API-ключи | list, create, delete |

`send` поддерживает все возможности сообщений: [уровни важности](https://info.pocketalert.app/features/priority-levels.md), [кнопки действий](https://info.pocketalert.app/features/action-buttons.md), [отложенную отправку](https://info.pocketalert.app/features/scheduled-delivery.md) (`send_at` / `delay`) и вложения-изображения (URL или строка в base64, либо загрузка файла).

## Ошибки

Ответы с кодом, отличным от 2xx, выбрасывают типизированные ошибки: `AuthenticationError` (401), `PermissionDeniedError` (403, например платная функция на бесплатном тарифе), `NotFoundError` (404), `RateLimitError` (429, с `limit`, `used` и `resets_at`, когда достигнут [дневной лимит](https://info.pocketalert.app/features/daily-limits.md)) и так далее. Go возвращает `*APIError` с вспомогательными функциями, например `pocketalert.IsRateLimited(err)`; PHP выбрасывает исключения из `PocketAlert\Exception`.

## Повторные попытки и идемпотентность

Запросы на чтение, обновление и удаление повторяются до 2 раз при сетевых ошибках и ответах 5xx. Отправка сообщения при таких ошибках не повторяется, поэтому нестабильная сеть не доставит одно и то же push-уведомление дважды. Ответ `429` с коротким `Retry-After` повторяется для любого запроса, так как ничего не было сохранено.

Каждый вызов `send` передаёт заголовок `Idempotency-Key`. Вы можете передать собственный ключ, чтобы связать повторные попытки в вашем коде с одним сообщением.

## Временные метки

`created_at` и `deliver_at` возвращаются как строки для отображения в часовом поясе вашего аккаунта (`DD.MM.YYYY HH:MM:SS`); SDK сохраняют их как строки. `deliver_at_utc` и `resets_at` приходят в формате RFC 3339.

## OpenAPI

SDK протестированы на OpenAPI-описании по адресу [pocketalert.app/openapi.json](https://pocketalert.app/openapi.json). Используйте его, чтобы сгенерировать клиент для любого другого языка.
