@international-iot-association/api-bridge 3.0.0-rc.1

package/README.md

@@ -0,0 +1,4 @@
+# @international-iot-association/api-bridge
+
+基于 Proxy 的类型安全 RPC 桥接层。
+属于**组 A · 协议锁步组**（与 `plugin-contracts`/`plugin-sdk`/`rct-state` 一起随 `agentApi` major 锁步发布）。

package/dist/index.cjs

@@ -0,0 +1,399 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APIProxy: () => APIProxy,
+  ApiBridgeError: () => ApiBridgeError,
+  BRIDGE_ERROR_SUGGESTIONS: () => BRIDGE_ERROR_SUGGESTIONS,
+  createAPIClient: () => createAPIClient,
+  createAPIProxy: () => createAPIProxy,
+  createAPIServer: () => createAPIServer,
+  makeErrorResponse: () => makeErrorResponse,
+  sendMessage: () => sendMessage,
+  subscribeToMessage: () => subscribeToMessage,
+  waitForMessage: () => waitForMessage
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/API.proxy.ts
+function createAPIProxy(customCallingFunction) {
+  const createHandler = (path) => {
+    return {
+      get(target, propKey, receiver) {
+        if (typeof propKey === "string") {
+          switch (propKey) {
+            case "call":
+            case "callWithOptions":
+            case "invoke":
+            case "invokeWithOptions":
+            case "onRequest":
+            case "on":
+            case "sendEvent":
+              return (...args) => {
+                if (customCallingFunction && typeof customCallingFunction === "function") {
+                  const callingResult = customCallingFunction(
+                    path,
+                    args,
+                    propKey
+                  );
+                  if (callingResult) {
+                    return callingResult;
+                  }
+                }
+                return {
+                  api: path,
+                  args
+                };
+              };
+            default: {
+              const newPath = [...path, propKey];
+              return new Proxy({}, createHandler(newPath));
+            }
+          }
+        }
+        return Reflect.get(target, propKey, receiver);
+      }
+    };
+  };
+  return new Proxy({}, createHandler([]));
+}
+var APIProxy = createAPIProxy();
+
+// src/core/errors.ts
+var BRIDGE_ERROR_SUGGESTIONS = {
+  TARGET_UNAVAILABLE: "\u786E\u8BA4\u76EE\u6807\u63D2\u4EF6/\u670D\u52A1\u5DF2\u5B89\u88C5\u5E76\u5904\u4E8E\u8FD0\u884C\u72B6\u6001\u540E\u91CD\u8BD5",
+  METHOD_NOT_FOUND: "\u68C0\u67E5 API \u540D\u79F0\u62FC\u5199\u4E0E\u76EE\u6807\u63D2\u4EF6\u7248\u672C\u662F\u5426\u63D0\u4F9B\u8BE5\u65B9\u6CD5",
+  REMOTE_HANDLER_ERROR: "\u67E5\u770B\u76EE\u6807 runtime \u65E5\u5FD7\u4E2D\u7684\u9519\u8BEF\u8BE6\u60C5",
+  TRANSPORT_CLOSED: "\u901A\u8BAF\u94FE\u8DEF\u5DF2\u5173\u95ED\uFF08runtime \u505C\u6B62/\u9875\u9762\u5378\u8F7D\uFF09\uFF0C\u91CD\u65B0\u5EFA\u7ACB\u540E\u91CD\u8BD5",
+  REQUEST_TIMEOUT: "\u786E\u8BA4\u5BF9\u7AEF\u5B58\u6D3B\u5E76\u9002\u5F53\u8C03\u5927 timeoutMs \u540E\u91CD\u8BD5"
+};
+var ApiBridgeError = class extends Error {
+  code;
+  /** 点分 API 路径，如 "station.runTest"。 */
+  apiPath;
+  requestId;
+  timeoutMs;
+  /** 建议动作（人可读，供 UI/日志展示）。 */
+  suggestion;
+  constructor(code, apiPath, message, options = {}) {
+    super(`[${code}] ${apiPath}: ${message}`);
+    this.name = "ApiBridgeError";
+    this.code = code;
+    this.apiPath = apiPath;
+    this.requestId = options.requestId;
+    this.timeoutMs = options.timeoutMs;
+    this.suggestion = options.suggestion ?? BRIDGE_ERROR_SUGGESTIONS[code];
+  }
+};
+function makeErrorResponse(request, code, message) {
+  return {
+    type: "response",
+    id: request.id ?? "",
+    result: void 0,
+    error: { code, message },
+    meta: { api: request.api, args: [] }
+  };
+}
+
+// src/core/API.server.ts
+function createAPIServer(config) {
+  const { sendMessageFunc } = config;
+  const requestProcessorCache = {};
+  const server = createAPIProxy((api, args, callingFunctionName) => {
+    switch (callingFunctionName) {
+      case "onRequest": {
+        const processor = args[0];
+        if (processor && typeof processor === "function") {
+          requestProcessorCache[api.join(".")] = args[0];
+        } else {
+          console.error(
+            `[Error] register API Server processor error for ${JSON.stringify(
+              api
+            )}, handler is not a function.`
+          );
+        }
+        break;
+      }
+      case "sendEvent":
+        if (config.sendEventFunc) {
+          const event = {
+            type: "event",
+            name: args[0],
+            data: args[1],
+            meta: {
+              api,
+              args
+            }
+          };
+          config.sendEventFunc(event);
+        } else {
+          console.warn("[Warn] sendEventFunc is not defined.");
+        }
+        break;
+      default:
+        break;
+    }
+  });
+  async function serverHandler(request) {
+    const { id, api, args, context } = request;
+    if (!(api && args)) {
+      console.warn(
+        "[Warn] [Skip] API Server process, original message:",
+        request
+      );
+      return;
+    }
+    const apiName = api.join(".");
+    const wantsTypedErrors = request.wantsTypedErrors === true;
+    if (!requestProcessorCache[apiName]) {
+      if (wantsTypedErrors && sendMessageFunc && id) {
+        sendMessageFunc(
+          makeErrorResponse(request, "METHOD_NOT_FOUND", `no handler registered for API: ${apiName}`)
+        );
+        return;
+      }
+      console.warn(`[Warn] There is no handler registered for API: ${apiName}`);
+      return;
+    }
+    let result;
+    try {
+      result = await requestProcessorCache[apiName].apply(null, [
+        ...args,
+        context
+      ]);
+    } catch (err) {
+      if (wantsTypedErrors && sendMessageFunc && id) {
+        sendMessageFunc(
+          makeErrorResponse(
+            request,
+            "REMOTE_HANDLER_ERROR",
+            err instanceof Error ? err.message : String(err)
+          )
+        );
+        return;
+      }
+      throw err;
+    }
+    if (sendMessageFunc && id) {
+      sendMessageFunc({
+        type: "response",
+        id,
+        result,
+        meta: {
+          api,
+          // v2 响应不回显请求参数（尤其不回显 token/敏感 payload）；
+          // 1.x 响应按原协议回显以保持兼容。
+          args: wantsTypedErrors ? [] : args,
+          context: wantsTypedErrors ? void 0 : context
+        }
+      });
+    }
+  }
+  return { server, serverHandler };
+}
+
+// src/core/API.client.ts
+var import_non_secure = require("nanoid/non-secure");
+
+// src/utils/RxMessage.ts
+var import_rxjs = require("rxjs");
+var messageDispatcher = new import_rxjs.Subject();
+function sendMessage(id, payload) {
+  const message = { id, payload };
+  messageDispatcher.next(message);
+}
+var DEFAULT_TIMEOUT_MS = 1e4;
+function subscribeToMessage(targetId, timeoutDurationMs = DEFAULT_TIMEOUT_MS) {
+  return messageDispatcher.pipe(
+    (0, import_rxjs.filter)((message) => message.id === targetId),
+    (0, import_rxjs.map)((message) => message.payload),
+    (0, import_rxjs.timeout)({
+      first: timeoutDurationMs,
+      with: () => (0, import_rxjs.of)(null)
+    }),
+    (0, import_rxjs.take)(1)
+  );
+}
+async function waitForMessage(targetId, timeoutMs) {
+  try {
+    const payload = await (0, import_rxjs.firstValueFrom)(
+      subscribeToMessage(targetId, timeoutMs)
+    );
+    return payload;
+  } catch (error) {
+    console.error(`[AsyncWait] Error waiting for ID=${targetId}:`, error);
+    return null;
+  }
+}
+
+// src/core/API.client.ts
+var DEFAULT_INVOKE_TIMEOUT_MS = 1e4;
+function createAPIClient(config) {
+  const { debug = false, requestServerFunc } = config;
+  const eventHandlerCache = {};
+  const pendingInvokes = /* @__PURE__ */ new Map();
+  const client = createAPIProxy((api, args, callingFunctionName) => {
+    if (debug) {
+      console.info(
+        "[API Client] API:",
+        api,
+        "Args:",
+        args,
+        "callingFunctionName:",
+        callingFunctionName
+      );
+    }
+    switch (callingFunctionName) {
+      case "call":
+      case "callWithOptions": {
+        const id = (0, import_non_secure.nanoid)();
+        const hasClientOptions = callingFunctionName === "callWithOptions";
+        const clientOptions = hasClientOptions ? args[0] ?? {} : void 0;
+        const requestArgs = hasClientOptions ? args.slice(1) : args;
+        const responseSub = waitForMessage(id, clientOptions?.timeoutMs);
+        return (async () => {
+          await requestServerFunc({
+            type: "request",
+            api,
+            args: requestArgs,
+            id
+          });
+          return responseSub;
+        })();
+      }
+      case "invoke":
+      case "invokeWithOptions": {
+        const id = (0, import_non_secure.nanoid)();
+        const hasClientOptions = callingFunctionName === "invokeWithOptions";
+        const clientOptions = hasClientOptions ? args[0] ?? {} : {};
+        const requestArgs = hasClientOptions ? args.slice(1) : args;
+        const apiPath = api.join(".");
+        const timeoutMs = clientOptions.timeoutMs ?? DEFAULT_INVOKE_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+          const timer = setTimeout(() => {
+            pendingInvokes.delete(id);
+            reject(
+              new ApiBridgeError(
+                "REQUEST_TIMEOUT",
+                apiPath,
+                `no response within ${timeoutMs}ms`,
+                { requestId: id, timeoutMs }
+              )
+            );
+          }, timeoutMs);
+          pendingInvokes.set(id, { resolve, reject, timer, apiPath });
+          Promise.resolve(
+            requestServerFunc({
+              type: "request",
+              api,
+              args: requestArgs,
+              id,
+              wantsTypedErrors: true
+            })
+          ).catch((err) => {
+            const pending = pendingInvokes.get(id);
+            if (!pending) return;
+            clearTimeout(pending.timer);
+            pendingInvokes.delete(id);
+            reject(
+              new ApiBridgeError(
+                "TARGET_UNAVAILABLE",
+                apiPath,
+                `transport send failed: ${err instanceof Error ? err.message : String(err)}`,
+                { requestId: id }
+              )
+            );
+          });
+        });
+      }
+      case "on": {
+        const apiName = api.join(".");
+        const key = `${apiName}:${args[0]}`;
+        const func = args[1];
+        eventHandlerCache[key] = func;
+        return () => {
+          delete eventHandlerCache[key];
+        };
+      }
+      default:
+        break;
+    }
+  });
+  function serverEventHandler(event, config2) {
+    const { name, data, meta } = event;
+    const { debug: debug2 = false } = config2 || {};
+    const key = `${meta.api.join(".")}:${name}`;
+    if (debug2) {
+      console.info("[API Client] Server Event:", key, "Data:", data);
+    }
+    if (key && eventHandlerCache[key]) {
+      eventHandlerCache[key](data);
+    }
+    if (eventHandlerCache["*"] && eventHandlerCache["*"] instanceof Function) {
+      eventHandlerCache["*"](data, event);
+    }
+    const eventKeyForTargetAPI = `${meta.api.join(".")}:*`;
+    if (eventHandlerCache[eventKeyForTargetAPI] && eventHandlerCache[eventKeyForTargetAPI] instanceof Function) {
+      eventHandlerCache[eventKeyForTargetAPI](data, event);
+    }
+  }
+  function clientMessageHandler(message) {
+    const pending = pendingInvokes.get(message.id);
+    if (pending) {
+      clearTimeout(pending.timer);
+      pendingInvokes.delete(message.id);
+      if (message.error) {
+        pending.reject(
+          new ApiBridgeError(message.error.code, pending.apiPath, message.error.message, {
+            requestId: message.id
+          })
+        );
+      } else {
+        pending.resolve(message.result);
+      }
+      return;
+    }
+    sendMessage(message.id, message);
+  }
+  function closeTransport(reason = "transport closed") {
+    for (const [id, pending] of pendingInvokes) {
+      clearTimeout(pending.timer);
+      pending.reject(
+        new ApiBridgeError("TRANSPORT_CLOSED", pending.apiPath, reason, { requestId: id })
+      );
+    }
+    pendingInvokes.clear();
+  }
+  return { client, serverEventHandler, clientMessageHandler, closeTransport };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIProxy,
+  ApiBridgeError,
+  BRIDGE_ERROR_SUGGESTIONS,
+  createAPIClient,
+  createAPIProxy,
+  createAPIServer,
+  makeErrorResponse,
+  sendMessage,
+  subscribeToMessage,
+  waitForMessage
+});

