# SDK

Library klien resmi untuk API Pocket Alert. Ringan dan bertipe: autentikasi, tipe request/response, kelas error, retry, dan pagination sudah ditangani untuk Anda.

| Bahasa | Paket | Instalasi | Sumber |
|----------|---------|---------|--------|
| 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) |

Setiap SDK membaca kunci API dari variabel lingkungan `POCKETALERT_API_KEY` jika Anda tidak memberikannya secara langsung. Buat kunci di halaman [API Keys](https://pocketalert.app/account/apikeys).

## Kirim pesan

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

## Cakupan SDK

| Resource | Methods |
|----------|---------|
| Messages | send, list (paginated), iterate (auto-paging), get, delete, mark read, mark all read, stats, usage |
| Scheduled messages | list, cancel |
| Applications | list, get, create, update, delete |
| Devices | list, get, update, delete |
| Webhooks | list, get, create, update, delete, history |
| API keys | list, create, delete |

`send` mendukung semua fitur pesan: [levels](https://info.pocketalert.app/features/priority-levels.md), [tombol aksi](https://info.pocketalert.app/features/action-buttons.md), [pengiriman terjadwal](https://info.pocketalert.app/features/scheduled-delivery.md) (`send_at` / `delay`) dan lampiran gambar (URL atau string base64, atau unggah file).

## Error

Respons non-2xx memunculkan error bertipe: `AuthenticationError` (401), `PermissionDeniedError` (403, misalnya fitur berbayar di paket gratis), `NotFoundError` (404), `RateLimitError` (429, dengan `limit`, `used` dan `resets_at` saat [batas harian](https://info.pocketalert.app/features/daily-limits.md) tercapai), dan seterusnya. Go mengembalikan `*APIError` dengan helper seperti `pocketalert.IsRateLimited(err)`; PHP melempar exception dari `PocketAlert\Exception`.

## Retry dan idempotency

Request read, update, dan delete di-retry hingga 2 kali saat terjadi error jaringan dan respons 5xx. Pengiriman pesan tidak di-retry untuk error tersebut, sehingga jaringan yang tidak stabil tidak akan mengirim push yang sama dua kali. Respons `429` dengan `Retry-After` yang singkat di-retry untuk semua request, karena tidak ada yang tersimpan.

Setiap panggilan `send` membawa header `Idempotency-Key`. Anda dapat memberikan kunci sendiri untuk mengaitkan retry di kode Anda dengan satu pesan.

## Timestamp

`created_at` dan `deliver_at` dikembalikan sebagai string tampilan dalam zona waktu akun Anda (`DD.MM.YYYY HH:MM:SS`); SDK menyimpannya sebagai string. `deliver_at_utc` dan `resets_at` menggunakan RFC 3339.

## OpenAPI

SDK diuji terhadap deskripsi OpenAPI di [pocketalert.app/openapi.json](https://pocketalert.app/openapi.json). Gunakan itu untuk membuat klien untuk bahasa lain.
