@ finamx/ extension- sdk

FinamX开放平台扩展开发者的TypeScript SDK. 将您的 Iframe 或 WebView 连接到 FinamX 主机桥上, 处理握手, 消息路由, 以及打印平台引用 .

部分 finamx 移动 单相机.

安装

npm install @finamx/extension-sdk @finamx/bridge-protocol

对于本地单列开发,直接参考软件包:

{
  "dependencies": {
    "@finamx/extension-sdk": "file:../../packages/extension-sdk",
    "@finamx/bridge-protocol": "file:../../packages/bridge-protocol"
  }
}

快开始

import { createExtensionBridge } from '@finamx/extension-sdk';

// Called once on extension load. Resolves after the host sends bridge:ready.
const bridge = await createExtensionBridge();

console.log(bridge.hostContext.theme);   // 'light' | 'dark'
console.log(bridge.grantedScopes);       // string[] of approved permission scopes

// Resize the iframe to fit content
bridge.ui.resize({ height: 400 });

// Show a toast notification in the host shell
bridge.ui.toast('Loaded', 'success');

// Invoke a platform method
const quote = await bridge.platform.invoke<{ last: number }>('market.quote', { symbol: 'SBER' });
console.log(quote.last);

// Subscribe to platform events (returns an unsubscribe function)
const off = bridge.platform.on('theme.changed', (payload) => {
  console.log('new theme:', payload.data);
});

CLI( finamx-ext) (中文(简体) )

包裹运送 finamx-ext 开发者 CLI (Node QQ 20).

npx @finamx/extension-sdk init my-widget
cd my-widget && npm install
finamx-ext login
finamx-ext hosts
finamx-ext domain pull <hostId>
finamx-ext publish

全球选项: --api <url>, (中文(简体) ), --token <key> (遗产,未为 login, (中文(简体) ), --json, (中文(简体) ), --help, (中文(简体) ), --version。 。 。 . serve 是静态的 CSP 服务器; dev 是本地开发商主机 .

门户和密钥存储

默认门户是 https://openplatform.changesandbox.ru; 使用 --api 或者说 FINAMX_API_URL 用于另一个项目(例如当地CMS)。 开发者密钥按此顺序解决: --token, (中文(简体) ), FINAMX_DEV_TOKEN,项目 .env, (中文(简体) ), ~/.config/finamx/credentials.json (第0600节). login 从隐藏的提示读取密钥或 --token-stdin; 密钥从未被打印. 主机密钥( E)fxh_...)被拒绝.

门户网站按以下顺序解决: --api, (中文(简体) ), FINAMX_API_URL 在工艺环境中, FINAMX_API_URL 在项目中 .env,默认值。 仅由项目命名的门户 .env 不决定从别处得到的密钥去向:当它是回回键或默认的出入口时,当密钥来自同一处时使用 .env,或当密钥由 login 确切的来源。 环境钥匙或 --token 拒绝使用 PORTAL_NOT_CONFIRMED 直到你通过 --api <url> 或导出 FINAMX_API_URL (克隆存储器控制) .env你控制你的壳. login 在门户网站读取密钥前打印该门户,并且 .env 门户网站,请求确认(与 --token-stdin 这需要 --api) (中文(简体) ).

.finamx/domain 版式

.finamx/
  domain/<hostId|templates>/
    CONTEXT.md        # human and agent readable summary
    domain.json       # topics, methods, scopes
    types.d.ts        # generated types
    mocks/<method>.json, mocks/<topic>.json
  mocks.override.json # { "methods": { "name": { "params": ..., "result": ... } }, "topics": { "name": payload } }

.finamx/ 承诺. domain pull --check 当主机域改变时,将文件保留在未动处并退出 1 .

这些文件中的主机文本是数据,而不是指令: in CONTEXT.md 所有的东西 code 后每行 >输入 types.d.ts jSDoc文本和所引用的名字。 名称或范围不是普通名的条目(字母,数字, . _ : @ / -,最多128个字符) ! <target>: skipped ... 警告 警告他们 混合文件名称跟随条目名称;在对大小写不敏感文件系统中拼接的名称(Market.Quote 财务报告和审定财务报表 market.quote每个得到一个 ~<8 hex> 后缀,和 CONTEXT.md 列出每个条目的文件. domain pull 财务报告和审定财务报表 init 拒绝通过符号链接写入( n)SYMLINK_REFUSED) (中文(简体) ).

QQ 出版商

第九十六期 出版商 а. {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}你还不知道吗.

• QQ 出版商 : --publisher <id>时 FINAMX_PUBLISHER, затем * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * (单位:千美元)finamx-ext publishers use <id>时 credentials.json) (中文(简体) ). {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}你觉得呢 出版者, а (PUBLISHER_REQUIRED{\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}你觉得呢.
• finamx-ext publishers {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}这才是你最爱的.
• push и status · 出版商, + + ; push {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}你觉得呢.
• {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}你觉得怎样/developer/invitations{\fn黑体\fs20\shad2\2aH82\3aH20\4aH33\fscx95\3cH592001\be1}你喜欢什么.
• ,开发者链接 # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # Link QQ,出击.

退出代码

0 成功; 1 失败, 或发现更改 domain pull --check; 2 环境问题 check --host (例如 playwright-core 或Chrome失踪).

分析(3.3.0)

finamx-ext analytics 阅读选定出版商在协调世界时每一天的发射、引用、拒绝、安装和延迟(要求有96.1阶段的CMS).

finamx-ext analytics --extension com.acme.x --from 2026-10-01 --group-by day,host
finamx-ext analytics --json

用户少于 k 的单元格被隐藏并显示为 < k; 总计只覆盖显示单元格。 选择使用 --publisher, (中文(简体) ), FINAMX_PUBLISHER 或者说 finamx-ext publishers use <id>。注意: --version <v> 在此以扩展版本过滤 .

没有终端的工具的背景包

V0 或 Data按钮等工具不能运行技能 . finamx-ext context [<hostId>|templates] 打印一个包含平台规则、SDK使用和目标域(方法、专题、范围、同意)的标记下包。 无 --remote 它在下面读取取的复制品 .finamx/domain/ 并且不需要密钥和网络 --remote 它用开发者密钥获取域并验证其 domainHash (没有印在不匹配上). 没有目标,只使用被拉住的主机(若干被拉住的主机是一个错误,从不猜测);没有被拉住, --remote 默认为 templates,而离线表则失败,请求拉出. --json 打印一个对象 { format, target, kind, origin, domainHash, markdown }。 。 。 .

finamx-ext context trading-diary > context.md

同样的包可以从开发商的柜式按钮"QQ"和CMS路由中找到 GET /api/v1/developer/context/{target} 使用开发者密钥。 渲染器是导出 @finamx/extension-sdk/context-pack (单位:千美元)renderContextPack, (中文(简体) ), mergeTemplateDomains)),所以三个都产生了相同的文本. 主机文本(描述,名称,计划)是数据,而不是指令:它坐落在代码跨度中的主机数据标记下, > 绳子和栅栏,包被封为48 000个字符。 包里没有钥匙.