package/dist/index.d.cts

@@ -0,0 +1,186 @@
+import { Observable } from 'rxjs';
+
+type BridgeErrorCode = "TARGET_UNAVAILABLE" | "METHOD_NOT_FOUND" | "REMOTE_HANDLER_ERROR" | "TRANSPORT_CLOSED" | "REQUEST_TIMEOUT";
+/** 各错误码的默认建议动作（诊断展示用，可被覆盖）。 */
+declare const BRIDGE_ERROR_SUGGESTIONS: Record<BridgeErrorCode, string>;
+interface ApiBridgeErrorOptions {
+    requestId?: string;
+    timeoutMs?: number;
+    suggestion?: string;
+}
+declare class ApiBridgeError extends Error {
+    readonly code: BridgeErrorCode;
+    /** 点分 API 路径，如 "station.runTest"。 */
+    readonly apiPath: string;
+    readonly requestId?: string;
+    readonly timeoutMs?: number;
+    /** 建议动作（人可读，供 UI/日志展示）。 */
+    readonly suggestion: string;
+    constructor(code: BridgeErrorCode, apiPath: string, message: string, options?: ApiBridgeErrorOptions);
+}
+/**
+ * 由传输层/服务端合成一个错误响应信封。
+ * 注意：错误响应的 meta 不回显请求参数（args 置空），避免 token/敏感 payload
+ * 在错误路径上被二次传播。
+ */
+declare function makeErrorResponse(request: Pick<Request, "id" | "api">, code: BridgeErrorCode, message: string): Response;
+
+interface Meta {
+    api: string[];
+    args: any[];
+    context?: any;
+}
+type Request = Meta & {
+    type: "request";
+    id?: string;
+    /**
+     * v2 客户端（invoke/invokeWithOptions）置 true：服务端对缺 handler/handler
+     * 抛错应答错误信封。1.x 请求没有该字段，服务端保持旧行为（警告 + 静默）。
+     */
+    wantsTypedErrors?: boolean;
+};
+interface Response<Result = any> {
+    type: "response";
+    id: string;
+    result: Result;
+    meta: Meta;
+    /** v2 错误信封：仅发给声明了 wantsTypedErrors 的请求。 */
+    error?: {
+        code: BridgeErrorCode;
+        message: string;
+    };
+}
+interface Event {
+    type: "event";
+    name: string;
+    data: any;
+    meta: Meta;
+}
+interface CallResult {
+    api: string[];
+    args: any[];
+}
+type OnRequestHandler<T extends any[]> = (...args: T) => any;
+interface ClientCallOptions {
+    timeoutMs?: number;
+}
+type FuncHandler<Args extends any[] = any[], Result = any> = {
+    /** 幻影判别符（仅类型层，运行时不存在）：供 ApiClient/ApiServer 方向映射识别叶子。 */
+    __kind?: "func";
+    /** 供 Client 使用（1.x：resolve 完整 envelope；超时/远端错误 resolve null） */
+    call: (...args: Args) => Promise<Response<Result>>;
+    /** 供 Client 使用，携带本地选项（选项不会发送给服务端） */
+    callWithOptions: (options: ClientCallOptions, ...args: Args) => Promise<Response<Result>>;
+    /** 供 Client 使用（v2）：resolve result 本体；失败以 ApiBridgeError reject */
+    invoke: (...args: Args) => Promise<Result>;
+    /** 供 Client 使用（v2）：带本地选项（如 timeoutMs）的 invoke */
+    invokeWithOptions: (options: ClientCallOptions, ...args: Args) => Promise<Result>;
+    /** 供 Server 使用 */
+    onRequest: (handler: OnRequestHandler<Args>) => any;
+    /** 供 Client 监听 Server 事件 */
+    on: (eventName: string, handler: (data: any) => void | Promise<void>) => () => void;
+    /** 供 Server 使用，向 Client 发送事件数据 */
+    sendEvent: (eventName: string, data: any) => void | Promise<void>;
+} & {
+    [key: string]: any;
+};
+type EventListener<EventName extends string, EventData> = {
+    /** 幻影判别符（仅类型层，运行时不存在）：供 ApiClient/ApiServer 方向映射识别叶子。 */
+    __kind?: "event";
+    /** 供 Client 监听 Server 事件 */
+    on: (eventName: EventName, handler: (data: EventData) => void | Promise<void>) => () => void;
+    /** 供 Server 使用，向 Client 发送事件数据 */
+    sendEvent: (eventName: EventName, data: EventData) => void | Promise<void>;
+} & {
+    [key: string]: any;
+};
+type ApiNode<T extends any[], P extends Record<string, any> = Record<string, any>> = {
+    [key: string]: ApiNode<T, P>;
+};
+type ApiRoot<T extends any[] = any[]> = {
+    [key: string]: ApiNode<T>;
+};
+type DynamicChainedProxy<T extends any[]> = ApiNode<T>;
+declare function createAPIProxy<T extends ApiRoot<any[]>>(customCallingFunction?: (api: string[], args: any[], callingFunctionName: "call" | "callWithOptions" | "invoke" | "invokeWithOptions" | "onRequest" | "on" | "sendEvent") => any): T;
+declare const APIProxy: ApiRoot<any[]>;
+
+/** 客户端方法面（请求/响应叶子）。 */
+interface ClientFuncFace<Args extends any[], Result> {
+    /** 1.x：resolve 完整 envelope；超时/远端错误 resolve null。 */
+    call(...args: Args): Promise<Response<Result>>;
+    callWithOptions(options: ClientCallOptions, ...args: Args): Promise<Response<Result>>;
+    /** v2：resolve result 本体；失败以 ApiBridgeError reject。 */
+    invoke(...args: Args): Promise<Result>;
+    invokeWithOptions(options: ClientCallOptions, ...args: Args): Promise<Result>;
+}
+/** 服务端方法面（请求/响应叶子）。 */
+interface ServerFuncFace<Args extends any[], Result> {
+    onRequest(handler: (...args: Args) => Result | Promise<Result>): unknown;
+}
+/** 客户端事件面（事件叶子）。 */
+interface ClientEventFace<EventName extends string, EventData> {
+    on(eventName: EventName, handler: (data: EventData) => void | Promise<void>): () => void;
+}
+/** 服务端事件面（事件叶子）。 */
+interface ServerEventFace<EventName extends string, EventData> {
+    sendEvent(eventName: EventName, data: EventData): void | Promise<void>;
+}
+/** 消费方向视图：UI/服务消费者持有的类型。 */
+type ApiClient<T> = {
+    [K in keyof T]: T[K] extends {
+        __kind?: "func";
+        call: (...args: infer A extends any[]) => Promise<Response<infer R>>;
+    } ? ClientFuncFace<A, R> : T[K] extends {
+        __kind?: "event";
+        on: (eventName: infer N extends string, handler: (data: infer D) => void | Promise<void>) => () => void;
+    } ? ClientEventFace<N, D> : ApiClient<T[K]>;
+};
+/** 提供方向视图：runtime/服务提供者持有的类型。 */
+type ApiServer<T> = {
+    [K in keyof T]: T[K] extends {
+        __kind?: "func";
+        call: (...args: infer A extends any[]) => Promise<Response<infer R>>;
+    } ? ServerFuncFace<A, R> : T[K] extends {
+        __kind?: "event";
+        on: (eventName: infer N extends string, handler: (data: infer D) => void | Promise<void>) => () => void;
+    } ? ServerEventFace<N, D> : ApiServer<T[K]>;
+};
+
+type SendEventFunction = (event: Event) => void;
+type SendMessageFunction = (response: Response) => void;
+interface CreateAPIServerConfig {
+    sendEventFunc?: SendEventFunction;
+    sendMessageFunc?: SendMessageFunction;
+    debug?: boolean;
+}
+declare function createAPIServer<T extends ApiRoot<any[]>>(config: CreateAPIServerConfig): {
+    server: T;
+    serverHandler: (request: Request) => Promise<void>;
+};
+
+type RequestServerFunc = (request: Request) => Promise<any>;
+interface CreateAPIClientConfig {
+    /** 是否打印调试信息，默认 false */
+    debug?: boolean;
+    requestServerFunc: RequestServerFunc;
+}
+declare function createAPIClient<T extends ApiRoot>(config: CreateAPIClientConfig): {
+    client: T;
+    serverEventHandler: (event: Event, config?: {
+        debug?: boolean;
+    }) => void;
+    clientMessageHandler: (message: Response) => void;
+    closeTransport: (reason?: string) => void;
+};
+
+/** 以 id 为键将消息推送到总线。 */
+declare function sendMessage<T>(id: string | number, payload: T): void;
+/**
+ * 订阅指定 id 的第一条消息。发出 payload，超时则发出 null，
+ * 随后完成（自动取消订阅）。
+ */
+declare function subscribeToMessage<T = any>(targetId: string | number, timeoutDurationMs?: number): Observable<T | null>;
+/** subscribeToMessage 的 async/await 封装。 */
+declare function waitForMessage<T = any>(targetId: string | number, timeoutMs?: number): Promise<T | null>;
+
+export { APIProxy, ApiBridgeError, type ApiBridgeErrorOptions, type ApiClient, type ApiRoot, type ApiServer, BRIDGE_ERROR_SUGGESTIONS, type BridgeErrorCode, type CallResult, type ClientCallOptions, type ClientEventFace, type ClientFuncFace, type DynamicChainedProxy, type Event, type EventListener, type FuncHandler, type Meta, type OnRequestHandler, type Request, type Response, type ServerEventFace, type ServerFuncFace, createAPIClient, createAPIProxy, createAPIServer, makeErrorResponse, sendMessage, subscribeToMessage, waitForMessage };

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+import { Observable } from 'rxjs';
+
+type BridgeErrorCode = "TARGET_UNAVAILABLE" | "METHOD_NOT_FOUND" | "REMOTE_HANDLER_ERROR" | "TRANSPORT_CLOSED" | "REQUEST_TIMEOUT";
+/** 各错误码的默认建议动作（诊断展示用，可被覆盖）。 */
+declare const BRIDGE_ERROR_SUGGESTIONS: Record<BridgeErrorCode, string>;
+interface ApiBridgeErrorOptions {
+    requestId?: string;
+    timeoutMs?: number;
+    suggestion?: string;
+}
+declare class ApiBridgeError extends Error {
+    readonly code: BridgeErrorCode;
+    /** 点分 API 路径，如 "station.runTest"。 */
+    readonly apiPath: string;
+    readonly requestId?: string;
+    readonly timeoutMs?: number;
+    /** 建议动作（人可读，供 UI/日志展示）。 */
+    readonly suggestion: string;
+    constructor(code: BridgeErrorCode, apiPath: string, message: string, options?: ApiBridgeErrorOptions);
+}
+/**
+ * 由传输层/服务端合成一个错误响应信封。
+ * 注意：错误响应的 meta 不回显请求参数（args 置空），避免 token/敏感 payload
+ * 在错误路径上被二次传播。
+ */
+declare function makeErrorResponse(request: Pick<Request, "id" | "api">, code: BridgeErrorCode, message: string): Response;
+
+interface Meta {
+    api: string[];
+    args: any[];
+    context?: any;
+}
+type Request = Meta & {
+    type: "request";
+    id?: string;
+    /**
+     * v2 客户端（invoke/invokeWithOptions）置 true：服务端对缺 handler/handler
+     * 抛错应答错误信封。1.x 请求没有该字段，服务端保持旧行为（警告 + 静默）。
+     */
+    wantsTypedErrors?: boolean;
+};
+interface Response<Result = any> {
+    type: "response";
+    id: string;
+    result: Result;
+    meta: Meta;
+    /** v2 错误信封：仅发给声明了 wantsTypedErrors 的请求。 */
+    error?: {
+        code: BridgeErrorCode;
+        message: string;
+    };
+}
+interface Event {
+    type: "event";
+    name: string;
+    data: any;
+    meta: Meta;
+}
+interface CallResult {
+    api: string[];
+    args: any[];
+}
+type OnRequestHandler<T extends any[]> = (...args: T) => any;
+interface ClientCallOptions {
+    timeoutMs?: number;
+}
+type FuncHandler<Args extends any[] = any[], Result = any> = {
+    /** 幻影判别符（仅类型层，运行时不存在）：供 ApiClient/ApiServer 方向映射识别叶子。 */
+    __kind?: "func";
+    /** 供 Client 使用（1.x：resolve 完整 envelope；超时/远端错误 resolve null） */
+    call: (...args: Args) => Promise<Response<Result>>;
+    /** 供 Client 使用，携带本地选项（选项不会发送给服务端） */
+    callWithOptions: (options: ClientCallOptions, ...args: Args) => Promise<Response<Result>>;
+    /** 供 Client 使用（v2）：resolve result 本体；失败以 ApiBridgeError reject */
+    invoke: (...args: Args) => Promise<Result>;
+    /** 供 Client 使用（v2）：带本地选项（如 timeoutMs）的 invoke */
+    invokeWithOptions: (options: ClientCallOptions, ...args: Args) => Promise<Result>;
+    /** 供 Server 使用 */
+    onRequest: (handler: OnRequestHandler<Args>) => any;
+    /** 供 Client 监听 Server 事件 */
+    on: (eventName: string, handler: (data: any) => void | Promise<void>) => () => void;
+    /** 供 Server 使用，向 Client 发送事件数据 */
+    sendEvent: (eventName: string, data: any) => void | Promise<void>;
+} & {
+    [key: string]: any;
+};
+type EventListener<EventName extends string, EventData> = {
+    /** 幻影判别符（仅类型层，运行时不存在）：供 ApiClient/ApiServer 方向映射识别叶子。 */
+    __kind?: "event";
+    /** 供 Client 监听 Server 事件 */
+    on: (eventName: EventName, handler: (data: EventData) => void | Promise<void>) => () => void;
+    /** 供 Server 使用，向 Client 发送事件数据 */
+    sendEvent: (eventName: EventName, data: EventData) => void | Promise<void>;
+} & {
+    [key: string]: any;
+};
+type ApiNode<T extends any[], P extends Record<string, any> = Record<string, any>> = {
+    [key: string]: ApiNode<T, P>;
+};
+type ApiRoot<T extends any[] = any[]> = {
+    [key: string]: ApiNode<T>;
+};
+type DynamicChainedProxy<T extends any[]> = ApiNode<T>;
+declare function createAPIProxy<T extends ApiRoot<any[]>>(customCallingFunction?: (api: string[], args: any[], callingFunctionName: "call" | "callWithOptions" | "invoke" | "invokeWithOptions" | "onRequest" | "on" | "sendEvent") => any): T;
+declare const APIProxy: ApiRoot<any[]>;
+
+/** 客户端方法面（请求/响应叶子）。 */
+interface ClientFuncFace<Args extends any[], Result> {
+    /** 1.x：resolve 完整 envelope；超时/远端错误 resolve null。 */
+    call(...args: Args): Promise<Response<Result>>;
+    callWithOptions(options: ClientCallOptions, ...args: Args): Promise<Response<Result>>;
+    /** v2：resolve result 本体；失败以 ApiBridgeError reject。 */
+    invoke(...args: Args): Promise<Result>;
+    invokeWithOptions(options: ClientCallOptions, ...args: Args): Promise<Result>;
+}
+/** 服务端方法面（请求/响应叶子）。 */
+interface ServerFuncFace<Args extends any[], Result> {
+    onRequest(handler: (...args: Args) => Result | Promise<Result>): unknown;
+}
+/** 客户端事件面（事件叶子）。 */
+interface ClientEventFace<EventName extends string, EventData> {
+    on(eventName: EventName, handler: (data: EventData) => void | Promise<void>): () => void;
+}
+/** 服务端事件面（事件叶子）。 */
+interface ServerEventFace<EventName extends string, EventData> {
+    sendEvent(eventName: EventName, data: EventData): void | Promise<void>;
+}
+/** 消费方向视图：UI/服务消费者持有的类型。 */
+type ApiClient<T> = {
+    [K in keyof T]: T[K] extends {
+        __kind?: "func";
+        call: (...args: infer A extends any[]) => Promise<Response<infer R>>;
+    } ? ClientFuncFace<A, R> : T[K] extends {
+        __kind?: "event";
+        on: (eventName: infer N extends string, handler: (data: infer D) => void | Promise<void>) => () => void;
+    } ? ClientEventFace<N, D> : ApiClient<T[K]>;
+};
+/** 提供方向视图：runtime/服务提供者持有的类型。 */
+type ApiServer<T> = {
+    [K in keyof T]: T[K] extends {
+        __kind?: "func";
+        call: (...args: infer A extends any[]) => Promise<Response<infer R>>;
+    } ? ServerFuncFace<A, R> : T[K] extends {
+        __kind?: "event";
+        on: (eventName: infer N extends string, handler: (data: infer D) => void | Promise<void>) => () => void;
+    } ? ServerEventFace<N, D> : ApiServer<T[K]>;
+};
+
+type SendEventFunction = (event: Event) => void;
+type SendMessageFunction = (response: Response) => void;
+interface CreateAPIServerConfig {
+    sendEventFunc?: SendEventFunction;
+    sendMessageFunc?: SendMessageFunction;
+    debug?: boolean;
+}
+declare function createAPIServer<T extends ApiRoot<any[]>>(config: CreateAPIServerConfig): {
+    server: T;
+    serverHandler: (request: Request) => Promise<void>;
+};
+
+type RequestServerFunc = (request: Request) => Promise<any>;
+interface CreateAPIClientConfig {
+    /** 是否打印调试信息，默认 false */
+    debug?: boolean;
+    requestServerFunc: RequestServerFunc;
+}
+declare function createAPIClient<T extends ApiRoot>(config: CreateAPIClientConfig): {
+    client: T;
+    serverEventHandler: (event: Event, config?: {
+        debug?: boolean;
+    }) => void;
+    clientMessageHandler: (message: Response) => void;
+    closeTransport: (reason?: string) => void;
+};
+
+/** 以 id 为键将消息推送到总线。 */
+declare function sendMessage<T>(id: string | number, payload: T): void;
+/**
+ * 订阅指定 id 的第一条消息。发出 payload，超时则发出 null，
+ * 随后完成（自动取消订阅）。
+ */
+declare function subscribeToMessage<T = any>(targetId: string | number, timeoutDurationMs?: number): Observable<T | null>;
+/** subscribeToMessage 的 async/await 封装。 */
+declare function waitForMessage<T = any>(targetId: string | number, timeoutMs?: number): Promise<T | null>;
+
+export { APIProxy, ApiBridgeError, type ApiBridgeErrorOptions, type ApiClient, type ApiRoot, type ApiServer, BRIDGE_ERROR_SUGGESTIONS, type BridgeErrorCode, type CallResult, type ClientCallOptions, type ClientEventFace, type ClientFuncFace, type DynamicChainedProxy, type Event, type EventListener, type FuncHandler, type Meta, type OnRequestHandler, type Request, type Response, type ServerEventFace, type ServerFuncFace, createAPIClient, createAPIProxy, createAPIServer, makeErrorResponse, sendMessage, subscribeToMessage, waitForMessage };

