# @fiskil/link 中文文档

规范地址：https://npmcn.com/package/%40fiskil/link/

版本：1\.0\.0
npm 元数据更新时间：2026-11-13T03:11:09.434Z
中文译文更新时间：2026-11-14T20:32:43.541Z
软件包许可：SEE LICENSE IN LICENSE\.md

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

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

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

- 包体积（解压后）：58.8 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-09-05T00:23:46.522Z
- 最新版本发布：2026-11-13T03:11:09.212Z
- 近 30 天下载量：23861（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 3 个）

## 中文简介

最小 TypeScript SDK 用于创建 Fiskil auth会话(直接或iframe).

## 安装

```sh
npm install @fiskil/link
```

也可以使用：`pnpm add @fiskil/link`、`yarn add @fiskil/link`、`bun add @fiskil/link`

## README

## Fiskil Link SDK (英语:`@fiskil/link`(中文(简体) )

[![Tests](https://github.com/fiskil/link-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/fiskil/link-sdk/actions/workflows/test.yml) [![npm version](https://img.shields.io/npm/v/@fiskil/link.svg)](https://www.npmjs.com/package/@fiskil/link)

Fiskil 链接 SDK (@ fiskil/link) 使得它容易嵌入 [Fiskil Auth 会话](https://docs.fiskil.com/auth-session) 在您的网络应用程序中。 一个 _Auth 会话_ 最终用户如何通过Fiskil平台连接其银行或金融机构,以分享消费者数据权利(CDR)数据.

SDK 处理完全同意过程并返回数据共享过程的结果 - 您只需要提供一个 Fiskil `auth_session_id` 启动和处理您的应用程序中的结果。 一旦用户批准CDR共享,您的后端就可以监听 [Fiskil 网络游戏](https://docs.fiskil.com/guide/core-concepts/webhooks) 然后开始通过 Fiskil 获取CDR 数据 [银行业务](https://docs.fiskil.com/banking/introduction) 或者说 [能源](https://docs.fiskil.com/energy/introduction) APIs (英语).

## 安装

用您首选的软件包管理器安装软件包 :

```bash
npm i @fiskil/link
# or
pnpm add @fiskil/link
```

## 快速启动( ESM/ TypeScript)

要使用这个SDK, 您需要一个 Fiskil 团队账户 。 如果你没有账户,你可以 [联系](https://www.fiskil.com/contact) 为快速演示。 如果你是新到菲斯基尔平台 [快速启动指南](https://docs.fiskil.com/guide/getting-started/quick-start)。 。 。 .

在启动同意前, 您的后端必须 [创建 Auth 会话](https://docs.fiskil.com/auth-session#create-auth-session) 通过费斯基尔API。 传出结果 `auth_session_id` 进入 SDK 开始您的应用程序中的流程 .

```ts
import { link, type LinkError } from '@fiskil/link';

// Start the consent flow
const flow = link('auth_session_id');

try {
  const result = await flow;
  console.log(result.consents);
} catch (err) {
  const linkError = err as LinkError;
  console.log('Link Error code:', linkError.code);
} 

// to cancel the consent flow programmatically
// flow.close();
```

## API 参考

### `link(sessionId, options?)`

创建和挂载同意的 UI 元素 。 回返a **`LinkFlow`** 对象,两者均为:

-   (单位:千美元) `Promise` 解决流动结果
-   控制器为 `.close()` 在程序上取消流量.

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `timeoutMs` | 编号 | 同意流的最大时间,以毫秒计。 默认为 `600000` (10分钟). |

### 结果

这个 `LinkFlow` 1. 决定成功有效载荷:

```ts
type LinkResult = {
  redirectURL?: string;
  consents: string[];
};
```

-   确定的结果包括: `redirectURL` (如果配置)和 `consents`,可以用来从 Fiskil 平台获取用户数据的一系列同意ID.
-   如果失败,承诺以 `LinkError` (见错误处理).

补全信息必须包含一个或多个非空白字符串ID. 无效 `consents` 不被忽略,而不回到 `consentID`; SDK 等待一个有效的结果或超时.

### 移动到 1.0.0

**中断更改 :** 替换 `result.consentID` 与 `result.consents`,一系列同意的ID, 并处理每个ID. `redirectURL` 仍然是可选的.

遗产补全消息仍然支持: SDK 转换 `consentID` 改为 `consents: [consentID]`。 。 。 .

SDK将其软件包版本添加到 Iframe URL 作为 `sdkVersion`。不需要配置.

### 处理错误

承诺拒绝 `LinkError` 如果在同意流过程中遇到任何错误.

```ts
interface LinkError extends Error {
  name: 'LinkError';
  code: LinkErrorCode;
  details?: unknown;
}
```

| 错误代码 | 说明 |
| --- | --- |
| `LINK_NOT_FOUND` | DOM 中没有容器元素 |
| `LINK_TIMEOUT` | 流量超过选项中指定的超时时间 |
| `LINK_USER_CANCELLED` | 用户取消或程序流程关闭 |
| `LINK_ORIGIN_MISMATCH` | 从出乎意料的来源收到信件 |
| `LINK_INTERNAL_ERROR` | 在同意流中遇到的未识别错误 。 未知错误类型保存于 `details.error_type` |
| `LINK_INVALID_SESSION` | 指定的认证会话无效 |
| `AUTH_SESSION_INVALID` | 自动会话无效 |
| `AUTH_SESSION_CANCELLED` | Auth 会话被取消 |
| `CONSENT_UPSTREAM_PROCESSING_ERROR` | 同意流期间的上游处理出错 |
| `CONSENT_ENDUSER_DENIED` | 用户在同意流动期间拒绝同意 |
| `CONSENT_OTP_FAILURE` | 在同意期间检察官办公室的核查失败 |
| `CONSENT_ENDUSER_INELIGIBLE` | 用户没有资格共享数据 |
| `CONSENT_TIMEOUT` | 同意程序超时 |

注:用于 `LINK_INVALID_SESSION`iframe仍然挂着。 你可以按程序关闭它 `.close()`。 。 。 . 对于 `AUTH_SESSION_INVALID`,当承诺拒绝时,iframe被删除.

## UMD / CDN 用户

```html
<script src="https://cdn.jsdelivr.net/npm/@fiskil/link@1.0.0/dist/fiskil-link.umd.js"></script>
<script>
  const flow = FiskilLink.link('session_123');
  flow.then((res) => console.log('done', res)).catch(console.error);
  // flow.close();
</script>
```

## 常见问题

### @fiskil/link 是什么？

最小 TypeScript SDK 用于创建 Fiskil auth会话\(直接或iframe\)\.

### 如何安装 @fiskil/link？

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

### @fiskil/link 支持 TypeScript 吗？

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

### @fiskil/link 支持 ESM 还是 CommonJS？

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

### @fiskil/link 可以商用吗？

@fiskil/link 使用 SEE LICENSE IN LICENSE\.md 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @fiskil/link 的下载量有多少？

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

### @fiskil/link 还在维护吗？

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