@djvlc/runtime-core 1.0.2 → 1.1.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as _djvlc_contracts_types from '@djvlc/contracts-types';
-import { ExpressionContext, Expression, ExpressionValidationResult, ActionRef, EventHandler, HostApi, NavigateOptions, TrackEvent, ActionResult, DialogOptions, DialogResult, ToastOptions, ClipboardApi, StorageApi, ShareOptions, ShareResult, ConfirmOptions, ActionSheetOptions, ActionSheetResult, PreviewImageOptions, ScanCodeResult, ComponentContext, ErrorCode, ManifestItem, PageManifest, CapabilityName, PageSchema, PageLifecycle } from '@djvlc/contracts-types';
+import { ExpressionContext, Expression, ExpressionValidationResult, ActionRef, EventHandler, PageResolveResponse, ActionResult, HostApi, NavigateOptions, TrackEvent, DialogOptions, DialogResult, ToastOptions, ClipboardApi, StorageApi, ShareOptions, ShareResult, ConfirmOptions, ActionSheetOptions, ActionSheetResult, PreviewImageOptions, ScanCodeResult, ComponentContext, ErrorCode, ManifestItem, PageManifest, CapabilityName, PageSchema, PageLifecycle } from '@djvlc/contracts-types';
 export { ActionExecuteRequest, ActionExecuteResponse, ActionPolicy, ActionRef, ActionResult, AnyValueOrExpression, BlockedComponentInfo, BuiltinActionType, CapabilityDeclaration, CompatInfo, ComponentContext, ComponentMeta, ComponentNode, DataBinding, DataLoadStrategy, DataQueryRequest, DataQueryResponse, DialogOptions, DialogResult, ErrorCode, ErrorMessages, EventDeclaration, EventHandler, Expression, ExpressionContext, ExpressionLocal, ExpressionMeta, ExpressionType, ExpressionValidationResult, HostApi as HostAPI, HostApi, JsonValue, LayoutConfig, LayoutValues, LoopConfig, ManifestItem, NavigateOptions, NodeStyleConfig, PageConfig, PageLifecycle, PageManifest, PageMeta, PageSEO, PageSchema, PageState, PropDefinition, PropsSchema, RuntimeSpec, SchemaVersion, SemVer, StateFieldDefinition, ToastOptions, TrackEvent, UniqueId } from '@djvlc/contracts-types';
+import { UserClientConfig } from '@djvlc/openapi-user-client';
 
 /**
  * 运行时初始化选项
@@ -8,8 +9,8 @@ export { ActionExecuteRequest, ActionExecuteResponse, ActionPolicy, ActionRef, A
 interface RuntimeOptions {
     /** 容器元素或选择器 */
     container: string | HTMLElement;
-    /** 页面 UID（pageId） */
-    pageUid: string;
+    /** 页面 ID（对应 contracts 中的 pageId） */
+    pageId: string;
     /** API 基础 URL */
     apiBaseUrl: string;
     /** CDN 基础 URL */
