# @finamx/bridge-protocol 中文文档

规范地址：https://npmcn.com/package/%40finamx/bridge-protocol/

版本：3\.7\.1
npm 元数据更新时间：2026-11-10T17:40:42.828Z
中文译文更新时间：2026-11-14T18:12:06.904Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：622 kB，268 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-06-10T03:46:30.977Z
- 最新版本发布：2026-11-10T17:40:42.513Z
- 近 30 天下载量：3977（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

@ finamx/ 桥- protocol

## 安装

```sh
npm install @finamx/bridge-protocol
```

也可以使用：`pnpm add @finamx/bridge-protocol`、`yarn add @finamx/bridge-protocol`、`bun add @finamx/bridge-protocol`

## README

# @ finamx/ 桥- protocol

在扩展iframes和FinamX主机应用程序之间共享Message后桥协议的TypeScript类型,常数和验证器.

两个东道方(`@finamx/host-bridge`)和扩展侧(`@finamx/extension-sdk`)依赖于这个软件包来保证消息形状,版本字符串,和范围定义的单一真理源.

## 安装

在单体内部,把它称为 `file:` 依赖性 :

```json
"dependencies": {
  "@finamx/bridge-protocol": "file:../bridge-protocol"
}
```

对于已公布的SDK扩展至npm,使用分解范围:

```json
"dependencies": {
  "@finamx/bridge-protocol": "^1.0.0"
}
```

## 使用量

```typescript
import {
  parseEnvelope,
  serializeEnvelope,
  isMethodAllowed,
  DEFAULT_GRANTED_SCOPES,
  type BridgeEnvelope,
  type BridgeHelloPayload,
} from '@finamx/bridge-protocol';

// Parse an incoming postMessage data value
const envelope = parseEnvelope(event.data); // throws BridgeProtocolError on invalid input

// Check whether a platform invoke is permitted
if (!isMethodAllowed('market.quote', session.grantedScopes)) {
  throw new Error('Scope not granted');
}
```

## 导出 API

### 常数

| 导出 | 数值 | 说明 |
| --- | --- | --- |
| `BRIDGE_VERSION` | `'1.0'` | 当前有线- protocol 版本; 在每个消息上验证 . |
| `EMBED_TO_HOST_TYPES` | 数组 | 所有消息类型 iframe 可发送扩展名 . |
| `HOST_TO_EMBED_TYPES` | 数组 | 主机可能发回的所有信件类型 . |
| `METHOD_SCOPE_MAP` | 对象 | 将平台方法名称映射到所需的能力范围. |
| `DEFAULT_GRANTED_SCOPES` | 数组 | 默认授予的范围`market.read`, (中文(简体) ), `ui.toast`, (中文(简体) ), `user.profile.read`) (中文(简体) ). |

### 类型/ 接口

| 类型 | 说明 |
| --- | --- |
| `BridgeEnvelope<T>` | 电线信封( E)`v`, (中文(简体) ), `type`, (中文(简体) ), `id?`, (中文(简体) ), `sessionId?`, (中文(简体) ), `payload?`) (中文(简体) ). |
| `BridgeMessageType` | 合并所有有效信件类型字符串 . |
| `BridgeHelloPayload` | 有效载荷 `bridge:hello` ——向主机识别出自己. |
| `BridgeReadyPayload` | 有效载荷 `bridge:ready` ——主办单位确认会话并授予范围. |
| `BridgeErrorPayload` | 有效载荷 `bridge:error` 结构错误 `code` 财务报告和审定财务报表 `message`。 。 。 . |
| `HostContext` | 主题、 地方、 平台 (`web`编号 :`ios`编号 :`android`),和app版本. |
| `UiResizePayload` | 有效载荷 `ui:resize` - 理想的iframe `height` 在像素中. |
| `UiSizePreferencePayload` | 有效载荷 `ui:sizePreference` — 宽比 XOR 命名断点; 不 `ui:resize`。大小是UI表面偏好(D-80-04),而不是新的扩展类型. |
| `UiWallPayload` | 有效载荷 `ui:wall` —— 说 `visible` 加号 `reason` `auth` | `payment`; 付款只按类型,没有计费字段. |
| `UiToastPayload` | 有效载荷 `ui:toast` —— 说 `message` 和可选 `variant`。 。 。 . |
| `PlatformInvokePayload` | 有效载荷 `platform:invoke` —— 说 `method` 和可选 `params`。 。 。 . |
| `PlatformResultPayload` | 有效载荷 `platform:result` —— 说 `ok`选项 `data` 或者说 `error`。 。 。 . |
| `PlatformEventPayload` | 有效载荷 `platform:event` 事件 `name` 和可选 `data`。 。 。 . |
| `PlatformRevokePayload` | 有效载荷 `platform:revoke` ——撤销 `reason`。 。 。 . |
| `BridgeSessionConfig` | 主办方持有的iframe活会的内部会话记录. |
| `LaunchResponse` | 形状返回由 `POST /embed/launch` 在 iframe 打开之前. |
| `InvokeRequest` | 内部类型用于主机-侧面方法发送. |
| `AuditEntry` | 每个平台都引用审计日志记录. |

