# 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 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 |
| Webhooks | 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，当达到[每日上限](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` 请求头。你可以传入自己的密钥，将代码中的重试与同一条消息关联起来。

## 时间戳

`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 描述进行测试。如需为其他语言生成客户端，可以使用该文件。
