@ finamx/ 桥- protocol
在扩展iframes和FinamX主机应用程序之间共享Message后桥协议的TypeScript类型,常数和验证器.
两个东道方(@finamx/host-bridge)和扩展侧(@finamx/extension-sdk)依赖于这个软件包来保证消息形状,版本字符串,和范围定义的单一真理源.
安装
在单体内部,把它称为 file: 依赖性 :
"dependencies": {
"@finamx/bridge-protocol": "file:../bridge-protocol"
}
对于已公布的SDK扩展至npm,使用分解范围:
"dependencies": {
"@finamx/bridge-protocol": "^1.0.0"
}
使用量
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 携带 identityTokenES256 JWT(由东道国签署)typ: platform.identity.v1(三); exchange 携带 exchangeCode + 键 redeemUrl. 混合两者的补助金被拒绝。 此软件包只定义和验证形状;它从不签名. sessionJwt 不得将核心/盖特韦标志置于框架或身份证书中.
构建
npm run build
编译类型脚本到 dist/ (ESM) (英语). 这个 prepare 脚本自动运行 npm install 在单体内.
测试
npm test
先构建, 然后运行 dist/validators.test.js 使用节点内置测试跑道(node --test) (中文(简体) ).