package/dist/index.js

@@ -0,0 +1,371 @@
+// src/core/API.proxy.ts
+function createAPIProxy(customCallingFunction) {
+  const createHandler = (path) => {
+    return {
+      get(target, propKey, receiver) {
+        if (typeof propKey === "string") {
+          switch (propKey) {
+            case "call":
+            case "callWithOptions":
+            case "invoke":
+            case "invokeWithOptions":
+            case "onRequest":
+            case "on":
+            case "sendEvent":
+              return (...args) => {
+                if (customCallingFunction && typeof customCallingFunction === "function") {
+                  const callingResult = customCallingFunction(
+                    path,
+                    args,
+                    propKey
+                  );
+                  if (callingResult) {
+                    return callingResult;
+                  }
+                }
+                return {
+                  api: path,
+                  args
+                };
+              };
+            default: {
+              const newPath = [...path, propKey];
+              return new Proxy({}, createHandler(newPath));
+            }
+          }
+        }
+        return Reflect.get(target, propKey, receiver);
+      }
+    };
+  };
+  return new Proxy({}, createHandler([]));
+}
+var APIProxy = createAPIProxy();
+
+// src/core/errors.ts
+var BRIDGE_ERROR_SUGGESTIONS = {
+  TARGET_UNAVAILABLE: "\u786E\u8BA4\u76EE\u6807\u63D2\u4EF6/\u670D\u52A1\u5DF2\u5B89\u88C5\u5E76\u5904\u4E8E\u8FD0\u884C\u72B6\u6001\u540E\u91CD\u8BD5",
+  METHOD_NOT_FOUND: "\u68C0\u67E5 API \u540D\u79F0\u62FC\u5199\u4E0E\u76EE\u6807\u63D2\u4EF6\u7248\u672C\u662F\u5426\u63D0\u4F9B\u8BE5\u65B9\u6CD5",
+  REMOTE_HANDLER_ERROR: "\u67E5\u770B\u76EE\u6807 runtime \u65E5\u5FD7\u4E2D\u7684\u9519\u8BEF\u8BE6\u60C5",
+  TRANSPORT_CLOSED: "\u901A\u8BAF\u94FE\u8DEF\u5DF2\u5173\u95ED\uFF08runtime \u505C\u6B62/\u9875\u9762\u5378\u8F7D\uFF09\uFF0C\u91CD\u65B0\u5EFA\u7ACB\u540E\u91CD\u8BD5",
+  REQUEST_TIMEOUT: "\u786E\u8BA4\u5BF9\u7AEF\u5B58\u6D3B\u5E76\u9002\u5F53\u8C03\u5927 timeoutMs \u540E\u91CD\u8BD5"
+};
+var ApiBridgeError = class extends Error {
+  code;
+  /** 点分 API 路径，如 "station.runTest"。 */
+  apiPath;
+  requestId;
+  timeoutMs;
+  /** 建议动作（人可读，供 UI/日志展示）。 */
+  suggestion;
+  constructor(code, apiPath, message, options = {}) {
+    super(`[${code}] ${apiPath}: ${message}`);
+    this.name = "ApiBridgeError";
+    this.code = code;
+    this.apiPath = apiPath;
+    this.requestId = options.requestId;
+    this.timeoutMs = options.timeoutMs;
+    this.suggestion = options.suggestion ?? BRIDGE_ERROR_SUGGESTIONS[code];
+  }
+};
+function makeErrorResponse(request, code, message) {
+  return {
+    type: "response",
+    id: request.id ?? "",
+    result: void 0,
+    error: { code, message },
+    meta: { api: request.api, args: [] }
+  };
+}
+
+// src/core/API.server.ts
+function createAPIServer(config) {
+  const { sendMessageFunc } = config;
+  const requestProcessorCache = {};
+  const server = createAPIProxy((api, args, callingFunctionName) => {
+    switch (callingFunctionName) {
+      case "onRequest": {
+        const processor = args[0];
+        if (processor && typeof processor === "function") {
+          requestProcessorCache[api.join(".")] = args[0];
+        } else {
+          console.error(
+            `[Error] register API Server processor error for ${JSON.stringify(
+              api
+            )}, handler is not a function.`
+          );
+        }
+        break;
+      }
+      case "sendEvent":
+        if (config.sendEventFunc) {
+          const event = {
+            type: "event",
+            name: args[0],
+            data: args[1],
+            meta: {
+              api,
+              args
+            }
+          };
+          config.sendEventFunc(event);
+        } else {
+          console.warn("[Warn] sendEventFunc is not defined.");
+        }
+        break;
+      default:
+        break;
+    }
+  });
+  async function serverHandler(request) {
+    const { id, api, args, context } = request;
+    if (!(api && args)) {
+      console.warn(
+        "[Warn] [Skip] API Server process, original message:",
+        request
+      );
+      return;
+    }
+    const apiName = api.join(".");
+    const wantsTypedErrors = request.wantsTypedErrors === true;
+    if (!requestProcessorCache[apiName]) {
+      if (wantsTypedErrors && sendMessageFunc && id) {
+        sendMessageFunc(
+          makeErrorResponse(request, "METHOD_NOT_FOUND", `no handler registered for API: ${apiName}`)
+        );
+        return;
+      }
+      console.warn(`[Warn] There is no handler registered for API: ${apiName}`);
+      return;
+    }
+    let result;
+    try {
+      result = await requestProcessorCache[apiName].apply(null, [
+        ...args,
+        context
+      ]);
+    } catch (err) {
+      if (wantsTypedErrors && sendMessageFunc && id) {
+        sendMessageFunc(
+          makeErrorResponse(
+            request,
+            "REMOTE_HANDLER_ERROR",
+            err instanceof Error ? err.message : String(err)
+          )
+        );
+        return;
+      }
+      throw err;
+    }
+    if (sendMessageFunc && id) {
+      sendMessageFunc({
+        type: "response",
+        id,
+        result,
+        meta: {
+          api,
+          // v2 响应不回显请求参数（尤其不回显 token/敏感 payload）；
+          // 1.x 响应按原协议回显以保持兼容。
+          args: wantsTypedErrors ? [] : args,
+          context: wantsTypedErrors ? void 0 : context
+        }
+      });
+    }
+  }
+  return { server, serverHandler };
+}
+
+// src/core/API.client.ts
+import { nanoid } from "nanoid/non-secure";
+
+// src/utils/RxMessage.ts
+import {
+  Subject,
+  filter,
+  firstValueFrom,
+  map,
+  of,
+  take,
+  timeout
+} from "rxjs";
+var messageDispatcher = new Subject();
+function sendMessage(id, payload) {
+  const message = { id, payload };
+  messageDispatcher.next(message);
+}
+var DEFAULT_TIMEOUT_MS = 1e4;
+function subscribeToMessage(targetId, timeoutDurationMs = DEFAULT_TIMEOUT_MS) {
+  return messageDispatcher.pipe(
+    filter((message) => message.id === targetId),
+    map((message) => message.payload),
+    timeout({
+      first: timeoutDurationMs,
+      with: () => of(null)
+    }),
+    take(1)
+  );
+}
+async function waitForMessage(targetId, timeoutMs) {
+  try {
+    const payload = await firstValueFrom(
+      subscribeToMessage(targetId, timeoutMs)
+    );
+    return payload;
+  } catch (error) {
+    console.error(`[AsyncWait] Error waiting for ID=${targetId}:`, error);
+    return null;
+  }
+}
+
+// src/core/API.client.ts
+var DEFAULT_INVOKE_TIMEOUT_MS = 1e4;
+function createAPIClient(config) {
+  const { debug = false, requestServerFunc } = config;
+  const eventHandlerCache = {};
+  const pendingInvokes = /* @__PURE__ */ new Map();
+  const client = createAPIProxy((api, args, callingFunctionName) => {
+    if (debug) {
+      console.info(
+        "[API Client] API:",
+        api,
+        "Args:",
+        args,
+        "callingFunctionName:",
+        callingFunctionName
+      );
+    }
+    switch (callingFunctionName) {
+      case "call":
+      case "callWithOptions": {
+        const id = nanoid();
+        const hasClientOptions = callingFunctionName === "callWithOptions";
+        const clientOptions = hasClientOptions ? args[0] ?? {} : void 0;
+        const requestArgs = hasClientOptions ? args.slice(1) : args;
+        const responseSub = waitForMessage(id, clientOptions?.timeoutMs);
+        return (async () => {
+          await requestServerFunc({
+            type: "request",
+            api,
+            args: requestArgs,
+            id
+          });
+          return responseSub;
+        })();
+      }
+      case "invoke":
+      case "invokeWithOptions": {
+        const id = nanoid();
+        const hasClientOptions = callingFunctionName === "invokeWithOptions";
+        const clientOptions = hasClientOptions ? args[0] ?? {} : {};
+        const requestArgs = hasClientOptions ? args.slice(1) : args;
+        const apiPath = api.join(".");
+        const timeoutMs = clientOptions.timeoutMs ?? DEFAULT_INVOKE_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+          const timer = setTimeout(() => {
+            pendingInvokes.delete(id);
+            reject(
+              new ApiBridgeError(
+                "REQUEST_TIMEOUT",
+                apiPath,
+                `no response within ${timeoutMs}ms`,
+                { requestId: id, timeoutMs }
+              )
+            );
+          }, timeoutMs);
+          pendingInvokes.set(id, { resolve, reject, timer, apiPath });
+          Promise.resolve(
+            requestServerFunc({
+              type: "request",
+              api,
+              args: requestArgs,
+              id,
+              wantsTypedErrors: true
+            })
+          ).catch((err) => {
+            const pending = pendingInvokes.get(id);
+            if (!pending) return;
+            clearTimeout(pending.timer);
+            pendingInvokes.delete(id);
+            reject(
+              new ApiBridgeError(
+                "TARGET_UNAVAILABLE",
+                apiPath,
+                `transport send failed: ${err instanceof Error ? err.message : String(err)}`,
+                { requestId: id }
+              )
+            );
+          });
+        });
+      }
+      case "on": {
+        const apiName = api.join(".");
+        const key = `${apiName}:${args[0]}`;
+        const func = args[1];
+        eventHandlerCache[key] = func;
+        return () => {
+          delete eventHandlerCache[key];
+        };
+      }
+      default:
+        break;
+    }
+  });
+  function serverEventHandler(event, config2) {
+    const { name, data, meta } = event;
+    const { debug: debug2 = false } = config2 || {};
+    const key = `${meta.api.join(".")}:${name}`;
+    if (debug2) {
+      console.info("[API Client] Server Event:", key, "Data:", data);
+    }
+    if (key && eventHandlerCache[key]) {
+      eventHandlerCache[key](data);
+    }
+    if (eventHandlerCache["*"] && eventHandlerCache["*"] instanceof Function) {
+      eventHandlerCache["*"](data, event);
+    }
+    const eventKeyForTargetAPI = `${meta.api.join(".")}:*`;
+    if (eventHandlerCache[eventKeyForTargetAPI] && eventHandlerCache[eventKeyForTargetAPI] instanceof Function) {
+      eventHandlerCache[eventKeyForTargetAPI](data, event);
+    }
+  }
+  function clientMessageHandler(message) {
+    const pending = pendingInvokes.get(message.id);
+    if (pending) {
+      clearTimeout(pending.timer);
+      pendingInvokes.delete(message.id);
+      if (message.error) {
+        pending.reject(
+          new ApiBridgeError(message.error.code, pending.apiPath, message.error.message, {
+            requestId: message.id
+          })
+        );
+      } else {
+        pending.resolve(message.result);
+      }
+      return;
+    }
+    sendMessage(message.id, message);
+  }
+  function closeTransport(reason = "transport closed") {
+    for (const [id, pending] of pendingInvokes) {
+      clearTimeout(pending.timer);
+      pending.reject(
+        new ApiBridgeError("TRANSPORT_CLOSED", pending.apiPath, reason, { requestId: id })
+      );
+    }
+    pendingInvokes.clear();
+  }
+  return { client, serverEventHandler, clientMessageHandler, closeTransport };
+}
+export {
+  APIProxy,
+  ApiBridgeError,
+  BRIDGE_ERROR_SUGGESTIONS,
+  createAPIClient,
+  createAPIProxy,
+  createAPIServer,
+  makeErrorResponse,
+  sendMessage,
+  subscribeToMessage,
+  waitForMessage
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@international-iot-association/api-bridge",
+  "version": "3.0.0-rc.1",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/International-IoT-Association/MES.git",
+    "directory": "electron-station-plugins/packages/api-bridge"
+  },
+  "description": "Proxy-based type-safe RPC bridge (production-validated). v2: typed errors + invoke/invokeWithOptions; 1.x call() semantics preserved.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm run build && node --test test/*.test.mjs",
+    "clean": "rimraf dist .turbo"
+  },
+  "dependencies": {
+    "nanoid": "^5.1.5",
+    "rxjs": "^7.8.2"
+  },
+  "devDependencies": {
+    "@international-iot-association/tsconfig": "1.0.0-rc.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.9.3"
+  },
+  "x-internal-version": "2.0.0",
+  "x-source-revision": "410a2f3b85ef03b678f04f22ea0a47718f5ddae1"
+}