# @faiber/faiber-asset 中文文档

规范地址：https://npmcn.com/package/%40faiber/faiber-asset/

版本：2\.8\.0
npm 元数据更新时间：2026-11-14T09:45:24.295Z
中文译文更新时间：2026-11-14T08:55:27.361Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40faiber/faiber-asset
原文对照：https://npmcn.com/package/%40faiber/faiber-asset/?lang=original

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

- 包体积（解压后）：530 kB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-07-18T14:29:33.691Z
- 最新版本发布：2026-11-14T09:45:24.099Z
- 近 30 天下载量：3986（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 66 个）

## 中文简介

钱包,余额,计划,订阅,购买,排行,奖励,使用,银行交易,沙箱计费,服务生命周期业务.

## 安装

```sh
npm install @faiber/faiber-asset
```

也可以使用：`pnpm add @faiber/faiber-asset`、`yarn add @faiber/faiber-asset`、`bun add @faiber/faiber-asset`

## README

# @faiber/faiber-资产

钱包,余额,计划,订阅,购买,排行,奖励,使用,银行交易,沙箱计费,服务生命周期业务.

## 安装

```bash
npm install @faiber/faiber-asset
```

## 配置

```ts
import { FaiberClient, MemoryTokenProvider } from "@faiber/sdk-core";
import { AssetApi } from "@faiber/faiber-asset";

const tokens = new MemoryTokenProvider();
const client = new FaiberClient("asset", {
  domains: { asset: process.env.FAIBER_ASSET_URL! },
  tokenProvider: tokens,
  axios: { timeout: 15_000, withCredentials: true },
});
const api = new AssetApi(client);

const assets = await api.assets.list({ "page[number]": 1 });
const wallet = await api.operations.walletBillingWalletShowGet();
```

## 完全能力

该软件包从资产和账单服务中披露110项注册业务。 通用工作流程有简洁的方法 `api`;每个已注册后端路由在 `api.operations`。生成的操作输入、查询、响应、路径、动词和许可合同从 `operations.types`。 。 。 .

