@realnation/builder-shared-sdk 0.1.1 → 1.0.1

package/README.md

@@ -0,0 +1,227 @@
+# @realnation/builder-shared-sdk
+
+一个为Vite模块联邦微前端设计的轻量级SDK，旨在简化Host（宿主应用）与Remote（远程模块）之间的通信和流程控制。
+
+## ✨ 功能
+
+- **HTTP客户端共享**: 提供统一的`axios`实例，自动处理鉴权Token，避免在每个Remote中重复配置。
+- **全局事件总线**: 一个简单的发布/订阅系统，用于在Host和Remotes之间或Remotes彼此之间进行解耦的通信。
+- **动态流程控制**: 一个极其灵活的事件驱动流程控制机制，允许Host动态注册回调，由任意Remote在特定时机触发。
+
+## 📦 安装
+
+```bash
+npm install @realnation/builder-shared-sdk
+# or
+yarn add @realnation/builder-shared-sdk
+# or
+pnpm add @realnation/builder-shared-sdk
+```
+
+## 🚀 快速上手
+
+### 1. 初始化HTTP客户端 (在Host中)
+
+在您的Host应用启动时，配置共享的HTTP客户端。
+
+```typescript
+import { configureHttpClient, setAuthToken } from '@realnation/builder-shared-sdk';
+
+// 登录后，从您的用户会话中获取Token
+const userToken = 'your-jwt-token-here';
+setAuthToken(userToken);
+
+// 配置API基础URL和超时
+configureHttpClient({
+  baseURL: 'https://api.example.com',
+  timeout: 15000,
+});
+```
+
+### 2. 在Remote中使用HTTP客户端
+
+在任何Remote模块中，直接获取已配置好的`axios`实例来发起请求。
+
+```typescript
+import { getHttpClient } from '@realnation/builder-shared-sdk';
+
+async function fetchSomeData() {
+  try {
+    const httpClient = getHttpClient();
+    const response = await httpClient.get('/data');
+    console.log(response.data);
+  } catch (error) {
+    console.error('Request failed:', error);
+  }
+}
+```
+
+### 3. 使用全局事件总线
+
+`SdkEventBus`可用于在不同模块间传递消息，而无需直接依赖。
+
+**在Host或某个Remote中监听事件:**
+
+```typescript
+import { getGlobalEventBus } from '@realnation/builder-shared-sdk';
+
+const eventBus = getGlobalEventBus();
+
+// 监听模块导航事件
+const unsubscribe = eventBus.on('module:navigate', (payload) => {
+  console.log('Navigating to:', payload.path);
+  // 在这里执行路由跳转逻辑...
+});
+
+// 在组件卸载或不再需要时取消监听
+// unsubscribe();
+```
+
+**在另一个Remote中触发事件:**
+
+```typescript
+import { getGlobalEventBus } from '@realnation/builder-shared-sdk';
+
+const eventBus = getGlobalEventBus();
+
+function onButtonClick() {
+  eventBus.emit('module:navigate', { path: '/new-page' });
+}
+```
+
+## 🔗 动态流程控制 (Flow Control)
+
+这是SDK的核心亮点之一，提供了一种比传统模块联邦更灵活的模块间协作方式。Host可以定义一组具名事件（例如 `success`, `failure`, `nextStep`），并将它们与具体的操作（例如加载下一个Remote模块）关联起来。Remote模块在完成其任务后，只需触发这些预定义的事件，而无需关心接下来会发生什么。
+
+### 系统事件与自定义事件
+
+Flow Control区分两种事件类型：
+
+1.  **系统事件 (System Events)**: 以`sys:`为前缀，由SDK或框架约定，用于处理通用的生命周期钩子。例如 `sys:ready`。这些事件**不会**被`clearEvents()`清除。
+2.  **自定义事件 (Custom Events)**: 不带前缀，由业务逻辑定义，例如 `welcome:completed` 或 `profile:submitted`。这些事件会被`clearEvents()`清除。
+
+### 工作流程
+
+1.  **Host注册事件**: Host应用使用`registerEvent`注册系统事件和自定义事件的回调。
+    *   注册`sys:ready`来处理Remote模块加载完成后的显示逻辑。
+    *   注册自定义事件来编排业务流程。
+2.  **Remote触发事件**:
+    *   Remote模块加载并初始化完成后，应立即触发`sys:ready`事件，通知Host可以将其UI插入DOM并显示。
+    *   在用户交互或内部状态改变后，触发相应的自定义事件。
+3.  **执行与回退**:
+    *   如果Host注册了该事件，对应的回调函数将被执行。
+    *   如果Host**没有**注册该事件，`emitEvent`会执行一个可选的本地回退函数（最后一个函数类型的参数），确保Remote在独立运行时也能正常工作。
+4.  **清理**: 在业务流程结束时，Host调用`clearEvents()`来清理所有**自定义事件**，而系统事件保持不变。
+
+### 代码示例
+
+#### 在Host中编排流程
+
+```typescript
+import { registerEvent, clearEvents } from '@realnation/builder-shared-sdk/flow';
+import { loadRemoteModule, showRemote, hideRemote } from './remoteLoader'; // 假设的加载器
+
+// 注册系统事件，用于显示已加载的模块
+registerEvent('sys:ready', (remoteId) => {
+  console.log(`Remote module [${remoteId}] is ready to be displayed.`);
+  showRemote(remoteId);
+});
+
+// 注册自定义业务事件
+registerEvent('welcome:completed', () => {
+  hideRemote('welcome'); // 隐藏旧模块
+  loadRemoteModule('user-profile'); // 加载新模块
+});
+
+registerEvent('profile:submitted', (userData) => {
+  hideRemote('user-profile');
+  loadRemoteModule('summary-view', { user: userData });
+});
+
+// 当整个业务流程结束时，清理自定义事件
+function cleanupBusinessFlow() {
+  clearEvents();
+}
+```
+
+#### 在Remote中触发事件
+
+**`welcome-module` (远程模块):**
+
+```typescript
+import { emitEvent } from '@realnation/builder-shared-sdk/flow';
+import React, { useEffect } from 'react';
+
+function WelcomeComponent({ remoteId }) {
+  // 1. 组件挂载后，触发 sys:ready 事件
+  useEffect(() => {
+    emitEvent('sys:ready', remoteId, () => {
+      console.log(`Standalone mode: [${remoteId}] is ready.`);
+    });
+  }, [remoteId]);
+
+  const handleStartClick = () => {
+    // 2. 用户交互，触发自定义事件
+    emitEvent('welcome:completed', () => {
+      console.log('Standalone mode: Welcome journey would start here.');
+    });
+  };
+
+  return <button onClick={handleStartClick}>开始</button>;
+}
+```
+
+**`user-profile-module` (远程模块):**
+
+```typescript
+import { emitEvent } from '@realnation/builder-shared-sdk/flow';
+
+function UserProfileForm() {
+  const handleSubmit = (formData) => {
+    // 触发 'profile:submitted' 事件，并传递表单数据
+    emitEvent('profile:submitted', formData, () => {
+      console.log('In standalone mode: Form submitted locally.', formData);
+      // 在独立模式下可以导航到本地的下一页
+    });
+  };
+
+  // ... 表单逻辑
+}
+```
+
+这种模式的优势在于：
+
+-   **高度解耦**: Remote模块不关心下一个模块是什么，只关心在何时完成了自己的任务。
+-   **灵活编排**: Host可以随时改变流程，例如在A/B测试中，通过注册不同的回调来加载不同的下一个模块，而无需修改任何Remote模块的代码。
+-   **易于测试**: Remote模块可以独立开发和测试，只需为其`emitEvent`提供本地回退函数即可。
+
+## 🛠️ API参考
+
+### HTTP
+
+-   `setAuthToken(token: string | null)`: 设置全局JWT Token。
+-   `setTokenResolver(resolver: () => string | null)`: (高级) 设置一个函数来动态解析Token，优先级高于`setAuthToken`。
+-   `configureHttpClient(options: HttpClientOptions)`: 配置共享的`axios`实例。
+-   `getHttpClient(): AxiosInstance`: 获取配置好的`axios`实例。
+
+### Events
+
+-   `getGlobalEventBus(): SdkEventBus`: 获取全局事件总线实例。
+-   `eventBus.on(name, handler)`: 监听一个事件。
+-   `eventBus.emit(name, payload)`: 触发一个事件。
+-   `eventBus.off(name, handler)`: 取消监听。
+
+### Flow
+
+-   `registerEvent(type: string, callback: Function)`: Host注册一个流程事件。以`sys:`为前缀的事件为系统事件，不会被`clearEvents`清除。
+-   `removeEvent(type: string)`: 移除一个已注册的事件。
+-   `clearEvents()`: 移除所有**非系统级**的自定义事件。
+-   `emitEvent(type: string, ...args: any[])`: Remote触发一个流程事件。参数会透传给回调，如果最后一个参数是函数，则被视作本地回退`callback`。
+
+## 🔧 构建
+
+```bash
+npm run build
+```
+
+该命令会使用`tsc`将`src`目录下的TypeScript源文件编译到`dist`目录。

