# @finteqhub/sdk-js 中文文档

规范地址：https://npmcn.com/package/%40finteqhub/sdk-js/

版本：0\.17\.0
npm 元数据更新时间：2026-09-24T09:39:49.273Z
中文译文更新时间：2026-11-14T19:45:53.536Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：40.9 kB，15 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2022-10-04T15:27:28.502Z
- 最新版本发布：2026-09-24T09:39:49.046Z
- 近 30 天下载量：2600（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 18 个）

## 中文简介

用于与处理 API 交互的 SDK

## 安装

```sh
npm install @finteqhub/sdk-js
```

也可以使用：`pnpm add @finteqhub/sdk-js`、`yarn add @finteqhub/sdk-js`、`bun add @finteqhub/sdk-js`

## README

# 处理 - sdk

使用 `new Processing(options: ProcessingOptions)` 以创建处理对象实例。 处理对象是处理 SDK 的切入点 .

```
interface ProcessingOptions {
  apiUrl: string;
  fingerprintVisitorId: string;
  sessionId: string;
  isSecure?: boolean; // default false
  retryOptions?: RetryOptions; // default {}
}

const processing = new Processing({
  apiUrl: 'api-url',
  fingerprintVisitorId: 'fingerprint-visitor-id',
  sessionId: 'session-id',
});
```

构造器验证其选项并扔出一个 `TypeError` 当它们不是对象时, 当它们包含一个未知的密钥( 例如拼写错误) `issecure`),何时 `apiUrl`, (中文(简体) ), `fingerprintVisitorId` 或者说 `sessionId` 缺少, 是否为空字符串, 当 `isSecure` 不是一个布尔,或者何时 `retryOptions` 格式错误( 见 [检索和错误诊断](https://npmcn.com/package/%40finteqhub/sdk-js/#readme-retries-and-error-diagnostics)) (中文(简体) ).

## 检索和错误诊断

失败的 HTTP 请求会自动以指数回放重试( S)`100ms → 200ms → 500ms → 1000ms → 2000ms`; 第5回等2000ms后每回试. 可以通过可选配置回覆 `retryOptions` 构造器选项 :

```
interface RetryOptions {
  retryCount?: number; // number of retries after the initial attempt, default 5; 0 disables retries
  retryStatusCode?: (statusCode: number) => boolean; // default: statusCode < 200 || statusCode === 408 || statusCode >= 500
}

const processing = new Processing({
  apiUrl: 'api-url',
  fingerprintVisitorId: 'fingerprint-visitor-id',
  sessionId: 'session-id',
  retryOptions: { retryCount: 3 },
});
```

要完全禁用重试, 请通过 `retryCount: 0` 如0.11.0所示,每一份请求都会发出一次。 错误诊断`RequestError`,则 `console.error` 仍可收集:

```
const processing = new Processing({
  apiUrl: 'api-url',
  fingerprintVisitorId: 'fingerprint-visitor-id',
  sessionId: 'session-id',
  retryOptions: { retryCount: 0 },
});
```

建筑师扔出一个 `TypeError` 何时 `retryOptions` 不是物体, `retryCount` 不是一个非负整数,或 `retryStatusCode` 不是一个函数.

网络出错( 浏览器完全无法到达服务器, 例如 ) . `TypeError: Failed to fetch`),或者在读取反应机体时连接下降)也总是被重试.

每一次重试都用 `console.warn`当请求最终失败时, SDK 日志 `console.error` (单位:千美元)`sdk-js: request failed: <message>`完全诊断的垃圾堆和拒绝的垃圾堆 `RequestError` 谁 `diagnostics` 字段载有同样的有效载荷——包括在您错误报告中. `diagnostics.kind` 告诉失败阶层:

