# 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 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 |
| 웹훅 | 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 명세를 기준으로 테스트돼요. 다른 언어의 클라이언트를 생성하려면 이 명세를 사용하세요.
