# SDK

Pocket Alert API 向けの公式クライアントライブラリです。軽量で型付けされており、認証、リクエストおよびレスポンスの型、エラークラス、リトライ、ページネーションを自動で処理します。

| 言語 | パッケージ | インストール | ソース |
|----------|---------|---------|--------|
| 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) |

API キーを渡さない場合、すべての SDK は `POCKETALERT_API_KEY` 環境変数から API キーを読み込みます。API キーは [API Keys](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 |
| Webhook | 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、[1 日の上限](https://info.pocketalert.app/features/daily-limits.md)に達した場合は `limit`、`used`、`resets_at` を含む）などがあります。Go では `*APIError` などのヘルパーを備えた `pocketalert.IsRateLimited(err)` を返します。PHP では `PocketAlert\Exception` から例外がスローされます。

## リトライと冪等性

読み取り、更新、削除のリクエストは、ネットワークエラーおよび 5xx レスポンス時に最大 2 回までリトライされます。メッセージの送信は、これらのエラーではリトライされません。そのため、ネットワークが不安定でも同じプッシュ通知が二重に届くことはありません。短い `429` を伴う `Retry-After` は、何も保存されていないため、すべてのリクエストでリトライされます。

`send` の各呼び出しには `Idempotency-Key` ヘッダーが付与されます。独自のキーを渡すことで、コード内のリトライを 1 つのメッセージに紐付けられます。

## タイムスタンプ

`created_at` と `deliver_at` は、アカウントのタイムゾーンでの表示用文字列（`DD.MM.YYYY HH:MM:SS`）として返されます。SDK ではこれらを文字列のまま保持します。`deliver_at_utc` と `resets_at` は RFC 3339 形式です。

## OpenAPI

SDK は [pocketalert.app/openapi.json](https://pocketalert.app/openapi.json) にある OpenAPI 定義に対してテストされています。他の言語向けのクライアントを生成する際にご利用ください。