package/dist/flow.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Host 注册一个事件回调。
+ * @param type 事件名称。以 'sys:' 开头的为系统事件，不会被 clearEvents 清除。
+ * @param callback 事件触发时执行的回调函数。
+ */
+export declare const registerEvent: (type: string, callback: Function) => void;
+/**
+ * 移除一个已注册的事件。
+ * @param type 要移除的事件名称。
+ */
+export declare const removeEvent: (type: string) => void;
+/**
+ * 清除所有非系统级的自定义事件。
+ */
+export declare const clearEvents: () => void;
+/**
+ * Remote 触发一个事件。
+ * @param type 事件名称。
+ * @param args 传递给事件回调的参数。如果最后一个参数是函数，它将被当作本地回退使用。
+ */
+export declare const emitEvent: (type: string, ...args: any[]) => void;
+//# sourceMappingURL=flow.d.ts.map

package/dist/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../src/flow.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,EAAE,UAAU,QAAQ,SAM7D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,SAMvC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,YAIvB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,EAAE,GAAG,MAAM,GAAG,EAAE,SASrD,CAAC"}

package/dist/flow.js

@@ -0,0 +1,51 @@
+const systemEvents = {};
+const customEvents = {};
+const isSystemEvent = (type) => type.startsWith('sys:');
+/**
+ * Host 注册一个事件回调。
+ * @param type 事件名称。以 'sys:' 开头的为系统事件，不会被 clearEvents 清除。
+ * @param callback 事件触发时执行的回调函数。
+ */
+export const registerEvent = (type, callback) => {
+    if (isSystemEvent(type)) {
+        systemEvents[type] = callback;
+    }
+    else {
+        customEvents[type] = callback;
+    }
+};
+/**
+ * 移除一个已注册的事件。
+ * @param type 要移除的事件名称。
+ */
+export const removeEvent = (type) => {
+    if (isSystemEvent(type)) {
+        delete systemEvents[type];
+    }
+    else {
+        delete customEvents[type];
+    }
+};
+/**
+ * 清除所有非系统级的自定义事件。
+ */
+export const clearEvents = () => {
+    for (const key in customEvents) {
+        delete customEvents[key];
+    }
+};
+/**
+ * Remote 触发一个事件。
+ * @param type 事件名称。
+ * @param args 传递给事件回调的参数。如果最后一个参数是函数，它将被当作本地回退使用。
+ */
+export const emitEvent = (type, ...args) => {
+    const eventHandler = customEvents[type] ?? systemEvents[type];
+    const fallback = args.length > 0 && typeof args[args.length - 1] === 'function' ? args.pop() : null;
+    if (eventHandler) {
+        eventHandler(...args);
+    }
+    else if (fallback) {
+        fallback();
+    }
+};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types';
 export * from './http';
 export * from './events';