出口

主要条目@finamx/extension-sdk(中文(简体) )

域会模拟条目( S)@finamx/extension-sdk/domain-mocks(中文(简体) )

纯模拟合成从主机域( E)buildDomainMocks, (中文(简体) ), parseMocksOverride, (中文(简体) ), synthesizeFromSchema, (中文(简体) ), buildMethodMock, (中文(简体) ), buildTopicMock和界限 exceedsDepth, (中文(简体) ), DOMAIN_MAX_DEPTH, (中文(简体) ), TOPIC_SCHEMA_MAX_CHARS。节点内置;同一代码服务 finamx-ext dev 和云德华主.

密舱条目( E)@finamx/extension-sdk/mock(中文(简体) )

createExtensionBridge(options?)

async function createExtensionBridge(
  options?: CreateExtensionBridgeOptions,
): Promise<ExtensionBridge>

interface CreateExtensionBridgeOptions {
  extensionId?: string;        // overrides value from window.__FINAMX_BRIDGE_SESSION__
  bridgeVersion?: string;      // defaults to BRIDGE_VERSION from @finamx/bridge-protocol
  invokeTimeoutMs?: number;    // default 30 000 ms
  transport?: EmbedTransport;  // custom transport; auto-detected if omitted
  debug?: boolean;             // enable envelope logging
  onLog?: (entry: BridgeLogEntry) => void; // required when debug=true
}

运输是自动检测的:WebView(window.FinamXBridge)优先于 postMessage。 。 。 .

地方发展的桥梁模拟器

使用 createMockBridge 在没有运行的主机的情况下开发和测试您的扩展名:

import { createMockBridge } from '@finamx/extension-sdk/mock';

const bridge = createMockBridge({
  hostContext: { theme: 'dark', locale: 'ru' },
  grantedScopes: ['market.quote', 'user.profile.read'],
  invokeHandler: async (method, params) => {
    if (method === 'market.quote') {
      return { symbol: params.symbol, last: 310.0, change: 0.5 };
    }
    throw new Error(`Unhandled: ${method}`);
  },
});

// Same ExtensionBridge interface — no code changes needed for production
const quote = await bridge.platform.invoke('market.quote', { symbol: 'GAZP' });

内置的接驳器( 无时使用) invokeHandler 提供:

调试日志

const bridge = await createExtensionBridge({
  debug: true,
  onLog: (entry) => console.log(`[bridge] ${entry.direction} ${entry.type}`, entry),
});

BridgeLogEntry 从未包含PII——引用参数,结果数据,以及 grantedScopes 数值被故意省略.

主机身份( 3. 0.0)

verifyHostIdentity 检查主机签名 platform.identity.v1 符号: 签名, 需要 typ准确 audience 财务报告和审定财务报表 issuer,到期后,主机 JWKS 密钥和 CMS 签名 authorized-issuers 对您的扩展( JWKS 成员资格还不够) . resolveHostIdentity(bridge, options) 等待着 widget.identity.grant 并进行同样的核查。 两者都是故障闭塞,没有HMAC路径,以及 platform.auth_context.v1 保留单独的、无子的发射授权证明. sessionJwt 不得将核心/盖特韦标志置于框架或身份证书中.

import { resolveHostIdentity } from '@finamx/extension-sdk';

const claims = await resolveHostIdentity(bridge, { audience, issuer, authorizedIssuersSig, cmsJwksUrl: `${cmsBase}/op/jwks`, jwksUrl });

构建

npm run build   # tsc -p tsconfig.json → dist/

没有 test 在此软件包中配置了脚本 。 融入测试现场 extension-template 应用程序,它消耗了这个软件包.

CMS 签名信托( 3. 9.1)

部署 /op/jwks 财务报告和审定财务报表 /host/jwks 在升级前在CMS中。 标准 CMS 代号 校验者在配置后选择此专用源 JWKS URL,无倒置. 自定义 JWKS 来源并注入 getKey编号 :cmsGetKey 解析器必须只包含 CMS 签名密钥 。 主机身份保留其单独的主机 密钥来源( e)/host/jwks)和CMS签名的安装装订. 当前/重叠主机密钥 保留在遗产中 /.well-known/jwks.json 兼容性的终点; 会员总数从未授予CMS授权.