# @foxy\.io/sdk 中文文档

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

版本：1\.19\.1
npm 元数据更新时间：2026-11-04T21:28:36.040Z
中文译文更新时间：2026-11-15T10:56:16.239Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：869 kB，349 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=10 \<=26
- 运行依赖：12 个
- 首次发布：2020-11-07T15:16:45.568Z
- 最新版本发布：2026-11-04T21:28:35.878Z
- 近 30 天下载量：12405（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：78（近 12 个月 10 个）

## 中文简介

Universal SDK用于全服务器侧和有限的内浏览器访问Foxy hAPI.

## 安装

```sh
npm install @foxy.io/sdk
```

也可以使用：`pnpm add @foxy.io/sdk`、`yarn add @foxy.io/sdk`、`bun add @foxy.io/sdk`

## README

## 狐狸 SDK 🦊🧱

Universal SDK用于全服务器侧和有限的内浏览器访问Foxy hAPI.

## 设置

安装软件包 :

```bash
npm i @foxy.io/sdk
```

然后使用普通JS( 第 10- 12 号) 导入 :

```js
const FoxySDK = require('@foxy.io/sdk');
```

或 ES 模块(节点13+, TypeScript, 浏览器):

```js
import * as FoxySDK from '@foxy.io/sdk';
```

## 开始

我们的SDK由三个主要部分组成,通过主文件提供:

1.  **后端** 用于构建从保险箱直接连接到hAPI的Node.JS应用程序 **服务器侧** 环境。 除了API客户端之外,您还会发现一些有用的功能,用于HMAC的签名,从响应中去掉敏感信息,并在此导出别名下进行webhook验证.
2.  **客户** 是用来建造的 **普遍** 与特定商店客户可用的hAPI子集交互的应用程序和网站. 此导出也作为我们CDN的预建库提供.
3.  **核心**:用于构建自定义的API客户端,与Hypermedia API端点交互. 这是其他每个内置API客户端所依赖的SDK最先进的部分. 你可以运行它服务器和客户端.

后端和客户输出 API 客户类,用于配合相应的端点. 如果您正在使用 TypeScript, 您也会看到 API 特定超介质关系和图的导出类型 `Rels` 财务报告和审定财务报表 `Graph`。让我们使用 `FoxySDK.Backend.API` 类 :

```js
const api = new FoxySDK.Backend.API({
  refreshToken: 'your refresh token',
  clientSecret: 'your client secret',
  clientId: 'your client id',
});
```

这将创建 HAPI 第 1 版客户端连接到 `https://api.foxy.io/` 带有给定的证书,使用内存存储以获取符和URL解析,日志错误,警告和信息消息到控制台. 您可以在构造参数中自定义其中每一个默认值, 您也会看到客户 API 的类似选项 .

无论你合作的API类型如何,在每个节点上都会看到相同的方法: `.follow()`, (中文(简体) ), `.get()`, (中文(简体) ), `.put()`, (中文(简体) ), `.post()`, (中文(简体) ), `.patch()` 财务报告和审定财务报表 `.delete()`。这里是您如何在三个步骤中使用它们:

### 1\. 寻找节点

要访问 hAPI 端点, 您不会在 URL 中键入, 而是通过链接通过 API 图表, 直到您到达目标 。 例如,要看到您的交易,需要加载书签 URL(`https://api.foxy.io/`,将您的商店装入 `bookmark._links['fx:store'].href` ,然后才能进行交易 `store._links['fx:transactions'].href`随着我们的SDK,这个漫长的过程变成了一行:

```js
const transactionsNode = api.follow('fx:store').follow('fx:transactions');
```

开始的字符串比特 `fx:` 如果您使用一个编辑器支持基于 TypeScript 定义的代码自动补全, 我们将尽可能为可用的目录提供建议.

现在我们有了节点,让我们从中获取一些数据:

### 2\. 获得一些数据

每个节点都有与所支持的HTTP方法相对应的类方法. 例如,制作 `GET` 请求,我们可以打电话 `.get()`数字 :

```js
const transactionsResponse = await transactionsNode.get();
```

我们刚刚称之为“返回承诺”的方法(即使用 `await` 关键词),用增强版本的本地 [回应](https://developer.mozilla.org/en-US/docs/Web/API/Response) 对象,使您能够访问响应状态、信头和更多。 但是现在我们只想让我们的JSON:

```js
const transactions = await transactionsResponse.json();
```

没问题! 现在你有API的响应 与计划一样 [文档](https://api.foxy.io/) 随你便 是的,我们也有它的类型定义, 这意味着你会得到类型检查 TypeScript 和丰富的自动化建议 与内含的docs 在每一个支持它们的编辑器。 但如果我们能更进一步呢?

### 3\. 提出复杂的询问

通常你需要获取一组特定项目, 可能应用一些过滤器, 跳过几个条目, 通过请求部分资源来加速事情的进行 。 您可以使用来自我们的查询参数使用 hAPI来完成 [欺骗表](https://api.foxy.io/docs/cheat-sheet)我们的SDK为这些参数提供了方便的快捷键 `.get()` 方法( 全部可选) :

```js
const transactionsResponse = await transactionsNode.get({
  zoom: { customer: ['default_billing_address'] },
  filters: ['total_order:greaterthan=50', 'attributes:name[color]=red'],
  fields: ['id', 'total_order', 'currency_code'],
  offset: 25,
  limit: 10,
});
```

响应类型也会尽可能地与您的查询相匹配,使您能够在点击API前消除可能的错误. 例如,对于上述请求,每笔交易将只有这3个字段,只有2个嵌入地块(+由于默认包含而支持的属性).

### 收益:后续反应

中每个链接 `_links` 从我们SDK收到的对象包括和正则节点相同的方法,所以你可以做这样的事情:

```js
const nextTransactionsPage = await transactions._links.next.get();
```

还可以使用嵌入式资源并跟踪,您将获得自动补全和输入式检查全程:

```js
const recentSubscriptions = await transactions._embedded['fx:customer']._links['fx:subscriptions'].follow('last').get();
```

## 发展

要启动, 克隆本地重播并安装依赖性 :

```bash
git clone https://github.com/foxy/foxy-sdk.git && cd foxy-sdk && npm i
```

您也可以通过在工程文件夹中运行以下内容来构建此软件包,并在本地测试它:

```bash
npm pack
```

使用下列命令进行测试:

```bash
npm test # run all tests
npm run test:watch # watch files for changes and re-run relevant tests
```

所有最新特稿均发表于 [β 语录](https://github.com/Foxy/foxy-sdk/tree/beta) 分支到 `beta` 发行渠道. 如果你提交了公关,请瞄准 `beta` 还有 发表于 [主要](https://github.com/Foxy/foxy-sdk/tree/main)。 。 。 .

## 常见问题

### @foxy\.io/sdk 是什么？

Universal SDK用于全服务器侧和有限的内浏览器访问Foxy hAPI\.

### 如何安装 @foxy\.io/sdk？

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

### @foxy\.io/sdk 支持 TypeScript 吗？

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

### @foxy\.io/sdk 支持 ESM 还是 CommonJS？

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

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

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

### @foxy\.io/sdk 可以商用吗？

@foxy\.io/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @foxy\.io/sdk 的下载量有多少？

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

### @foxy\.io/sdk 还在维护吗？

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