| 区域 | 业务 | HTTP 方法 |
| --- | --: | --- |
| `action` | 6个 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST` |
| `ai-billing` | 3个 | `POST` |
| `bank` | 页:1 | `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST` |
| `catalog` | 页:1 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST` |
| `charge` | 2个 | `GET`, (中文(简体) ), `PATCH` |
| `dashboard` | 1个 | `GET` |
| `economy` | 第13条 | `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `fitness` | 1个 | `PUT` |
| `game-escrow` | 页:1 | `GET`, (中文(简体) ), `POST` |
| `integration` | 3个 | `GET` |
| `leaderboard` | 1个 | `GET` |
| `llm-usage` | 页:1 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PUT` |
| `logs` | 2个 | `GET` |
| `rank` | 页:1 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `PATCH`, (中文(简体) ), `POST` |
| `router` | 3个 | `GET` |
| `sandbox-billing` | 第11个 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `service-lifecycle` | 页:1 | `DELETE`, (中文(简体) ), `POST` |
| `trial-gifts` | 6个 | `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |
| `wallet` | 第9条 | `GET` |
| `wallet-billing` | 22个 | `DELETE`, (中文(简体) ), `GET`, (中文(简体) ), `POST`, (中文(简体) ), `PUT` |

行政和自助收费路线是不同的业务。 购买,上注,暂停,恢复,去除,永久数据删除方法保留后端动词和权限说明.

## 受资助范围奖励

`myEconomy()`, (中文(简体) ), `economyValuation()`, (中文(简体) ), `myEconomyHistory()` 财务报告和审定财务报表 `economyLeaderboard({role, period_id})` 暴露课堂平衡、供资能力、, 恢复区块、会话收费、应享权利和单独角色排名。 货币 数量和币值为十进制字符串。 估值包括 货币;在显示托曼时,明确将IRR除以10.

```ts
const valuation = await api.economyValuation();
const preview = await api.previewEconomyReward({
  action_name: "configured-action", role: "student", scope_id: classroomId,
  source_id: verifiedEvidenceId, session_id: roomId, replay: false,
});
const purchase = await api.purchaseEconomyItem({
  event_id: crypto.randomUUID(), item_id: "configured-pack", payment: "money",
});
```

预览绝不改变平衡 。 完成需要经过核实的领域证据或 使用 `economyCommand()` 有审计原因 服务 通过RabbitMQ发送资助,录取和交互指令. 客户端 HTTP 不能编造这些命令。 操作政策和日记方法要求 在每个方法上记录的权限.

重新使用购买/信贷 `event_id` 重试时。 货币引用锁定显示 金额直到 `expires_at`;从 `myEconomy()` 支付款项 重定向 URL 或提供者出错 。 一次成功的支付信用。 赎罪 在退款或支助不足的情况下可能失败。 购置信贷 与开庭无关; `applySessionChargeCredit()` 仅填充 位于会话最大值以下的空间。 所有方法都保留 Axios 正常错误反应, 授权和取消选项.

## 认证和授权

配置资产 URL 以使用您认证的 Faiber 网关 。 使用一个 `TokenProvider` 为纪念物,或 `withCredentials` 用于安全的 Http 唯一的饼干会话。 被绑定的资产服务读取了可信赖的网关身份头;其路由许可说明描述了网关ACL元数据,而本身并不验证用户Bearer令牌或cookie. 执行网关必须认证呼叫者并应用这些权限。 每个 SDK 操作使用共享 `FaiberClient` 运输.

游戏代管业务额外需要只使用服务器 `x-game-service-token` 头;健身产品出版物使用自有的仅服务器服务 Bearer sord. 这些证书必须保留在信任的服务器上. 通过为相关操作配置的请求选项传递它们 .

## 投入、询问、答复和运输

所有方法都返回完整的Axios响应,包括状态,头,以及请求ID. 钱包余额,目录数量和日常使用成本等十进制输出为字符串;小数输入接受字符串或数字. 资产/排名/行动删除回报 `data: null`. 自助订阅返回 `data.subscriptions` 没有帕吉尼特。 请求机构和查询对象被命名为导出接口. 网纹页化使用密钥, 如 `page[number]` 财务报告和审定财务报表 `page[size]` 服务需要时。 标准 Axios 请求选项、信头、超时、适配器、拦截器和 `AbortSignal` 取消被支持为最后参数.

一般性的REST资源得到能力保障。 调用未注册的遗留方法 `UnsupportedOperationError` 在发送请求之前, 而不是生成后端 `405`。 。 。 .

## 错误和取消

```ts
try {
  await api.client.get("/health", undefined, { signal: AbortSignal.timeout(5_000) });
} catch (error) {
  // Axios errors retain response.status and the service error body.
}
```

使用 `@faiber/faiber-ts-sdk` 当一个应用程序需要多个具有一个配置的Faiber服务时.

### 试赠和钱包取出

`operations.trialGiftsListGet(product, query)` 通过产品拥有的礼品提供页面; `trialGiftsCreatePost`, (中文(简体) ), `trialGiftsUpdatePut`,以及 `trialGiftsCopyTokenGet` 管理它们。 产品标识是 `2done` 财务报告和审定财务报表 `fitapp`. 需要申报的管理充电许可和资产充电许可。 重用 `request_id` 在创建礼物时; 复制符号需要可用的金库和未使用的礼物.

`operations.sandboxBillingQuoteResourcesPost(input)` 引用资源而不分配或借记。 货币引用值为十进制字符串. `walletBillingWalletSubscriptionsPost` 以稳定方式从当前钱包中购买订阅 `request_id` 和最大接受金额; 已更改的引号返回409, 余额不足返回402. `walletBillingWalletPurchaseShowGet` 只读经认证的所有人收据。 Fitness产品出版物是只使用服务器的,拒绝更改已发布的分级.

### 目录和规则模型

以 `{name, asset_type}` (单位:千美元)`Coin`, (中文(简体) ), `Badge`, (中文(简体) ), `XP`, (中文(简体) ), `Charge`,或 `Gem`和排队 `{name, min_xp}`。用户 AI 计划更新接受 `{tier}`。 。 。 . `dashboard({month: "2026-10"})` 选择一个月。 充值映射条件为标记对象,例如 `{type: "xp_balance", operator: "gte", value: "100"}`行动标准、奖励条件、上限和乘数模型与操作模型一起输出.

`economyPolicy()` 返回时 `null` 在配置之前并包含 `configuration_revision` 后; 策略更新返回已保存的策略 。 政策模式包括供资设置和证据约束,能力包括规则创建/更新旗帜。 经济日记接受 `before` 财务报告和审定财务报表 `descending`; 自有历史支持 `after` 财务报告和审定财务报表 `limit` 只有这个 礼品清单/详细有效载荷仍然是由产品拥有的JSON,因为资产转发了配置的适配器数据; 资产说明细节/项目 `can_copy` 并暴露出具体的象征性反应.

### 资助 Do 和 私人 Dox

`asset.doEconomy` 管理单独配置的注资奖励政策。 没错 并没有改变目前范围经济对硬币购买的禁令. 价格 使用整数的里亚尔和整数的硬币。 运算符配置不活动包、目录 (b) 支助、交付费用、审查要求和晋升准备金.

需要更新政策 `admin:coin_settings:update`,当前版本和 审计理由。 需要只读政策/审计电话 `admin:coin_settings:read`。 。 。 . 运动资金使用稳定的 `request_id`;复试不能发行两次. 资金转移、采购和应享权利交付需要可靠的后端 一体化。 从不把他们的证书放入浏览器.

```ts
const snapshot = await asset.doEconomy.policy({ signal: controller.signal });
console.log(snapshot.data.data.version, snapshot.data.data.policy.enabled);
```

## 一般 Dox 分类账( 受托后端)

多克思是一个封闭的,空间范围的资产,独立于可购买多克. `AssetApi.dox` 拥有发行、账户余额、不可改变的账面、重新播放保护,以及 原子转移。 任务核查成员及工作审查许可 请求调职 没有浏览器应用程序持有服务证书.

```ts
const asset = new AssetApi(new FaiberClient('asset', {
  domains: { asset: process.env.ASSET_URL! }, authMode: 'cookie'
}));
const result = await asset.dox.management({
  profile_id: moderatorId, space_id: spaceId,
  dox_management: { account: 'space', direction: 'out', page: 1, page_size: 20 }
}, { headers: { 'x-do-service-token': process.env.ASSET_TASK_TOKEN! }, signal });
```

`execute()` 接受带有稳定的命名配置/传输命令 `id` 财务报告和审定财务报表 `actor_id`。源/去向 UUID 是成员;无效代表空间. 每个成员获得一次性500个分配,按配置模式排列. 转账节省供应,拒绝超支。 任务或购买身份 无法支付两次,即使使用不同的申请身份证. `management()` 是任务服务 仅限; `read()` 页面 一名成员的历史。 页大小为 1- 100; 需要方向 账户(`space` 或者说 `user:UUID`) (中文(简体) ). 完全 Axios 响应和取消 保存; 处理 401/403, 平衡不足, 以及相冲突的重放 。 这些 合同是通用合同,没有产品路线或UI假设.

## 管理产品执行政策

使用 `DoEconomyApi` 与您现有的认证 `FaiberClient('asset', …)`。 。 。 . `policy()` 返回时 `{ version, can_edit, policy }` 内部 `response.data.data`。 。 。 . `savePolicy({ version, policy, reason })` 更新同一版本,记录 审计理由,并返回所保存的快照 。 需要读写 `admin:coin_settings:read` 财务报告和审定财务报表 `admin:coin_settings:update`分别是:. 从不将信任的后端服务符放入管理员浏览器中.

该政策包括包、产品、双语礼品、个性化奖励、, 每日付款顺序、转介奖励和限制、竞选资金和 重新提交限额和供资/审查规则。 礼品图像路径必须是本地的, 标识符独有,且数量为有效整数。 现有政策默认为 零个性化奖励和空入计时表。 空时间表 禁用每日硬币赠与;否则超过数日使用最终金额.

在编辑和保存窗体以外的字段之前, 读取保存的策略 . 打开 `do.version_conflict`,保留草案,并明确重新装入/调和 新版本; 不要用被猜测的版本重试。 拒绝后端验证 资金不足的包和无效值。 两通电话都保留Axios的完整回复 并接受 `RequestOptions`,包括中止 `signal`。 。 。 .

## 常见问题

### @faiber/faiber-asset 是什么？

钱包,余额,计划,订阅,购买,排行,奖励,使用,银行交易,沙箱计费,服务生命周期业务\.

### 如何安装 @faiber/faiber-asset？

在项目目录运行 npm install @faiber/faiber-asset，或使用 pnpm add / yarn add / bun add。

### @faiber/faiber-asset 支持 TypeScript 吗？

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

### @faiber/faiber-asset 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @faiber/faiber-asset 可以商用吗？

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

### @faiber/faiber-asset 的下载量有多少？

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

### @faiber/faiber-asset 还在维护吗？

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