-   `"network"` ——浏览器从未获得完整的响应(例如. `TypeError: Failed to fetch`,或无法读取尸体; `diagnostics.error` 描述抛出的错误, `diagnostics.response.status` 当信头在故障前到达时就在场, `message` 实值 `request to <url> failed after N attempt(s): ...`· ;
-   `"http_error"` 错误反应(非200状态,或 `error` (a) 实体内; `message` 是来自响应机构(或 `unexpected response status <code>` 当尸体没有的时候, `diagnostics.response.status` 带有 HTTP 状态,并 `diagnostics.response.error` 机构错误文本;
-   `"invalid_json"` - 反应机构不是有效的JSON `diagnostics.error` (解析出的错误;其信息遵循与机构相同的政策——为非200个进行消毒,为200个答复省略)和 `diagnostics.response` 已经设定.

每个 `diagnostics` 有效载荷还包括:

-   `sdkVersion`· ;
-   `request`:url,方法, `x-request-id`,会话 id 和 任意日志 `attempts: [{ durationMs, status?, error? }]` 尝试持续时间有助于从绞刑(出站/手摇)中看出即时失败(DNA/连接被拒绝);
-   `response.body` 对于非200个答复——短到500个带有长数字的字符被蒙住(`***`200份答复的正文从未列入,因为它可能携带会议全权证书;请求机构从未列入任何地方;
-   `response.error` - 那个 `error` 对于任何状态(包括200份答复,包括: `error` 字段);它是一个商业错误文本,因此既不被截断,也不被遮盖;
-   `environment`数字 : `navigator.onLine`, (中文(简体) ), `document.visibilityState`, (中文(简体) ), `navigator.connection` (单位:千美元)`effectiveType`编号 :`rtt`编号 :`downlink`只有铬),时间戳.

无论复试是否启用,都要收集诊断.

## SDK 识别头

SDK的每个请求都带有一个额外的标题:

```
x-pgw-sdk: sdk-js/<version>
```

该值包含 SDK 名称和版本( 与 SDK 同步) `package.json` ——例如 `sdk-js/0.11.0`. 后端使用这个头来识别来自官方SDK集成的流量——例如当安全固定放行时通知受影响的商人. 它不影响认证或请求路由.

每个请求都会自动添加标题,不能禁用.

## API 密码

### 处理.getSession ()

使用 `processing.getSession` 以获取会话信息(支付方法、证书字段、业务金额和货币、入帐凭证)来制作表格。 这是可选的: `submitForm` 并不依赖于它,可以在构建实例后立即被调用.

```
processing
  .getSession()
  .then(result => console.log(result))
  .catch(error => console.warn(error));
```

### 正在处理. sumitForm( 数据)

使用 `processing.submitForm` 以提交交易。 当呼叫时, `processing.submitForm` 将试图完成处理交易所需的任何行动。 这种方法返回以响应解决的许诺( E)`{ "type": "redirect", "redirectUrl": string}`)或描述失败的错误.

```
processing
  .submitForm(data)
  .then(result => console.log(result))
  .catch(error => console.warn(error));
```

## 使用量

### 只提交

最小流量是构建实例和呼叫 `submitForm` ——无需再提出其他要求. 当您自己的用户界面已经知道要向客户收取什么时使用它(例如,付款方法及其证书字段固定在您一边):

```
import { Processing } from "@finteqhub/sdk-js";
import FingerprintJS from "@fingerprintjs/fingerprintjs";

const fp = await FingerprintJS.load();
const result = await fp.get();

const processing = new Processing({ apiUrl, fingerprintVisitorId: result.visitorId, sessionId });

const data = {/** collect data from form **/}

processing
  .submitForm(data)
  .then(result => console.log(result))
  .catch(error => console.warn(error));
```

### 从会话数据渲染窗体

打电话 `getSession` 当窗体本身从会话中构建时:可用的支付方法、其证书字段、操作金额和货币. `submitForm` 不使用结果—— 它只驱动您的 UI :

```
const processing = new Processing({ apiUrl, fingerprintVisitorId: result.visitorId, sessionId });

const session = await processing.getSession();

const data = {/** collect data from form rendered from session **/}

processing
  .submitForm(data)
  .then(result => console.log(result))
  .catch(error => console.warn(error));
```

## 释放

在每个版本的突起更新上 **两者** `package.json` `version` 财务报告和审定财务报表 `SDK_VERSION` 内 `src/version.ts` 他们必须保持同步 所以 `x-pgw-sdk` 标题报告正确的版本 . `src/version.test.ts` 如果它们漂移, CI 失败( N)`node scripts/sync-version.js` 更新 `src/version.ts` 从 `package.json`) (中文(简体) ). 说明释放情况 [变动情况](https://npmcn.com/package/%40finteqhub/sdk-js/CHANGELOG.md),包括用于突破变化的移民笔记.

### Beta 发布

要尝试修改后, 才会撞出版本, 请运行 `publish-beta` 工作流程(GitHub – Actions – 发布-β – 运行工作流程,选择你的分支). 它出版 `<current version>-beta.<run number>` 到 npm 下边 `beta` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}这太夸张了 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}我.. `latest` 而Repo中的版本则保持不变。 安装于 :

```
npm i @finteqhub/sdk-js@beta
```

或将工作流程摘要中打印的确切版本标出.

## 常见问题

### @finteqhub/sdk-js 是什么？

用于与处理 API 交互的 SDK

### 如何安装 @finteqhub/sdk-js？

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

### @finteqhub/sdk-js 支持 TypeScript 吗？

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

### @finteqhub/sdk-js 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @finteqhub/sdk-js 可以商用吗？

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

### @finteqhub/sdk-js 的下载量有多少？

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

### @finteqhub/sdk-js 还在维护吗？

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