### 验证器/公用事业

| 导出 | 说明 |
| --- | --- |
| `parseEnvelope(data)` | 解析并验证原始文件 `postMessage` 数据值; 抛出 `BridgeProtocolError`。 。 。 . |
| `serializeEnvelope(envelope)` | JSON 将一个信封序列化 `postMessage`。 。 。 . |
| `parseInvokePayload(payload)` | 验证 a `platform:invoke` 载荷. |
| `parseResizePayload(payload, maxHeight)` | 验证 a `ui:resize` 载荷和夹子高度. |
| `parseSizePreferencePayload(payload)` | 验证 a `ui:sizePreference` 有效载荷(确切地说是比例或断点). |
| `resolveSizePreference(pref, bounds)` | 共享主机布局数学:偏好 → 夹住像素高. |
| `parseWallPayload(payload)` | 验证 a `ui:wall` 有效载荷(`visible` + 关闭 `reason` `auth` | `payment`) (中文(简体) ). |
| `assertSessionMatch(envelope, session)` | 如果信封丢出 `sessionId` 不匹配活动会话. |
| `assertExternalEmbedPolicy(props)` | 如果外部扩展试图提供原始文件, 则丢弃 `embedUrl`。 。 。 . |
| `requiredScopeForMethod(method)` | 返回给定平台方法所需的范围字符串. |
| `isMethodAllowed(method, grantedScopes)` | 回返 `true` 当该方法所要求的范围在 `grantedScopes`。 。 。 . |
| `BridgeProtocolError` | 带有错误类 `code` 结构化错误处理的字符串 . |

## 身份补助金(3.0.0)

`widget.identity.grant` 保留其电线名称,但3.0.0移除了 HMAC 身份助手和 `./identity-context` 子路径。 该补助金现用于: `profile`数字 : `identity` 携带 `identityToken`ES256 JWT(由东道国签署)`typ: platform.identity.v1`(三); `exchange` 携带 `exchangeCode` + 键 `redeemUrl`. 混合两者的补助金被拒绝。 此软件包只定义和验证形状;它从不签名. `sessionJwt` 不得将核心/盖特韦标志置于框架或身份证书中.

## 构建

```bash
npm run build
```

编译类型脚本到 `dist/` (ESM) (英语). 这个 `prepare` 脚本自动运行 `npm install` 在单体内.

## 测试

```bash
npm test
```

先构建, 然后运行 `dist/validators.test.js` 使用节点内置测试跑道(`node --test`) (中文(简体) ).

## 常见问题

### @finamx/bridge-protocol 是什么？

@ finamx/ 桥- protocol

### 如何安装 @finamx/bridge-protocol？

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

### @finamx/bridge-protocol 支持 TypeScript 吗？

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

### @finamx/bridge-protocol 支持 ESM 还是 CommonJS？

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

### @finamx/bridge-protocol 可以商用吗？

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

### @finamx/bridge-protocol 的下载量有多少？

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

### @finamx/bridge-protocol 还在维护吗？

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