gg-customer-adpter

TypeScript 扩展执行核心与 HostBridge 基线接入工具。客户协议、SDK、连接地址和初始化实现由使用方提供，本包不包含具体客户或演示实现。

安装

npm install gg-customer-adpter

ESM 包，提供类型声明；TypeScript 使用 moduleResolution: "Bundler"。无运行时 npm 依赖，不提供 CommonJS 入口。

职责

• 基线提供产品默认行为和扩展 API。
• 客户拓展实现使用本包注册能力，封装实际客户 SDK 或协议。
• 客户必须提供已实现、可调用的接口及协议说明。

本包不会自动连接客户、读取环境配置或接管业务。发布内容中没有 iframe 协议客户端、客户地址或默认客户能力配置。

扩展核心

import { ExtensionRegistry, type ExtensionPoint } from 'gg-customer-adpter/core';

const point: ExtensionPoint<string, string> = {
  key: 'greeting', version: 1,
  parseInput(value) {
    if (typeof value !== 'string') throw new Error('输入必须为字符串');
    return value;
  },
  parseOutput(value) {
    if (typeof value !== 'string') throw new Error('输出必须为字符串');
    return value;
  },
};
const registry = new ExtensionRegistry();
registry.registerDefault(point, name => `Hello ${name}`);
const restore = registry.replace(point, name => `你好，${name}`);
await registry.invoke(point, 'Alice');
restore();

未替换时执行默认实现；卸载后恢复默认实现。重复替换会报错。执行包含版本检查、输入输出校验、异步结果和错误传播。客户失败不重复执行默认行为，避免副作用。

调用上下文可传入 AbortSignal 进行协作式取消，不能撤销已经发生的外部操作。核心不依赖 DOM、UI 或 Node 专用模块。

HostBridge 接入

import {
  HostBridgeEvent, registerCapabilities,
  type CapabilityPolicy, type CustomerHandlers, type HostBridgeExtensionApi,
} from 'gg-customer-adpter';

export function install(
  api: HostBridgeExtensionApi,
  handlers: CustomerHandlers,
  policy: CapabilityPolicy,
) {
  return registerCapabilities(api, handlers, policy);
}

使用方提供处理函数和能力归属配置。每个事件分别选择 receive、send 为 baseline 或 customer。baseline 保留默认实现；customer 必须提供对应 handler，缺失则回滚本次注册并报错。返回的函数用于卸载。

契约覆盖全部 10 个事件：导航、登出、显示/隐藏遮罩、参数消费确认、关闭指定/当前标签、主题、token 和激活状态。

API 包含 replaceReceive、replaceSend、emitToTab、emitToApp、emitToAll、emitToWindow、listTargets 和 resolveNavigation。监听启动/停止与目标注册由基线负责。

类型定义见 baseline/contract.ts。基线与包内契约分别维护，协议变更时需同步验证。HostBridge 契约包含 Window 等浏览器类型；不使用 HostBridge 的运行环境可单独使用 core 子入口。

导航辅助与生命周期

createAdapter(client, allowedOrigin, options?) 接收使用方的 openPage 实现，校验 HTTP(S) 地址、目标 origin 和业务参数，可应用显式提供的 query 配置。它不提供客户通信方式或固定地址。

Scope 提供 defer、dispose、rollback，支持同步资源的逆序清理、幂等卸载和初始化失败回滚。清理失败仍尝试其余资源，以 AggregateError 报告。不支持等待异步 cleanup。

目录

| 目录 | 内容 | | --- | --- | | core/ | 注册、替换、执行、资源生命周期 | | baseline/ | HostBridge 契约、能力注册、URL 导航辅助 | | index.ts | 包入口 |

客户环境判断、SDK 封装、协议映射、能力配置和初始化组装应在使用方工程维护，不属于本包发布内容。

开发与发布

npm ci
npm test
npm pack

prepack 构建产物，prepublishOnly 执行测试。源码相对导入不带 .js，构建输出为打包 ESM。发布内容仅包含 dist、README 与包元数据。

发布前应在独立工程安装 tarball，验证主入口、core 入口和类型声明。正式项目使用版本依赖。

使用许可

当前为 UNLICENSED，未授予开源许可证。使用授权请联系维护者。