# SDK


# SDK

官方 SDK 用 TypeScript 写成，零依赖，需要 Node 18 以上。只在服务器端使用。

## 安装

```bash
npm install https://aida.xinnet.com/docs/downloads/aida-sdk.tgz
```

代理商的用户级接口在单独的代理版 SDK 里，在「代理中心 · API」下载。

## 初始化

```js
import { AidaSite } from "aida-sdk";

const site = new AidaSite({
  baseUrl: "https://aida.xinnet.com",
  site: "<网站编号>",
  key: process.env.AIDA_SITE_KEY,
});
```

## 读写数据

```js
// 表与字段
const tables = await site.tables();

// 查询一页
const { records, total } = await site.table("products").query({
  select: ["id", "model", "price"],
  filters: [{ key: "price", op: "gte", value: 10 }],
  order: [{ key: "model", dir: "asc" }],
  limit: 50,
});

// 逐页读完（每页 100 条）
for await (const product of site.table("products").all()) {
  console.log(product.model);
}

// 新建：SDK 自动生成编号，网络重试不会建出两条
const created = await site.table("products").create({ model: "6204", price: 12.5 });

// 修改、删除（按编号）
await site.table("products").update(created.id, { price: 13 });
await site.table("products").delete(created.id);
```

## 上传文件

```js
import { readFile } from "node:fs/promises";

const image = await site.upload(await readFile("6204.png"), "6204.png", "image/png");
await site.table("products").update(id, { image: image.url });
```

文件按分片直接传到存储，不经过工作台，也不会把密钥发给存储。图片和文件字段只能填本站文件地址，所以要先上传再填。

## 错误与重试

```js
import { AidaError } from "aida-sdk";

try {
  await site.table("orders").create({ note: "x" });
} catch (error) {
  if (error instanceof AidaError) {
    console.log(error.status, error.code, error.message, error.requestId);
  }
}
```

- 返回 429 时，SDK 按 `Retry-After` 自动等待重试（默认最多 3 次，可用 `maxRetries` 调整）。
- 网络错误只在不会产生重复的请求上重试：读取、带编号的新建、删除。
- 在浏览器里创建客户端会直接报错，避免密钥被放进前端代码。

## 示例

SDK 包里的 `examples/` 目录有可以直接运行的示例：

- `list-products.mjs`：列出表和前 20 条记录；
- `upload-and-create.mjs`：上传一张图并新建一条带图的记录。
