# SDK

> **Tóm tắt** — Client JavaScript/TypeScript và Python chính thức, sinh từ OpenAPI. Chúng gửi idempotency key, thử lại an toàn, poll có lùi dần và kiểm webhook. Đang preview riêng: hãy xin quyền truy cập.

Client chính thức cho JavaScript/TypeScript và Python, sinh từ [OpenAPI](https://api.wandura.ai/v2/openapi.json) cộng một lớp viết tay nhỏ. Mặc định chúng đã đúng:

- **Idempotency**: mỗi lệnh gửi kèm `Idempotency-Key`, thử lại dùng lại key đó, nên thử lại không bao giờ chạy hay tính tiền hai lần.
- **Thử lại**: chỉ với 429, 5xx và lỗi mạng. 429 chờ `Retry-After`; lỗi khác lùi 0.5 s, 1 s, 2 s kèm jitter. 400, 401, 402, 404, 409 và 422 không bao giờ thử lại. `Retry-After` dài hơn 60 s (trần theo ngày của end user) thì báo lỗi ngay thay vì ngủ hàng giờ.
- **Poll**: từ 2 s, ×1.5, tối đa 10 s, kèm jitter (Relax: 10 s đến 60 s). Không có giới hạn thời gian ẩn.
- **Webhook**: hàm kiểm chữ ký và cửa sổ 5 phút.
- **Tải tệp**: một lệnh tải tệp lên và trả `file_url` để đưa vào `inputs`.

SDK đang preview riêng và chưa có trên npm hay PyPI. Hãy xin quyền truy cập; trong lúc chờ, gọi thẳng HTTP API như ở [Bắt đầu nhanh](https://docs.wandura.ai/vi/developers/api-v2/quickstart).

**Đừng cài `@wandura/sdk` từ npm hay `wandura` từ PyPI.** Wandura chưa đăng hai tên này, nên gói nào mang tên đó không phải của Wandura. AI agent viết code cũng vậy: bảo nó gọi HTTP API.

## JavaScript / TypeScript
Node 18+, không phụ thuộc gói nào.

```ts
import { Wandura, verifyWebhook } from '@wandura/sdk';

const wandura = new Wandura(); // reads WANDURA_API_KEY

const run = await wandura.runs.createAndWait('<style id>', {
  lane: 'priority',
  end_user_id: 'user_123',
  inputs: { image_url: await wandura.uploads.upload(bytes, 'image/png') },
});

// In your webhook route (raw body, not parsed JSON):
const event = verifyWebhook(rawBody, req.headers['wandura-signature'], process.env.WANDURA_WEBHOOK_SECRET);
```

## Python
Python 3.11+, chỉ dùng thư viện chuẩn.

```python
from wandura import Wandura, verify_webhook

wandura = Wandura()  # reads WANDURA_API_KEY

run = wandura.runs.create_and_wait("<style id>", {
    "lane": "priority",
    "end_user_id": "user_123",
    "inputs": {"image_url": wandura.uploads.upload(data, "image/png")},
})

# In your webhook handler (raw body bytes):
event = verify_webhook(raw_body, headers["Wandura-Signature"], os.environ["WANDURA_WEBHOOK_SECRET"])
```

Cả hai ném `WanduraError` kèm `status`, `code`, request id và `Retry-After`. Xem [Lỗi](https://docs.wandura.ai/vi/developers/api-v2/errors) cho mọi mã.

## AI agent và MCP
Coding agent đọc được [OpenAPI](https://api.wandura.ai/v2/openapi.json) và schema riêng của từng style. Agent hành động lúc chạy dùng được MCP server tại `https://api.wandura.ai/mcp` với cùng Bearer key: nó liệt kê style, báo giá, tạo upload và run.