@anerevol/node-sdk

用于构建 AIO Platform Node（运行在 iframe 里的前端应用）的 SDK，通过 postMessage 与 Host 通信。

安装

npm install @anerevol/[email protected]

5 分钟接入

import { createNode } from "@anerevol/node-sdk";

const node = createNode({
  manifest: {
    id: "my-node",
    name: "我的节点",
    version: "1.0.0",
    input: { text: "string" },
    output: { result: "string" }
  },
  
  onInit(context, token) {
    node.progress(50, "处理中...");
    
    // 你的业务逻辑
    const result = doSomething(context);
    
    node.complete({ result });
  }
});

// 页面加载后调用：向 Host 声明 READY + 发送 manifest
node.ready();

通信流程

1. Node 加载完成后调用 node.ready()，发送 READY（包含 manifest）。
2. Host 收到 READY 后发送 INIT，带上 context + token。
3. Node 在 onInit(context, token) 里开始执行任务，并可发送：
   • PROGRESS：进度更新（可选）
   • EVENT：交互事件（可选，双向）
   • RESULT：最终结果（成功/失败）

API

createNode(options)

创建节点实例。

type NodeOptions = {
  manifest: Manifest;
  hostOrigins?: string[]; // 限定允许的 Host origin（推荐线上配置）
  onInit: (context: Record<string, unknown>, token: string) => void | Promise<void>;
  onEvent?: (name: string, payload?: Record<string, unknown>) => void;
};

node.ready()

通知 Host 节点已就绪，发送 manifest。

node.progress(percent, message?)

上报进度 (0-100)。

node.complete(data)

任务成功，返回结果数据。

node.fail(code, message)

任务失败，返回错误。

交互式节点：EVENT 事件

当 Node 需要“与 Host/UI 交互”（例如：打开侧边栏、请求选择资源、通知 Host 刷新数据、Host 控制 Node 切换视图）时，使用 EVENT。

事件结构：

{
  protocol: "aio-node-v1",
  type: "EVENT",
  name: string,
  payload?: Record<string, unknown>
}

node.emit(name, payload?)

Node → Host：发送事件给 Host。

// 发送事件，Host 会在日志面板中显示
node.emit("item_created", { id: "123", title: "New Item" });

// 纯通知事件
node.emit("user_interaction");

onEvent(name, payload?)

Host → Node：接收 Host 发来的事件。

const node = createNode({
  manifest: { /* ... */ },
  onInit(context, token) {
    // ...
  },
  onEvent(name, payload) {
    if (name === "set_filters") {
      // payload: { status: "open" }
      applyFilters(payload);
      return;
    }

    if (name === "ping") {
      node.emit("pong", { at: Date.now() });
    }
  }
});

Host 侧示例（伪代码）：

// 监听 Node -> Host 的事件
window.addEventListener("message", (e) => {
  if (e.data?.protocol !== "aio-node-v1") return;
  if (e.data.type === "EVENT") console.log("event from node:", e.data.name, e.data.payload);
});

// 向 Node iframe 发送 Host -> Node 的事件
iframeEl.contentWindow?.postMessage(
  { protocol: "aio-node-v1", type: "EVENT", name: "set_filters", payload: { status: "open" } },
  nodeOrigin
);

node.getToken()

获取 Host 签发的 JWT token。

node.isTokenExpiringSoon(thresholdMs?)

检查 token 是否即将过期（默认 5 分钟内）。

完整文档

见 docs/node-protocol

发布（维护者）

cd sdk/node-sdk
npm ci
npm version patch   # 或 minor/major
npm publish