# @finatic/client 中文文档

规范地址：https://npmcn.com/package/%40finatic/client/

版本：1\.1\.6
npm 元数据更新时间：2026-10-17T10:32:25.553Z
中文译文更新时间：2026-11-14T20:17:02.449Z
软件包许可：PROPRIETARY

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

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

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

- 包体积（解压后）：1.2 MB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：5 个
- peer 依赖：react \>=16\.8\.0，react-dom \>=16\.8\.0
- 首次发布：2025-07-16T22:31:38.630Z
- 最新版本发布：2026-10-17T10:32:25.199Z
- 近 30 天下载量：2129（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 24 个）

## 中文简介

用于浏览器集成的 Finatic 客户端 SDK

## 安装

```sh
npm install @finatic/client
```

也可以使用：`pnpm add @finatic/client`、`yarn add @finatic/client`、`bun add @finatic/client`

## README

# Finatic 客户端 SDK

浏览器 SDK 将 Finatic 连接和账户第一数据嵌入到 **您的前端**。公司 API 密钥从不属于此软件包。 您的后端( Server SDK) 薄荷能一次性地得到一个符; 浏览器只接收该符.

## 安装

```bash
npm install @finatic/client
```

## 快开始

```ts
import { FinaticConnect, isPortalLifecycleEventPayload } from '@finatic/client';

const finatic = await FinaticConnect.init('one-time-token', undefined, {
  apiEnvironment: 'sandbox', // or 'live'
});

await finatic.openPortal({
  mode: 'dark',
  onSuccess: (userId) => {
    // OTP / session ready. The user has not necessarily granted an account yet.
    console.log('Portal user linked:', userId);
  },
  onEvent: async (eventName, payload) => {
    if (eventName !== 'account.grant.created') return;
    const grant = payload as { accountId?: string };
    const accounts = await finatic.v1.listAccounts({ includeSyncStatus: true });
    const ready = accounts.success?.data ?? [];
    console.log('Grant created for', grant.accountId, 'accounts', ready);
  },
});
```

`openPortal` 必须使用 **对象** 要收到的表格 `onEvent`. 职位超载没有赠款活动.

连接解除时嵌入应用程序控制 。 打电话 `closePortal()` 从主机 UI 或处理可选的门户事件后; 重复呼叫为 在没有门户打开时安全无事:

```ts
await finatic.openPortal({
  onEvent: (eventName) => {
    if (eventName === 'account.grant.created') {
      finatic.closePortal();
    }
  },
  onClose: () => {
    // Runs once for either the portal close control or closePortal().
  },
});
```

### 门户认证和连接准备

`onSuccess(userId)` 表示门户会话认证. 这并不意味着 中间连接已经存在或连接器数据已经准备好 。 连接 schema v1 通过键入方式发布后期的转换 `portal.lifecycle` 事件:

```ts
await finatic.openPortal({
  onEvent: (eventName, payload) => {
    if (eventName !== 'portal.lifecycle' || !isPortalLifecycleEventPayload(payload)) return;

    switch (payload.stage) {
      case 'portal_authenticated':
        console.log('Portal authenticated', payload.userId);
        break;
      case 'broker_connection_created':
        console.log('Connection persisted', payload.connectionId);
        break;
      case 'push_agent_state_changed':
        // Only LIVE_DATA and STALE_LIVE_DATA can report dataReady: true.
        console.log(payload.state, payload.dataReady ?? 'not asserted');
        break;
    }
  },
});
```

SDK只有在符合Schema版本1和时才会接受生命周期消息 导出阶段/状态允许列表。 不支持的版本,错误的有效载荷, 出乎意料的字段(包括有秘密字段),以及无效的准备状态 放弃索赔。 现有范围 `(eventName: string, payload?: unknown)` 处理者仍然可以指派,非生命周期事件继续被转交.

客户端数据方法返回电线信封 `{ success, error, warning }` (无) `{ data, errors }`) (中文(简体) ).

### 精确的仪器描述符

