# @channel3/sdk 中文文档

规范地址：https://npmcn.com/package/%40channel3/sdk/

版本：4\.8\.0
npm 元数据更新时间：2026-11-05T02:44:39.858Z
中文译文更新时间：2026-11-09T10:23:41.144Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40channel3/sdk
原文对照：https://npmcn.com/package/%40channel3/sdk/?lang=original
项目主页：https://github.com/channel3-ai/channel3-ts-sdk#readme
源码仓库：https://github.com/channel3-ai/channel3-ts-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.3 MB，2283 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2025-09-16T20:02:14.391Z
- 最新版本发布：2026-11-05T02:44:39.665Z
- 近 30 天下载量：3422（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 35 个）

## 中文简介

[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com/?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Ffern-demo%2Fchannel3-ts-sdk) \[npm屏障\]

## 安装

```sh
npm install @channel3/sdk
```

也可以使用：`pnpm add @channel3/sdk`、`yarn add @channel3/sdk`、`bun add @channel3/sdk`

## README

# 频道3 类型脚本 SDK

[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com/?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Ffern-demo%2Fchannel3-ts-sdk) [![npm shield](https://img.shields.io/npm/v/@channel3/sdk)](https://www.npmjs.com/package/@channel3/sdk)

官方类型SDK [频道3 API](https://channel3.docs.buildwithfern.com/) ——通用产品数据库为AI购物应用和代理提供动力.

## 文档

API 文档和指南全文见 [channel3.docs.build withfern.com 互联网档案馆的存檔,存档日期2013-12-02](https://channel3.docs.buildwithfern.com/)。 。 。 .

## 运行时间兼容性

| 所需经费 | 版本 |
| --- | --- |
| 节点.js | `>= 18.0.0` |
| 类型脚本 | `>= 4.5` (可选——在普通联合来文中工作) |
| 模块系统 | 无害环境管理和共同JS(双包) |
| 浏览器 | 任何环境 `fetch` (或通过多填充) |
| 边缘运行时间 | Cloudflare 工人,韦尔塞尔边缘,德诺 |
| 原生反应 | 支助 |

## 安装

```sh
npm install @channel3/sdk
# or
yarn add @channel3/sdk
# or
pnpm add @channel3/sdk
```

## 认证

SDK通过一个 `x-api-key` 头曰. 初始化客户端时通过您的密钥 :

```typescript
import { Channel3Client } from "@channel3/sdk";

const client = new Channel3Client({ apiKey: "YOUR_API_KEY" });
```

您也可以为动态密钥解析提供函数( 用于密钥旋转 ):

```typescript
const client = new Channel3Client({
    apiKey: async () => getKeyFromVault(),
});
```

## 使用量

### 搜索产品

```typescript
const response = await client.products.search({
    query: "organic cotton t-shirt",
    limit: 10,
});

for (const product of response.products) {
    console.log(product.title, product.offers?.[0]?.price);
}
```

### 通过结果粘贴

搜索答复包括a `nextPageToken` 用于光标平面图 :

```typescript
let pageToken: string | undefined;

do {
    const response = await client.products.search({
        query: "sneakers",
        pageToken,
    });

    for (const product of response.products) {
        console.log(product.title);
    }

    pageToken = response.nextPageToken ?? undefined;
} while (pageToken);
```

### 通过图像进行视觉搜索

```typescript
const response = await client.products.imageSearch({
    imageUrl: "https://example.com/photo.jpg",
});
```

### 查找类似产品

```typescript
const response = await client.products.similar({
    productId: "prod-12345",
});
```

### 通过 URL 查找产品

```typescript
const product = await client.products.lookup({
    url: "https://example.com/product/abc",
});
```

### 浏览品牌和类别

标注品牌和类别:

```typescript
const brands = await client.brands.list({ limit: 50 });
console.log(brands.items);       // Brand[]
console.log(brands.nextCursor);  // pass as `cursor` for the next page

const categories = await client.categories.list({ pageSize: 50 });
```

### 轨价

```typescript
// Start tracking
await client.priceTracking.start({ canonicalProductId: "prod-12345" });

// Get price history
const history = await client.priceTracking.getHistory({ canonicalProductId: "prod-12345" });

// List active subscriptions
const subs = await client.priceTracking.listSubscriptions();

// Stop tracking
await client.priceTracking.stop({ canonicalProductId: "prod-12345" });
```

## 类型智能

所有请求和响应类型均导出于 `Channel3` 方便发现的命名空间 :

```typescript
import { Channel3 } from "@channel3/sdk";

// Full autocomplete on request fields
const request: Channel3.SearchRequest = {
    query: "wireless headphones",
    limit: 20,
    filters: { gender: "female" },
    config: { country: "US", currency: "USD" },
};

// Response types are also typed
const response: Channel3.SearchResponse = await client.products.search(request);
```

资源客户端可通过点标记访问——类型 `client.` 在编辑器中发现 :

| 访问器 | 方法 |
| --- | --- |
| `client.products` | `search`, (中文(简体) ), `imageSearch`, (中文(简体) ), `similar`, (中文(简体) ), `lookup`, (中文(简体) ), `retrieve`, (中文(简体) ), `enrich` |
| `client.brands` | `list`, (中文(简体) ), `search`, (中文(简体) ), `get` |
| `client.categories` | `list`, (中文(简体) ), `search` |
| `client.priceTracking` | `start`, (中文(简体) ), `stop`, (中文(简体) ), `getHistory`, (中文(简体) ), `listSubscriptions` |
| `client.websites` | `list` |

## 处理错误

SDK 每 HTTP 状态代码丢入打入错误 :

```typescript
import { Channel3Error, Channel3TimeoutError } from "@channel3/sdk";

try {
    await client.products.search({ query: "test" });
} catch (err) {
    if (err instanceof Channel3Error) {
        console.log(err.statusCode); // 401, 402, 422, etc.
        console.log(err.message);
        console.log(err.body);
    }
}
```

## 高级

### 检索

在 5xx 和网络错误( 默认: 2 重试) 上自动回转 :

```typescript
const response = await client.products.search(
    { query: "shoes" },
    { maxRetries: 5 },
);
```

### 超时

默认超时为60秒. 覆盖每个客户或每个请求:

```typescript
const client = new Channel3Client({
    apiKey: "YOUR_API_KEY",
    timeoutInSeconds: 30,
});

// Per-request
await client.products.search({ query: "shoes" }, { timeoutInSeconds: 10 });
```

### 中止请求

```typescript
const controller = new AbortController();
await client.products.search({ query: "shoes" }, { abortSignal: controller.signal });
```

### 原始反应访问

访问 HTTP 头和状态并附解析数据 :

```typescript
const response = await client.products.search({ query: "shoes" });
console.log(response.rawResponse.status);
console.log(response.rawResponse.headers);
```

## 参考文献

参见全部 API 参考文献 : [页:1](https://npmcn.com/package/%40channel3/sdk/reference.md)。 。 。 .

## 捐款

见 [捐款额](https://npmcn.com/package/%40channel3/sdk/CONTRIBUTING.md) (c) 发展结构和准则.

## 常见问题

### @channel3/sdk 是什么？

\[npm屏障\]

### 如何安装 @channel3/sdk？

在项目目录运行 npm install @channel3/sdk，或使用 pnpm add / yarn add / bun add。

### @channel3/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @channel3/sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @channel3/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @channel3/sdk 可以商用吗？

@channel3/sdk 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @channel3/sdk 的下载量有多少？

根据 npm 官方下载统计，@channel3/sdk 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,422 次，日均约 114 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @channel3/sdk 还在维护吗？

最新版本 4\.8\.0 发布于 2026/11/05（4 天前）；至今共发布 39 个版本，其中过去 12 个月发布了 35 个；首次发布于 2025/09/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。