# @fuul/sdk 中文文档

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

版本：7\.47\.0
npm 元数据更新时间：2026-08-17T17:13:14.657Z
中文译文更新时间：2026-11-15T19:09:21.119Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：313 kB，47 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2023-03-16T09:42:12.183Z
- 最新版本发布：2026-08-17T17:13:14.312Z
- 近 30 天下载量：6411（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：179（近 12 个月 62 个）

## 中文简介

福尔SDK

## 安装

```sh
npm install @fuul/sdk
```

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

## README

# 开始使用 Fuul SDK

## 设置最小值( L)

### 1\. 安装

运行以下命令之一以添加 Fuul SDK 到您的工程中 :

无 :

```bash
npm install @fuul/sdk
```

亚伦:

```bash
yarn add @fuul/sdk
```

### 2\. 设立

在使用 SDK 之前, 您必须先初始化它, 提供 您的 Fuul 发行的 API 密钥 .

注意: 请在您的应用软件的根部进行操作, 这样您就可以在使用点导入 SDK .

```tsx
import { Fuul } from ('@fuul/sdk');

Fuul.init({ apiKey: "your-fuul-api-key" });
```

现在你可以开始发送事件.

### 3\. 发送活动

Fuul要属性转换事件,您需要报告以下跟踪事件

#### 页面查看事件

项目必须每次用户访问其网站上的一页时发送此事件.

```tsx
import { Fuul } from ('@fuul/sdk');

await Fuul.sendPageview();
```

#### 识别用户

每次用户将钱包连接到自己的网站时,项目必须发送此事件.

```tsx
import { Fuul } from ('@fuul/sdk');

await Fuul.identifyUser({
  userIdentifier: "0xe06099DbbF626892397f9A74C7f42F16748292Db",
  identifierType: UserIdentifierType.EvmAddress,
  signature: "0xb823038d78e541470946e5125b74878c226a84f891671946f18fbe7e5995171731b92f569c3e83f1c9fb89c5351245494c5d2ce6273f74c853a2cace6073f09c1c",
  message: "Connect wallet"
});
```

注:在第一次连接钱包时,以及在会话中更改钱包时,确保发送事件.

## 索赔核对

SDK提供了检索用户索赔支票的方法——这些都是用户可以在链上赎回的可要求的奖励.

### 获得可索赔支票

为用户收回所有可索赔的索偿支票。 这只返回有有效( 未过期) 期限的未申报检查 .

```tsx
import { Fuul, UserIdentifierType } from '@fuul/sdk';

const claimableChecks = await Fuul.getClaimableChecks({
  user_identifier: '0xe06099DbbF626892397f9A74C7f42F16748292Db',
  user_identifier_type: UserIdentifierType.EvmAddress
});

// Process each claimable check
claimableChecks.forEach(check => {
  console.log(`Amount: ${check.amount}`);
  console.log(`Currency: ${check.currency}`);
  console.log(`Deadline: ${new Date(check.deadline * 1000).toISOString()}`);
  console.log(`Proof: ${check.proof}`);
  console.log(`Signatures:`, check.signatures);
});
```

答复包括进行链上索赔核实所需的所有数据,包括密码证明和签名.

### 获取索赔核对总数

获得一个用户的合计索赔核对总数,每个州一行.

每一行都带着 `status` 标签。 这个 `unclaimed` 数组是 **伞** 两个国家: `'open'` (仍在积累奖励——必须关闭才能要求)和 `'closed'` (准备就绪) “准备索赔”数字只须与 `status: 'closed'`注:其他终点(例如:. `getClaimChecks`)使用存储状态值 `unclaimed` 以表示此端点标签 `closed`。 。 。 .

```tsx
import { ClaimCheckTotalsStatusFilter, Fuul, UserIdentifierType } from '@fuul/sdk';

const totals = await Fuul.getClaimCheckTotals({
  user_identifier: '0xe06099DbbF626892397f9A74C7f42F16748292Db',
  user_identifier_type: UserIdentifierType.EvmAddress
});

// Display claimed totals
console.log('Claimed:');
totals.claimed.forEach(item => {
  console.log(`  ${item.currency_name}: ${item.amount} (${item.currency_address})`);
});

// Display unclaimed totals, split by state
console.log('Ready to claim:');
totals.unclaimed
  .filter(item => item.status === 'closed')
  .forEach(item => {
    console.log(`  ${item.currency_name}: ${item.amount} (${item.currency_address})`);
  });

console.log('Still accumulating:');
totals.unclaimed
  .filter(item => item.status === 'open')
  .forEach(item => {
    console.log(`  ${item.currency_name}: ${item.amount} (${item.currency_address})`);
  });
```

可选 `status` 类型过滤器 `ClaimCheckTotalsStatusFilter` 限制对单个状态的反应——例如 `status: ClaimCheckTotalsStatusFilter.Closed` 仅返回已准备好的行. `ClaimCheckTotalsStatusFilter.Unclaimed` 过滤到伞上(均为 `open` 财务报告和审定财务报表 `closed` ) (中文(简体) ). enum 成员映射到线值 `'claimed' | 'unclaimed' | 'open' | 'closed'`; 无效值返回 a `400` 列出有效的.

可选 `reason` 类型过滤器 `ClaimCheckTotalsReasonFilter` 缩小按收入类型归纳的行: `AffiliatePayout` 因转介他人而获得的佣金, `EndUserPayout` 是用户因自身活动而获得的退款, `AgencyPayout` 这是一个机构的份额。 在省略时,所有收入类型被合并为每个货币和状态的一个数字.

过滤器不会改变响应形状——行带不 `reason` 字段——将佣金和回扣作为单独数字显示意味着两次呼叫:

```tsx
import { ClaimCheckTotalsReasonFilter, Fuul, UserIdentifierType } from '@fuul/sdk';

const ids = {
  user_identifier: '0xe06099DbbF626892397f9A74C7f42F16748292Db',
  user_identifier_type: UserIdentifierType.EvmAddress
};

const commission = await Fuul.getClaimCheckTotals({ ...ids, reason: ClaimCheckTotalsReasonFilter.AffiliatePayout });
const rebates = await Fuul.getClaimCheckTotals({ ...ids, reason: ClaimCheckTotalsReasonFilter.EndUserPayout });
```

`reason` 组合与 `status` ——通过两者,以获得,例如,只有即时要求回扣行.

过期支票不包括在 `open` 财务报告和审定财务报表 `closed` 排队,所以 `closed` 钱现在总是可以收回的 索赔总额是用户的索赔历史.

## 常见问题

### @fuul/sdk 是什么？

福尔SDK

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

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

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

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

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

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

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

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

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

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

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

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