+export * from './flow';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC"}

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from './types';
 export * from './http';
 export * from './events';
+export * from './flow';

package/dist/types.d.ts

@@ -8,7 +8,7 @@ export interface RequestContext {
     headers?: Record<string, string>;
 }
 export type EventPayload = Record<string, unknown>;
-export type SdkEventName = 'sdk:ready' | 'sdk:error' | 'module:navigate' | 'module:metrics' | 'module:error' | 'module:open-surface' | 'module:close-surface' | 'host:refresh-token';
+export type SdkEventName = 'sdk:ready' | 'sdk:error' | 'module:navigate' | 'module:metrics' | 'module:error' | 'module:open-surface' | 'module:close-surface' | 'module:load-component' | 'host:refresh-token';
 export interface ModuleSurfaceRequest extends EventPayload {
     surfaceId: string;
     title?: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,WAAW,GACX,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,qBAAqB,GACrB,sBAAsB,GACtB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,yBAA0B,SAAQ,YAAY;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ,CAAC,QAAQ,SAAS,YAAY,GAAG,YAAY;IACpE,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,QAAQ,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,WAAW,GACX,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,qBAAqB,GACrB,sBAAsB,GACtB,uBAAuB,GACvB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,yBAA0B,SAAQ,YAAY;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ,CAAC,QAAQ,SAAS,YAAY,GAAG,YAAY;IACpE,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,QAAQ,CAAC;CACnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@realnation/builder-shared-sdk",
-  "version": "0.1.1",
+  "version": "1.0.1",
   "type": "module",
   "private": false,
   "exports": {