@@ -68,17 +69,21 @@ interface RuntimeState {
 }
 /**
  * 页面解析结果（Runtime 使用）
+ *
+ * @description
+ * 这是 Runtime 内部使用的类型，从 PageResolveResponse 和 PageSnapshotJson 转换而来。
+ * 使用 pageId 符合 contracts 定义。
  */
 interface PageResolveResult {
-    /** 页面 UID */
-    pageUid: string;
+    /** 页面 ID（对应 contracts 中的 pageId） */
+    pageId: string;
     /** 页面版本 ID */
     pageVersionId: string;
     /** 页面 JSON（PageSchema） */
     pageJson: _djvlc_contracts_types.PageSchema;
     /** 组件清单 */
     manifest: _djvlc_contracts_types.PageManifest;
-    /** 运行时配置 */
+    /** 运行时配置（从 OpsConfig 转换而来） */
     runtimeConfig?: {
         /** 被阻断的组件列表 */
         blockedComponents?: Array<{
@@ -837,6 +842,139 @@ declare class ActionBridge {
     private log;
 }
 
+/**
+ * User API 适配器接口
+ * 统一 Runtime 与 User API 的交互：页面解析、动作执行、数据查询、埋点
+ * 认证、请求头、重试等逻辑由实现类统一处理，便于测试与切换实现（如 openapi-user-client）
+ */
+
+/** 页面解析入参 */
+interface ResolvePageParams {
+    pageId: string;
+    uid?: string;
+    deviceId?: string;
+    env?: 'preview' | 'staging' | 'prod';
+    channel?: string;
+    previewToken?: string;
+}
+/** 动作执行入参 */
+interface ExecuteActionParams {
+    actionType: string;
+    params: Record<string, unknown>;
+    context: {
+        pageVersionId: string;
+        uid?: string;
+        deviceId?: string;
+        channel?: string;
+        appId: string;
+    };
+    idempotencyKey: string;
+}
+/** 数据查询入参 */
+interface ExecuteQueryParams {
+    queryVersionId: string;
+    params?: Record<string, unknown>;
+    context: {
+        pageVersionId: string;
+        uid?: string;
+        deviceId?: string;
+    };
+}
+/** 数据查询出参（与 User API /data/query 一致） */
+interface ExecuteQueryResult {
+    success: boolean;
+    data?: unknown;
+    message?: string;
+    errorMessage?: string;
+}
+/** 埋点 payload（与 User API /track 一致） */
+interface TrackPayload {
+    eventName: string;
+    params?: Record<string, unknown>;
+    type?: string;
+    timestamp?: number;
+    context: {
+        pageVersionId: string;
+        runtimeVersion: string;
+        userId?: string;
+        deviceId?: string;
+        channel?: string;
+        appId: string;
+        env: string;
+    };
+}
+/**
+ * User API 适配器
+ * 只约定入参/出参，不绑定具体 HTTP 库；由 Runtime 注入实现，单测可注入 Mock
+ */
+interface UserApiAdapter {
+    /** 页面解析 GET /page/resolve */
+    resolvePage(params: ResolvePageParams): Promise<PageResolveResponse>;
+    /** 动作执行 POST /actions/execute */
+    executeAction<T = unknown>(params: ExecuteActionParams): Promise<ActionResult<T>>;
+    /** 数据查询 POST /data/query */
+    executeQuery(params: ExecuteQueryParams): Promise<ExecuteQueryResult>;
+    /** 埋点 POST /track（可异步、不阻塞） */
+    track(payload: TrackPayload): void;
+}
+
+/**
+ * 基于 @djvlc/openapi-user-client 的 User API 适配器
+ * 统一认证、请求头、重试等逻辑，不直接使用 fetch
+ */
+
+type OpenApiUserAdapterOptions = UserClientConfig;
+/**
+ * 基于 openapi-user-client 的 User API 适配器实现
+ * Runtime 与 User API 的交互仅通过此适配器
+ */
+declare class OpenApiUserAdapter implements UserApiAdapter {
+    private readonly client;
+    constructor(options?: OpenApiUserAdapterOptions);
+    resolvePage(params: ResolvePageParams): Promise<PageResolveResponse>;
+    executeAction<T = unknown>(params: ExecuteActionParams): Promise<ActionResult<T>>;
+    executeQuery(params: ExecuteQueryParams): Promise<ExecuteQueryResult>;
+    track(payload: TrackPayload): void;
+}
+
+/**
+ * 测试用 User API 适配器 Mock
+ * 单测中注入，不再 mock global.fetch
+ */
+
+interface MockUserApiAdapterOptions {
+    /** resolvePage 返回值（可覆盖） */
+    resolvePageResponse?: PageResolveResponse;
+    /** executeAction 返回值（可覆盖） */
+    executeActionResponse?: ActionResult<unknown>;
+    /** executeQuery 返回值（可覆盖） */
+    executeQueryResponse?: ExecuteQueryResult;
+    /** 是否在 resolve 时抛错 */
+    resolvePageThrow?: Error;
+    /** 是否在 executeAction 时抛错 */
+    executeActionThrow?: Error;
+    /** 是否在 executeQuery 时抛错 */
+    executeQueryThrow?: Error;
+}
+/**
+ * 测试用 Mock 实现
+ * 记录调用次数与参数，返回可配置的默认值或自定义值
+ */
+declare class MockUserApiAdapter implements UserApiAdapter {
+    private readonly options;
+    readonly calls: {
+        resolvePage: ResolvePageParams[];
+        executeAction: ExecuteActionParams[];
+        executeQuery: ExecuteQueryParams[];
+        track: TrackPayload[];
+    };
+    constructor(options?: MockUserApiAdapterOptions);
+    resolvePage(params: ResolvePageParams): Promise<PageResolveResponse>;
+    executeAction<T = unknown>(params: ExecuteActionParams): Promise<ActionResult<T>>;
+    executeQuery(params: ExecuteQueryParams): Promise<ExecuteQueryResult>;
+    track(payload: TrackPayload): void;
+}
+
 /**
  * Host API 实现
  * 提供给组件的安全 API，完全对齐 @djvlc/contracts-types 中的 HostApi 定义
@@ -852,7 +990,7 @@ declare class ActionBridge {
  * 运行时上下文
  */
 interface RuntimeContext {
-    pageUid: string;
+    pageId: string;
     pageVersionId: string;
     runtimeVersion: string;
     userId?: string;
@@ -867,12 +1005,8 @@ interface RuntimeContext {
  * Host API 配置
  */
 interface HostAPIOptions {
-    /** API 基础 URL */
-    apiBaseUrl: string;
-    /** 认证 Token */
-    authToken?: string;
-    /** 请求头 */
-    headers?: Record<string, string>;
+    /** User API 适配器（必填，仅通过适配器调用 User API） */
+    userApiAdapter: UserApiAdapter;
     /** 状态管理器 */
     stateManager: StateManager;
     /** 事件总线 */
@@ -915,7 +1049,6 @@ declare class HostAPIImpl implements HostApi {
     getState<T = unknown>(path: string): T | undefined;
     setState(path: string, value: unknown): void;
     getContext(): ComponentContext;
-    private buildHeaders;
     private generateIdempotencyKey;
     private simpleHash;
     private fallbackCopy;
@@ -961,6 +1094,8 @@ declare class DjvlcRuntime {
     private renderer;
     private hostApi;
     private lifecycleManager;
+    /** User API 适配器，统一认证/请求头，供 PageLoader 与 HostAPIImpl 使用 */
+    private userApiAdapter;
     private logger;
     constructor(options: RuntimeOptions);
     /**
@@ -1130,22 +1265,24 @@ declare class RenderError extends DjvlcRuntimeError {
 
 /**
  * 页面加载器
- * 负责从 API 解析页面配置
+ * 负责从 API 解析页面配置，严格按照 @djvlc/contracts-types 定义
  */
 
 /**
  * 页面加载器配置
  */
 interface PageLoaderOptions {
-    /** API 基础 URL */
+    /** API 基础 URL（用于 preconnect、CDN 请求头） */
     apiBaseUrl: string;
+    /** User API 适配器（必填，仅通过适配器调用 User API） */
+    userApiAdapter: UserApiAdapter;
+    /** 环境 */
+    env?: 'preview' | 'staging' | 'prod';
     /** 渠道 */
-    channel?: 'preview' | 'prod' | 'gray';
-    /** 认证 Token */
-    authToken?: string;
+    channel?: string;
     /** 预览 Token */
     previewToken?: string;
-    /** 请求头 */
+    /** 请求头（CDN 请求用） */
     headers?: Record<string, string>;
     /** 缓存配置 */
     cache?: {
@@ -1158,6 +1295,7 @@ interface PageLoaderOptions {
 /**
  * 页面加载器
  * 负责调用 /page/resolve 接口获取页面数据
+ * 严格按照 contracts 中的 PageResolveResponse 定义
  */
 declare class PageLoader {
     private options;
@@ -1165,13 +1303,39 @@ declare class PageLoader {
     constructor(options: PageLoaderOptions);
     /**
      * 解析页面
-     * @param pageUid 页面 UID
+     * @param pageId 页面 ID（对应 contracts 中的 pageId）
      * @param params 额外参数
      */
-    resolve(pageUid: string, params?: {
+    resolve(pageId: string, params?: {
         uid?: string;
         deviceId?: string;
     }): Promise<PageResolveResult>;
+    /**
+     * 通过 User API 适配器调用 resolve
+     */
+    private callResolveViaAdapter;
+    /**
+     * 从 CDN 加载 snapshot 和 manifest
+     */
+    private loadFromCdn;
+    /**
+     * 转换 PageSnapshotJson 为 PageResolveResult
+     */
+    private convertSnapshotToResult;
+    /**
+     * 转换 PageSnapshotPage 为 PageSchema
+     * 严格按照 contracts 定义进行转换
+     */
+    private convertSnapshotPageToPageSchema;
+    /**
+     * 转换 PageSnapshotManifest 为 PageManifest
+     * 注意：PageSnapshotManifest 是简化版本，缺少一些字段，需要从其他地方获取或使用默认值
+     */
+    private convertSnapshotManifestToPageManifest;
+    /**
+     * 验证 PageResolveResponse（严格按照 contracts 定义）
+     */
+    private isValidPageResolveResponse;
     /**
      * 预连接 API 服务器
      */
@@ -1179,40 +1343,43 @@ declare class PageLoader {
     /**
      * 清除缓存
      */
-    clearCache(pageUid?: string): void;
-    private buildResolveUrl;
+    clearCache(pageId?: string): void;
     private buildHeaders;
     private getCacheKey;
     private isCacheValid;
-    private isValidPageResolveResult;
     private log;
 }
 
 /**
  * 组件加载器
- * 负责从 CDN 加载组件资源
+ * 负责从 CDN 动态加载 Web Components，支持 SRI 完整性校验、组件阻断、并行加载与降级处理。
+ * @see SKILL: runtime-component-loading
  */
 
 /**
  * 组件加载器配置
  */
 interface ComponentLoaderOptions {
-    /** CDN 基础 URL */
+    /** CDN 基础 URL，用于解析相对 entry 路径 */
     cdnBaseUrl: string;
-    /** 是否启用 SRI 校验 */
+    /** 是否启用 SRI 完整性校验，默认 true */
     enableSRI?: boolean;
-    /** 被阻断的组件列表 */
+    /** 被阻断的组件列表（如 `['comp@1.0.0']` 或仅组件名 `['comp']`），用于紧急止血 */
     blockedComponents?: string[];
-    /** 并行加载数量 */
+    /** 并行加载数量，默认 4 */
     concurrency?: number;
-    /** 超时时间（毫秒） */
+    /** 单次请求超时（毫秒），默认 30000 */
     timeout?: number;
+    /** 请求 CDN 时附加的请求头（如认证等） */
+    headers?: Record<string, string>;
+    /** 自定义拉取脚本的实现，不传则使用全局 fetch；测试或自定义 CDN 客户端时注入 */
+    fetchComponentScript?: (url: string, init?: RequestInit) => Promise<Response>;
     /** 日志器 */
     logger?: Logger;
 }
 /**
  * 组件加载器
- * 负责加载 Web Components
+ * 负责从 CDN 加载 Web Components，支持缓存、阻断、SRI 校验与并行加载。
  */
 declare class ComponentLoader {
     private options;
@@ -1221,37 +1388,47 @@ declare class ComponentLoader {
     private blockedSet;
     constructor(options: ComponentLoaderOptions);
     /**
-     * 加载单个组件
+     * 加载单个组件（按 name@version 去重，同一组件并发请求复用同一 Promise）
+     * @param item - 清单项（name、version、entry、integrity 等）
+     * @returns 已加载的组件信息（含 Component 构造函数）
+     * @throws ComponentBlockedError 当组件在阻断列表中
+     * @throws ComponentLoadError 当拉取或执行失败
+     * @throws IntegrityError 当 SRI 校验失败
      */
     load(item: ManifestItem): Promise<LoadedComponent>;
     /**
-     * 加载 Manifest 中的所有组件
+     * 按 manifest 批量加载组件，按 concurrency 分批并行；关键组件失败会抛出，非关键组件记录失败。
+     * @param manifest - 页面清单（含 components 数组）
+     * @returns 以 name@version 为 key 的加载结果 Map（status: loaded | failed | blocked）
      */
     loadAll(manifest: PageManifest): Promise<Map<string, ComponentLoadResult>>;
     /**
-     * 预加载组件
+     * 预加载组件：向 document.head 插入 &lt;link rel="preload" as="script"&gt;，仅作提示，不阻塞 load。
+     * @param items - 需要预加载的清单项
      */
     preload(items: ManifestItem[]): void;
     /**
-     * 检查组件是否已加载
+     * 检查指定 name@version 的组件是否已加载并缓存
      */
     isLoaded(name: string, version: string): boolean;
     /**
-     * 获取已加载的组件
+     * 获取已加载的组件信息，未加载则返回 undefined
      */
     get(name: string, version: string): LoadedComponent | undefined;
     /**
-     * 检查组件是否被阻断
+     * 检查组件是否在阻断列表中（支持 `name@version` 或仅 `name`）
      */
     isBlocked(name: string, version: string): boolean;
     /**
-     * 更新阻断列表
+     * 更新阻断列表（会完全替换当前列表）
      */
     updateBlockedList(blocked: string[]): void;
     private loadComponent;
     private fetchWithTimeout;
     private validateIntegrity;
     private executeScript;
+    /** kebab-case -> PascalCase，用于匹配组件命名导出 */
+    private kebabToPascal;
     private resolveUrl;
     private getComponentKey;
     private log;
@@ -2008,4 +2185,4 @@ declare class LifecycleManager {
  */
 declare const RUNTIME_VERSION = "1.0.0";
 
-export { type ASTNode, ActionBridge, type ActionBridgeOptions, ActionError, type ActionExecutor, AssetLoader, type AssetLoaderOptions, BaseRenderer, type BaseRendererOptions, ComponentBlockedError, ComponentLoadError, type ComponentLoadResult, type ComponentLoadStatus, ComponentLoader, type ComponentLoaderOptions, DjvlcRuntime, DjvlcRuntimeError, type EvaluationResult, Evaluator, type EvaluatorOptions, EventBus, type EventBusOptions, type EventHandlerFn, ExpressionEngine, type ExpressionEngineOptions, ExpressionError, HostAPIImpl, type HostAPIOptions, IntegrityError, Lexer, type LifecycleEventType, LifecycleManager, type LifecycleManagerOptions, type LoadedComponent, type LogLevel, type Logger, type MetricType, PageLoadError, PageLoader, type PageLoaderOptions, type PageResolveResult, Parser, type PerformanceMetric, QueryError, RUNTIME_VERSION, RenderError, type Renderer, type RuntimeError, type RuntimeErrorType, type RuntimeEvent, type RuntimeEventType, type RuntimeOptions, type RuntimePhase, type RuntimeState, SUPPORTED_SCHEMA_VERSION as SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSION, SecurityManager, type SecurityManagerOptions, type Span, type StateListener, StateManager, TelemetryManager, type TelemetryManagerOptions, type Token, type TokenType, type Unsubscribe, builtinFunctions, createFallbackElement, createRuntime, registerFallbackComponents };
+export { type ASTNode, ActionBridge, type ActionBridgeOptions, ActionError, type ActionExecutor, AssetLoader, type AssetLoaderOptions, BaseRenderer, type BaseRendererOptions, ComponentBlockedError, ComponentLoadError, type ComponentLoadResult, type ComponentLoadStatus, ComponentLoader, type ComponentLoaderOptions, DjvlcRuntime, DjvlcRuntimeError, type EvaluationResult, Evaluator, type EvaluatorOptions, EventBus, type EventBusOptions, type EventHandlerFn, type ExecuteActionParams, type ExecuteQueryParams, type ExecuteQueryResult, ExpressionEngine, type ExpressionEngineOptions, ExpressionError, HostAPIImpl, type HostAPIOptions, IntegrityError, Lexer, type LifecycleEventType, LifecycleManager, type LifecycleManagerOptions, type LoadedComponent, type LogLevel, type Logger, type MetricType, MockUserApiAdapter, type MockUserApiAdapterOptions, OpenApiUserAdapter, type OpenApiUserAdapterOptions, PageLoadError, PageLoader, type PageLoaderOptions, type PageResolveResult, Parser, type PerformanceMetric, QueryError, RUNTIME_VERSION, RenderError, type Renderer, type ResolvePageParams, type RuntimeContext, type RuntimeError, type RuntimeErrorType, type RuntimeEvent, type RuntimeEventType, type RuntimeOptions, type RuntimePhase, type RuntimeState, SUPPORTED_SCHEMA_VERSION as SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSION, SecurityManager, type SecurityManagerOptions, type Span, type StateListener, StateManager, TelemetryManager, type TelemetryManagerOptions, type Token, type TokenType, type TrackPayload, type Unsubscribe, type UserApiAdapter, builtinFunctions, createFallbackElement, createRuntime, registerFallbackComponents };