账户订单、订单填充和事件、职位、位置、位置和数量都显示 API 生成 `FDXInstrumentDescriptor` 从包根。 准确的将来,保持满载 合同身份(`MGCZ6` 财务报告和审定财务报表 `MGCG7` ; 仅根符号,例如 `MGC` 为: 标记为 `future.identityQuality === 'ROOT_ONLY'`. 可选过期、交换、提供者符号, 并且当 API 无法校验时, 出处字段则不在此列 。 浏览器 SDK 不推断 或正常的仪器身份.

```ts
import {
  FDXFutureInstrumentDetailsIdentityQualityEnum,
  type FDXBrokerPosition,
} from '@finatic/client';

const result = await finatic.v1.listPositions({ accountId: 'account-id' });
const position: FDXBrokerPosition | undefined = result.success?.data[0];

if (
  position?.instrument?.future?.identityQuality ===
  FDXFutureInstrumentDetailsIdentityQualityEnum.Exact
) {
  console.log(position.instrument.finaticInstrumentId, position.instrument.future.contractCode);
}

await finatic.v1.createAccountOrder({
  accountId: 'account-id',
  idempotencyKey: crypto.randomUUID(),
  body: {
    order: {
      symbol: 'MGCZ6',
      finaticInstrumentId: 'fininst_mgcz6',
      instrumentId: 'provider-native-id',
    },
  },
});
```

后遗症符号唯命令体和现有的平面身份字段仍然得到支持. 当两者 提供身份字段,API验证它们在授权账户范围内同意.

### 合同能力和订单类型

包根导出 `FDXAssetType.EventContract`, (中文(简体) ), `EventContractCapabilityResponse`, (中文(简体) ), `AccountOrderSchemaResponse`,以及 `FinaticAPIErrorResponse` 从核准的公众开放API 艺术品 能力轴是独立的:提供者提供和执行证据不 意味着公共写作授权或账户权利。 处理 `publicEnabled !== true`, (中文(简体) ), `accountEntitled !== true`,或 `closingOnly === true` 作为不提交开业令的理由.

```ts
import {
  FDXAssetType,
  type AccountOrderSchemaResponse,
} from '@finatic/client';

const response = await finatic.v1.getAccountOrderSchema<AccountOrderSchemaResponse>({
  accountId: 'account-id',
  action: 'place',
});
const capability = response.success?.data.eventContract;

if (
  capability?.publicEnabled === true &&
  capability.accountEntitled === true &&
  capability.closingOnly !== true
) {
  await finatic.v1.createAccountOrder({
    accountId: 'account-id',
    idempotencyKey: crypto.randomUUID(),
    body: { order: { assetType: FDXAssetType.EventContract, symbol: 'EVENT-SYMBOL' } },
  });
}
```

`EVENT_CONTRACT` 是公共资产元素值。 供应商自有有效载荷领域,例如: `asset_type: 'event_contract'` 穿过没有改变。 未知的公开 `assetType` 值失败 而不是被省略或绘制为公平。 经认证的事件合同写作 公共授权仍需要提供者/账户证据;SDK的这一释放并不要求这些证据.

打电话 `FinaticConnect.reset()` 在此之前 `init` 当您需要一个新的会话边界时.

## 接头

```ts
// Backend (@finatic/server-node) — keep FINATIC_API_KEY here
const token = await finatic.v1.getToken();
// 90 seconds. Send token to the browser only.
```

从未在 Vite 中设置 API 密钥`NEXT_PUBLIC_` 用于生产.

## 从β移动

| Beta 路径家族 | v1 替换 |
| --- | --- |
| `/api/beta/session/init` | 后端 `v1.getToken()` 编号 : `session/init` |
| `/api/beta/session/start` | `FinaticConnect.init(oneTimeToken)` |
| `/api/beta/session/portal` | `finatic.openPortal(...)` 或后端 `v1.getPortalUrl()` |
| `/api/beta/brokers/data/accounts` | `finatic.v1.listAccounts(...)` |
| `/api/beta/brokers/data/balances` | `finatic.v1.listBalances({ accountId })` |
| `/api/beta/brokers/data/positions` | `finatic.v1.listPositions({ accountId })` |
| `/api/beta/brokers/data/orders` | `finatic.v1.listOrders({ accountId })` |
| `/api/beta/brokers/data/transactions` | `finatic.v1.listTransactions({ accountId })` |
| `/api/beta/brokers/orders` | `finatic.v1.createAccountOrder({ accountId, body, idempotencyKey })` |
| `/api/beta/brokers/connections` | `finatic.v1.listAccounts()` 加号 `finatic.v1.listAccountGrants()` |

连接拥有门户机构/自动/同意UX. 这些流动不是公布于 `finatic.v1`。位置批号不在v1外观上 `listPositions`不要通过β `connectionId` 作为 `{accountId}`。 。 。 .

## 环境

`apiEnvironment` 实值 `live` | `sandbox` (单位:千美元)`X-Finatic-Environment`) URL 预设(`environment: 'staging' | 'production' | ...`)与沙盒 vs活数据相分离.

## 常见命令

| 任务 | 命令 |
| --- | --- |
| 构建 | `npm run build` |
| 测试 | `npm test` |
| 林特 | `npm run lint` |

## 文档

这个README是客户SDK合同. 在写完整集成之前获取其余部分 :

-   快速开始 : [https://finatic.dev/docs/快克-起步/快克-起步](https://finatic.dev/docs/quick-start/quick-start)
-   节点后端读取器 : [https://github.com/FinaticORG/FinaticServerSDK-Node/blob/develop/README.md 互联网档案馆的存檔,存档日期2013-12-20](https://github.com/FinaticORG/FinaticServerSDK-Node/blob/develop/README.md)
-   Python 后端读取器 : [https://github.com/FinaticORG/FinaticServerSDK-Python/blob/develop/README.md 互联网档案馆的存檔,存档日期2013-12-21](https://github.com/FinaticORG/FinaticServerSDK-Python/blob/develop/README.md)
-   嵌入连接 : [https://finatic.dev/docs/quick-start/portal-configulation 页面存档备份,存于互联网档案馆](https://finatic.dev/docs/quick-start/portal-configuration)
-   演示应用 : [https://github.com/FinaticORG/FinaticDemoApps/blob/develop/README.md 互联网档案馆的存檔,存档日期2014-12-21](https://github.com/FinaticORG/FinaticDemoApps/blob/develop/README.md)
-   API 参考 : [https://finatic.dev/docs/api-参考资料](https://finatic.dev/docs/api-reference)
-   打开API : [https://finatic.dev/openapi.json 页面存档备份,存于互联网档案馆](https://finatic.dev/openapi.json)
-   代理索引 : [https://finatic.dev/llms.txt](https://finatic.dev/llms.txt)
-   代理笔记 : [https://finatic.dev/AGENTS.md (英语)](https://finatic.dev/AGENTS.md)

## 常见问题

### @finatic/client 是什么？

用于浏览器集成的 Finatic 客户端 SDK

### 如何安装 @finatic/client？

在项目目录运行 npm install @finatic/client，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8\.0）、react-dom（\>=16\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @finatic/client 支持 TypeScript 吗？

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

### @finatic/client 支持 ESM 还是 CommonJS？

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

### @finatic/client 需要什么版本的 Node\.js？

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

### @finatic/client 可以商用吗？

@finatic/client 使用 PROPRIETARY 许可。声明的许可为 PROPRIETARY，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @finatic/client 的下载量有多少？

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

### @finatic/client 还在维护吗？

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